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 TPMI_DH_OBJECT+ 3722 3723 tpmKey 3724 3725 handle of a loaded decrypt key used to encrypt salt 3726 may be TPM_RH_NULL 3727 Auth Index: None 3728 3729 TPMI_DH_ENTITY+ 3730 3731 bind 3732 3733 entity providing the authValue 3734 may be TPM_RH_NULL 3735 Auth Index: None 3736 3737 TPM2B_NONCE 3738 3739 nonceCaller 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 3747 3748 encryptedSalt 3749 3750 value encrypted according to the type of tpmKey 3751 If tpmKey is TPM_RH_NULL, this shall be the Empty 3752 Buffer. 3753 3754 TPM_SE 3755 3756 sessionType 3757 3758 indicates the type of the session; simple HMAC or policy 3759 (including a trial policy) 3760 3761 TPMT_SYM_DEF+ 3762 3763 symmetric 3764 3765 the algorithm and key size for parameter encryption 3766 may select TPM_ALG_NULL 3767 3768 TPMI_ALG_HASH 3769 3770 authHash 3771 3772 hash algorithm to use for the session 3773 Shall be a hash algorithm supported by the TPM and 3774 not TPM_ALG_NULL 3775 3776 Table 16 TPM2_StartAuthSession Response 3777 Type 3778 3779 Name 3780 3781 Description 3782 3783 TPM_ST 3784 3785 tag 3786 3787 see clause 8 3788 3789 UINT32 3790 3791 responseSize 3792 3793 TPM_RC 3794 3795 responseCode 3796 3797 TPMI_SH_AUTH_SESSION 3798 3799 sessionHandle 3800 3801 handle for the newly created session 3802 3803 TPM2B_NONCE 3804 3805 nonceTPM 3806 3807 the initial nonce from the TPM, used in the computation 3808 of the sessionKey 3809 3810 Page 40 3811 October 31, 2013 3812 3813 Published 3814 Copyright TCG 2006-2013 3815 3816 Family 2.0 3817 Level 00 Revision 00.99 3818 3819 Trusted Platform Module Library 3821 3822 Part 3: Commands 3823 3824 13.1.3 Detailed Actions 3825 1 3826 2 3827 3828 #include "InternalRoutines.h" 3829 #include "StartAuthSession_fp.h" 3830 Error Returns 3831 TPM_RC_ATTRIBUTES 3832 3833 tpmKey does not reference a decrypt key 3834 3835 TPM_RC_CONTEXT_GAP 3836 3837 the difference between the most recently created active context and 3838 the oldest active context is at the limits of the TPM 3839 3840 TPM_RC_HANDLE 3841 3842 input decrypt key handle only has public portion loaded 3843 3844 TPM_RC_MODE 3845 3846 symmetric specifies a block cipher but the mode is not 3847 TPM_ALG_CFB. 3848 3849 TPM_RC_SESSION_HANDLES 3850 3851 no session handle is available 3852 3853 TPM_RC_SESSION_MEMORY 3854 3855 no more slots for loading a session 3856 3857 TPM_RC_SIZE 3858 3859 nonce less than 16 octets or greater than the size of the digest 3860 produced by authHash 3861 3862 TPM_RC_VALUE 3863 3864 3 3865 4 3866 5 3867 6 3868 7 3869 8 3870 9 3871 10 3872 11 3873 12 3874 13 3875 14 3876 15 3877 16 3878 17 3879 18 3880 19 3881 20 3882 21 3883 22 3884 23 3885 24 3886 25 3887 26 3888 27 3889 28 3890 29 3891 30 3892 31 3893 32 3894 33 3895 34 3896 35 3897 36 3898 3899 Meaning 3900 3901 secret size does not match decrypt key type; or the recovered secret 3902 is larget than the digest size of the nameAlg of tpmKey; or, for an 3903 RSA decrypt key, if encryptedSecret is greater than the public 3904 exponent of tpmKey. 3905 3906 TPM_RC 3907 TPM2_StartAuthSession( 3908 StartAuthSession_In 3909 StartAuthSession_Out 3910 3911 *in, 3912 *out 3913 3914 // IN: input parameter buffer 3915 // OUT: output parameter buffer 3916 3917 TPM_RC 3918 OBJECT 3919 SESSION 3920 TPM2B_DATA 3921 3922 result = TPM_RC_SUCCESS; 3923 *tpmKey; 3924 // TPM key for decrypt salt 3925 *session; 3926 // session internal data 3927 salt; 3928 3929 ) 3930 { 3931 3932 // Input Validation 3933 // Check input nonce size. IT should be at least 16 bytes but not larger 3934 // than the digest size of session hash. 3935 if( 3936 in->nonceCaller.t.size < 16 3937 || in->nonceCaller.t.size > CryptGetHashDigestSize(in->authHash)) 3938 return TPM_RC_SIZE + RC_StartAuthSession_nonceCaller; 3939 // If an decrypt key is passed in, check its validation 3940 if(in->tpmKey != TPM_RH_NULL) 3941 { 3942 // secret size cannot be 0 3943 if(in->encryptedSalt.t.size == 0) 3944 return TPM_RC_VALUE + RC_StartAuthSession_encryptedSalt; 3945 // Get pointer to loaded decrypt key 3946 tpmKey = ObjectGet(in->tpmKey); 3947 // Decrypting salt requires accessing the private portion of a key. 3948 // Therefore, tmpKey can not be a key with only public portion loaded 3949 if(tpmKey->attributes.publicOnly) 3950 return TPM_RC_HANDLE + RC_StartAuthSession_tpmKey; 3951 3952 Family 2.0 3953 Level 00 Revision 00.99 3954 3955 Published 3956 Copyright TCG 2006-2013 3957 3958 Page 41 3959 October 31, 2013 3960 3961 Part 3: Commands 3963 37 3964 38 3965 39 3966 40 3967 41 3968 42 3969 43 3970 44 3971 45 3972 46 3973 47 3974 48 3975 49 3976 50 3977 51 3978 52 3979 53 3980 54 3981 55 3982 56 3983 57 3984 58 3985 59 3986 60 3987 61 3988 62 3989 63 3990 64 3991 65 3992 66 3993 67 3994 68 3995 69 3996 70 3997 71 3998 72 3999 73 4000 74 4001 75 4002 76 4003 77 4004 78 4005 79 4006 80 4007 81 4008 82 4009 83 4010 84 4011 85 4012 86 4013 87 4014 88 4015 89 4016 90 4017 4018 Trusted Platform Module Library 4019 4020 // HMAC session input handle check. 4021 // tpmKey should be a decryption key 4022 if(tpmKey->publicArea.objectAttributes.decrypt != SET) 4023 return TPM_RC_ATTRIBUTES + RC_StartAuthSession_tpmKey; 4024 // Secret Decryption. A TPM_RC_VALUE, TPM_RC_KEY or Unmarshal errors 4025 // may be returned at this point 4026 result = CryptSecretDecrypt(in->tpmKey, &in->nonceCaller, "SECRET", 4027 &in->encryptedSalt, &salt); 4028 if(result != TPM_RC_SUCCESS) 4029 return TPM_RC_VALUE + RC_StartAuthSession_encryptedSalt; 4030 } 4031 else 4032 { 4033 // secret size must be 0 4034 if(in->encryptedSalt.t.size != 0) 4035 return TPM_RC_VALUE + RC_StartAuthSession_encryptedSalt; 4036 salt.t.size = 0; 4037 } 4038 // If 'symmetric' is a symmetric block cipher (not TPM_ALG_NULL or TPM_ALG_XOR) 4039 // then the mode must be CFB. 4040 if( 4041 in->symmetric.algorithm != TPM_ALG_NULL 4042 && in->symmetric.algorithm != TPM_ALG_XOR 4043 && in->symmetric.mode.sym != TPM_ALG_CFB) 4044 return TPM_RC_MODE + RC_StartAuthSession_symmetric; 4045 // Internal Data Update 4046 // Create internal session structure. TPM_RC_CONTEXT_GAP, TPM_RC_NO_HANDLES 4047 // or TPM_RC_SESSION_MEMORY errors may be returned returned at this point. 4048 // 4049 // The detailed actions for creating the session context are not shown here 4050 // as the details are implementation dependent 4051 // SessionCreate sets the output handle 4052 result = SessionCreate(in->sessionType, in->authHash, 4053 &in->nonceCaller, &in->symmetric, 4054 in->bind, &salt, &out->sessionHandle); 4055 if(result != TPM_RC_SUCCESS) 4056 return result; 4057 // Command Output 4058 // Get session pointer 4059 session = SessionGet(out->sessionHandle); 4060 // Copy nonceTPM 4061 out->nonceTPM = session->nonceTPM; 4062 return TPM_RC_SUCCESS; 4063 } 4064 4065 Page 42 4066 October 31, 2013 4067 4068 Published 4069 Copyright TCG 2006-2013 4070 4071 Family 2.0 4072 Level 00 Revision 00.99 4073 4074 Trusted Platform Module Library 4076 4077 13.2 4078 4079 Part 3: Commands 4080 4081 TPM2_PolicyRestart 4082 4083 13.2.1 General Description 4084 This command allows a policy authorization session to be returned to its initial state. This command is 4085 used after the TPM returns TPM_RC_PCR_CHANGED. That response code indicates that a policy will 4086 fail because the PCR have changed after TPM2_PolicyPCR() was executed. Restarting the session 4087 allows the authorizations to be replayed because the session restarts with the same nonceTPM. If the 4088 PCR are valid for the policy, the policy may then succeed. 4089 This command does not reset the policy ID or the policy start time. 4090 4091 Family 2.0 4092 Level 00 Revision 00.99 4093 4094 Published 4095 Copyright TCG 2006-2013 4096 4097 Page 43 4098 October 31, 2013 4099 4100 Part 3: Commands 4102 4103 Trusted Platform Module Library 4104 4105 13.2.2 Command and Response 4106 Table 17 TPM2_PolicyRestart Command 4107 Type 4108 4109 Name 4110 4111 Description 4112 4113 TPMI_ST_COMMAND_TAG 4114 4115 tag 4116 4117 UINT32 4118 4119 commandSize 4120 4121 TPM_CC 4122 4123 commandCode 4124 4125 TPM_CC_PolicyRestart 4126 4127 TPMI_SH_POLICY 4128 4129 sessionHandle 4130 4131 the handle for the policy session 4132 4133 Table 18 TPM2_PolicyRestart Response 4134 Type 4135 4136 Name 4137 4138 Description 4139 4140 TPM_ST 4141 4142 tag 4143 4144 see clause 8 4145 4146 UINT32 4147 4148 responseSize 4149 4150 TPM_RC 4151 4152 responseCode 4153 4154 Page 44 4155 October 31, 2013 4156 4157 Published 4158 Copyright TCG 2006-2013 4159 4160 Family 2.0 4161 Level 00 Revision 00.99 4162 4163 Trusted Platform Module Library 4165 4166 Part 3: Commands 4167 4168 13.2.3 Detailed Actions 4169 1 4170 2 4171 3 4172 4 4173 5 4174 6 4175 7 4176 8 4177 9 4178 10 4179 11 4180 12 4181 13 4182 14 4183 15 4184 16 4185 17 4186 18 4187 19 4188 20 4189 21 4190 22 4191 4192 #include "InternalRoutines.h" 4193 #include "PolicyRestart_fp.h" 4194 4195 TPM_RC 4196 TPM2_PolicyRestart( 4197 PolicyRestart_In 4198 4199 *in 4200 4201 // IN: input parameter list 4202 4203 SESSION 4204 BOOL 4205 4206 *session; 4207 wasTrialSession; 4208 4209 ) 4210 { 4211 4212 // Internal Data Update 4213 session = SessionGet(in->sessionHandle); 4214 wasTrialSession = session->attributes.isTrialPolicy == SET; 4215 // Initialize policy session 4216 SessionResetPolicyData(session); 4217 session->attributes.isTrialPolicy = wasTrialSession; 4218 return TPM_RC_SUCCESS; 4219 } 4220 4221 Family 2.0 4222 Level 00 Revision 00.99 4223 4224 Published 4225 Copyright TCG 2006-2013 4226 4227 Page 45 4228 October 31, 2013 4229 4230 Part 3: Commands 4232 4233 Trusted Platform Module Library 4234 4235 Object Commands 4236 4237 14 4238 14.1 4239 4240 TPM2_Create 4241 4242 14.1.1 General Description 4243 This command is used to create an object that can be loaded into a TPM using TPM2_Load(). If the 4244 command completes successfully, the TPM will create the new object and return the objects creation 4245 data (creationData), its public area (outPublic), and its encrypted sensitive area (outPrivate). Preservation 4246 of the returned data is the responsibility of the caller. The object will need to be loaded (TPM2_Load()) 4247 before it may be used. 4248 TPM2B_PUBLIC template (inPublic) contains all of the fields necessary to define the properties of the 4249 new object. The setting for these fields is defined in Public Area Template in Part 1 and 4250 TPMA_OBJECT in Part 2. 4251 The parentHandle parameter shall reference a loaded decryption key that has both the public and 4252 sensitive area loaded. 4253 When defining the object, the caller provides a template structure for the object in a TPM2B_PUBLIC 4254 structure (inPublic), an initial value for the objects authValue (inSensitive.authValue), and, if the object is 4255 a symmetric object, an optional initial data value (inSensitive.data). The TPM shall validate the 4256 consistency of inPublic.attributes according to the Creation rules in TPMA_OBJECT in Part 2. 4257 The sensitive parameter may be encrypted using parameter encryption. 4258 The methods in this clause are used by both TPM2_Create() and TPM2_CreatePrimary(). When a value 4259 is indicated as being TPM-generated, the value is filled in by bits from the RNG if the command is 4260 TPM2_Create() and with values from KDFa() if the command is TPM2_CreatePrimary(). The parameters 4261 of each creation value are specified in Part 1. 4262 The sensitiveDataOrigin attribute of inPublic shall be SET if inSensitive.data is an Empty Buffer and 4263 CLEAR if inSensitive.data is not an Empty Buffer or the TPM shall return TPM_RC_ATTRIBUTES. 4264 The TPM will create new data for the sensitive area and compute a TPMT_PUBLIC.unique from the 4265 sensitive area based on the object type: 4266 a) For a symmetric key: 4267 1) If inSensitive.data is the Empty Buffer, a TPM-generated key value is placed in the new objects 4268 TPMT_SENSITIVE.sensitive.sym. The size of the key will be determined by 4269 inPublic.publicArea.parameters. 4270 2) If inSensitive.data is not the Empty Buffer, the TPM will validate that the size of inSensitive.data is 4271 no larger than the key size indicated in the inPublic template (TPM_RC_SIZE) and copy the 4272 inSensitive.data to TPMT_SENSITIVE.sensitive.sym of the new object. 4273 3) A TPM-generated obfuscation value is placed in TPMT_SENSITIVE.sensitive.seedValue. The 4274 size of the obfuscation value is the size of the digest produced by the nameAlg in inPublic. This 4275 value prevents the public unique value from leaking information about the sensitive area. 4276 4) The TPMT_PUBLIC.unique.sym.buffer value for the new object is then generated, as shown in 4277 equation (1) below, by hashing the key and obfuscation values in the TPMT_SENSITIVE with the 4278 nameAlg of the object. 4279 4280 unique HnameAlg(sensitive.seedValue.buffer || sensitive.any.buffer) 4281 4282 (1) 4283 4284 b) If the Object is an asymmetric key: 4285 1) If sensitive.data is not the Empty Buffer, then the TPM shall return TPM_RC_VALUE. 4286 4287 Page 46 4288 October 31, 2013 4289 4290 Published 4291 Copyright TCG 2006-2013 4292 4293 Family 2.0 4294 Level 00 Revision 00.99 4295 4296 Trusted Platform Module Library 4298 4299 Part 3: Commands 4300 4301 2) A TPM-generated private key value is created with the size determined by the parameters of 4302 inPublic.publicArea.parameters. 4303 3) If the key is a Storage Key, a TPM-generated TPMT_SENSITIVE.symKey value is created; 4304 otherwise, TPMT_SENSITIVE.symKey.size is set to zero. 4305 4) The public unique value is computed from the private key according to the methods of the key 4306 type. 4307 5) If the key is an ECC key and the scheme required by the curveID is not the same as scheme in 4308 the public area of the template, then the TPM shall return TPM_RC_SCHEME. 4309 6) If the key is an ECC key and the KDF required by the curveID is not the same as kdf in the pubic 4310 area of the template, then the TPM shall return TPM_RC_KDF. 4311 NOTE 1 4312 4313 There is currently no command in which the caller may specify the KDF to be used with an 4314 ECC decryption key. Since there is no use for this capability, the reference implementation 4315 requires that the kdf in the template be set to TPM_ALG_NULL or TPM_RC_KDF is 4316 returned. 4317 4318 c) If the Object is a keyedHash object: 4319 1) If inSensitive.data is an Empty Buffer, and neither sign nor decrypt is SET in inPublic.attributes, 4320 the TPM shall return TPM_RC_ATTRIBUTES. This would be a data object with no data. 4321 2) If inSensitive.data is not an Empty Buffer, the TPM will copy the inSensitive.data to 4322 TPMT_SENSITIVE.sensitive of the new object. 4323 NOTE 2 4324 4325 The size of inSensitive.data is limited to be no larger 4326 TPMT_SENSITIVE.sensitive.bits.data by MAX_SYM_DATA. 4327 4328 than 4329 4330 the 4331 4332 largest 4333 4334 value 4335 4336 of 4337 4338 3) If inSensitive.data is an Empty Buffer, a TPM-generated key value that is the size of the digest 4339 produced by the nameAlg in inPublic is placed in TPMT_SENSITIVE.sensitive.any.buffer. 4340 4) A TPM-generated obfuscation value that is the size of the digest produced by the nameAlg of 4341 inPublic is placed in TPMT_SENSITIVE.symKey.buffer. 4342 5) The TPMT_PUBLIC.unique.sym.buffer value for the new object is then generated, as shown in 4343 equation (1) above, by hashing the key and obfuscation values in the TPMT_SENSITIVE with the 4344 nameAlg of the object. 4345 For TPM2_Load(), the TPM will apply normal symmetric protections to the created TPMT_SENSITIVE to 4346 create outPublic. 4347 NOTE 3 4348 4349 The encryption key is derived from the symmetric seed in the sensitive area of the parent. 4350 4351 In addition to outPublic and outPrivate, the TPM will build a TPMS_CREATION_DATA structure for the 4352 object. TPMS_CREATION_DATA.outsideInfo is set to outsideInfo. This structure is returned in 4353 creationData. Additionally, the digest of this structure is returned in creationHash, and, finally, a 4354 TPMT_TK_CREATION is created so that the association between the creation data and the object may 4355 be validated by TPM2_CertifyCreation(). 4356 If the object being created is a Storage Key and inPublic.objectAttributes.fixedParent is SET, then the 4357 algorithms of inPublic are required to match those of the parent. The algorithms that must match are 4358 inPublic.type, inPublic.nameAlg, and inPublic.parameters. If inPublic.type does not match, the TPM shall 4359 return TPM_RC_TYPE. If inPublic.nameAlg does not match, the TPM shall return TPM_RC_HASH. If 4360 inPublic.parameters does not match, the TPM shall return TPM_RC_ASSYMETRIC. The TPM shall not 4361 differentiate between mismatches of the components of inPublic.parameters. 4362 EXAMPLE 4363 4364 If the inPublic.parameters.ecc.symmetric.algorithm does not match the parent, the TPM shall return 4365 TPM_RC_ ASYMMETRIC rather than TPM_RC_SYMMETRIC. 4366 4367 Family 2.0 4368 Level 00 Revision 00.99 4369 4370 Published 4371 Copyright TCG 2006-2013 4372 4373 Page 47 4374 October 31, 2013 4375 4376 Part 3: Commands 4378 4379 Trusted Platform Module Library 4380 4381 14.1.2 Command and Response 4382 Table 19 TPM2_Create Command 4383 Type 4384 4385 Name 4386 4387 Description 4388 4389 TPMI_ST_COMMAND_TAG 4390 4391 tag 4392 4393 UINT32 4394 4395 commandSize 4396 4397 TPM_CC 4398 4399 commandCode 4400 4401 TPM_CC_Create 4402 4403 TPMI_DH_OBJECT 4404 4405 @parentHandle 4406 4407 handle of parent for new object 4408 Auth Index: 1 4409 Auth Role: USER 4410 4411 TPM2B_SENSITIVE_CREATE 4412 4413 inSensitive 4414 4415 the sensitive data 4416 4417 TPM2B_PUBLIC 4418 4419 inPublic 4420 4421 the public template 4422 4423 TPM2B_DATA 4424 4425 outsideInfo 4426 4427 data that will be included in the creation data for this 4428 object to provide permanent, verifiable linkage between 4429 this object and some object owner data 4430 4431 TPML_PCR_SELECTION 4432 4433 creationPCR 4434 4435 PCR that will be used in creation data 4436 4437 Table 20 TPM2_Create Response 4438 Type 4439 4440 Name 4441 4442 Description 4443 4444 TPM_ST 4445 4446 tag 4447 4448 see clause 8 4449 4450 UINT32 4451 4452 responseSize 4453 4454 TPM_RC 4455 4456 responseCode 4457 4458 TPM2B_PRIVATE 4459 4460 outPrivate 4461 4462 the private portion of the object 4463 4464 TPM2B_PUBLIC 4465 4466 outPublic 4467 4468 the public portion of the created object 4469 4470 TPM2B_CREATION_DATA 4471 4472 creationData 4473 4474 contains a TPMS_CREATION_DATA 4475 4476 TPM2B_DIGEST 4477 4478 creationHash 4479 4480 digest of creationData using nameAlg of outPublic 4481 4482 TPMT_TK_CREATION 4483 4484 creationTicket 4485 4486 ticket used by TPM2_CertifyCreation() to validate that 4487 the creation data was produced by the TPM 4488 4489 Page 48 4490 October 31, 2013 4491 4492 Published 4493 Copyright TCG 2006-2013 4494 4495 Family 2.0 4496 Level 00 Revision 00.99 4497 4498 Trusted Platform Module Library 4500 4501 Part 3: Commands 4502 4503 14.1.3 Detailed Actions 4504 1 4505 2 4506 3 4507 4508 #include "InternalRoutines.h" 4509 #include "Object_spt_fp.h" 4510 #include "Create_fp.h" 4511 Error Returns 4512 TPM_RC_ASYMMETRIC 4513 4514 non-duplicable storage key and its parent have different public 4515 params 4516 4517 TPM_RC_ATTRIBUTES 4518 4519 sensitiveDataOrigin is CLEAR when 'sensitive. data' is an Empty 4520 Buffer, or is SET when 'sensitive. data' is not empty; fixedTPM, 4521 fixedParent, or encryptedDuplication attributes are inconsistent 4522 between themselves or with those of the parent object; inconsistent 4523 restricted, decrypt and sign attributes; attempt to inject sensitive data 4524 for an asymmetric key; attempt to create a symmetric cipher key that 4525 is not a decryption key 4526 4527 TPM_RC_HASH 4528 4529 non-duplicable storage key and its parent have different name 4530 algorithm 4531 4532 TPM_RC_KDF 4533 4534 incorrect KDF specified for decrypting keyed hash object 4535 4536 TPM_RC_KEY 4537 4538 invalid key size values in an asymmetric key public area 4539 4540 TPM_RC_KEY_SIZE 4541 4542 key size in public area for symmetric key differs from the size in the 4543 sensitive creation area; may also be returned if the TPM does not 4544 allow the key size to be used for a Storage Key 4545 4546 TPM_RC_RANGE 4547 4548 FOr() an RSA key, the exponent value is not supported. 4549 4550 TPM_RC_SCHEME 4551 4552 inconsistent attributes decrypt, sign, restricted and key's scheme ID; 4553 or hash algorithm is inconsistent with the scheme ID for keyed hash 4554 object 4555 4556 TPM_RC_SIZE 4557 4558 size of public auth policy or sensitive auth value does not match 4559 digest size of the name algorithm sensitive data size for the keyed 4560 hash object is larger than is allowed for the scheme 4561 4562 TPM_RC_SYMMETRIC 4563 4564 a storage key with no symmetric algorithm specified; or non-storage 4565 key with symmetric algorithm different from TPM_ALG_NULL 4566 4567 TPM_RC_TYPE 4568 4569 unknown object type; non-duplicable storage key and its parent have 4570 different types; parentHandle does not reference a restricted 4571 decryption key in the storage hierarchy with both public and sensitive 4572 portion loaded 4573 4574 TPM_RC_VALUE 4575 4576 exponent is not prime or could not find a prime using the provided 4577 parameters for an RSA key; unsupported name algorithm for an ECC 4578 key 4579 4580 TPM_RC_OBJECT_MEMORY 4581 4582 4 4583 5 4584 6 4585 7 4586 8 4587 9 4588 10 4589 11 4590 12 4591 13 4592 4593 Meaning 4594 4595 there is no free slot for the object. This implementation does not 4596 return this error. 4597 4598 TPM_RC 4599 TPM2_Create( 4600 Create_In 4601 Create_Out 4602 4603 *in, 4604 *out 4605 4606 // IN: input parameter list 4607 // OUT: output parameter list 4608 4609 ) 4610 { 4611 TPM_RC 4612 TPMT_SENSITIVE 4613 TPM2B_NAME 4614 4615 Family 2.0 4616 Level 00 Revision 00.99 4617 4618 result = TPM_RC_SUCCESS; 4619 sensitive; 4620 name; 4621 4622 Published 4623 Copyright TCG 2006-2013 4624 4625 Page 49 4626 October 31, 2013 4627 4628 Part 3: Commands 4630 14 4631 15 4632 16 4633 17 4634 18 4635 19 4636 20 4637 21 4638 22 4639 23 4640 24 4641 25 4642 26 4643 27 4644 28 4645 29 4646 30 4647 31 4648 32 4649 33 4650 34 4651 35 4652 36 4653 37 4654 38 4655 39 4656 40 4657 41 4658 42 4659 43 4660 44 4661 45 4662 46 4663 47 4664 48 4665 49 4666 50 4667 51 4668 52 4669 53 4670 54 4671 55 4672 56 4673 57 4674 58 4675 59 4676 60 4677 61 4678 62 4679 63 4680 64 4681 65 4682 66 4683 67 4684 68 4685 69 4686 70 4687 71 4688 72 4689 73 4690 4691 Trusted Platform Module Library 4692 4693 // Input Validation 4694 OBJECT 4695 4696 *parentObject; 4697 4698 parentObject = ObjectGet(in->parentHandle); 4699 // Does parent have the proper attributes? 4700 if(!AreAttributesForParent(parentObject)) 4701 return TPM_RC_TYPE + RC_Create_parentHandle; 4702 // The sensitiveDataOrigin attribute must be consistent with the setting of 4703 // the size of the data object in inSensitive. 4704 if( 4705 (in->inPublic.t.publicArea.objectAttributes.sensitiveDataOrigin == SET) 4706 != (in->inSensitive.t.sensitive.data.t.size == 0)) 4707 // Mismatch between the object attributes and the parameter. 4708 return TPM_RC_ATTRIBUTES + RC_Create_inSensitive; 4709 // Check attributes in input public area. TPM_RC_ASYMMETRIC, TPM_RC_ATTRIBUTES, 4710 // TPM_RC_HASH, TPM_RC_KDF, TPM_RC_SCHEME, TPM_RC_SIZE, TPM_RC_SYMMETRIC, 4711 // or TPM_RC_TYPE error may be returned at this point. 4712 result = PublicAttributesValidation(FALSE, in->parentHandle, 4713 &in->inPublic.t.publicArea); 4714 if(result != TPM_RC_SUCCESS) 4715 return RcSafeAddToResult(result, RC_Create_inPublic); 4716 // Validate the sensitive area values 4717 if( MemoryRemoveTrailingZeros(&in->inSensitive.t.sensitive.userAuth) 4718 > CryptGetHashDigestSize(in->inPublic.t.publicArea.nameAlg)) 4719 return TPM_RC_SIZE + RC_Create_inSensitive; 4720 // Command Output 4721 // Create object crypto data 4722 result = CryptCreateObject(in->parentHandle, &in->inPublic.t.publicArea, 4723 &in->inSensitive.t.sensitive, &sensitive); 4724 if(result != TPM_RC_SUCCESS) 4725 return result; 4726 // Fill in creation data 4727 FillInCreationData(in->parentHandle, in->inPublic.t.publicArea.nameAlg, 4728 &in->creationPCR, &in->outsideInfo, 4729 &out->creationData, &out->creationHash); 4730 // Copy public area from input to output 4731 out->outPublic.t.publicArea = in->inPublic.t.publicArea; 4732 // Compute name from public area 4733 ObjectComputeName(&(out->outPublic.t.publicArea), &name); 4734 // Compute creation ticket 4735 TicketComputeCreation(EntityGetHierarchy(in->parentHandle), &name, 4736 &out->creationHash, &out->creationTicket); 4737 // Prepare output private data from sensitive 4738 SensitiveToPrivate(&sensitive, &name, in->parentHandle, 4739 out->outPublic.t.publicArea.nameAlg, 4740 &out->outPrivate); 4741 return TPM_RC_SUCCESS; 4742 } 4743 4744 Page 50 4745 October 31, 2013 4746 4747 Published 4748 Copyright TCG 2006-2013 4749 4750 Family 2.0 4751 Level 00 Revision 00.99 4752 4753 Trusted Platform Module Library 4755 4756 14.2 4757 4758 Part 3: Commands 4759 4760 TPM2_Load 4761 4762 14.2.1 General Description 4763 This command is used to load objects into the TPM. This command is used when both a TPM2B_PUBLIC 4764 and TPM2B_PRIVATE are to be loaded. If only a TPM2B_PUBLIC is to be loaded, the 4765 TPM2_LoadExternal command is used. 4766 NOTE 1 4767 4768 Loading an object is not the same as restoring a saved object context. 4769 4770 The objects TPMA_OBJECT attributes will be checked according to the rules defined in 4771 TPMA_OBJECT in Part 2 of this specification. 4772 Objects loaded using this command will have a Name. The Name is the concatenation of nameAlg and 4773 the digest of the public area using the nameAlg. 4774 NOTE 2 4775 4776 nameAlg is a parameter in the public area of the inPublic structure. 4777 4778 If inPrivate.size is zero, the load will fail. 4779 After inPrivate.buffer is decrypted using the symmetric key of the parent, the integrity value shall be 4780 checked before the sensitive area is used, or unmarshaled. 4781 NOTE 3 4782 4783 Checking the integrity before the data is used prevents attacks o n the sensitive area by fuzzing the 4784 data and looking at the differences in the response codes. 4785 4786 The command returns a handle for the loaded object and the Name that the TPM computed for 4787 inPublic.public (that is, the digest of the TPMT_PUBLIC structure in inPublic). 4788 NOTE 4 4789 4790 The TPM-computed Name is provided as a convenience to the caller for those cases where the 4791 caller does not implement the hash algorithms specified in the nameAlg of the object. 4792 4793 NOTE 5 4794 4795 The returned handle is associated with the object until the object is flushed (TPM2_FlushContext) or 4796 until the next TPM2_Startup. 4797 4798 For all objects, the size of the key in the sensitive area shall be consistent with the key size indicated in 4799 the public area or the TPM shall return TPM_RC_KEY_SIZE. 4800 Before use, a loaded object shall be checked to validate that the public and sensitive portions are 4801 properly linked, cryptographically. Use of an object includes use in any policy command. If the parts of the 4802 object are not properly linked, the TPM shall return TPM_RC_BINDING. 4803 EXAMPLE 1 4804 4805 For a symmetric object, the unique value in the public area shall be the digest of the sensitive key 4806 and the obfuscation value. 4807 4808 EXAMPLE 2 4809 4810 For a two-prime RSA key, the remainder when dividing the public modulus by the private key shall 4811 be zero and it shall be possible to form a private exponent from the two prime factors of the public 4812 modulus. 4813 4814 EXAMPLE 3 4815 4816 For an ECC key, the public point shall be f(x) where x is the private key. 4817 4818 Family 2.0 4819 Level 00 Revision 00.99 4820 4821 Published 4822 Copyright TCG 2006-2013 4823 4824 Page 51 4825 October 31, 2013 4826 4827 Part 3: Commands 4829 4830 Trusted Platform Module Library 4831 4832 14.2.2 Command and Response 4833 Table 21 TPM2_Load Command 4834 Type 4835 4836 Name 4837 4838 Description 4839 4840 TPMI_ST_COMMAND_TAG 4841 4842 tag 4843 4844 UINT32 4845 4846 commandSize 4847 4848 TPM_CC 4849 4850 commandCode 4851 4852 TPM_CC_Load 4853 4854 TPMI_DH_OBJECT 4855 4856 @parentHandle 4857 4858 TPM handle of parent key; shall not be a reserved 4859 handle 4860 Auth Index: 1 4861 Auth Role: USER 4862 4863 TPM2B_PRIVATE 4864 4865 inPrivate 4866 4867 the private portion of the object 4868 4869 TPM2B_PUBLIC 4870 4871 inPublic 4872 4873 the public portion of the object 4874 4875 Table 22 TPM2_Load Response 4876 Type 4877 4878 Name 4879 4880 Description 4881 4882 TPM_ST 4883 4884 tag 4885 4886 see clause 8 4887 4888 UINT32 4889 4890 responseSize 4891 4892 TPM_RC 4893 4894 responseCode 4895 4896 TPM_HANDLE 4897 4898 objectHandle 4899 4900 handle for the loaded object 4901 4902 TPM2B_NAME 4903 4904 name 4905 4906 Name of the loaded object 4907 4908 Page 52 4909 October 31, 2013 4910 4911 Published 4912 Copyright TCG 2006-2013 4913 4914 Family 2.0 4915 Level 00 Revision 00.99 4916 4917 Trusted Platform Module Library 4919 4920 Part 3: Commands 4921 4922 14.2.3 Detailed Actions 4923 1 4924 2 4925 3 4926 4927 #include "InternalRoutines.h" 4928 #include "Load_fp.h" 4929 #include "Object_spt_fp.h" 4930 Error Returns 4931 TPM_RC_ASYMMETRIC 4932 4933 storage key with different asymmetric type than parent 4934 4935 TPM_RC_ATTRIBUTES 4936 4937 inPulblic attributes are not allowed with selected parent 4938 4939 TPM_RC_BINDING 4940 4941 inPrivate and inPublic are not cryptographically bound 4942 4943 TPM_RC_HASH 4944 4945 incorrect hash selection for signing key 4946 4947 TPM_RC_INTEGRITY 4948 4949 HMAC on inPrivate was not valid 4950 4951 TPM_RC_KDF 4952 4953 KDF selection not allowed 4954 4955 TPM_RC_KEY 4956 4957 the size of the object's unique field is not consistent with the indicated 4958 size in the object's parameters 4959 4960 TPM_RC_OBJECT_MEMORY 4961 4962 no available object slot 4963 4964 TPM_RC_SCHEME 4965 4966 the signing scheme is not valid for the key 4967 4968 TPM_RC_SENSITIVE 4969 4970 the inPrivate did not unmarshal correctly 4971 4972 TPM_RC_SIZE 4973 4974 inPrivate missing, or authPolicy size for inPublic or is not valid 4975 4976 TPM_RC_SYMMETRIC 4977 4978 symmetric algorithm not provided when required 4979 4980 TPM_RC_TYPE 4981 4982 parentHandle is not a storage key, or the object to load is a storage 4983 key but its parameters do not match the parameters of the parent. 4984 4985 TPM_RC_VALUE 4986 4 4987 5 4988 6 4989 7 4990 8 4991 9 4992 10 4993 11 4994 12 4995 13 4996 14 4997 15 4998 16 4999 17 5000 18 5001 19 5002 20 5003 21 5004 22 5005 23 5006 24 5007 25 5008 26 5009 27 5010 28 5011 29 5012 30 5013 5014 Meaning 5015 5016 decryption failure 5017 5018 TPM_RC 5019 TPM2_Load( 5020 Load_In *in, 5021 Load_Out *out 5022 5023 // IN: input parameter list 5024 // OUT: output parameter list 5025 5026 ) 5027 { 5028 TPM_RC 5029 TPMT_SENSITIVE 5030 TPMI_RH_HIERARCHY 5031 OBJECT 5032 BOOL 5033 5034 result = TPM_RC_SUCCESS; 5035 sensitive; 5036 hierarchy; 5037 *parentObject = NULL; 5038 skipChecks = FALSE; 5039 5040 // Input Validation 5041 if(in->inPrivate.t.size == 0) 5042 return TPM_RC_SIZE + RC_Load_inPrivate; 5043 parentObject = ObjectGet(in->parentHandle); 5044 // Is the object that is being used as the parent actually a parent. 5045 if(!AreAttributesForParent(parentObject)) 5046 return TPM_RC_TYPE + RC_Load_parentHandle; 5047 // If the parent is fixedTPM, then the attributes of the object 5048 // are either "correct by construction" or were validated 5049 // when the object was imported. If they pass the integrity 5050 // check, then the values are valid 5051 if(parentObject->publicArea.objectAttributes.fixedTPM) 5052 skipChecks = TRUE; 5053 5054 Family 2.0 5055 Level 00 Revision 00.99 5056 5057 Published 5058 Copyright TCG 2006-2013 5059 5060 Page 53 5061 October 31, 2013 5062 5063 Part 3: Commands 5065 31 5066 32 5067 33 5068 34 5069 35 5070 36 5071 37 5072 38 5073 39 5074 40 5075 41 5076 42 5077 43 5078 44 5079 45 5080 46 5081 47 5082 48 5083 49 5084 50 5085 51 5086 52 5087 53 5088 54 5089 55 5090 56 5091 57 5092 58 5093 59 5094 60 5095 61 5096 62 5097 63 5098 64 5099 65 5100 66 5101 67 5102 68 5103 69 5104 70 5105 71 5106 72 5107 73 5108 74 5109 75 5110 76 5111 5112 Trusted Platform Module Library 5113 5114 else 5115 { 5116 // If parent doesn't have fixedTPM SET, then this can't have 5117 // fixedTPM SET. 5118 if(in->inPublic.t.publicArea.objectAttributes.fixedTPM == SET) 5119 return TPM_RC_ATTRIBUTES + RC_Load_inPublic; 5120 // Perform self check on input public area. A TPM_RC_SIZE, TPM_RC_SCHEME, 5121 // TPM_RC_VALUE, TPM_RC_SYMMETRIC, TPM_RC_TYPE, TPM_RC_HASH, 5122 // TPM_RC_ASYMMETRIC, TPM_RC_ATTRIBUTES or TPM_RC_KDF error may be returned 5123 // at this point 5124 result = PublicAttributesValidation(TRUE, in->parentHandle, 5125 &in->inPublic.t.publicArea); 5126 if(result != TPM_RC_SUCCESS) 5127 return RcSafeAddToResult(result, RC_Load_inPublic); 5128 } 5129 // Compute the name of object 5130 ObjectComputeName(&in->inPublic.t.publicArea, &out->name); 5131 // Retrieve sensitive data. PrivateToSensitive() may return TPM_RC_INTEGRITY or 5132 // TPM_RC_SENSITIVE 5133 // errors may be returned at this point 5134 result = PrivateToSensitive(&in->inPrivate, &out->name, in->parentHandle, 5135 in->inPublic.t.publicArea.nameAlg, 5136 &sensitive); 5137 if(result != TPM_RC_SUCCESS) 5138 return RcSafeAddToResult(result, RC_Load_inPrivate); 5139 // Internal Data Update 5140 // Get hierarchy of parent 5141 hierarchy = ObjectGetHierarchy(in->parentHandle); 5142 // Create internal object. A lot of different errors may be returned by this 5143 // loading operation as it will do several validations, including the public 5144 // binding check 5145 result = ObjectLoad(hierarchy, &in->inPublic.t.publicArea, &sensitive, 5146 &out->name, in->parentHandle, skipChecks, 5147 &out->objectHandle); 5148 if(result != TPM_RC_SUCCESS) 5149 return result; 5150 return TPM_RC_SUCCESS; 5151 } 5152 5153 Page 54 5154 October 31, 2013 5155 5156 Published 5157 Copyright TCG 2006-2013 5158 5159 Family 2.0 5160 Level 00 Revision 00.99 5161 5162 Trusted Platform Module Library 5164 5165 14.3 5166 5167 Part 3: Commands 5168 5169 TPM2_LoadExternal 5170 5171 14.3.1 General Description 5172 This command is used to load an object that is not a Protected Object into the TPM. The command allows 5173 loading of a public area or both a public and sensitive area. 5174 NOTE 1 5175 5176 Typical use for loading a public area is to allow the TPM to validate an asymmetric signature. 5177 Typical use for loading both a public and sensitive area is to allow the TPM to be used as a crypto 5178 accelerator. 5179 5180 Load of a public external object area allows the object be associated with a hierarchy so that the correct 5181 algorithms may be used when creating tickets. The hierarchy parameter provides this association. If the 5182 public and sensitive portions of the object are loaded, hierarchy is required to be TPM_RH_NULL. 5183 NOTE 2 5184 5185 If both the public and private portions of an object are loaded, the object is not allowed to appear to 5186 be part of a hierarchy. 5187 5188 The objects TPMA_OBJECT attributes will be checked according to the rules defined in 5189 TPMA_OBJECT in Part 2. In particular, fixedTPM, fixedParent, and restricted shall be CLEAR if 5190 inPrivate is not the Empty Buffer. 5191 NOTE 3 5192 5193 The duplication status of a public key needs to be able to be the same as the full key which may be 5194 resident on a different TPM. If both the public and private parts of the key are loaded, then it is not 5195 possible for the key to be either fixedTPM or fixedParent, since, its private area would not be 5196 available in the clear to load. 5197 5198 Objects loaded using this command will have a Name. The Name is the nameAlg of the object 5199 concatenated with the digest of the public area using the nameAlg. The Qualified Name for the object will 5200 be the same as its Name. The TPM will validate that the authPolicy is either the size of the digest 5201 produced by nameAlg or the Empty Buffer. 5202 NOTE 4 5203 5204 If nameAlg is TPM_ALG_NULL, then the Name is the Empty Buffer. When the authorization value for 5205 an object with no Name is computed, no Name value is included in the HMAC. To ensure that these 5206 unnamed entities are not substituted, they should have an authValue that is statistically unique. 5207 5208 NOTE 5 5209 5210 The digest size for TPM_ALG_NULL is zero. 5211 5212 If the nameAlg is TPM_ALG_NULL, the TPM shall not verify the cryptographic binding between the public 5213 and sensitive areas, but the TPM will validate that the size of the key in the sensitive area is consistent 5214 with the size indicated in the public area. If it is not, the TPM shall return TPM_RC_KEY_SIZE. 5215 NOTE 6 5216 5217 For an ECC object, the TPM will verify that the public key is on the curve of the key before the public 5218 area is used. 5219 5220 If nameAlg is not TPM_ALG_NULL, then the same consistency checks between inPublic and inPrivate 5221 are made as for TPM2_Load(). 5222 NOTE 7 5223 5224 Consistency checks are necessary because an object with a Name needs to have the public and 5225 sensitive portions cryptographically bound so that an attacker cannot mix pubic and sensitive areas. 5226 5227 The command returns a handle for the loaded object and the Name that the TPM computed for 5228 inPublic.public (that is, the TPMT_PUBLIC structure in inPublic). 5229 NOTE 8 5230 5231 The TPM-computed Name is provided as a convenience to the caller for those cases where the 5232 caller does not implement the hash algorithm specified in the nameAlg of the object. 5233 5234 Family 2.0 5235 Level 00 Revision 00.99 5236 5237 Published 5238 Copyright TCG 2006-2013 5239 5240 Page 55 5241 October 31, 2013 5242 5243 Part 3: Commands 5245 5246 Trusted Platform Module Library 5247 5248 The hierarchy parameter associates the external object with a hierarchy. External objects are flushed 5249 when their associated hierarchy is disabled. If hierarchy is TPM_RH_NULL, the object is part of no 5250 hierarchy, and there is no implicit flush. 5251 If hierarchy is TPM_RH_NULL or nameAlg is TPM_ALG_NULL, a ticket produced using the object shall 5252 be a NULL Ticket. 5253 EXAMPLE 5254 5255 If a key is loaded with hierarchy set to TPM_RH_NULL, then TPM2_VerifySignature() will produce a 5256 NULL Ticket of the required type. 5257 5258 External objects are Temporary Objects. The saved external object contexts shall be invalidated at the 5259 next TPM Reset. 5260 5261 Page 56 5262 October 31, 2013 5263 5264 Published 5265 Copyright TCG 2006-2013 5266 5267 Family 2.0 5268 Level 00 Revision 00.99 5269 5270 Trusted Platform Module Library 5272 5273 Part 3: Commands 5274 5275 14.3.2 Command and Response 5276 Table 23 TPM2_LoadExternal Command 5277 Type 5278 5279 Name 5280 5281 Description 5282 5283 TPMI_ST_COMMAND_TAG 5284 5285 tag 5286 5287 UINT32 5288 5289 commandSize 5290 5291 TPM_CC 5292 5293 commandCode 5294 5295 TPM_CC_LoadExternal 5296 5297 TPM2B_SENSITIVE 5298 5299 inPrivate 5300 5301 the sensitive portion of the object (optional) 5302 5303 TPM2B_PUBLIC+ 5304 5305 inPublic 5306 5307 the public portion of the object 5308 5309 TPMI_RH_HIERARCHY+ 5310 5311 hierarchy 5312 5313 hierarchy with which the object area is associated 5314 5315 Table 24 TPM2_LoadExternal Response 5316 Type 5317 5318 Name 5319 5320 Description 5321 5322 TPM_ST 5323 5324 tag 5325 5326 see clause 8 5327 5328 UINT32 5329 5330 responseSize 5331 5332 TPM_RC 5333 5334 responseCode 5335 5336 TPM_HANDLE 5337 5338 objectHandle 5339 5340 handle for the loaded object 5341 5342 TPM2B_NAME 5343 5344 name 5345 5346 name of the loaded object 5347 5348 Family 2.0 5349 Level 00 Revision 00.99 5350 5351 Published 5352 Copyright TCG 2006-2013 5353 5354 Page 57 5355 October 31, 2013 5356 5357 Part 3: Commands 5359 5360 Trusted Platform Module Library 5361 5362 14.3.3 Detailed Actions 5363 1 5364 2 5365 3 5366 5367 #include "InternalRoutines.h" 5368 #include "LoadExternal_fp.h" 5369 #include "Object_spt_fp.h" 5370 Error Returns 5371 TPM_RC_ATTRIBUTES 5372 5373 'fixedParent" and fixedTPM must be CLEAR on on an external key if 5374 both public and sensitive portions are loaded 5375 5376 TPM_RC_BINDING 5377 5378 the inPublic and inPrivate structures are not cryptographically bound. 5379 5380 TPM_RC_HASH 5381 5382 incorrect hash selection for signing key 5383 5384 TPM_RC_HIERARCHY 5385 5386 hierarchy is turned off, or only NULL hierarchy is allowed when 5387 loading public and private parts of an object 5388 5389 TPM_RC_KDF 5390 5391 incorrect KDF selection for decrypting keyedHash object 5392 5393 TPM_RC_KEY 5394 5395 the size of the object's unique field is not consistent with the indicated 5396 size in the object's parameters 5397 5398 TPM_RC_OBJECT_MEMORY 5399 5400 if there is no free slot for an object 5401 5402 TPM_RC_SCHEME 5403 5404 the signing scheme is not valid for the key 5405 5406 TPM_RC_SIZE 5407 5408 authPolicy is not zero and is not the size of a digest produced by the 5409 object's nameAlg TPM_RH_NULL hierarchy 5410 5411 TPM_RC_SYMMETRIC 5412 5413 symmetric algorithm not provided when required 5414 5415 TPM_RC_TYPE 5416 4 5417 5 5418 6 5419 7 5420 8 5421 9 5422 10 5423 11 5424 12 5425 13 5426 14 5427 15 5428 16 5429 17 5430 18 5431 19 5432 20 5433 21 5434 22 5435 23 5436 24 5437 25 5438 26 5439 27 5440 28 5441 29 5442 30 5443 31 5444 32 5445 33 5446 5447 Meaning 5448 5449 inPublic and inPrivate are not the same type 5450 5451 TPM_RC 5452 TPM2_LoadExternal( 5453 LoadExternal_In 5454 LoadExternal_Out 5455 5456 *in, 5457 *out 5458 5459 // IN: input parameter list 5460 // OUT: output parameter list 5461 5462 TPM_RC 5463 TPMT_SENSITIVE 5464 BOOL 5465 5466 result; 5467 *sensitive; 5468 skipChecks; 5469 5470 ) 5471 { 5472 5473 // Input Validation 5474 // If the target hierarchy is turned off, the object can not be loaded. 5475 if(!HierarchyIsEnabled(in->hierarchy)) 5476 return TPM_RC_HIERARCHY + RC_LoadExternal_hierarchy; 5477 // the size of authPolicy is either 0 or the digest size of nameAlg 5478 if(in->inPublic.t.publicArea.authPolicy.t.size != 0 5479 && in->inPublic.t.publicArea.authPolicy.t.size != 5480 CryptGetHashDigestSize(in->inPublic.t.publicArea.nameAlg)) 5481 return TPM_RC_SIZE + RC_LoadExternal_inPublic; 5482 // For loading an object with both public and sensitive 5483 if(in->inPrivate.t.size != 0) 5484 { 5485 // An external object can only be loaded at TPM_RH_NULL hierarchy 5486 if(in->hierarchy != TPM_RH_NULL) 5487 return TPM_RC_HIERARCHY + RC_LoadExternal_hierarchy; 5488 // An external object with a sensitive area must have fixedTPM == CLEAR 5489 // fixedParent == CLEAR, and must have restrict CLEAR so that it does not 5490 5491 Page 58 5492 October 31, 2013 5493 5494 Published 5495 Copyright TCG 2006-2013 5496 5497 Family 2.0 5498 Level 00 Revision 00.99 5499 5500 Trusted Platform Module Library 5502 34 5503 35 5504 36 5505 37 5506 38 5507 39 5508 40 5509 41 5510 42 5511 43 5512 44 5513 45 5514 46 5515 47 5516 48 5517 49 5518 50 5519 51 5520 52 5521 53 5522 54 5523 55 5524 56 5525 57 5526 58 5527 59 5528 60 5529 61 5530 62 5531 63 5532 64 5533 65 5534 5535 Part 3: Commands 5536 5537 // appear to be a key that was created by this TPM. 5538 if( 5539 in->inPublic.t.publicArea.objectAttributes.fixedTPM != CLEAR 5540 || in->inPublic.t.publicArea.objectAttributes.fixedParent != CLEAR 5541 || in->inPublic.t.publicArea.objectAttributes.restricted != CLEAR 5542 ) 5543 return TPM_RC_ATTRIBUTES + RC_LoadExternal_inPublic; 5544 } 5545 // Validate the scheme parameters 5546 result = SchemeChecks(TRUE, TPM_RH_NULL, &in->inPublic.t.publicArea); 5547 if(result != TPM_RC_SUCCESS) 5548 return RcSafeAddToResult(result, RC_LoadExternal_inPublic); 5549 // Internal Data Update 5550 // Need the name to compute the qualified name 5551 ObjectComputeName(&in->inPublic.t.publicArea, &out->name); 5552 skipChecks = (in->inPublic.t.publicArea.nameAlg == TPM_ALG_NULL); 5553 // If a sensitive area was provided, load it 5554 if(in->inPrivate.t.size != 0) 5555 sensitive = &in->inPrivate.t.sensitiveArea; 5556 else 5557 sensitive = NULL; 5558 // Create external object. A TPM_RC_BINDING, TPM_RC_KEY, TPM_RC_OBJECT_MEMORY 5559 // or TPM_RC_TYPE error may be returned by ObjectLoad() 5560 result = ObjectLoad(in->hierarchy, &in->inPublic.t.publicArea, 5561 sensitive, &out->name, TPM_RH_NULL, skipChecks, 5562 &out->objectHandle); 5563 return result; 5564 } 5565 5566 Family 2.0 5567 Level 00 Revision 00.99 5568 5569 Published 5570 Copyright TCG 2006-2013 5571 5572 Page 59 5573 October 31, 2013 5574 5575 Part 3: Commands 5577 5578 14.4 5579 5580 Trusted Platform Module Library 5581 5582 TPM2_ReadPublic 5583 5584 14.4.1 General Description 5585 This command allows access to the public area of a loaded object. 5586 Use of the objectHandle does not require authorization. 5587 NOTE 5588 5589 Since the caller is not likely to know the public area of the object associated with objectHandle, it 5590 would not be possible to include the Name associated with objectHandle in the cpHash computation. 5591 5592 If objectHandle references a sequence object, the TPM shall return TPM_RC_SEQUENCE. 5593 5594 Page 60 5595 October 31, 2013 5596 5597 Published 5598 Copyright TCG 2006-2013 5599 5600 Family 2.0 5601 Level 00 Revision 00.99 5602 5603 Trusted Platform Module Library 5605 5606 Part 3: Commands 5607 5608 14.4.2 Command and Response 5609 Table 25 TPM2_ReadPublic Command 5610 Type 5611 5612 Name 5613 5614 Description 5615 5616 TPMI_ST_COMMAND_TAG 5617 5618 tag 5619 5620 UINT32 5621 5622 commandSize 5623 5624 TPM_CC 5625 5626 commandCode 5627 5628 TPM_CC_ReadPublic 5629 5630 TPMI_DH_OBJECT 5631 5632 objectHandle 5633 5634 TPM handle of an object 5635 Auth Index: None 5636 5637 Table 26 TPM2_ReadPublic Response 5638 Type 5639 5640 Name 5641 5642 Description 5643 5644 TPM_ST 5645 5646 tag 5647 5648 see clause 8 5649 5650 UINT32 5651 5652 responseSize 5653 5654 TPM_RC 5655 5656 responseCode 5657 5658 TPM2B_PUBLIC 5659 5660 outPublic 5661 5662 structure containing the public area of an object 5663 5664 TPM2B_NAME 5665 5666 name 5667 5668 name of the object 5669 5670 TPM2B_NAME 5671 5672 qualifiedName 5673 5674 the Qualified Name of the object 5675 5676 Family 2.0 5677 Level 00 Revision 00.99 5678 5679 Published 5680 Copyright TCG 2006-2013 5681 5682 Page 61 5683 October 31, 2013 5684 5685 Part 3: Commands 5687 5688 Trusted Platform Module Library 5689 5690 14.4.3 Detailed Actions 5691 1 5692 2 5693 5694 #include "InternalRoutines.h" 5695 #include "ReadPublic_fp.h" 5696 Error Returns 5697 TPM_RC_SEQUENCE 5698 5699 3 5700 4 5701 5 5702 6 5703 7 5704 8 5705 9 5706 10 5707 11 5708 12 5709 13 5710 14 5711 15 5712 16 5713 17 5714 18 5715 19 5716 20 5717 21 5718 22 5719 23 5720 24 5721 25 5722 26 5723 27 5724 28 5725 29 5726 30 5727 31 5728 32 5729 33 5730 34 5731 35 5732 36 5733 5734 Meaning 5735 can not read the public area of a sequence object 5736 5737 TPM_RC 5738 TPM2_ReadPublic( 5739 ReadPublic_In 5740 ReadPublic_Out 5741 5742 *in, 5743 *out 5744 5745 // IN: input parameter list 5746 // OUT: output parameter list 5747 5748 OBJECT 5749 5750 *object; 5751 5752 ) 5753 { 5754 // Input Validation 5755 // Get loaded object pointer 5756 object = ObjectGet(in->objectHandle); 5757 // Can not read public area of a sequence object 5758 if(ObjectIsSequence(object)) 5759 return TPM_RC_SEQUENCE; 5760 // Command Output 5761 // Compute size of public area in canonical form 5762 out->outPublic.t.size = TPMT_PUBLIC_Marshal(&object->publicArea, NULL, NULL); 5763 // Copy public area to output 5764 out->outPublic.t.publicArea = object->publicArea; 5765 // Copy name to output 5766 out->name.t.size = ObjectGetName(in->objectHandle, &out->name.t.name); 5767 // Copy qualified name to output 5768 ObjectGetQualifiedName(in->objectHandle, &out->qualifiedName); 5769 return TPM_RC_SUCCESS; 5770 } 5771 5772 Page 62 5773 October 31, 2013 5774 5775 Published 5776 Copyright TCG 2006-2013 5777 5778 Family 2.0 5779 Level 00 Revision 00.99 5780 5781 Trusted Platform Module Library 5783 5784 14.5 5785 5786 Part 3: Commands 5787 5788 TPM2_ActivateCredential 5789 5790 14.5.1 General Description 5791 This command enables the association of a credential with an object in a way that ensures that the TPM 5792 has validated the parameters of the credentialed object. 5793 If both the public and private portions of activateHandle and keyHandle are not loaded, then the TPM 5794 shall return TPM_RC_AUTH_UNAVAILABLE. 5795 If keyHandle is not a Storage Key, then the TPM shall return TPM_RC_TYPE. 5796 Authorization for activateHandle requires the ADMIN role. 5797 The key associated with keyHandle is used to recover a seed from secret, which is the encrypted seed. 5798 The Name of the object associated with activateHandle and the recovered seed are used in a KDF to 5799 recover the symmetric key. The recovered seed (but not the Name) is used is used in a KDF to recover 5800 the HMAC key. 5801 The HMAC is used to validate that the credentialBlob is associated with activateHandle and that the data 5802 in credentialBlob has not been modified. The linkage to the object associated with activateHandle is 5803 achieved by including the Name in the HMAC calculation. 5804 If the integrity checks succeed, credentialBlob is decrypted and returned as certInfo. 5805 5806 Family 2.0 5807 Level 00 Revision 00.99 5808 5809 Published 5810 Copyright TCG 2006-2013 5811 5812 Page 63 5813 October 31, 2013 5814 5815 Part 3: Commands 5817 5818 Trusted Platform Module Library 5819 5820 14.5.2 Command and Response 5821 Table 27 TPM2_ActivateCredential Command 5822 Type 5823 5824 Name 5825 5826 TPMI_ST_COMMAND_TAG 5827 5828 tag 5829 5830 UINT32 5831 5832 commandSize 5833 5834 TPM_CC 5835 5836 commandCode 5837 5838 Description 5839 5840 TPM_CC_ActivateCredential 5841 5842 TPMI_DH_OBJECT 5843 5844 @activateHandle 5845 5846 handle of the object associated with certificate in 5847 credentialBlob 5848 Auth Index: 1 5849 Auth Role: ADMIN 5850 5851 TPMI_DH_OBJECT 5852 5853 @keyHandle 5854 5855 loaded key used to decrypt the TPMS_SENSITIVE in 5856 credentialBlob 5857 Auth Index: 2 5858 Auth Role: USER 5859 5860 TPM2B_ID_OBJECT 5861 5862 credentialBlob 5863 5864 the credential 5865 5866 TPM2B_ENCRYPTED_SECRET 5867 5868 secret 5869 5870 keyHandle algorithm-dependent encrypted seed that 5871 protects credentialBlob 5872 5873 Table 28 TPM2_ActivateCredential Response 5874 Type 5875 5876 Name 5877 5878 Description 5879 5880 TPM_ST 5881 5882 tag 5883 5884 see clause 8 5885 5886 UINT32 5887 5888 responseSize 5889 5890 TPM_RC 5891 5892 responseCode 5893 5894 TPM2B_DIGEST 5895 5896 certInfo 5897 5898 Page 64 5899 October 31, 2013 5900 5901 the decrypted certificate information 5902 the data should be no larger than the size of the digest 5903 of the nameAlg associated with keyHandle 5904 5905 Published 5906 Copyright TCG 2006-2013 5907 5908 Family 2.0 5909 Level 00 Revision 00.99 5910 5911 Trusted Platform Module Library 5913 5914 Part 3: Commands 5915 5916 14.5.3 Detailed Actions 5917 1 5918 2 5919 3 5920 5921 #include "InternalRoutines.h" 5922 #include "ActivateCredential_fp.h" 5923 #include "Object_spt_fp.h" 5924 Error Returns 5925 TPM_RC_ATTRIBUTES 5926 5927 keyHandle does not reference a decryption key 5928 5929 TPM_RC_ECC_POINT 5930 5931 secret is invalid (when keyHandle is an ECC key) 5932 5933 TPM_RC_INSUFFICIENT 5934 5935 secret is invalid (when keyHandle is an ECC key) 5936 5937 TPM_RC_INTEGRITY 5938 5939 credentialBlob fails integrity test 5940 5941 TPM_RC_NO_RESULT 5942 5943 secret is invalid (when keyHandle is an ECC key) 5944 5945 TPM_RC_SIZE 5946 5947 secret size is invalid or the credentialBlob does not unmarshal 5948 correctly 5949 5950 TPM_RC_TYPE 5951 5952 keyHandle does not reference an asymmetric key. 5953 5954 TPM_RC_VALUE 5955 4 5956 5 5957 6 5958 7 5959 8 5960 9 5961 10 5962 11 5963 12 5964 13 5965 14 5966 15 5967 16 5968 17 5969 18 5970 19 5971 20 5972 21 5973 22 5974 23 5975 24 5976 25 5977 26 5978 27 5979 28 5980 29 5981 30 5982 31 5983 32 5984 33 5985 34 5986 35 5987 36 5988 37 5989 38 5990 39 5991 40 5992 41 5993 5994 Meaning 5995 5996 secret is invalid (when keyHandle is an RSA key) 5997 5998 TPM_RC 5999 TPM2_ActivateCredential( 6000 ActivateCredential_In 6001 ActivateCredential_Out 6002 6003 *in, 6004 *out 6005 6006 // IN: input parameter list 6007 // OUT: output parameter list 6008 6009 TPM_RC 6010 OBJECT 6011 OBJECT 6012 // credential 6013 TPM2B_DATA 6014 6015 result = TPM_RC_SUCCESS; 6016 *object; 6017 // decrypt key 6018 *activateObject;// key associated with 6019 6020 ) 6021 { 6022 6023 data; 6024 6025 // credential data 6026 6027 // Input Validation 6028 // Get decrypt key pointer 6029 object = ObjectGet(in->keyHandle); 6030 // Get certificated object pointer 6031 activateObject = ObjectGet(in->activateHandle); 6032 // input decrypt key must be an asymmetric, restricted decryption key 6033 if( 6034 !CryptIsAsymAlgorithm(object->publicArea.type) 6035 || object->publicArea.objectAttributes.decrypt == CLEAR 6036 || object->publicArea.objectAttributes.restricted == CLEAR) 6037 return TPM_RC_TYPE + RC_ActivateCredential_keyHandle; 6038 // Command output 6039 // Decrypt input credential data via asymmetric decryption. A 6040 // TPM_RC_VALUE, TPM_RC_KEY or unmarshal errors may be returned at this 6041 // point 6042 result = CryptSecretDecrypt(in->keyHandle, NULL, 6043 "IDENTITY", &in->secret, &data); 6044 if(result != TPM_RC_SUCCESS) 6045 { 6046 if(result == TPM_RC_KEY) 6047 return TPM_RC_FAILURE; 6048 6049 Family 2.0 6050 Level 00 Revision 00.99 6051 6052 Published 6053 Copyright TCG 2006-2013 6054 6055 Page 65 6056 October 31, 2013 6057 6058 Part 3: Commands 6060 42 6061 43 6062 44 6063 45 6064 46 6065 47 6066 48 6067 49 6068 50 6069 51 6070 52 6071 53 6072 54 6073 55 6074 56 6075 6076 Trusted Platform Module Library 6077 6078 return RcSafeAddToResult(result, RC_ActivateCredential_secret); 6079 } 6080 // Retrieve secret data. A TPM_RC_INTEGRITY error or unmarshal 6081 // errors may be returned at this point 6082 result = CredentialToSecret(&in->credentialBlob, 6083 &activateObject->name, 6084 (TPM2B_SEED *) &data, 6085 in->keyHandle, 6086 &out->certInfo); 6087 if(result != TPM_RC_SUCCESS) 6088 return RcSafeAddToResult(result,RC_ActivateCredential_credentialBlob); 6089 return TPM_RC_SUCCESS; 6090 } 6091 6092 Page 66 6093 October 31, 2013 6094 6095 Published 6096 Copyright TCG 2006-2013 6097 6098 Family 2.0 6099 Level 00 Revision 00.99 6100 6101 Trusted Platform Module Library 6103 6104 14.6 6105 6106 Part 3: Commands 6107 6108 TPM2_MakeCredential 6109 6110 14.6.1 General Description 6111 This command allows the TPM to perform the actions required of a Certificate Authority (CA) in creating a 6112 TPM2B_ID_OBJECT containing an activation credential. 6113 The TPM will produce a TPM_ID_OBJECT according to the methods in Credential Protection in Part 1. 6114 The loaded public area referenced by handle is required to be the public area of a Storage key, 6115 otherwise, the credential cannot be properly sealed. 6116 This command does not use any TPM secrets nor does it require authorization. It is a convenience 6117 function, using the TPM to perform cryptographic calculations that could be done externally. 6118 6119 Family 2.0 6120 Level 00 Revision 00.99 6121 6122 Published 6123 Copyright TCG 2006-2013 6124 6125 Page 67 6126 October 31, 2013 6127 6128 Part 3: Commands 6130 6131 Trusted Platform Module Library 6132 6133 14.6.2 Command and Response 6134 Table 29 TPM2_MakeCredential Command 6135 Type 6136 6137 Name 6138 6139 Description 6140 6141 TPMI_ST_COMMAND_TAG 6142 6143 tag 6144 6145 UINT32 6146 6147 commandSize 6148 6149 TPM_CC 6150 6151 commandCode 6152 6153 TPM_CC_MakeCredential 6154 6155 TPMI_DH_OBJECT 6156 6157 handle 6158 6159 loaded public area, used to encrypt the sensitive area 6160 containing the credential key 6161 Auth Index: None 6162 6163 TPM2B_DIGEST 6164 6165 credential 6166 6167 the credential information 6168 6169 TPM2B_NAME 6170 6171 objectName 6172 6173 Name of the object to which the credential applies 6174 6175 Table 30 TPM2_MakeCredential Response 6176 Type 6177 6178 Name 6179 6180 Description 6181 6182 TPM_ST 6183 6184 tag 6185 6186 see clause 8 6187 6188 UINT32 6189 6190 responseSize 6191 6192 TPM_RC 6193 6194 responseCode 6195 6196 TPM2B_ID_OBJECT 6197 6198 credentialBlob 6199 6200 TPM2B_ENCRYPTED_SECRET 6201 6202 secret 6203 6204 Page 68 6205 October 31, 2013 6206 6207 the credential 6208 handle algorithm-dependent data that wraps the key 6209 that encrypts credentialBlob 6210 6211 Published 6212 Copyright TCG 2006-2013 6213 6214 Family 2.0 6215 Level 00 Revision 00.99 6216 6217 Trusted Platform Module Library 6219 6220 Part 3: Commands 6221 6222 14.6.3 Detailed Actions 6223 1 6224 2 6225 3 6226 6227 #include "InternalRoutines.h" 6228 #include "MakeCredential_fp.h" 6229 #include "Object_spt_fp.h" 6230 Error Returns 6231 TPM_RC_KEY 6232 6233 handle referenced an ECC key that has a unique field that is not a 6234 point on the curve of the key 6235 6236 TPM_RC_SIZE 6237 6238 credential is larger than the digest size of Name algorithm of handle 6239 6240 TPM_RC_TYPE 6241 4 6242 5 6243 6 6244 7 6245 8 6246 9 6247 10 6248 11 6249 12 6250 13 6251 14 6252 15 6253 16 6254 17 6255 18 6256 19 6257 20 6258 21 6259 22 6260 23 6261 24 6262 25 6263 26 6264 27 6265 28 6266 29 6267 30 6268 31 6269 32 6270 33 6271 34 6272 35 6273 36 6274 37 6275 38 6276 39 6277 40 6278 41 6279 42 6280 43 6281 44 6282 45 6283 46 6284 47 6285 6286 Meaning 6287 6288 handle does not reference an asymmetric decryption key 6289 6290 TPM_RC 6291 TPM2_MakeCredential( 6292 MakeCredential_In 6293 MakeCredential_Out 6294 6295 *in, 6296 *out 6297 6298 // IN: input parameter list 6299 // OUT: output parameter list 6300 6301 TPM_RC 6302 6303 result = TPM_RC_SUCCESS; 6304 6305 OBJECT 6306 TPM2B_DATA 6307 6308 *object; 6309 data; 6310 6311 ) 6312 { 6313 6314 // Input Validation 6315 // Get object pointer 6316 object = ObjectGet(in->handle); 6317 // input key must be an asymmetric, restricted decryption key 6318 // NOTE: Needs to be restricted to have a symmetric value. 6319 if( 6320 !CryptIsAsymAlgorithm(object->publicArea.type) 6321 || object->publicArea.objectAttributes.decrypt == CLEAR 6322 || object->publicArea.objectAttributes.restricted == CLEAR 6323 ) 6324 return TPM_RC_TYPE + RC_MakeCredential_handle; 6325 // The credential information may not be larger than the digest size used for 6326 // the Name of the key associated with handle. 6327 if(in->credential.t.size > CryptGetHashDigestSize(object->publicArea.nameAlg)) 6328 return TPM_RC_SIZE + RC_MakeCredential_credential; 6329 // Command Output 6330 // Make encrypt key and its associated secret structure. 6331 // Even though CrypeSecretEncrypt() may return 6332 out->secret.t.size = sizeof(out->secret.t.secret); 6333 result = CryptSecretEncrypt(in->handle, "IDENTITY", &data, &out->secret); 6334 if(result != TPM_RC_SUCCESS) 6335 return result; 6336 // Prepare output credential data from secret 6337 SecretToCredential(&in->credential, &in->objectName, (TPM2B_SEED *) &data, 6338 in->handle, &out->credentialBlob); 6339 return TPM_RC_SUCCESS; 6340 } 6341 6342 Family 2.0 6343 Level 00 Revision 00.99 6344 6345 Published 6346 Copyright TCG 2006-2013 6347 6348 Page 69 6349 October 31, 2013 6350 6351 Part 3: Commands 6353 6354 14.7 6355 6356 Trusted Platform Module Library 6357 6358 TPM2_Unseal 6359 6360 14.7.1 General Description 6361 This command returns the data in a loaded Sealed Data Object. 6362 NOTE 6363 6364 A random, TPM-generated, Sealed Data Object may be created by the TPM with TPM2_Create() or 6365 TPM2_CreatePrimary() using the template for a Sealed Data Object. A Sealed Data Object is more 6366 likely to be created externally and imported (TPM2_Import()) so that the data is not created by the 6367 TPM. 6368 6369 The returned value may be encrypted using authorization session encryption. 6370 If either restricted, decrypt, or sign is SET in the attributes of itemHandle, then the TPM shall return 6371 TPM_RC_ATTRIBUTES. If the type of itemHandle is not TPM_ALG_KEYEDHASH, then the TPM shall 6372 return TPM_RC_TYPE. 6373 6374 Page 70 6375 October 31, 2013 6376 6377 Published 6378 Copyright TCG 2006-2013 6379 6380 Family 2.0 6381 Level 00 Revision 00.99 6382 6383 Trusted Platform Module Library 6385 6386 Part 3: Commands 6387 6388 14.7.2 Command and Response 6389 Table 31 TPM2_Unseal Command 6390 Type 6391 6392 Name 6393 6394 TPMI_ST_COMMAND_TAG 6395 6396 Tag 6397 6398 UINT32 6399 6400 commandSize 6401 6402 TPM_CC 6403 6404 commandCode 6405 6406 TPM_CC_Unseal 6407 6408 TPMI_DH_OBJECT 6409 6410 @itemHandle 6411 6412 handle of a loaded data object 6413 Auth Index: 1 6414 Auth Role: USER 6415 6416 Description 6417 6418 Table 32 TPM2_Unseal Response 6419 Type 6420 6421 Name 6422 6423 Description 6424 6425 TPM_ST 6426 6427 tag 6428 6429 see clause 8 6430 6431 UINT32 6432 6433 responseSize 6434 6435 TPM_RC 6436 6437 responseCode 6438 6439 TPM2B_SENSITIVE_DATA 6440 6441 outData 6442 6443 Family 2.0 6444 Level 00 Revision 00.99 6445 6446 unsealed data 6447 Size of outData is limited to be no more than 128 octets. 6448 6449 Published 6450 Copyright TCG 2006-2013 6451 6452 Page 71 6453 October 31, 2013 6454 6455 Part 3: Commands 6457 6458 Trusted Platform Module Library 6459 6460 14.7.3 Detailed Actions 6461 1 6462 2 6463 6464 #include "InternalRoutines.h" 6465 #include "Unseal_fp.h" 6466 Error Returns 6467 TPM_RC_ATTRIBUTES 6468 6469 itemHandle has wrong attributes 6470 6471 TPM_RC_TYPE 6472 3 6473 4 6474 5 6475 6 6476 7 6477 8 6478 9 6479 10 6480 11 6481 12 6482 13 6483 14 6484 15 6485 16 6486 17 6487 18 6488 19 6489 20 6490 21 6491 22 6492 23 6493 24 6494 25 6495 26 6496 27 6497 28 6498 6499 Meaning 6500 6501 itemHandle is not a KEYEDHASH data object 6502 6503 TPM_RC 6504 TPM2_Unseal(Unseal_In *in, Unseal_Out *out) 6505 { 6506 OBJECT 6507 6508 *object; 6509 6510 // Input Validation 6511 // Get pointer to loaded object 6512 object = ObjectGet(in->itemHandle); 6513 // Input handle must be a data object 6514 if(object->publicArea.type != TPM_ALG_KEYEDHASH) 6515 return TPM_RC_TYPE + RC_Unseal_itemHandle; 6516 if( 6517 object->publicArea.objectAttributes.decrypt == SET 6518 || object->publicArea.objectAttributes.sign == SET 6519 || object->publicArea.objectAttributes.restricted == SET) 6520 return TPM_RC_ATTRIBUTES + RC_Unseal_itemHandle; 6521 // Command Output 6522 // Copy data 6523 MemoryCopy2B(&out->outData.b, &object->sensitive.sensitive.bits.b, 6524 sizeof(out->outData.t.buffer)); 6525 return TPM_RC_SUCCESS; 6526 } 6527 6528 Page 72 6529 October 31, 2013 6530 6531 Published 6532 Copyright TCG 2006-2013 6533 6534 Family 2.0 6535 Level 00 Revision 00.99 6536 6537 Trusted Platform Module Library 6539 6540 14.8 6541 6542 Part 3: Commands 6543 6544 TPM2_ObjectChangeAuth 6545 6546 14.8.1 General Description 6547 This command is used to change the authorization secret for a TPM-resident object. 6548 If successful, a new private area for the TPM-resident object associated with objectHandle is returned, 6549 which includes the new authorization value. 6550 This command does not change the authorization of the TPM-resident object on which it operates. 6551 Therefore, the old authValue (of the TPM-resident object) is used when generating the response HMAC 6552 key if required.. 6553 NOTE 1 6554 6555 The returned outPrivate will need to be loaded before the new authorization will apply. 6556 6557 NOTE 2 6558 6559 The TPM-resident object may be persistent and changing the authorization value of the persistent 6560 object could prevent other users from accessing the object. This is why this command does not 6561 change the TPM-resident object. 6562 6563 EXAMPLE 6564 6565 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 6566 persistent key would deny access to other users. 6567 6568 This command may not be used to change the authorization value for an NV Index or a Primary Object. 6569 NOTE 3 6570 6571 If an NV Index is to have a new authorization, it is done with TPM2_NV_ChangeAuth(). 6572 6573 NOTE 4 6574 6575 If a Primary Object is to have a new authorization, it needs to be recreated (TPM2_CreatePrimary()). 6576 6577 Family 2.0 6578 Level 00 Revision 00.99 6579 6580 Published 6581 Copyright TCG 2006-2013 6582 6583 Page 73 6584 October 31, 2013 6585 6586 Part 3: Commands 6588 6589 Trusted Platform Module Library 6590 6591 14.8.2 Command and Response 6592 Table 33 TPM2_ObjectChangeAuth Command 6593 Type 6594 6595 Name 6596 6597 Description 6598 6599 TPMI_ST_COMMAND_TAG 6600 6601 tag 6602 6603 UINT32 6604 6605 commandSize 6606 6607 TPM_CC 6608 6609 commandCode 6610 6611 TPM_CC_ObjectChangeAuth 6612 6613 TPMI_DH_OBJECT 6614 6615 @objectHandle 6616 6617 handle of the object 6618 Auth Index: 1 6619 Auth Role: ADMIN 6620 6621 TPMI_DH_OBJECT 6622 6623 parentHandle 6624 6625 handle of the parent 6626 Auth Index: None 6627 6628 TPM2B_AUTH 6629 6630 newAuth 6631 6632 new authorization value 6633 6634 Table 34 TPM2_ObjectChangeAuth Response 6635 Type 6636 6637 Name 6638 6639 Description 6640 6641 TPM_ST 6642 6643 tag 6644 6645 see clause 8 6646 6647 UINT32 6648 6649 responseSize 6650 6651 TPM_RC 6652 6653 responseCode 6654 6655 TPM2B_PRIVATE 6656 6657 outPrivate 6658 6659 Page 74 6660 October 31, 2013 6661 6662 private area containing the new authorization value 6663 6664 Published 6665 Copyright TCG 2006-2013 6666 6667 Family 2.0 6668 Level 00 Revision 00.99 6669 6670 Trusted Platform Module Library 6672 6673 Part 3: Commands 6674 6675 14.8.3 Detailed Actions 6676 1 6677 2 6678 3 6679 6680 #include "InternalRoutines.h" 6681 #include "ObjectChangeAuth_fp.h" 6682 #include "Object_spt_fp.h" 6683 Error Returns 6684 TPM_RC_SIZE 6685 6686 newAuth is larger than the size of the digest of the Name algorithm of 6687 objectHandle 6688 6689 TPM_RC_TYPE 6690 6691 4 6692 5 6693 6 6694 7 6695 8 6696 9 6697 10 6698 11 6699 12 6700 13 6701 14 6702 15 6703 16 6704 17 6705 18 6706 19 6707 20 6708 21 6709 22 6710 23 6711 24 6712 25 6713 26 6714 27 6715 28 6716 29 6717 30 6718 31 6719 32 6720 33 6721 34 6722 35 6723 36 6724 37 6725 38 6726 39 6727 40 6728 41 6729 42 6730 43 6731 44 6732 45 6733 46 6734 47 6735 48 6736 49 6737 50 6738 51 6739 6740 Meaning 6741 6742 the key referenced by parentHandle is not the parent of the object 6743 referenced by objectHandle; or objectHandle is a sequence object. 6744 6745 TPM_RC 6746 TPM2_ObjectChangeAuth( 6747 ObjectChangeAuth_In 6748 ObjectChangeAuth_Out 6749 6750 *in, 6751 *out 6752 6753 // IN: input parameter list 6754 // OUT: output parameter list 6755 6756 ) 6757 { 6758 TPMT_SENSITIVE 6759 OBJECT 6760 TPM2B_NAME 6761 TPM2B_NAME 6762 6763 sensitive; 6764 *object; 6765 objectQN, QNCompare; 6766 parentQN; 6767 6768 // Input Validation 6769 // Get object pointer 6770 object = ObjectGet(in->objectHandle); 6771 // Can not change auth on sequence object 6772 if(ObjectIsSequence(object)) 6773 return TPM_RC_TYPE + RC_ObjectChangeAuth_objectHandle; 6774 // Make sure that the auth value is consistent with the nameAlg 6775 if( MemoryRemoveTrailingZeros(&in->newAuth) 6776 > CryptGetHashDigestSize(object->publicArea.nameAlg)) 6777 return TPM_RC_SIZE + RC_ObjectChangeAuth_newAuth; 6778 // Check parent for object 6779 // parent handle must be the parent of object handle. In this 6780 // implementation we verify this by checking the QN of object. Other 6781 // implementation may choose different method to verify this attribute. 6782 ObjectGetQualifiedName(in->parentHandle, &parentQN); 6783 ObjectComputeQualifiedName(&parentQN, object->publicArea.nameAlg, 6784 &object->name, &QNCompare); 6785 ObjectGetQualifiedName(in->objectHandle, &objectQN); 6786 if(!Memory2BEqual(&objectQN.b, &QNCompare.b)) 6787 return TPM_RC_TYPE + RC_ObjectChangeAuth_parentHandle; 6788 // Command Output 6789 // Copy internal sensitive area 6790 sensitive = object->sensitive; 6791 // Copy authValue 6792 sensitive.authValue = in->newAuth; 6793 // Prepare output private data from sensitive 6794 SensitiveToPrivate(&sensitive, &object->name, in->parentHandle, 6795 6796 Family 2.0 6797 Level 00 Revision 00.99 6798 6799 Published 6800 Copyright TCG 2006-2013 6801 6802 Page 75 6803 October 31, 2013 6804 6805 Part 3: Commands 6807 52 6808 53 6809 54 6810 55 6811 56 6812 6813 Trusted Platform Module Library 6814 object->publicArea.nameAlg, 6815 &out->outPrivate); 6816 6817 return TPM_RC_SUCCESS; 6818 } 6819 6820 Page 76 6821 October 31, 2013 6822 6823 Published 6824 Copyright TCG 2006-2013 6825 6826 Family 2.0 6827 Level 00 Revision 00.99 6828 6829 Trusted Platform Module Library 6831 6832 15 6833 6834 Part 3: Commands 6835 6836 Duplication Commands 6837 6838 15.1 6839 6840 TPM2_Duplicate 6841 6842 15.1.1 General Description 6843 This command duplicates a loaded object so that it may be used in a different hierarchy. The new parent 6844 key for the duplicate may be on the same or different TPM or TPM_RH_NULL. Only the public area of 6845 newParentHandle is required to be loaded. 6846 NOTE 1 6847 6848 Since the new parent may only be extant on a different TPM, it is likely that the new parents 6849 sensitive area could not be loaded in the TPM from which objectHandle is being duplicated. 6850 6851 If encryptedDuplication is SET in the object being duplicated, then the TPM shall return 6852 TPM_RC_SYMMETRIC if symmetricAlg is TPM_RH_NULL or TPM_RC_HIERARCHY if 6853 newParentHandle is TPM_RH_NULL. 6854 The authorization for this command shall be with a policy session. 6855 If fixedParent of objectHandleattributes is SET, the TPM shall return TPM_RC_ATTRIBUTES. If 6856 objectHandlenameAlg is TPM_ALG_NULL, the TPM shall return TPM_RC_TYPE. 6857 The policySessioncommandCode parameter in the policy session is required to be TPM_CC_Duplicate 6858 to indicate that authorization for duplication has been provided. This indicates that the policy that is being 6859 used is a policy that is for duplication, and not a policy that would approve another use. That is, authority 6860 to use an object does not grant authority to duplicate the object. 6861 The policy is likely to include cpHash in order to restrict where duplication can occur. 6862 If 6863 TPM2_PolicyCpHash() has been executed as part of the policy, the policySessioncpHash is compared 6864 to the cpHash of the command. 6865 If TPM2_PolicyDuplicationSelect() has 6866 policySessionnameHash is compared to 6867 6868 been 6869 6870 executed 6871 6872 as 6873 6874 part 6875 6876 of 6877 6878 the 6879 6880 policy, 6881 6882 HpolicyAlg(objectHandleName || newParentHandleName) 6883 6884 the 6885 (2) 6886 6887 If the compared hashes are not the same, then the TPM shall return TPM_RC_POLICY_FAIL. 6888 NOTE 2 6889 6890 It is allowed that policySesionnameHash and policySessioncpHash share the same memory 6891 space. 6892 6893 NOTE 3 6894 6895 A duplication policy is not required to have either TPM2_PolicyDuplicationSelect() or 6896 TPM2_PolicyCpHash() as part of the policy. If neither is present, then the duplication policy may be 6897 satisfied with a policy that only contains TPM2_PolicyCommaneCode( code = TPM_CC_Duplicate). 6898 6899 The TPM shall follow the process of encryption defined in the Duplication subclause of Protected 6900 Storage Hierarchy in Part 1 of this specification. 6901 6902 Family 2.0 6903 Level 00 Revision 00.99 6904 6905 Published 6906 Copyright TCG 2006-2013 6907 6908 Page 77 6909 October 31, 2013 6910 6911 Part 3: Commands 6913 6914 Trusted Platform Module Library 6915 6916 15.1.2 Command and Response 6917 Table 35 TPM2_Duplicate Command 6918 Type 6919 6920 Name 6921 6922 Description 6923 6924 TPMI_ST_COMMAND_TAG 6925 6926 tag 6927 6928 UINT32 6929 6930 commandSize 6931 6932 TPM_CC 6933 6934 commandCode 6935 6936 TPM_CC_Duplicate 6937 6938 TPMI_DH_OBJECT 6939 6940 @objectHandle 6941 6942 loaded object to duplicate 6943 Auth Index: 1 6944 Auth Role: DUP 6945 6946 TPMI_DH_OBJECT+ 6947 6948 newParentHandle 6949 6950 shall reference the public area of an asymmetric key 6951 Auth Index: None 6952 6953 TPM2B_DATA 6954 6955 encryptionKeyIn 6956 6957 optional symmetric encryption key 6958 The size for this key is set to zero when the TPM is to 6959 generate the key. This parameter may be encrypted. 6960 6961 TPMT_SYM_DEF_OBJECT+ 6962 6963 symmetricAlg 6964 6965 definition for the symmetric algorithm to be used for the 6966 inner wrapper 6967 may be TPM_ALG_NULL if no inner wrapper is applied 6968 6969 Table 36 TPM2_Duplicate Response 6970 Type 6971 6972 Name 6973 6974 Description 6975 6976 TPM_ST 6977 6978 tag 6979 6980 see clause 8 6981 6982 UINT32 6983 6984 responseSize 6985 6986 TPM_RC 6987 6988 responseCode 6989 6990 TPM2B_DATA 6991 6992 encryptionKeyOut 6993 6994 If the caller provided an encryption key or if 6995 symmetricAlg was TPM_ALG_NULL, then this will be 6996 the Empty Buffer; otherwise, it shall contain the TPMgenerated, symmetric encryption key for the inner 6997 wrapper. 6998 6999 TPM2B_PRIVATE 7000 7001 duplicate 7002 7003 private area that may be encrypted by encryptionKeyIn; 7004 and may be doubly encrypted 7005 7006 TPM2B_ENCRYPTED_SECRET 7007 7008 outSymSeed 7009 7010 Page 78 7011 October 31, 2013 7012 7013 seed protected by the asymmetric algorithms of new 7014 parent (NP) 7015 7016 Published 7017 Copyright TCG 2006-2013 7018 7019 Family 2.0 7020 Level 00 Revision 00.99 7021 7022 Trusted Platform Module Library 7024 7025 Part 3: Commands 7026 7027 15.1.3 Detailed Actions 7028 1 7029 2 7030 3 7031 7032 #include "InternalRoutines.h" 7033 #include "Duplicate_fp.h" 7034 #include "Object_spt_fp.h" 7035 Error Returns 7036 TPM_RC_ATTRIBUTES 7037 7038 key to duplicate has fixedParent SET 7039 7040 TPM_RC_HIERARCHY 7041 7042 encryptedDuplication is SET and newParentHandle specifies Null 7043 Hierarchy 7044 7045 TPM_RC_KEY 7046 7047 newParentHandle references invalid ECC key (public point not on the 7048 curve) 7049 7050 TPM_RC_SIZE 7051 7052 input encryption key size does not match the size specified in 7053 symmetric algorithm 7054 7055 TPM_RC_SYMMETRIC 7056 7057 encryptedDuplication is SET but no symmetric algorithm is provided 7058 7059 TPM_RC_TYPE 7060 7061 4 7062 5 7063 6 7064 7 7065 8 7066 9 7067 10 7068 11 7069 12 7070 13 7071 14 7072 15 7073 16 7074 17 7075 18 7076 19 7077 20 7078 21 7079 22 7080 23 7081 24 7082 25 7083 26 7084 27 7085 28 7086 29 7087 30 7088 31 7089 32 7090 33 7091 34 7092 35 7093 36 7094 37 7095 38 7096 39 7097 40 7098 41 7099 42 7100 7101 Meaning 7102 7103 newParentHandle is neither a storage key nor TPM_RH_NULL; or 7104 the object has a NULL nameAlg 7105 7106 TPM_RC 7107 TPM2_Duplicate( 7108 Duplicate_In 7109 Duplicate_Out 7110 7111 *in, 7112 *out 7113 7114 // IN: input parameter list 7115 // OUT: output parameter list 7116 7117 ) 7118 { 7119 TPM_RC 7120 TPMT_SENSITIVE 7121 7122 result = TPM_RC_SUCCESS; 7123 sensitive; 7124 7125 UINT16 7126 7127 innerKeySize = 0; // encrypt key size for inner wrap 7128 7129 OBJECT 7130 TPM2B_DATA 7131 7132 *object; 7133 data; 7134 7135 // Input Validation 7136 // Get duplicate object pointer 7137 object = ObjectGet(in->objectHandle); 7138 // duplicate key must have fixParent bit CLEAR. 7139 if(object->publicArea.objectAttributes.fixedParent == SET) 7140 return TPM_RC_ATTRIBUTES + RC_Duplicate_objectHandle; 7141 // Do not duplicate object with NULL nameAlg 7142 if(object->publicArea.nameAlg == TPM_ALG_NULL) 7143 return TPM_RC_TYPE + RC_Duplicate_objectHandle; 7144 // new parent key must be a storage object or TPM_RH_NULL 7145 if(in->newParentHandle != TPM_RH_NULL 7146 && !ObjectIsStorage(in->newParentHandle)) 7147 return TPM_RC_TYPE + RC_Duplicate_newParentHandle; 7148 // If the duplicates object has encryptedDuplication SET, then there must be 7149 // an inner wrapper and the new parent may not be TPM_RH_NULL 7150 if(object->publicArea.objectAttributes.encryptedDuplication == SET) 7151 { 7152 if(in->symmetricAlg.algorithm == TPM_ALG_NULL) 7153 return TPM_RC_SYMMETRIC + RC_Duplicate_symmetricAlg; 7154 if(in->newParentHandle == TPM_RH_NULL) 7155 7156 Family 2.0 7157 Level 00 Revision 00.99 7158 7159 Published 7160 Copyright TCG 2006-2013 7161 7162 Page 79 7163 October 31, 2013 7164 7165 Part 3: Commands 7167 43 7168 44 7169 45 7170 46 7171 47 7172 48 7173 49 7174 50 7175 51 7176 52 7177 53 7178 54 7179 55 7180 56 7181 57 7182 58 7183 59 7184 60 7185 61 7186 62 7187 63 7188 64 7189 65 7190 66 7191 67 7192 68 7193 69 7194 70 7195 71 7196 72 7197 73 7198 74 7199 75 7200 76 7201 77 7202 78 7203 79 7204 80 7205 81 7206 82 7207 83 7208 84 7209 85 7210 86 7211 87 7212 88 7213 89 7214 90 7215 91 7216 92 7217 93 7218 94 7219 95 7220 96 7221 7222 Trusted Platform Module Library 7223 7224 return TPM_RC_HIERARCHY + RC_Duplicate_newParentHandle; 7225 } 7226 if(in->symmetricAlg.algorithm == TPM_ALG_NULL) 7227 { 7228 // if algorithm is TPM_ALG_NULL, input key size must be 0 7229 if(in->encryptionKeyIn.t.size != 0) 7230 return TPM_RC_SIZE + RC_Duplicate_encryptionKeyIn; 7231 } 7232 else 7233 { 7234 // Get inner wrap key size 7235 innerKeySize = in->symmetricAlg.keyBits.sym; 7236 // If provided the input symmetric key must match the size of the algorithm 7237 if(in->encryptionKeyIn.t.size != 0 7238 && in->encryptionKeyIn.t.size != (innerKeySize + 7) / 8) 7239 return TPM_RC_SIZE + RC_Duplicate_encryptionKeyIn; 7240 } 7241 // Command Output 7242 if(in->newParentHandle != TPM_RH_NULL) 7243 { 7244 // Make encrypt key and its associated secret structure. A TPM_RC_KEY 7245 // error may be returned at this point 7246 out->outSymSeed.t.size = sizeof(out->outSymSeed.t.secret); 7247 result = CryptSecretEncrypt(in->newParentHandle, 7248 "DUPLICATE", &data, &out->outSymSeed); 7249 pAssert(result != TPM_RC_VALUE); 7250 if(result != TPM_RC_SUCCESS) 7251 return result; 7252 } 7253 else 7254 { 7255 // Do not apply outer wrapper 7256 data.t.size = 0; 7257 out->outSymSeed.t.size = 0; 7258 } 7259 // Copy sensitive area 7260 sensitive = object->sensitive; 7261 // Prepare output private data from sensitive 7262 SensitiveToDuplicate(&sensitive, &object->name, in->newParentHandle, 7263 object->publicArea.nameAlg, (TPM2B_SEED *) &data, 7264 &in->symmetricAlg, &in->encryptionKeyIn, 7265 &out->duplicate); 7266 out->encryptionKeyOut = in->encryptionKeyIn; 7267 return TPM_RC_SUCCESS; 7268 } 7269 7270 Page 80 7271 October 31, 2013 7272 7273 Published 7274 Copyright TCG 2006-2013 7275 7276 Family 2.0 7277 Level 00 Revision 00.99 7278 7279 Trusted Platform Module Library 7281 7282 15.2 7283 7284 Part 3: Commands 7285 7286 TPM2_Rewrap 7287 7288 15.2.1 General Description 7289 This command allows the TPM to serve in the role as a Duplication Authority. If proper authorization for 7290 use of the oldParent is provided, then an HMAC key and a symmetric key are recovered from inSymSeed 7291 and used to integrity check and decrypt inDuplicate. A new protection seed value is generated according 7292 to the methods appropriate for newParent and the blob is re-encrypted and a new integrity value is 7293 computed. The re-encrypted blob is returned in outDuplicate and the symmetric key returned in 7294 outSymKey. 7295 In the rewrap process, L is DUPLICATE (see Terms and Definitions in Part 1). 7296 If inSymSeed has a zero length, then oldParent is required to be TPM_RH_NULL and no decryption of 7297 inDuplicate takes place. 7298 If newParent is TPM_RH_NULL, then no encryption is performed on outDuplicate. outSymSeed will have 7299 a zero length. See Part 2 encryptedDuplication. 7300 7301 Family 2.0 7302 Level 00 Revision 00.99 7303 7304 Published 7305 Copyright TCG 2006-2013 7306 7307 Page 81 7308 October 31, 2013 7309 7310 Part 3: Commands 7312 7313 Trusted Platform Module Library 7314 7315 15.2.2 Command and Response 7316 Table 37 TPM2_Rewrap Command 7317 Type 7318 7319 Name 7320 7321 TPMI_ST_COMMAND_TAG 7322 7323 tag 7324 7325 UINT32 7326 7327 commandSize 7328 7329 TPM_CC 7330 7331 commandCode 7332 7333 TPM_CC_Rewrap 7334 7335 TPMI_DH_OBJECT+ 7336 7337 @oldParent 7338 7339 parent of object 7340 Auth Index: 1 7341 Auth Role: User 7342 7343 TPMI_DH_OBJECT+ 7344 7345 newParent 7346 7347 new parent of the object 7348 Auth Index: None 7349 7350 TPM2B_PRIVATE 7351 7352 inDuplicate 7353 7354 an object encrypted using symmetric key derived from 7355 inSymSeed 7356 7357 TPM2B_NAME 7358 7359 name 7360 7361 the Name of the object being rewrapped 7362 7363 TPM2B_ENCRYPTED_SECRET 7364 7365 inSymSeed 7366 7367 Description 7368 7369 seed for symmetric key 7370 needs oldParent private key to recover the seed and 7371 generate the symmetric key 7372 7373 Table 38 TPM2_Rewrap Response 7374 Type 7375 7376 Name 7377 7378 Description 7379 7380 TPM_ST 7381 7382 tag 7383 7384 see clause 8 7385 7386 UINT32 7387 7388 responseSize 7389 7390 TPM_RC 7391 7392 responseCode 7393 7394 TPM2B_PRIVATE 7395 7396 outDuplicate 7397 7398 TPM2B_ENCRYPTED_SECRET 7399 7400 outSymSeed 7401 7402 Page 82 7403 October 31, 2013 7404 7405 an object encrypted using symmetric key derived from 7406 outSymSeed 7407 seed for a symmetric key protected by newParent 7408 asymmetric key 7409 7410 Published 7411 Copyright TCG 2006-2013 7412 7413 Family 2.0 7414 Level 00 Revision 00.99 7415 7416 Trusted Platform Module Library 7418 7419 Part 3: Commands 7420 7421 15.2.3 Detailed Actions 7422 1 7423 2 7424 3 7425 7426 #include "InternalRoutines.h" 7427 #include "Rewrap_fp.h" 7428 #include "Object_spt_fp.h" 7429 Error Returns 7430 TPM_RC_ATTRIBUTES 7431 7432 newParent is not a decryption key 7433 7434 TPM_RC_HANDLE 7435 7436 oldParent does not consistent with inSymSeed 7437 7438 TPM_RC_INTEGRITY 7439 7440 the integrity check of inDuplicate failed 7441 7442 TPM_RC_KEY 7443 7444 for an ECC key, the public key is not on the curve of the curve ID 7445 7446 TPM_RC_KEY_SIZE 7447 7448 the decrypted input symmetric key size does not matches the 7449 symmetric algorithm key size of oldParent 7450 7451 TPM_RC_TYPE 7452 7453 oldParent is not a storage key, or 'newParent is not a storage key 7454 7455 TPM_RC_VALUE 7456 7457 for an 'oldParent; RSA key, the data to be decrypted is greater than 7458 the public exponent 7459 7460 Unmarshal errors 7461 7462 4 7463 5 7464 6 7465 7 7466 8 7467 9 7468 10 7469 11 7470 12 7471 13 7472 14 7473 15 7474 16 7475 17 7476 18 7477 19 7478 20 7479 21 7480 22 7481 23 7482 24 7483 25 7484 26 7485 27 7486 28 7487 29 7488 30 7489 31 7490 32 7491 33 7492 34 7493 35 7494 36 7495 37 7496 38 7497 39 7498 7499 Meaning 7500 7501 errors during unmarshaling the input encrypted buffer to a ECC public 7502 key, or unmarshal the private buffer to sensitive 7503 7504 TPM_RC 7505 TPM2_Rewrap( 7506 Rewrap_In 7507 Rewrap_Out 7508 7509 *in, 7510 *out 7511 7512 // IN: input parameter list 7513 // OUT: output parameter list 7514 7515 TPM_RC 7516 OBJECT 7517 TPM2B_DATA 7518 UINT16 7519 TPM2B_PRIVATE 7520 7521 result = TPM_RC_SUCCESS; 7522 *oldParent; 7523 data; 7524 // symmetric key 7525 hashSize = 0; 7526 privateBlob; 7527 // A temporary private blob 7528 // to transit between old 7529 // and new wrappers 7530 7531 ) 7532 { 7533 7534 // Input Validation 7535 if((in->inSymSeed.t.size == 0 && in->oldParent != TPM_RH_NULL) 7536 || (in->inSymSeed.t.size != 0 && in->oldParent == TPM_RH_NULL)) 7537 return TPM_RC_HANDLE + RC_Rewrap_oldParent; 7538 if(in->oldParent != TPM_RH_NULL) 7539 { 7540 // Get old parent pointer 7541 oldParent = ObjectGet(in->oldParent); 7542 // old parent key must be a storage object 7543 if(!ObjectIsStorage(in->oldParent)) 7544 return TPM_RC_TYPE + RC_Rewrap_oldParent; 7545 // Decrypt input secret data via asymmetric decryption. A 7546 // TPM_RC_VALUE, TPM_RC_KEY or unmarshal errors may be returned at this 7547 // point 7548 result = CryptSecretDecrypt(in->oldParent, NULL, 7549 "DUPLICATE", &in->inSymSeed, &data); 7550 if(result != TPM_RC_SUCCESS) 7551 return TPM_RC_VALUE + RC_Rewrap_inSymSeed; 7552 7553 Family 2.0 7554 Level 00 Revision 00.99 7555 7556 Published 7557 Copyright TCG 2006-2013 7558 7559 Page 83 7560 October 31, 2013 7561 7562 Part 3: Commands 7564 40 7565 41 7566 42 7567 43 7568 44 7569 45 7570 46 7571 47 7572 48 7573 49 7574 50 7575 51 7576 52 7577 53 7578 54 7579 55 7580 56 7581 57 7582 58 7583 59 7584 60 7585 61 7586 62 7587 63 7588 64 7589 65 7590 66 7591 67 7592 68 7593 69 7594 70 7595 71 7596 72 7597 73 7598 74 7599 75 7600 76 7601 77 7602 78 7603 79 7604 80 7605 81 7606 82 7607 83 7608 84 7609 85 7610 86 7611 87 7612 88 7613 89 7614 90 7615 91 7616 92 7617 93 7618 94 7619 95 7620 96 7621 97 7622 98 7623 99 7624 100 7625 101 7626 102 7627 103 7628 7629 Trusted Platform Module Library 7630 7631 // Unwrap Outer 7632 result = UnwrapOuter(in->oldParent, &in->name, 7633 oldParent->publicArea.nameAlg, (TPM2B_SEED *) &data, 7634 FALSE, 7635 in->inDuplicate.t.size, in->inDuplicate.t.buffer); 7636 if(result != TPM_RC_SUCCESS) 7637 return RcSafeAddToResult(result, RC_Rewrap_inDuplicate); 7638 // Copy unwrapped data to temporary variable, remove the integrity field 7639 hashSize = sizeof(UINT16) + 7640 CryptGetHashDigestSize(oldParent->publicArea.nameAlg); 7641 privateBlob.t.size = in->inDuplicate.t.size - hashSize; 7642 MemoryCopy(privateBlob.t.buffer, in->inDuplicate.t.buffer + hashSize, 7643 privateBlob.t.size, sizeof(privateBlob.t.buffer)); 7644 } 7645 else 7646 { 7647 // No outer wrap from input blob. 7648 privateBlob = in->inDuplicate; 7649 } 7650 7651 Direct copy. 7652 7653 if(in->newParent != TPM_RH_NULL) 7654 { 7655 OBJECT 7656 *newParent; 7657 newParent = ObjectGet(in->newParent); 7658 // New parent must be a storage object 7659 if(!ObjectIsStorage(in->newParent)) 7660 return TPM_RC_TYPE + RC_Rewrap_newParent; 7661 // Make new encrypt key and its associated secret structure. A 7662 // TPM_RC_VALUE error may be returned at this point if RSA algorithm is 7663 // enabled in TPM 7664 out->outSymSeed.t.size = sizeof(out->outSymSeed.t.secret); 7665 result = CryptSecretEncrypt(in->newParent, 7666 "DUPLICATE", &data, &out->outSymSeed); 7667 if(result != TPM_RC_SUCCESS) return result; 7668 // Command output 7669 // Copy temporary variable to output, reserve the space for integrity 7670 hashSize = sizeof(UINT16) + 7671 CryptGetHashDigestSize(newParent->publicArea.nameAlg); 7672 out->outDuplicate.t.size = privateBlob.t.size; 7673 MemoryCopy(out->outDuplicate.t.buffer + hashSize, privateBlob.t.buffer, 7674 privateBlob.t.size, sizeof(out->outDuplicate.t.buffer)); 7675 // Produce outer wrapper for output 7676 out->outDuplicate.t.size = ProduceOuterWrap(in->newParent, &in->name, 7677 newParent->publicArea.nameAlg, 7678 (TPM2B_SEED *) &data, 7679 FALSE, 7680 out->outDuplicate.t.size, 7681 out->outDuplicate.t.buffer); 7682 } 7683 else // New parent is a null key so there is no seed 7684 { 7685 out->outSymSeed.t.size = 0; 7686 // Copy privateBlob directly 7687 out->outDuplicate = privateBlob; 7688 } 7689 7690 Page 84 7691 October 31, 2013 7692 7693 Published 7694 Copyright TCG 2006-2013 7695 7696 Family 2.0 7697 Level 00 Revision 00.99 7698 7699 Trusted Platform Module Library 7701 104 7702 105 7703 7704 Part 3: Commands 7705 7706 return TPM_RC_SUCCESS; 7707 } 7708 7709 Family 2.0 7710 Level 00 Revision 00.99 7711 7712 Published 7713 Copyright TCG 2006-2013 7714 7715 Page 85 7716 October 31, 2013 7717 7718 Part 3: Commands 7720 7721 15.3 7722 7723 Trusted Platform Module Library 7724 7725 TPM2_Import 7726 7727 15.3.1 General Description 7728 This command allows an object to be encrypted using the symmetric encryption values of a Storage Key. 7729 After encryption, the object may be loaded and used in the new hierarchy. The imported object (duplicate) 7730 may be singly encrypted, multiply encrypted, or unencrypted. 7731 If fixedTPM or fixedParent is SET in objectPublic, the TPM shall return TPM_RC_ATTRIBUTES. 7732 If encryptedDuplication is SET in the object referenced by parentHandle, then encryptedDuplication shall 7733 be set in objectPublic (TPM_RC_ATTRIBUTES). However, see Note 2. 7734 Recovery of the sensitive data of the object occurs in the TPM in a three-step process in the following 7735 order: 7736 7737 7738 If present, the outer layer of symmetric encryption is removed. If inSymSeed has a non-zero size, the 7739 asymmetric parameters and private key of parentHandle are used to recover the seed used in the 7740 creation of the HMAC key and encryption keys used to protect the duplication blob. When recovering 7741 the seed, L is DUPLICATE. 7742 NOTE 1 7743 7744 If the encryptedDuplication attribute of the object 7745 TPM_RC_ATTRIBUTES if inSymSeed is an empty buffer. 7746 7747 is 7748 7749 SET, 7750 7751 the 7752 7753 TPM 7754 7755 shall 7756 7757 return 7758 7759 7760 7761 If present, the inner layer of symmetric encryption is removed. If encryptionKey and symmetricAlg are 7762 provided, they are used to decrypt duplication. 7763 7764 7765 7766 If present, the integrity value of the blob is checked. The presence of the integrity value is indicated 7767 by a non-zero value for duplicate.data.integrity.size. The integrity of the private area is validated using 7768 the Name of objectPublic in the integrity HMAC computation. If either the outer layer or inner layer of 7769 encryption is performed, then the integrity value shall be present. 7770 7771 If the inner or outer wrapper is present, then a valid integrity value shall be present or the TPM shall 7772 return TPM_RC_INTEGRITY. 7773 NOTE 2 7774 7775 It is not necessary to validate that the sensitive area data is cryptographically bound to the public 7776 area other than that the Name of the public area is included in the HMAC. However, if the binding is 7777 not validated by this command, the binding must be checked each time the object is loaded. For an 7778 object that is imported under a parent with fixedTPM SET, binding need only be checked at import. If 7779 the parent has fixedTPM CLEAR, then the binding needs to be checked each time the object is 7780 loaded, or before the TPM performs an operation for which the binding affects the outcome of the 7781 operation (for example, TPM2_PolicySigned() or TPM2_Certify()). 7782 Similarly, if the new parent's fixedTPM is set, the encryptedDuplication state need only be checked 7783 at import. 7784 If the new parent is not fixedTPM, then that object will be loadable on any TPM (including SW 7785 versions) on which the new parent exists. This means that, each time an object is loaded under a 7786 parent that is not fixedTPM, it is necessary to validate all of the properties of that object. If the 7787 parent is fixedTPM, then the new private blob is integrity protected by the TPM that owns the 7788 parent. So, it is sufficient to validate the objects properties (attribute and public -private binding) on 7789 import and not again. 7790 7791 Before duplicate.buffer is decrypted using the symmetric key of the parent, the integrity value shall be 7792 checked before the sensitive area is used, or unmarshaled. 7793 After integrity checks and decryption, the TPM will create a new symmetrically encrypted private area 7794 using the encryption key of the parent. 7795 NOTE 3 7796 7797 Checking the integrity before the data is used prevents attacks on the sensitive area by fuzzing the 7798 data and looking at the differences in the response codes. 7799 7800 Page 86 7801 October 31, 2013 7802 7803 Published 7804 Copyright TCG 2006-2013 7805 7806 Family 2.0 7807 Level 00 Revision 00.99 7808 7809 Trusted Platform Module Library 7811 NOTE 4 7812 7813 Part 3: Commands 7814 7815 The symmetric re-encryption is the normal integrity generation and symmetric encryption applied to 7816 a child object. 7817 7818 Family 2.0 7819 Level 00 Revision 00.99 7820 7821 Published 7822 Copyright TCG 2006-2013 7823 7824 Page 87 7825 October 31, 2013 7826 7827 Part 3: Commands 7829 7830 Trusted Platform Module Library 7831 7832 15.3.2 Command and Response 7833 Table 39 TPM2_Import Command 7834 Type 7835 7836 Name 7837 7838 TPMI_ST_COMMAND_TAG 7839 7840 tag 7841 7842 UINT32 7843 7844 commandSize 7845 7846 TPM_CC 7847 7848 commandCode 7849 7850 TPM_CC_Import 7851 7852 TPMI_DH_OBJECT 7853 7854 @parentHandle 7855 7856 the handle of the new parent for the object 7857 Auth Index: 1 7858 Auth Role: USER 7859 7860 TPM2B_DATA 7861 7862 encryptionKey 7863 7864 the optional symmetric encryption key used as the inner 7865 wrapper for duplicate 7866 If symmetricAlg is TPM_ALG_NULL, then this 7867 parameter shall be the Empty Buffer. 7868 7869 TPM2B_PUBLIC 7870 7871 objectPublic 7872 7873 Description 7874 7875 the public area of the object to be imported 7876 This is provided so that the integrity value for duplicate 7877 and the object attributes can be checked. 7878 NOTE 7879 7880 TPM2B_PRIVATE 7881 7882 duplicate 7883 7884 Even if the integrity value of the object is not 7885 checked on input, the object Name is required to 7886 create the integrity value for the imported object. 7887 7888 the symmetrically encrypted duplicate object that may 7889 contain an inner symmetric wrapper 7890 7891 TPM2B_ENCRYPTED_SECRET 7892 inSymSeed 7893 7894 symmetric key used to encrypt duplicate 7895 inSymSeed is encrypted/encoded using the algorithms 7896 of newParent. 7897 7898 TPMT_SYM_DEF_OBJECT+ 7899 7900 symmetricAlg 7901 7902 definition for the symmetric algorithm to use for the inner 7903 wrapper 7904 If this algorithm is TPM_ALG_NULL, no inner wrapper is 7905 present and encryptionKey shall be the Empty Buffer. 7906 7907 Table 40 TPM2_Import Response 7908 Type 7909 7910 Name 7911 7912 Description 7913 7914 TPM_ST 7915 7916 tag 7917 7918 see clause 8 7919 7920 UINT32 7921 7922 responseSize 7923 7924 TPM_RC 7925 7926 responseCode 7927 7928 TPM2B_PRIVATE 7929 7930 outPrivate 7931 7932 Page 88 7933 October 31, 2013 7934 7935 the sensitive area encrypted with the symmetric key of 7936 parentHandle 7937 7938 Published 7939 Copyright TCG 2006-2013 7940 7941 Family 2.0 7942 Level 00 Revision 00.99 7943 7944 Trusted Platform Module Library 7946 7947 Part 3: Commands 7948 7949 15.3.3 Detailed Actions 7950 1 7951 2 7952 3 7953 7954 #include "InternalRoutines.h" 7955 #include "Import_fp.h" 7956 #include "Object_spt_fp.h" 7957 Error Returns 7958 7959 Meaning 7960 7961 TPM_RC_ASYMMETRIC 7962 7963 non-duplicable storage key represented by objectPublic and its 7964 parent referenced by parentHandle have different public params 7965 7966 TPM_RC_ATTRIBUTES 7967 7968 attributes FixedTPM and fixedParent of objectPublic are not both 7969 CLEAR; or inSymSeed is nonempty and parentHandle does not 7970 reference a decryption key; or objectPublic and parentHandle have 7971 incompatible or inconsistent attributes 7972 7973 TPM_RC_BINDING 7974 7975 duplicate and objectPublic are not cryptographically bound 7976 7977 TPM_RC_ECC_POINT 7978 7979 inSymSeed is nonempty and ECC point in inSymSeed is not on the 7980 curve 7981 7982 TPM_RC_HASH 7983 7984 non-duplicable storage key represented by objectPublic and its 7985 parent referenced by parentHandle have different name algorithm 7986 7987 TPM_RC_INSUFFICIENT 7988 7989 inSymSeed is nonempty and failed to retrieve ECC point from the 7990 secret; or unmarshaling sensitive value from duplicate failed the 7991 result of inSymSeed decryption 7992 7993 TPM_RC_INTEGRITY 7994 7995 duplicate integrity is broken 7996 7997 TPM_RC_KDF 7998 7999 objectPublic representing decrypting keyed hash object specifies 8000 invalid KDF 8001 8002 TPM_RC_KEY 8003 8004 inconsistent parameters of objectPublic; or inSymSeed is nonempty 8005 and parentHandle does not reference a key of supported type; or 8006 invalid key size in objectPublic representing an asymmetric key 8007 8008 TPM_RC_NO_RESULT 8009 8010 inSymSeed is nonempty and multiplication resulted in ECC point at 8011 infinity 8012 8013 TPM_RC_OBJECT_MEMORY 8014 8015 no available object slot 8016 8017 TPM_RC_SCHEME 8018 8019 inconsistent attributes decrypt, sign, restricted and key's scheme ID 8020 in objectPublic; or hash algorithm is inconsistent with the scheme ID 8021 for keyed hash object 8022 8023 TPM_RC_SIZE 8024 8025 authPolicy size does not match digest size of the name algorithm in 8026 objectPublic; or symmetricAlg and encryptionKey have different 8027 sizes; or inSymSeed is nonempty and it is not of the same size as 8028 RSA key referenced by parentHandle; or unmarshaling sensitive 8029 value from duplicate failed 8030 8031 TPM_RC_SYMMETRIC 8032 8033 objectPublic is either a storage key with no symmetric algorithm or a 8034 non-storage key with symmetric algorithm different from 8035 TPM_ALG_NULL 8036 8037 TPM_RC_TYPE 8038 8039 unsupported type of objectPublic; or non-duplicable storage key 8040 represented by objectPublic and its parent referenced by 8041 parentHandle are of different types; or parentHandle is not a storage 8042 key; or only the public portion of parentHandle is loaded; or 8043 objectPublic and duplicate are of different types 8044 8045 TPM_RC_VALUE 8046 8047 nonempty inSymSeed and its numeric value is greater than the 8048 modulus of the key referenced by parentHandle or inSymSeed is 8049 larger than the size of the digest produced by the name algorithm of 8050 the symmetric key referenced by parentHandle 8051 8052 Family 2.0 8053 Level 00 Revision 00.99 8054 8055 Published 8056 Copyright TCG 2006-2013 8057 8058 Page 89 8059 October 31, 2013 8060 8061 Part 3: Commands 8063 4 8064 5 8065 6 8066 7 8067 8 8068 9 8069 10 8070 11 8071 12 8072 13 8073 14 8074 15 8075 16 8076 17 8077 18 8078 19 8079 20 8080 21 8081 22 8082 23 8083 24 8084 25 8085 26 8086 27 8087 28 8088 29 8089 30 8090 31 8091 32 8092 33 8093 34 8094 35 8095 36 8096 37 8097 38 8098 39 8099 40 8100 41 8101 42 8102 43 8103 44 8104 45 8105 46 8106 47 8107 48 8108 49 8109 50 8110 51 8111 52 8112 53 8113 54 8114 55 8115 56 8116 57 8117 58 8118 59 8119 60 8120 61 8121 62 8122 63 8123 64 8124 65 8125 66 8126 67 8127 8128 Trusted Platform Module Library 8129 8130 TPM_RC 8131 TPM2_Import( 8132 Import_In 8133 Import_Out 8134 8135 *in, 8136 *out 8137 8138 // IN: input parameter list 8139 // OUT: output parameter list 8140 8141 ) 8142 { 8143 TPM_RC 8144 OBJECT 8145 TPM2B_DATA 8146 TPMT_SENSITIVE 8147 TPM2B_NAME 8148 8149 result = TPM_RC_SUCCESS; 8150 *parentObject; 8151 data; 8152 // symmetric key 8153 sensitive; 8154 name; 8155 8156 UINT16 8157 8158 innerKeySize = 0; 8159 8160 // encrypt key size for inner 8161 // wrapper 8162 8163 // Input Validation 8164 // FixedTPM and fixedParent must be CLEAR 8165 if( 8166 in->objectPublic.t.publicArea.objectAttributes.fixedTPM == SET 8167 || in->objectPublic.t.publicArea.objectAttributes.fixedParent == SET) 8168 return TPM_RC_ATTRIBUTES + RC_Import_objectPublic; 8169 // Get parent pointer 8170 parentObject = ObjectGet(in->parentHandle); 8171 if(!AreAttributesForParent(parentObject)) 8172 return TPM_RC_TYPE + RC_Import_parentHandle; 8173 if(in->symmetricAlg.algorithm != TPM_ALG_NULL) 8174 { 8175 // Get inner wrap key size 8176 innerKeySize = in->symmetricAlg.keyBits.sym; 8177 // Input symmetric key must match the size of algorithm. 8178 if(in->encryptionKey.t.size != (innerKeySize + 7) / 8) 8179 return TPM_RC_SIZE + RC_Import_encryptionKey; 8180 } 8181 else 8182 { 8183 // If input symmetric algorithm is NULL, input symmetric key size must 8184 // be 0 as well 8185 if(in->encryptionKey.t.size != 0) 8186 return TPM_RC_SIZE + RC_Import_encryptionKey; 8187 } 8188 // See if there is an outer wrapper 8189 if(in->inSymSeed.t.size != 0) 8190 { 8191 // Decrypt input secret data via asymmetric decryption. TPM_RC_ATTRIBUTES, 8192 // TPM_RC_ECC_POINT, TPM_RC_INSUFFICIENT, TPM_RC_KEY, TPM_RC_NO_RESULT, 8193 // TPM_RC_SIZE, TPM_RC_VALUE may be returned at this point 8194 result = CryptSecretDecrypt(in->parentHandle, NULL, "DUPLICATE", 8195 &in->inSymSeed, &data); 8196 pAssert(result != TPM_RC_BINDING); 8197 if(result != TPM_RC_SUCCESS) 8198 return TPM_RC_VALUE + RC_Import_inSymSeed; 8199 } 8200 else 8201 { 8202 data.t.size = 0; 8203 } 8204 // Compute name of object 8205 ObjectComputeName(&(in->objectPublic.t.publicArea), &name); 8206 8207 Page 90 8208 October 31, 2013 8209 8210 Published 8211 Copyright TCG 2006-2013 8212 8213 Family 2.0 8214 Level 00 Revision 00.99 8215 8216 Trusted Platform Module Library 8218 68 8219 69 8220 70 8221 71 8222 72 8223 73 8224 74 8225 75 8226 76 8227 77 8228 78 8229 79 8230 80 8231 81 8232 82 8233 83 8234 84 8235 85 8236 86 8237 87 8238 88 8239 89 8240 90 8241 91 8242 92 8243 93 8244 94 8245 95 8246 96 8247 97 8248 98 8249 99 8250 100 8251 101 8252 102 8253 103 8254 104 8255 105 8256 106 8257 107 8258 108 8259 109 8260 110 8261 111 8262 112 8263 113 8264 114 8265 8266 Part 3: Commands 8267 8268 // Retrieve sensitive from private. 8269 // TPM_RC_INSUFFICIENT, TPM_RC_INTEGRITY, TPM_RC_SIZE may be returned here. 8270 result = DuplicateToSensitive(&in->duplicate, &name, in->parentHandle, 8271 in->objectPublic.t.publicArea.nameAlg, 8272 (TPM2B_SEED *) &data, &in->symmetricAlg, 8273 &in->encryptionKey, &sensitive); 8274 if(result != TPM_RC_SUCCESS) 8275 return RcSafeAddToResult(result, RC_Import_duplicate); 8276 // If the parent of this object has fixedTPM SET, then fully validate this 8277 // object so that validation can be skipped when it is loaded 8278 if(parentObject->publicArea.objectAttributes.fixedTPM == SET) 8279 { 8280 TPM_HANDLE 8281 objectHandle; 8282 // Perform self check on input public area. A TPM_RC_SIZE, TPM_RC_SCHEME, 8283 // TPM_RC_VALUE, TPM_RC_SYMMETRIC, TPM_RC_TYPE, TPM_RC_HASH, 8284 // TPM_RC_ASYMMETRIC, TPM_RC_ATTRIBUTES or TPM_RC_KDF error may be returned 8285 // at this point 8286 result = PublicAttributesValidation(TRUE, in->parentHandle, 8287 &in->objectPublic.t.publicArea); 8288 if(result != TPM_RC_SUCCESS) 8289 return RcSafeAddToResult(result, RC_Import_objectPublic); 8290 // Create internal object. A TPM_RC_KEY_SIZE, TPM_RC_KEY or 8291 // TPM_RC_OBJECT_MEMORY error may be returned at this point 8292 result = ObjectLoad(TPM_RH_NULL, &in->objectPublic.t.publicArea, 8293 &sensitive, NULL, in->parentHandle, FALSE, 8294 &objectHandle); 8295 if(result != TPM_RC_SUCCESS) 8296 return result; 8297 // Don't need the object, just needed the checks to be performed so 8298 // flush the object 8299 ObjectFlush(objectHandle); 8300 } 8301 // Command output 8302 // Prepare output private data from sensitive 8303 SensitiveToPrivate(&sensitive, &name, in->parentHandle, 8304 in->objectPublic.t.publicArea.nameAlg, 8305 &out->outPrivate); 8306 return TPM_RC_SUCCESS; 8307 } 8308 8309 Family 2.0 8310 Level 00 Revision 00.99 8311 8312 Published 8313 Copyright TCG 2006-2013 8314 8315 Page 91 8316 October 31, 2013 8317 8318 Part 3: Commands 8320 8321 16 8322 8323 Trusted Platform Module Library 8324 8325 Asymmetric Primitives 8326 8327 16.1 8328 8329 Introduction 8330 8331 The commands in this clause provide low-level primitives for access to the asymmetric algorithms 8332 implemented in the TPM. Many of these commands are only allowed if the asymmetric key is an 8333 unrestricted key. 8334 16.2 8335 8336 TPM2_RSA_Encrypt 8337 8338 16.2.1 General Description 8339 This command performs RSA encryption using the indicated padding scheme according to PKCS#1v2.1 8340 (PKCS#1). If the scheme of keyHandle is TPM_ALG_NULL, then the caller may use inScheme to specify 8341 the padding scheme. If scheme of keyHandle is not TPM_ALG_NULL, then inScheme shall either be 8342 TPM_ALG_NULL or be the same as scheme (TPM_RC_SCHEME). 8343 The key referenced by keyHandle is required to be an RSA key (TPM_RC_KEY) with the decrypt attribute 8344 SET (TPM_RC_ATTRIBUTES). 8345 NOTE 8346 8347 Requiring that the decrypt attribute be set allows the TPM to ensure that the scheme selection is 8348 done with the presumption that the scheme of the key is a decryption scheme selection. It is 8349 understood that this command will operate on a key with only the publi c part loaded so the caller 8350 may modify any key in any desired way. So, this constraint only serves to simplify the TPM logic. 8351 8352 The three types of allowed padding are: 8353 1) TPM_ALG_OAEP Data is OAEP padded as described in 7.1 of PKCS#1 v2.1. The only 8354 supported mask generation is MGF1. 8355 2) TPM_ALG_RSAES Data is padded as described in 7.2 of PKCS#1 v2.1. 8356 3) TPM_ALG_NULL Data is not padded by the TPM and the TPM will treat message as an 8357 unsigned integer and perform a modular exponentiation of message using the public 8358 exponent of the key referenced by keyHandle. This scheme is only used if both the scheme 8359 in the key referenced by keyHandle is TPM_ALG_NULL, and the inScheme parameter of the 8360 command is TPM_ALG_NULL. The input value cannot be larger than the public modulus of 8361 the key referenced by keyHandle. 8362 Table 41 Padding Scheme Selection 8363 keyHandlescheme 8364 8365 OAEP 8366 RSAES 8367 8368 TPM_ALG_RSAES 8369 8370 RSAES 8371 error (TPM_RC_SCHEME) 8372 8373 TPM_ALG_NULL 8374 8375 OAEP 8376 8377 TPM_ALG_RSAES 8378 8379 error (TPM_RC_SCHEME) 8380 8381 TPM_AGL_OAEP 8382 8383 October 31, 2013 8384 8385 RSAES 8386 8387 TPM_ALG_OAEP 8388 8389 Page 92 8390 8391 TPM_ALG_RSAES 8392 8393 TPM_ALG_NULL 8394 8395 TPM_ALG_OAEP 8396 8397 none 8398 8399 TPM_ALG_OAEP 8400 8401 TPM_ALG_RSAES 8402 8403 padding scheme used 8404 8405 TPM_ALG_NULL 8406 TPM_ALG_NULL 8407 8408 inScheme 8409 8410 OAEP 8411 8412 Published 8413 Copyright TCG 2006-2013 8414 8415 Family 2.0 8416 Level 00 Revision 00.99 8417 8418 Trusted Platform Module Library 8420 8421 Part 3: Commands 8422 8423 After padding, the data is RSAEP encrypted according to 5.1.1 of PKCS#1v2.1. 8424 NOTE 1 8425 8426 It is required that decrypt be SET so that the commands that load a key can validate that the 8427 scheme is consistent rather than have that deferred until the key is used. 8428 8429 NOTE 2 8430 8431 If it is desired to use a key that had restricted SET, the caller may CLEAR restricted and load the 8432 public part of the key and use that unrestricted version of the key for encryption. 8433 8434 If inScheme is used, and the scheme requires a hash algorithm it may not be TPM_ALG_NULL. 8435 NOTE 3 8436 8437 Because only the public portion of the key needs to be loaded for this command, the caller can 8438 manipulate the attributes of the key in any way desired. As a result , the TPM shall not check the 8439 consistency of the attributes. The only property checking is that the key is an RSA key and that the 8440 padding scheme is supported. 8441 8442 The message parameter is limited in size by the padding scheme according to the following table: 8443 Table 42 Message Size Limits Based on Padding 8444 Scheme 8445 8446 Maximum Message Length 8447 (mLen) in Octets 8448 8449 TPM_ALG_OAEP 8450 8451 mLen k 2hLen 2 8452 8453 TPM_ALG_RSAES 8454 8455 mLen k 11 8456 8457 TPM_ALG_NULL 8458 8459 mLen k 8460 8461 Comments 8462 8463 The numeric value of the message must be 8464 less than the numeric value of the public 8465 modulus (n). 8466 8467 NOTES 8468 1) 8469 2) 8470 8471 k the number of byes in the public modulus 8472 hLen the number of octets in the digest produced by the hash algorithm used in the process 8473 8474 The label parameter is optional. If provided (label.size != 0) then the TPM shall return TPM_RC_VALUE if 8475 the last octet in label is not zero. If a zero octet occurs before label.buffer[label.size-1], the TPM shall 8476 truncate the label at that point. The terminating octet of zero is included in the label used in the padding 8477 scheme. 8478 NOTE 4 8479 8480 If the scheme does not use a label, the TPM will still verify that label is properly formatted if label is 8481 present. 8482 8483 The function returns padded and encrypted value outData. 8484 The message parameter in the command may be encrypted using parameter encryption. 8485 NOTE 5 8486 8487 Only the public area of keyHandle is required to be loaded. A public key may be loaded with any 8488 desired scheme. If the scheme is to be changed, a different public area must be loaded. 8489 8490 Family 2.0 8491 Level 00 Revision 00.99 8492 8493 Published 8494 Copyright TCG 2006-2013 8495 8496 Page 93 8497 October 31, 2013 8498 8499 Part 3: Commands 8501 8502 Trusted Platform Module Library 8503 8504 16.2.2 Command and Response 8505 Table 43 TPM2_RSA_Encrypt Command 8506 Type 8507 8508 Name 8509 8510 Description 8511 8512 TPMI_ST_COMMAND_TAG 8513 8514 tag 8515 8516 UINT32 8517 8518 commandSize 8519 8520 TPM_CC 8521 8522 commandCode 8523 8524 TPM_CC_RSA_Encrypt 8525 8526 TPMI_DH_OBJECT 8527 8528 keyHandle 8529 8530 reference to public portion of RSA key to use for 8531 encryption 8532 Auth Index: None 8533 message to be encrypted 8534 8535 TPM2B_PUBLIC_KEY_RSA 8536 8537 message 8538 8539 TPMT_RSA_DECRYPT+ 8540 8541 inScheme 8542 8543 TPM2B_DATA 8544 8545 label 8546 8547 NOTE 1 8548 8549 The data type was chosen because it limits the 8550 overall size of the input to no greater than the size 8551 of the largest RSA public key. This may be larger 8552 than allowed for keyHandle. 8553 8554 the padding scheme to use if scheme associated with 8555 keyHandle is TPM_ALG_NULL 8556 optional label L to be associated with the message 8557 Size of the buffer is zero if no label is present 8558 NOTE 2 8559 8560 See description of label above. 8561 8562 Table 44 TPM2_RSA_Encrypt Response 8563 Type 8564 8565 Name 8566 8567 Description 8568 8569 TPM_ST 8570 8571 tag 8572 8573 see clause 8 8574 8575 UINT32 8576 8577 responseSize 8578 8579 TPM_RC 8580 8581 responseCode 8582 8583 TPM2B_PUBLIC_KEY_RSA 8584 8585 outData 8586 8587 Page 94 8588 October 31, 2013 8589 8590 encrypted output 8591 8592 Published 8593 Copyright TCG 2006-2013 8594 8595 Family 2.0 8596 Level 00 Revision 00.99 8597 8598 Trusted Platform Module Library 8600 8601 Part 3: Commands 8602 8603 16.2.3 Detailed Actions 8604 1 8605 2 8606 3 8607 8608 #include "InternalRoutines.h" 8609 #include "RSA_Encrypt_fp.h" 8610 #ifdef TPM_ALG_RSA 8611 Error Returns 8612 TPM_RC_ATTRIBUTES 8613 8614 decrypt attribute is not SET in key referenced by keyHandle 8615 8616 TPM_RC_KEY 8617 8618 keyHandle does not reference an RSA key 8619 8620 TPM_RC_SCHEME 8621 8622 incorrect input scheme, or the chosen scheme is not a valid RSA 8623 decrypt scheme 8624 8625 TPM_RC_VALUE 8626 8627 4 8628 5 8629 6 8630 7 8631 8 8632 9 8633 10 8634 11 8635 12 8636 13 8637 14 8638 15 8639 16 8640 17 8641 18 8642 19 8643 20 8644 21 8645 22 8646 23 8647 24 8648 25 8649 26 8650 27 8651 28 8652 29 8653 30 8654 31 8655 32 8656 33 8657 34 8658 35 8659 36 8660 37 8661 38 8662 39 8663 40 8664 41 8665 42 8666 43 8667 44 8668 45 8669 46 8670 8671 Meaning 8672 8673 the numeric value of message is greater than the public modulus of 8674 the key referenced by keyHandle, or label is not a null-terminated 8675 string 8676 8677 TPM_RC 8678 TPM2_RSA_Encrypt( 8679 RSA_Encrypt_In 8680 RSA_Encrypt_Out 8681 8682 *in, 8683 *out 8684 8685 // IN: input parameter list 8686 // OUT: output parameter list 8687 8688 TPM_RC 8689 OBJECT 8690 TPMT_RSA_DECRYPT 8691 char 8692 8693 result; 8694 *rsaKey; 8695 *scheme; 8696 *label = NULL; 8697 8698 ) 8699 { 8700 8701 // Input Validation 8702 rsaKey = ObjectGet(in->keyHandle); 8703 // selected key must be an RSA key 8704 if(rsaKey->publicArea.type != TPM_ALG_RSA) 8705 return TPM_RC_KEY + RC_RSA_Encrypt_keyHandle; 8706 // selected key must have the decryption attribute 8707 if(rsaKey->publicArea.objectAttributes.decrypt != SET) 8708 return TPM_RC_ATTRIBUTES + RC_RSA_Encrypt_keyHandle; 8709 // Is there a label? 8710 if(in->label.t.size > 0) 8711 { 8712 // label is present, so make sure that is it NULL-terminated 8713 if(in->label.t.buffer[in->label.t.size - 1] != 0) 8714 return TPM_RC_VALUE + RC_RSA_Encrypt_label; 8715 label = (char *)in->label.t.buffer; 8716 } 8717 // Command Output 8718 // Select a scheme for encryption 8719 scheme = CryptSelectRSAScheme(in->keyHandle, &in->inScheme); 8720 if(scheme == NULL) 8721 return TPM_RC_SCHEME + RC_RSA_Encrypt_inScheme; 8722 // Encryption. TPM_RC_VALUE, or TPM_RC_SCHEME errors my be returned buy 8723 // CryptEncyptRSA. Note: It can also return TPM_RC_ATTRIBUTES if the key does 8724 // not have the decrypt attribute but that was checked above. 8725 out->outData.t.size = sizeof(out->outData.t.buffer); 8726 8727 Family 2.0 8728 Level 00 Revision 00.99 8729 8730 Published 8731 Copyright TCG 2006-2013 8732 8733 Page 95 8734 October 31, 2013 8735 8736 Part 3: Commands 8738 47 8739 48 8740 49 8741 50 8742 51 8743 52 8744 8745 Trusted Platform Module Library 8746 8747 result = CryptEncryptRSA(&out->outData.t.size, out->outData.t.buffer, rsaKey, 8748 scheme, in->message.t.size, in->message.t.buffer, 8749 label); 8750 return result; 8751 } 8752 #endif 8753 8754 Page 96 8755 October 31, 2013 8756 8757 Published 8758 Copyright TCG 2006-2013 8759 8760 Family 2.0 8761 Level 00 Revision 00.99 8762 8763 Trusted Platform Module Library 8765 8766 16.3 8767 8768 Part 3: Commands 8769 8770 TPM2_RSA_Decrypt 8771 8772 16.3.1 General Description 8773 This command performs RSA decryption using the indicated padding scheme according to PKCS#1v2.1 8774 (PKCS#1). 8775 The scheme selection for this command is the same as for TPM2_RSA_Encrypt() and is shown in Table 8776 41. 8777 The key referenced by keyHandle shall be an RSA key (TPM_RC_KEY) with restricted CLEAR and 8778 decrypt SET (TPM_RC_ATTRIBUTES). 8779 This command uses the private key of keyHandle for this operation and authorization is required. 8780 The TPM will perform a modular exponentiation of ciphertext using the private exponent associated with 8781 keyHandle (this is described in PKCS#1v2.1, clause 5.1.2). It will then validate the padding according to 8782 the selected scheme. If the padding checks fail, TPM_RC_VALUE is returned. Otherwise, the data is 8783 returned with the padding removed. If no padding is used, the returned value is an unsigned integer value 8784 that is the result of the modular exponentiation of cipherText using the private exponent of keyHandle. 8785 The returned value may include leading octets zeros so that it is the same size as the public modulus. For 8786 the other padding schemes, the returned value will be smaller than the public modulus but will contain all 8787 the data remaining after padding is removed and this may include leading zeros if the original encrypted 8788 value contained leading zeros.. 8789 If a label is used in the padding process of the scheme, the label parameter is required to be present in 8790 the decryption process and label is required to be the same in both cases. The TPM shall verify that the 8791 label is consistent and if not it shall return TPM_RC_VALUE. 8792 If label is present (label.size != 0), it 8793 shall be a NULL-terminated string or the TPM will return TPM_RC_VALUE. 8794 NOTE 1 8795 8796 The size of label includes the terminating null. 8797 8798 The message parameter in the response may be encrypted using parameter encryption. 8799 If the decryption scheme does not require a hash function, the hash parameter of inScheme may be set 8800 to any valid hash function or TPM_ALG_NULL. 8801 If the description scheme does not require a label, the value in label is not used but the size of the label 8802 field is checked for consistency with the indicated data type (TPM2B_DATA). That is, the field may not be 8803 larger than allowed for a TPM2B_DATA. 8804 8805 Family 2.0 8806 Level 00 Revision 00.99 8807 8808 Published 8809 Copyright TCG 2006-2013 8810 8811 Page 97 8812 October 31, 2013 8813 8814 Part 3: Commands 8816 8817 Trusted Platform Module Library 8818 8819 16.3.2 Command and Response 8820 Table 45 TPM2_RSA_Decrypt Command 8821 Type 8822 8823 Name 8824 8825 Description 8826 8827 TPMI_ST_COMMAND_TAG 8828 8829 tag 8830 8831 UINT32 8832 8833 commandSize 8834 8835 TPM_CC 8836 8837 commandCode 8838 8839 TPM_CC_RSA_Decrypt 8840 8841 TPMI_DH_OBJECT 8842 8843 @keyHandle 8844 8845 RSA key to use for decryption 8846 Auth Index: 1 8847 Auth Role: USER 8848 8849 TPM2B_PUBLIC_KEY_RSA 8850 8851 cipherText 8852 8853 NOTE 8854 8855 TPMT_RSA_DECRYPT+ 8856 8857 inScheme 8858 8859 the padding scheme to use if scheme associated with 8860 keyHandle is TPM_ALG_NULL 8861 8862 TPM2B_DATA 8863 8864 label 8865 8866 label whose association with the message is to be 8867 verified 8868 8869 cipher text to be decrypted 8870 An encrypted RSA data block is the size of the 8871 public modulus. 8872 8873 Table 46 TPM2_RSA_Decrypt Response 8874 Type 8875 8876 Name 8877 8878 Description 8879 8880 TPM_ST 8881 8882 tag 8883 8884 see clause 8 8885 8886 UINT32 8887 8888 responseSize 8889 8890 TPM_RC 8891 8892 responseCode 8893 8894 TPM2B_PUBLIC_KEY_RSA 8895 8896 message 8897 8898 Page 98 8899 October 31, 2013 8900 8901 decrypted output 8902 8903 Published 8904 Copyright TCG 2006-2013 8905 8906 Family 2.0 8907 Level 00 Revision 00.99 8908 8909 Trusted Platform Module Library 8911 8912 Part 3: Commands 8913 8914 16.3.3 Detailed Actions 8915 1 8916 2 8917 3 8918 8919 #include "InternalRoutines.h" 8920 #include "RSA_Decrypt_fp.h" 8921 #ifdef TPM_ALG_RSA 8922 Error Returns 8923 TPM_RC_KEY 8924 8925 keyHandle does not reference an unrestricted decrypt key 8926 8927 TPM_RC_SCHEME 8928 8929 incorrect input scheme, or the chosen scheme is not a valid RSA 8930 decrypt scheme 8931 8932 TPM_RC_SIZE 8933 8934 cipherText is not the size of the modulus of key referenced by 8935 keyHandle 8936 8937 TPM_RC_VALUE 8938 8939 4 8940 5 8941 6 8942 7 8943 8 8944 9 8945 10 8946 11 8947 12 8948 13 8949 14 8950 15 8951 16 8952 17 8953 18 8954 19 8955 20 8956 21 8957 22 8958 23 8959 24 8960 25 8961 26 8962 27 8963 28 8964 29 8965 30 8966 31 8967 32 8968 33 8969 34 8970 35 8971 36 8972 37 8973 38 8974 39 8975 40 8976 41 8977 42 8978 43 8979 44 8980 45 8981 46 8982 8983 Meaning 8984 8985 label is not a null terminated string or the value of cipherText is 8986 greater that the modulus of keyHandle 8987 8988 TPM_RC 8989 TPM2_RSA_Decrypt( 8990 RSA_Decrypt_In 8991 RSA_Decrypt_Out 8992 8993 *in, 8994 *out 8995 8996 // IN: input parameter list 8997 // OUT: output parameter list 8998 8999 TPM_RC 9000 OBJECT 9001 TPMT_RSA_DECRYPT 9002 char 9003 9004 result; 9005 *rsaKey; 9006 *scheme; 9007 *label = NULL; 9008 9009 ) 9010 { 9011 9012 // Input Validation 9013 rsaKey = ObjectGet(in->keyHandle); 9014 // The selected key must be an RSA key 9015 if(rsaKey->publicArea.type != TPM_ALG_RSA) 9016 return TPM_RC_KEY + RC_RSA_Decrypt_keyHandle; 9017 // The selected key must be an unrestricted decryption key 9018 if( 9019 rsaKey->publicArea.objectAttributes.restricted == SET 9020 || rsaKey->publicArea.objectAttributes.decrypt == CLEAR) 9021 return TPM_RC_ATTRIBUTES + RC_RSA_Decrypt_keyHandle; 9022 // 9023 // 9024 // 9025 // 9026 9027 NOTE: Proper operation of this command requires that the sensitive area 9028 of the key is loaded. This is assured because authorization is required 9029 to use the sensitive area of the key. In order to check the authorization, 9030 the sensitive area has to be loaded, even if authorization is with policy. 9031 9032 // If label is present, make sure that it is a NULL-terminated string 9033 if(in->label.t.size > 0) 9034 { 9035 // Present, so make sure that it is NULL-terminated 9036 if(in->label.t.buffer[in->label.t.size - 1] != 0) 9037 return TPM_RC_VALUE + RC_RSA_Decrypt_label; 9038 label = (char *)in->label.t.buffer; 9039 } 9040 // Command Output 9041 // Select a scheme for decrypt. 9042 scheme = CryptSelectRSAScheme(in->keyHandle, &in->inScheme); 9043 if(scheme == NULL) 9044 9045 Family 2.0 9046 Level 00 Revision 00.99 9047 9048 Published 9049 Copyright TCG 2006-2013 9050 9051 Page 99 9052 October 31, 2013 9053 9054 Part 3: Commands 9056 47 9057 48 9058 49 9059 50 9060 51 9061 52 9062 53 9063 54 9064 55 9065 56 9066 57 9067 58 9068 59 9069 60 9070 61 9071 9072 Trusted Platform Module Library 9073 9074 return TPM_RC_SCHEME + RC_RSA_Decrypt_inScheme; 9075 // Decryption. TPM_RC_VALUE, TPM_RC_SIZE, and TPM_RC_KEY error may be 9076 // returned by CryptDecryptRSA. 9077 // NOTE: CryptDecryptRSA can also return TPM_RC_ATTRIBUTES or TPM_RC_BINDING 9078 // when the key is not a decryption key but that was checked above. 9079 out->message.t.size = sizeof(out->message.t.buffer); 9080 result = CryptDecryptRSA(&out->message.t.size, out->message.t.buffer, rsaKey, 9081 scheme, in->cipherText.t.size, 9082 in->cipherText.t.buffer, 9083 label); 9084 return result; 9085 } 9086 #endif 9087 9088 Page 100 9089 October 31, 2013 9090 9091 Published 9092 Copyright TCG 2006-2013 9093 9094 Family 2.0 9095 Level 00 Revision 00.99 9096 9097 Trusted Platform Module Library 9099 9100 16.4 9101 9102 Part 3: Commands 9103 9104 TPM2_ECDH_KeyGen 9105 9106 16.4.1 General Description 9107 This command uses the TPM to generate an ephemeral key pair (de, Qe where Qe [de]G). It uses the private 9108 ephemeral key and a loaded public key (QS) to compute the shared secret value (P [hde]QS). 9109 9110 keyHandle shall refer to a loaded ECC key. The sensitive portion of this key need not be loaded. 9111 The curve parameters of the loaded ECC key are used to generate the ephemeral key. 9112 NOTE 1 9113 9114 This function is the equivalent of encrypting data to another objects public key. The seed value is 9115 used in a KDF to generate a symmetric key and that key is used to encrypt the data. Once the data 9116 is encrypted and the symmetric key discarded, only the ob ject with the private portion of the 9117 keyHandle will be able to decrypt it. 9118 9119 The zPoint in the response may be encrypted using parameter encryption. 9120 9121 Family 2.0 9122 Level 00 Revision 00.99 9123 9124 Published 9125 Copyright TCG 2006-2013 9126 9127 Page 101 9128 October 31, 2013 9129 9130 Part 3: Commands 9132 9133 Trusted Platform Module Library 9134 9135 16.4.2 Command and Response 9136 Table 47 TPM2_ECDH_KeyGen Command 9137 Type 9138 9139 Name 9140 9141 Description 9142 9143 TPMI_ST_COMMAND_TAG 9144 9145 tag 9146 9147 UINT32 9148 9149 commandSize 9150 9151 TPM_CC 9152 9153 commandCode 9154 9155 TPM_CC_ECDH_KeyGen 9156 9157 TPMI_DH_OBJECT 9158 9159 keyHandle 9160 9161 Handle of a loaded ECC key public area. 9162 Auth Index: None 9163 9164 Table 48 TPM2_ECDH_KeyGen Response 9165 Type 9166 9167 Name 9168 9169 Description 9170 9171 TPM_ST 9172 9173 tag 9174 9175 see clause 8 9176 9177 UINT32 9178 9179 responseSize 9180 9181 TPM_RC 9182 9183 responseCode 9184 9185 TPM2B_ECC_POINT 9186 9187 zPoint 9188 9189 results of P h[de]Qs 9190 9191 TPM2B_ECC_POINT 9192 9193 pubPoint 9194 9195 generated ephemeral public point (Qe) 9196 9197 Page 102 9198 October 31, 2013 9199 9200 Published 9201 Copyright TCG 2006-2013 9202 9203 Family 2.0 9204 Level 00 Revision 00.99 9205 9206 Trusted Platform Module Library 9208 9209 Part 3: Commands 9210 9211 16.4.3 Detailed Actions 9212 1 9213 2 9214 3 9215 9216 #include "InternalRoutines.h" 9217 #include "ECDH_KeyGen_fp.h" 9218 #ifdef TPM_ALG_ECC 9219 Error Returns 9220 TPM_RC_KEY 9221 9222 4 9223 5 9224 6 9225 7 9226 8 9227 9 9228 10 9229 11 9230 12 9231 13 9232 14 9233 15 9234 16 9235 17 9236 18 9237 19 9238 20 9239 21 9240 22 9241 23 9242 24 9243 25 9244 26 9245 27 9246 28 9247 29 9248 30 9249 31 9250 32 9251 33 9252 34 9253 35 9254 36 9255 37 9256 38 9257 39 9258 40 9259 41 9260 42 9261 43 9262 44 9263 45 9264 46 9265 47 9266 48 9267 49 9268 50 9269 51 9270 52 9271 53 9272 9273 Meaning 9274 keyHandle does not reference a non-restricted decryption ECC key 9275 9276 TPM_RC 9277 TPM2_ECDH_KeyGen( 9278 ECDH_KeyGen_In 9279 ECDH_KeyGen_Out 9280 9281 *in, 9282 *out 9283 9284 // IN: input parameter list 9285 // OUT: output parameter list 9286 9287 ) 9288 { 9289 OBJECT 9290 TPM2B_ECC_PARAMETER 9291 TPM_RC 9292 9293 *eccKey; 9294 sensitive; 9295 result; 9296 9297 // Input Validation 9298 eccKey = ObjectGet(in->keyHandle); 9299 // Input key must be a non-restricted, decrypt ECC key 9300 if( 9301 eccKey->publicArea.type != TPM_ALG_ECC 9302 || eccKey->publicArea.objectAttributes.restricted == SET 9303 || eccKey->publicArea.objectAttributes.decrypt != SET 9304 ) 9305 return TPM_RC_KEY + RC_ECDH_KeyGen_keyHandle; 9306 // Command Output 9307 do 9308 { 9309 // Create ephemeral ECC key 9310 CryptNewEccKey(eccKey->publicArea.parameters.eccDetail.curveID, 9311 &out->pubPoint.t.point, &sensitive); 9312 out->pubPoint.t.size = TPMS_ECC_POINT_Marshal(&out->pubPoint.t.point, 9313 NULL, NULL); 9314 // Compute Z 9315 result = CryptEccPointMultiply(&out->zPoint.t.point, 9316 eccKey->publicArea.parameters.eccDetail.curveID, 9317 &sensitive, &eccKey->publicArea.unique.ecc); 9318 // The point in the key is not on the curve. Indicate that the key is bad. 9319 if(result == TPM_RC_ECC_POINT) 9320 return TPM_RC_KEY + RC_ECDH_KeyGen_keyHandle; 9321 // The other possible error is TPM_RC_NO_RESULT indicating that the 9322 // multiplication resulted in the point at infinity, so get a new 9323 // random key and start over (hardly ever happens). 9324 } 9325 while(result != TPM_RC_SUCCESS); 9326 // Marshal the values to generate the point. 9327 out->zPoint.t.size = TPMS_ECC_POINT_Marshal(&out->zPoint.t.point, NULL, NULL); 9328 return TPM_RC_SUCCESS; 9329 } 9330 #endif 9331 9332 Family 2.0 9333 Level 00 Revision 00.99 9334 9335 Published 9336 Copyright TCG 2006-2013 9337 9338 Page 103 9339 October 31, 2013 9340 9341 Part 3: Commands 9343 9344 16.5 9345 9346 Trusted Platform Module Library 9347 9348 TPM2_ECDH_ZGen 9349 9350 16.5.1 General Description 9351 This command uses the TPM to recover the Z value from a public point (QB) and a private key (ds). It will 9352 perform the multiplication of the provided inPoint (QB) with the private key (ds) and return the coordinates 9353 of the resultant point (Z = (xZ , yZ) [hds]QB; where h is the cofactor of the curve). 9354 keyHandle shall refer to a loaded, ECC key (TPM_RC_KEY) with the restricted attribute CLEAR and the 9355 decrypt attribute SET (TPM_RC_ATTRIBUTES). 9356 The scheme of the key referenced by keyHandle is required to be either TPM_ALG_ECDH or 9357 TPM_ALG_NULL (TPM_RC_SCHEME). 9358 inPoint is required to be on the curve of the key referenced by keyHandle (TPM_RC_ECC_POINT). 9359 The parameters of the key referenced by keyHandle are used to perform the point multiplication. 9360 9361 Page 104 9362 October 31, 2013 9363 9364 Published 9365 Copyright TCG 2006-2013 9366 9367 Family 2.0 9368 Level 00 Revision 00.99 9369 9370 Trusted Platform Module Library 9372 9373 Part 3: Commands 9374 9375 16.5.2 Command and Response 9376 Table 49 TPM2_ECDH_ZGen Command 9377 Type 9378 9379 Name 9380 9381 Description 9382 9383 TPMI_ST_COMMAND_TAG 9384 9385 tag 9386 9387 UINT32 9388 9389 commandSize 9390 9391 TPM_CC 9392 9393 commandCode 9394 9395 TPM_CC_ECDH_ZGen 9396 9397 TPMI_DH_OBJECT 9398 9399 @keyHandle 9400 9401 handle of a loaded ECC key 9402 Auth Index: 1 9403 Auth Role: USER 9404 9405 TPM2B_ECC_POINT 9406 9407 inPoint 9408 9409 a public key 9410 9411 Table 50 TPM2_ECDH_ZGen Response 9412 Type 9413 9414 Name 9415 9416 Description 9417 9418 TPM_ST 9419 9420 tag 9421 9422 see clause 8 9423 9424 UINT32 9425 9426 responseSize 9427 9428 TPM_RC 9429 9430 responseCode 9431 9432 TPM2B_ECC_POINT 9433 9434 outPoint 9435 9436 Family 2.0 9437 Level 00 Revision 00.99 9438 9439 X and Y coordinates of the product of the multiplication 9440 9441 Z = (xZ , yZ) [hdS]QB 9442 9443 Published 9444 Copyright TCG 2006-2013 9445 9446 Page 105 9447 October 31, 2013 9448 9449 Part 3: Commands 9451 9452 Trusted Platform Module Library 9453 9454 16.5.3 Detailed Actions 9455 1 9456 2 9457 3 9458 9459 #include "InternalRoutines.h" 9460 #include "ECDH_ZGen_fp.h" 9461 #ifdef TPM_ALG_ECC 9462 Error Returns 9463 TPM_RC_KEY 9464 9465 keyHandle does not reference a non-restricted decryption ECC key 9466 9467 TPM_RC_ECC_POINT 9468 9469 invalid argument 9470 9471 TPM_RC_NO_RESULT 9472 4 9473 5 9474 6 9475 7 9476 8 9477 9 9478 10 9479 11 9480 12 9481 13 9482 14 9483 15 9484 16 9485 17 9486 18 9487 19 9488 20 9489 21 9490 22 9491 23 9492 24 9493 25 9494 26 9495 27 9496 28 9497 29 9498 30 9499 31 9500 32 9501 33 9502 34 9503 35 9504 36 9505 37 9506 38 9507 39 9508 9509 Meaning 9510 9511 multiplying inPoint resulted in a point at infinity 9512 9513 TPM_RC 9514 TPM2_ECDH_ZGen( 9515 ECDH_ZGen_In 9516 ECDH_ZGen_Out 9517 9518 *in, 9519 *out 9520 9521 // IN: input parameter list 9522 // OUT: output parameter list 9523 9524 ) 9525 { 9526 TPM_RC 9527 OBJECT 9528 9529 result; 9530 *eccKey; 9531 9532 // Input Validation 9533 eccKey = ObjectGet(in->keyHandle); 9534 // Input key must be a non-restricted, decrypt ECC key 9535 if( 9536 eccKey->publicArea.type != TPM_ALG_ECC 9537 || eccKey->publicArea.objectAttributes.restricted == SET 9538 || eccKey->publicArea.objectAttributes.decrypt != SET 9539 ) 9540 return TPM_RC_KEY + RC_ECDH_ZGen_keyHandle; 9541 // Command Output 9542 // Compute Z. TPM_RC_ECC_POINT or TPM_RC_NO_RESULT may be returned here. 9543 result = CryptEccPointMultiply(&out->outPoint.t.point, 9544 eccKey->publicArea.parameters.eccDetail.curveID, 9545 &eccKey->sensitive.sensitive.ecc, 9546 &in->inPoint.t.point); 9547 if(result != TPM_RC_SUCCESS) 9548 return RcSafeAddToResult(result, RC_ECDH_ZGen_inPoint); 9549 out->outPoint.t.size = TPMS_ECC_POINT_Marshal(&out->outPoint.t.point, 9550 NULL, NULL); 9551 return TPM_RC_SUCCESS; 9552 } 9553 #endif 9554 9555 Page 106 9556 October 31, 2013 9557 9558 Published 9559 Copyright TCG 2006-2013 9560 9561 Family 2.0 9562 Level 00 Revision 00.99 9563 9564 Trusted Platform Module Library 9566 9567 16.6 9568 9569 Part 3: Commands 9570 9571 TPM2_ECC_Parameters 9572 9573 16.6.1 General Description 9574 This command returns the parameters of an ECC curve identified by its TCG-assigned curveID. 9575 16.6.2 Command and Response 9576 Table 51 TPM2_ECC_Parameters Command 9577 Type 9578 9579 Name 9580 9581 Description 9582 9583 TPMI_ST_COMMAND_TAG 9584 9585 tag 9586 9587 UINT32 9588 9589 commandSize 9590 9591 TPM_CC 9592 9593 commandCode 9594 9595 TPM_CC_ECC_Parameters 9596 9597 TPMI_ECC_CURVE 9598 9599 curveID 9600 9601 parameter set selector 9602 9603 Table 52 TPM2_ECC_Parameters Response 9604 Type 9605 9606 Name 9607 9608 Description 9609 9610 TPM_ST 9611 9612 tag 9613 9614 see clause 8 9615 9616 UINT32 9617 9618 responseSize 9619 9620 TPM_RC 9621 9622 responseCode 9623 9624 TPMS_ALGORITHM_DETAIL_ECC 9625 9626 parameters 9627 9628 Family 2.0 9629 Level 00 Revision 00.99 9630 9631 ECC parameters for the selected curve 9632 9633 Published 9634 Copyright TCG 2006-2013 9635 9636 Page 107 9637 October 31, 2013 9638 9639 Part 3: Commands 9641 9642 Trusted Platform Module Library 9643 9644 16.6.3 Detailed Actions 9645 1 9646 2 9647 3 9648 9649 #include "InternalRoutines.h" 9650 #include "ECC_Parameters_fp.h" 9651 #ifdef TPM_ALG_ECC 9652 Error Returns 9653 TPM_RC_VALUE 9654 9655 4 9656 5 9657 6 9658 7 9659 8 9660 9 9661 10 9662 11 9663 12 9664 13 9665 14 9666 15 9667 16 9668 17 9669 18 9670 9671 Meaning 9672 Unsupported ECC curve ID 9673 9674 TPM_RC 9675 TPM2_ECC_Parameters( 9676 ECC_Parameters_In 9677 ECC_Parameters_Out 9678 9679 *in, 9680 *out 9681 9682 // IN: input parameter list 9683 // OUT: output parameter list 9684 9685 ) 9686 { 9687 // Command Output 9688 // Get ECC curve parameters 9689 if(CryptEccGetParameters(in->curveID, &out->parameters)) 9690 return TPM_RC_SUCCESS; 9691 else 9692 return TPM_RC_VALUE + RC_ECC_Parameters_curveID; 9693 } 9694 #endif 9695 9696 16.7 9697 16.7.1 9698 9699 TPM2_ZGen_2Phase 9700 General Description 9701 9702 This command supports two-phase key exchange protocols. The command is used in combination with 9703 TPM2_EC_Ephemeral(). TPM2_EC_Ephemeral() generates an ephemeral key and returns the public 9704 point of that ephemeral key along with a numeric value that allows the TPM to regenerate the associated 9705 private key. 9706 The input parameters for this command are a static public key (inQsU), an ephemeral key (inQeU) from 9707 party B, and the commitCounter returned by TPM2_EC_Ephemeral(). The TPM uses the counter value to 9708 regenerate the ephemeral private key (de,V) and the associated public key (Qe,V). keyA provides the static 9709 ephemeral elements ds,V and Qs,V. This provides the two pairs of ephemeral and static keys that are 9710 required for the schemes supported by this command. 9711 The TPM will compute Z or Zs and Ze according to the selected scheme. If the scheme is not a two-phase 9712 key exchange scheme or if the scheme is not supported, the TPM will return TPM_RC_SCHEME. 9713 It is an error if inQsB or inQeB are not on the curve of keyA (TPM_RC_ECC_POINT). 9714 The two-phase key schemes that were assigned an algorithm ID as of the time of the publication of this 9715 specification are TPM_ALG_ECDH, TPM_ALG_ECMQV, and TPM_ALG_SM2. 9716 If this command is supported, then support for TPM_ALG_ECDH is required. Support for 9717 TPM_ALG_ECMQV or TPM_ALG_SM2 is optional. 9718 NOTE 1 9719 9720 If SM2 is supported and this command is supported, then the implementation is required to support 9721 the key exchange protocol of SM2, part 3. 9722 9723 For TPM_ALG_ECDH outZ1 will be Zs and outZ2 will Ze as defined in 6.1.1.2 of SP800-56A. 9724 9725 Page 108 9726 October 31, 2013 9727 9728 Published 9729 Copyright TCG 2006-2013 9730 9731 Family 2.0 9732 Level 00 Revision 00.99 9733 9734 Trusted Platform Module Library 9736 NOTE 2 9737 9738 Part 3: Commands 9739 9740 A non-restricted decryption key using ECDH may be used in either TPM2_ECDH_ZGen() or 9741 TPM2_ZGen_2Phase as the computation done with the private part of keyA is the same in both 9742 cases. 9743 9744 For TPM_ALG_ECMQV or TPM_ALG_SM2 outZ1 will be Z and outZ2 will be an Empty Point. 9745 NOTE 3 9746 9747 An Empty Point has two Empty Buffers as coordinates meaning the minimum size value for outZ2 9748 will be four. 9749 9750 If the input scheme is TPM_ALG_ECDH, then outZ1 will be Zs and outZ2 will be Ze. For schemes like 9751 MQV (including SM2), outZ1 will contain the computed value and outZ2 will be an Empty Point. 9752 NOTE 9753 9754 The Z values returned by the TPM are a full point and not ju st an x-coordinate. 9755 9756 If a computation of either Z produces the point at infinity, then the corresponding Z value will be an Empty 9757 Point. 9758 9759 Family 2.0 9760 Level 00 Revision 00.99 9761 9762 Published 9763 Copyright TCG 2006-2013 9764 9765 Page 109 9766 October 31, 2013 9767 9768 Part 3: Commands 9770 9771 16.7.2 9772 9773 Trusted Platform Module Library 9774 9775 Command and Response 9776 Table 53 TPM2_ZGen_2Phase Command 9777 9778 Type 9779 9780 Name 9781 9782 TPMI_ST_COMMAND_TAG 9783 9784 tag 9785 9786 UINT32 9787 9788 commandSize 9789 9790 TPM_CC 9791 9792 commandCode 9793 9794 Description 9795 9796 TPM_CC_ZGen_2Phase 9797 handle of an unrestricted decryption key ECC 9798 The private key referenced by this handle is used as dS,A 9799 9800 TPMI_DH_OBJECT 9801 9802 @keyA 9803 9804 TPM2B_ECC_POINT 9805 9806 inQsB 9807 9808 other partys static public key (Qs,B = (Xs,B, Ys,B)) 9809 9810 TPM2B_ECC_POINT 9811 9812 inQeB 9813 9814 other party's ephemeral public key (Qe,B = (Xe,B, Ye,B)) 9815 9816 TPMI_ECC_KEY_EXCHANGE 9817 9818 inScheme 9819 9820 the key exchange scheme 9821 9822 UINT16 9823 9824 counter 9825 9826 value returned by TPM2_EC_Ephemeral() 9827 9828 Auth Index: 1 9829 Auth Role: USER 9830 9831 Table 54 TPM2_ZGen_2Phase Response 9832 Type 9833 9834 Name 9835 9836 TPM_ST 9837 9838 tag 9839 9840 UINT32 9841 9842 responseSize 9843 9844 TPM_RC 9845 9846 responseCode 9847 9848 TPM2B_ECC_POINT 9849 9850 outZ1 9851 9852 X and Y coordinates of the computed value (scheme 9853 dependent) 9854 9855 TPM2B_ECC_POINT 9856 9857 outZ2 9858 9859 X and Y coordinates of the second computed value 9860 (scheme dependent) 9861 9862 Page 110 9863 October 31, 2013 9864 9865 Description 9866 9867 Published 9868 Copyright TCG 2006-2013 9869 9870 Family 2.0 9871 Level 00 Revision 00.99 9872 9873 Trusted Platform Module Library 9875 9876 16.7.3 9877 1 9878 2 9879 3 9880 9881 Part 3: Commands 9882 9883 Detailed Actions 9884 9885 #include "InternalRoutines.h" 9886 #include "ZGen_2Phase_fp.h" 9887 #if defined TPM_ALG_ECC && (CC_ZGen_2Phase == YES) 9888 9889 This command uses the TPM to recover one or two Z values in a two phase key exchange protocol 9890 Error Returns 9891 TPM_RC_ATTRIBUTES 9892 9893 key referenced by keyA is restricted or not a decrypt key 9894 9895 TPM_RC_ECC_POINT 9896 9897 inQsB or inQeB is not on the curve of the key reference by keyA 9898 9899 TPM_RC_KEY 9900 9901 key referenced by keyA is not an ECC key 9902 9903 TPM_RC_SCHEME 9904 9905 4 9906 5 9907 6 9908 7 9909 8 9910 9 9911 10 9912 11 9913 12 9914 13 9915 14 9916 15 9917 16 9918 17 9919 18 9920 19 9921 20 9922 21 9923 22 9924 23 9925 24 9926 25 9927 26 9928 27 9929 28 9930 29 9931 30 9932 31 9933 32 9934 33 9935 34 9936 35 9937 36 9938 37 9939 38 9940 39 9941 40 9942 41 9943 42 9944 43 9945 44 9946 45 9947 46 9948 47 9949 9950 Meaning 9951 9952 the scheme of the key referenced by keyA is not TPM_ALG_NULL, 9953 TPM_ALG_ECDH, TPM_ALG_ECMQV or TPM_ALG_SM2 9954 9955 TPM_RC 9956 TPM2_ZGen_2Phase( 9957 ZGen_2Phase_In 9958 ZGen_2Phase_Out 9959 9960 *in, 9961 *out 9962 9963 // IN: input parameter list 9964 // OUT: output parameter list 9965 9966 ) 9967 { 9968 TPM_RC 9969 OBJECT 9970 TPM2B_ECC_PARAMETER 9971 TPM_ALG_ID 9972 9973 result; 9974 *eccKey; 9975 r; 9976 scheme; 9977 9978 // Input Validation 9979 eccKey = ObjectGet(in->keyA); 9980 // keyA must be an ECC key 9981 if(eccKey->publicArea.type != TPM_ALG_ECC) 9982 return TPM_RC_KEY + RC_ZGen_2Phase_keyA; 9983 // keyA must not be restricted and must be a decrypt key 9984 if( 9985 eccKey->publicArea.objectAttributes.restricted == SET 9986 || eccKey->publicArea.objectAttributes.decrypt != SET 9987 ) 9988 return TPM_RC_ATTRIBUTES + RC_ZGen_2Phase_keyA; 9989 // if the scheme of keyA is TPM_ALG_NULL, then use the input scheme; otherwise 9990 // the input scheme must be the same as the scheme of keyA 9991 scheme = eccKey->publicArea.parameters.asymDetail.scheme.scheme; 9992 if(scheme != TPM_ALG_NULL) 9993 { 9994 if(scheme != in->inScheme) 9995 return TPM_RC_SCHEME + RC_ZGen_2Phase_inScheme; 9996 } 9997 else 9998 scheme = in->inScheme; 9999 if(scheme == TPM_ALG_NULL) 10000 return TPM_RC_SCHEME + RC_ZGen_2Phase_inScheme; 10001 // Input points must be on the curve of keyA 10002 if(!CryptEccIsPointOnCurve(eccKey->publicArea.parameters.eccDetail.curveID, 10003 &in->inQsB.t.point)) 10004 return TPM_RC_ECC_POINT + RC_ZGen_2Phase_inQsB; 10005 if(!CryptEccIsPointOnCurve(eccKey->publicArea.parameters.eccDetail.curveID, 10006 10007 Family 2.0 10008 Level 00 Revision 00.99 10009 10010 Published 10011 Copyright TCG 2006-2013 10012 10013 Page 111 10014 October 31, 2013 10015 10016 Part 3: Commands 10018 48 10019 49 10020 50 10021 51 10022 52 10023 53 10024 54 10025 55 10026 56 10027 57 10028 58 10029 59 10030 60 10031 61 10032 62 10033 63 10034 64 10035 65 10036 66 10037 67 10038 68 10039 69 10040 70 10041 71 10042 72 10043 73 10044 10045 Trusted Platform Module Library 10046 10047 &in->inQeB.t.point)) 10048 return TPM_RC_ECC_POINT + RC_ZGen_2Phase_inQeB; 10049 if(!CryptGenerateR(&r, &in->counter, 10050 eccKey->publicArea.parameters.eccDetail.curveID, 10051 NULL)) 10052 return TPM_RC_VALUE + RC_ZGen_2Phase_counter; 10053 // Command Output 10054 result = CryptEcc2PhaseKeyExchange(&out->outZ1.t.point, 10055 &out->outZ2.t.point, 10056 eccKey->publicArea.parameters.eccDetail.curveID, 10057 scheme, 10058 &eccKey->sensitive.sensitive.ecc, 10059 &r, 10060 &in->inQsB.t.point, 10061 &in->inQeB.t.point); 10062 if(result != TPM_RC_SUCCESS) 10063 return result; 10064 CryptEndCommit(in->counter); 10065 return TPM_RC_SUCCESS; 10066 } 10067 #endif 10068 10069 Page 112 10070 October 31, 2013 10071 10072 Published 10073 Copyright TCG 2006-2013 10074 10075 Family 2.0 10076 Level 00 Revision 00.99 10077 10078 Trusted Platform Module Library 10080 10081 17 10082 17.1 10083 10084 Part 3: Commands 10085 10086 Symmetric Primitives 10087 Introduction 10088 10089 The commands in this clause provide low-level primitives for access to the symmetric algorithms 10090 implemented in the TPM that operate on blocks of data. These include symmetric encryption and 10091 decryption as well as hash and HMAC. All of the commands in this group are stateless. That is, they have 10092 no persistent state that is retained in the TPM when the command is complete. 10093 For hashing, HMAC, and Events that require large blocks of data with retained state, the sequence 10094 commands are provided (see clause 1). 10095 Some of the symmetric encryption/decryption modes use an IV. When an IV is used, it may be an 10096 initiation value or a chained value from a previous stage. The chaining for each mode is: 10097 10098 Family 2.0 10099 Level 00 Revision 00.99 10100 10101 Published 10102 Copyright TCG 2006-2013 10103 10104 Page 113 10105 October 31, 2013 10106 10107 Part 3: Commands 10109 10110 Trusted Platform Module Library 10111 Table 55 Symmetric Chaining Process 10112 10113 Mode 10114 10115 Chaining process 10116 10117 TPM_ALG_CTR 10118 10119 The TPM will increment the entire IV provided by the caller. The last encrypted value will be 10120 returned to the caller as ivOut. This can be the input value to the next encrypted buffer. 10121 ivIn is required to be the size of a block encrypted by the selected algorithm and key 10122 combination. If the size of ivIn is not correct, the TPM shall return TPM_RC_SIZE. 10123 EXAMPLE 1 AES requires that ivIn be 128 bits (16 octets). 10124 10125 ivOut will be the size of a cipher block and not the size of the last encrypted block. 10126 NOTE 10127 10128 ivOut will be the value of the counter after the last block is encrypted. 10129 10130 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 10131 were encrypted, ivOut will have a value of 10132 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0416. 10133 10134 All the bits of the IV are incremented as if it were an unsigned integer. 10135 TPM_ALG_OFB 10136 10137 In Output Feedback (OFB), the output of the pseudo-random function (the block encryption 10138 algorithm) is XORed with a plaintext block to produce a ciphertext block. ivOut will be the 10139 value that was XORed with the last plaintext block. That value can be used as the ivIn for a 10140 next buffer. 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 ivOut will be the size of a cipher block and not the size of the last encrypted block. 10144 10145 TPM_ALG_CBC 10146 10147 For Cipher Block Chaining (CBC), a block of ciphertext is XORed with the next plaintext 10148 block and that block is encrypted. The encrypted block is then input to the encryption of the 10149 next block. The last ciphertext block then is used as an IV for the next buffer. 10150 Even though the last ciphertext block is evident in the encrypted data, it is also returned in 10151 ivOut. 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 inData is required to be an even multiple of the block encrypted by the selected algorithm 10155 and key combination. If the size of inData is not correct, the TPM shall return 10156 TPM_RC_SIZE. 10157 10158 TPM_ALG_CFB 10159 10160 Similar to CBC in that the last ciphertext block is an input to the encryption of the next block. 10161 ivOut will be the value that was XORed with the last plaintext block. That value can be used 10162 as the ivIn for a next buffer. 10163 ivIn is required to be the size of a block encrypted by the selected algorithm and key 10164 combination. If the size of ivIn is not correct, the TPM shall return TPM_RC_SIZE. 10165 ivOut will be the size of a cipher block and not the size of the last encrypted block. 10166 10167 TPM_ALG_ECB 10168 10169 Electronic Codebook (ECB) has no chaining. Each block of plaintext is encrypted using the 10170 key. ECB does not support chaining and ivIn shall be the Empty Buffer. ivOut will be the 10171 Empty Buffer. 10172 inData is required to be an even multiple of the block encrypted by the selected algorithm 10173 and key combination. If the size of inData is not correct, the TPM shall return 10174 TPM_RC_SIZE. 10175 10176 Page 114 10177 October 31, 2013 10178 10179 Published 10180 Copyright TCG 2006-2013 10181 10182 Family 2.0 10183 Level 00 Revision 00.99 10184 10185 Trusted Platform Module Library 10187 10188 17.2 10189 10190 Part 3: Commands 10191 10192 TPM2_EncryptDecrypt 10193 10194 17.2.1 General Description 10195 This command performs symmetric encryption or decryption. 10196 keyHandle shall reference a symmetric cipher object (TPM_RC_KEY). 10197 For a restricted key, mode shall be either the same as the mode of the key, or TPM_ALG_NULL 10198 (TPM_RC_VALUE). For an unrestricted key, mode may be the same or different from the mode of the key 10199 but both shall not be TPM_ALG_NULL (TPM_RC_VALUE). 10200 If the TPM allows this command to be canceled before completion, then the TPM may produce 10201 incremental results and return TPM_RC_SUCCESS rather than TPM_RC_CANCEL. In such case, 10202 outData may be less than inData. 10203 10204 Family 2.0 10205 Level 00 Revision 00.99 10206 10207 Published 10208 Copyright TCG 2006-2013 10209 10210 Page 115 10211 October 31, 2013 10212 10213 Part 3: Commands 10215 10216 Trusted Platform Module Library 10217 10218 17.2.2 Command and Response 10219 Table 56 TPM2_EncryptDecrypt Command 10220 Type 10221 10222 Name 10223 10224 Description 10225 10226 TPMI_ST_COMMAND_TAG 10227 10228 tag 10229 10230 UINT32 10231 10232 commandSize 10233 10234 TPM_CC 10235 10236 commandCode 10237 10238 TPM_CC_EncryptDecrypt 10239 10240 TPMI_DH_OBJECT 10241 10242 @keyHandle 10243 10244 the symmetric key used for the operation 10245 Auth Index: 1 10246 Auth Role: USER 10247 10248 TPMI_YES_NO 10249 10250 decrypt 10251 10252 if YES, then the operation is decryption; if NO, the 10253 operation is encryption 10254 10255 TPMI_ALG_SYM_MODE+ 10256 10257 mode 10258 10259 symmetric mode 10260 For a restricted key, this field shall match the default 10261 mode of the key or be TPM_ALG_NULL. 10262 10263 TPM2B_IV 10264 10265 ivIn 10266 10267 an initial value as required by the algorithm 10268 10269 TPM2B_MAX_BUFFER 10270 10271 inData 10272 10273 the data to be encrypted/decrypted 10274 10275 Table 57 TPM2_EncryptDecrypt Response 10276 Type 10277 10278 Name 10279 10280 Description 10281 10282 TPM_ST 10283 10284 tag 10285 10286 see clause 8 10287 10288 UINT32 10289 10290 responseSize 10291 10292 TPM_RC 10293 10294 responseCode 10295 10296 TPM2B_MAX_BUFFER 10297 10298 outData 10299 10300 encrypted output 10301 10302 TPM2B_IV 10303 10304 ivOut 10305 10306 chaining value to use for IV in next round 10307 10308 Page 116 10309 October 31, 2013 10310 10311 Published 10312 Copyright TCG 2006-2013 10313 10314 Family 2.0 10315 Level 00 Revision 00.99 10316 10317 Trusted Platform Module Library 10319 10320 Part 3: Commands 10321 10322 17.2.3 Detailed Actions 10323 1 10324 2 10325 10326 #include "InternalRoutines.h" 10327 #include "EncryptDecrypt_fp.h" 10328 Error Returns 10329 TPM_RC_KEY 10330 10331 is not a symmetric decryption key with both public and private 10332 portions loaded 10333 10334 TPM_RC_SIZE 10335 10336 IvIn size is incompatible with the block cipher mode; or inData size is 10337 not an even multiple of the block size for CBC or ECB mode 10338 10339 TPM_RC_VALUE 10340 10341 3 10342 4 10343 5 10344 6 10345 7 10346 8 10347 9 10348 10 10349 11 10350 12 10351 13 10352 14 10353 15 10354 16 10355 17 10356 18 10357 19 10358 20 10359 21 10360 22 10361 23 10362 24 10363 25 10364 26 10365 27 10366 28 10367 29 10368 30 10369 31 10370 32 10371 33 10372 34 10373 35 10374 36 10375 37 10376 38 10377 39 10378 40 10379 41 10380 42 10381 43 10382 44 10383 45 10384 46 10385 47 10386 48 10387 10388 Meaning 10389 10390 keyHandle is restricted and the argument mode does not match the 10391 key's mode 10392 10393 TPM_RC 10394 TPM2_EncryptDecrypt( 10395 EncryptDecrypt_In 10396 EncryptDecrypt_Out 10397 10398 *in, 10399 *out 10400 10401 // IN: input parameter list 10402 // OUT: output parameter list 10403 10404 ) 10405 { 10406 OBJECT 10407 UINT16 10408 UINT16 10409 BYTE 10410 TPM_ALG_ID 10411 10412 *symKey; 10413 keySize; 10414 blockSize; 10415 *key; 10416 alg; 10417 10418 // Input Validation 10419 symKey = ObjectGet(in->keyHandle); 10420 // The input key should be a symmetric decrypt key. 10421 if( 10422 symKey->publicArea.type != TPM_ALG_SYMCIPHER 10423 || symKey->attributes.publicOnly == SET) 10424 return TPM_RC_KEY + RC_EncryptDecrypt_keyHandle; 10425 // If the input mode is TPM_ALG_NULL, use the key's mode 10426 if( in->mode == TPM_ALG_NULL) 10427 in->mode = symKey->publicArea.parameters.symDetail.sym.mode.sym; 10428 // If the key is restricted, the input sym mode should match the key's sym 10429 // mode 10430 if( 10431 symKey->publicArea.objectAttributes.restricted == SET 10432 && symKey->publicArea.parameters.symDetail.sym.mode.sym != in->mode) 10433 return TPM_RC_VALUE + RC_EncryptDecrypt_mode; 10434 // If the mode is null, then we have a problem. 10435 // Note: Construction of a TPMT_SYM_DEF does not allow the 'mode' to be 10436 // TPM_ALG_NULL so setting in->mode to the mode of the key should have 10437 // produced a valid mode. However, this is suspenders. 10438 if(in->mode == TPM_ALG_NULL) 10439 return TPM_RC_VALUE + RC_EncryptDecrypt_mode; 10440 // The input iv for ECB mode should be null. All the other modes should 10441 // have an iv size same as encryption block size 10442 keySize = symKey->publicArea.parameters.symDetail.sym.keyBits.sym; 10443 alg = symKey->publicArea.parameters.symDetail.sym.algorithm; 10444 blockSize = CryptGetSymmetricBlockSize(alg, keySize); 10445 if( 10446 (in->mode == TPM_ALG_ECB && in->ivIn.t.size != 0) 10447 || (in->mode != TPM_ALG_ECB && in->ivIn.t.size != blockSize)) 10448 return TPM_RC_SIZE + RC_EncryptDecrypt_ivIn; 10449 10450 Family 2.0 10451 Level 00 Revision 00.99 10452 10453 Published 10454 Copyright TCG 2006-2013 10455 10456 Page 117 10457 October 31, 2013 10458 10459 Part 3: Commands 10461 49 10462 50 10463 51 10464 52 10465 53 10466 54 10467 55 10468 56 10469 57 10470 58 10471 59 10472 60 10473 61 10474 62 10475 63 10476 64 10477 65 10478 66 10479 67 10480 68 10481 69 10482 70 10483 71 10484 72 10485 73 10486 74 10487 75 10488 76 10489 77 10490 78 10491 79 10492 80 10493 81 10494 82 10495 83 10496 84 10497 85 10498 86 10499 87 10500 88 10501 89 10502 90 10503 91 10504 10505 Trusted Platform Module Library 10506 10507 // The input data size of CBC mode or ECB mode must be an even multiple of 10508 // the symmetric algorithm's block size 10509 if( 10510 (in->mode == TPM_ALG_CBC || in->mode == TPM_ALG_ECB) 10511 && (in->inData.t.size % blockSize) != 0) 10512 return TPM_RC_SIZE + RC_EncryptDecrypt_inData; 10513 // Copy IV 10514 // Note: This is copied here so that the calls to the encrypt/decrypt functions 10515 // will modify the output buffer, not the input buffer 10516 out->ivOut = in->ivIn; 10517 // Command Output 10518 key = symKey->sensitive.sensitive.sym.t.buffer; 10519 // For symmetric encryption, the cipher data size is the same as plain data 10520 // size. 10521 out->outData.t.size = in->inData.t.size; 10522 if(in->decrypt == YES) 10523 { 10524 // Decrypt data to output 10525 CryptSymmetricDecrypt(out->outData.t.buffer, 10526 alg, 10527 keySize, in->mode, key, 10528 &(out->ivOut), 10529 in->inData.t.size, 10530 in->inData.t.buffer); 10531 } 10532 else 10533 { 10534 // Encrypt data to output 10535 CryptSymmetricEncrypt(out->outData.t.buffer, 10536 alg, 10537 keySize, 10538 in->mode, key, 10539 &(out->ivOut), 10540 in->inData.t.size, 10541 in->inData.t.buffer); 10542 } 10543 return TPM_RC_SUCCESS; 10544 } 10545 10546 Page 118 10547 October 31, 2013 10548 10549 Published 10550 Copyright TCG 2006-2013 10551 10552 Family 2.0 10553 Level 00 Revision 00.99 10554 10555 Trusted Platform Module Library 10557 10558 17.3 10559 10560 Part 3: Commands 10561 10562 TPM2_Hash 10563 10564 17.3.1 General Description 10565 This command performs a hash operation on a data buffer and returns the results. 10566 NOTE 10567 10568 If the data buffer to be hashed is larger than will fit into the TPMs input buffer, then the sequence 10569 hash commands will need to be used. 10570 10571 If the results of the hash will be used in a signing operation that uses a restricted signing key, then the 10572 ticket returned by this command can indicate that the hash is safe to sign. 10573 If the digest is not safe to sign, then the TPM will return a TPMT_TK_HASHCHECK with the hierarchy set 10574 to TPM_RH_NULL and digest set to the Empty Buffer. 10575 If hierarchy is TPM_RH_NULL, then digest in the ticket will be the Empty Buffer. 10576 10577 Family 2.0 10578 Level 00 Revision 00.99 10579 10580 Published 10581 Copyright TCG 2006-2013 10582 10583 Page 119 10584 October 31, 2013 10585 10586 Part 3: Commands 10588 10589 Trusted Platform Module Library 10590 10591 17.3.2 Command and Response 10592 Table 58 TPM2_Hash Command 10593 Type 10594 10595 Name 10596 10597 Description 10598 10599 TPMI_ST_COMMAND_TAG 10600 10601 tag 10602 10603 Shall have at least one session 10604 10605 UINT32 10606 10607 commandSize 10608 10609 TPM_CC 10610 10611 commandCode 10612 10613 TPM_CC_Hash 10614 10615 TPM2B_MAX_BUFFER 10616 10617 data 10618 10619 data to be hashed 10620 10621 TPMI_ALG_HASH 10622 10623 hashAlg 10624 10625 algorithm for the hash being computed shall not be 10626 TPM_ALG_NULL 10627 10628 TPMI_RH_HIERARCHY+ 10629 10630 hierarchy 10631 10632 hierarchy to use for the ticket (TPM_RH_NULL allowed) 10633 10634 Table 59 TPM2_Hash Response 10635 Type 10636 10637 Name 10638 10639 Description 10640 10641 TPM_ST 10642 10643 tag 10644 10645 see clause 8 10646 10647 UINT32 10648 10649 responseSize 10650 10651 TPM_RC 10652 10653 responseCode 10654 10655 TPM2B_DIGEST 10656 10657 outHash 10658 10659 results 10660 10661 TPMT_TK_HASHCHECK 10662 10663 validation 10664 10665 ticket indicating that the sequence of octets used to 10666 compute outDigest did not start with 10667 TPM_GENERATED_VALUE 10668 will be a NULL ticket if the digest may not be signed 10669 with a restricted key 10670 10671 Page 120 10672 October 31, 2013 10673 10674 Published 10675 Copyright TCG 2006-2013 10676 10677 Family 2.0 10678 Level 00 Revision 00.99 10679 10680 Trusted Platform Module Library 10682 10683 Part 3: Commands 10684 10685 17.3.3 Detailed Actions 10686 1 10687 2 10688 3 10689 4 10690 5 10691 6 10692 7 10693 8 10694 9 10695 10 10696 11 10697 12 10698 13 10699 14 10700 15 10701 16 10702 17 10703 18 10704 19 10705 20 10706 21 10707 22 10708 23 10709 24 10710 25 10711 26 10712 27 10713 28 10714 29 10715 30 10716 31 10717 32 10718 33 10719 34 10720 35 10721 36 10722 37 10723 38 10724 39 10725 40 10726 41 10727 42 10728 43 10729 44 10730 45 10731 10732 #include "InternalRoutines.h" 10733 #include "Hash_fp.h" 10734 10735 TPM_RC 10736 TPM2_Hash( 10737 Hash_In 10738 Hash_Out 10739 10740 *in, 10741 *out 10742 10743 // IN: input parameter list 10744 // OUT: output parameter list 10745 10746 ) 10747 { 10748 HASH_STATE 10749 10750 hashState; 10751 10752 // Command Output 10753 // Output hash 10754 // Start hash stack 10755 out->outHash.t.size = CryptStartHash(in->hashAlg, &hashState); 10756 // Adding hash data 10757 CryptUpdateDigest2B(&hashState, &in->data.b); 10758 // Complete hash 10759 CryptCompleteHash2B(&hashState, &out->outHash.b); 10760 // Output ticket 10761 out->validation.tag = TPM_ST_HASHCHECK; 10762 out->validation.hierarchy = in->hierarchy; 10763 if(in->hierarchy == TPM_RH_NULL) 10764 { 10765 // Ticket is not required 10766 out->validation.hierarchy = TPM_RH_NULL; 10767 out->validation.digest.t.size = 0; 10768 } 10769 else if( in->data.t.size >= sizeof(TPM_GENERATED) 10770 && !TicketIsSafe(&in->data.b)) 10771 { 10772 // Ticket is not safe 10773 out->validation.hierarchy = TPM_RH_NULL; 10774 out->validation.digest.t.size = 0; 10775 } 10776 else 10777 { 10778 // Compute ticket 10779 TicketComputeHashCheck(in->hierarchy, &out->outHash, &out->validation); 10780 } 10781 return TPM_RC_SUCCESS; 10782 } 10783 10784 Family 2.0 10785 Level 00 Revision 00.99 10786 10787 Published 10788 Copyright TCG 2006-2013 10789 10790 Page 121 10791 October 31, 2013 10792 10793 Part 3: Commands 10795 10796 17.4 10797 10798 Trusted Platform Module Library 10799 10800 TPM2_HMAC 10801 10802 17.4.1 General Description 10803 This command performs an HMAC on the supplied data using the indicated hash algorithm. 10804 The caller shall provide proper authorization for use of handle. 10805 If the sign attribute is not SET in the key referenced by handle then the TPM shall return 10806 TPM_RC_ATTRIBUTES. If the key type is not TPM_ALG_KEYEDHASH then the TPM shall return 10807 TPM_RC_TYPE. 10808 If handle references a restricted key, then the hash algorithm specified in the key's scheme is used as the 10809 hash algorithm for the HMAC and the TPM shall return TPM_RC_VALUE if hashAlg is not 10810 TPM_ALG_NULL or the same algorithm as selected in the key's scheme. 10811 NOTE 1 10812 A restricted key may only have one of sign or decrypt SET and the default scheme may not 10813 be TPM_ALG_NULL. These restrictions are enforced by TPM2_Create() and TPM2_CreatePrimary(), 10814 If the key referenced by handle is not restricted, then the TPM will use hashAlg for the HMAC. However, if 10815 hashAlg is TPM_ALG_NULL the TPM will use the default scheme of the key. 10816 If both hashAlg and the key default are TPM_ALG_NULL, the TPM shall return TPM_RC_VALUE. 10817 NOTE 10818 10819 A key may only have both sign and decrypt SET if the key is unrestricted. When bo th sign and 10820 decrypt are set, there is no default scheme for the key and the hash algorithm must be specified . 10821 10822 Page 122 10823 October 31, 2013 10824 10825 Published 10826 Copyright TCG 2006-2013 10827 10828 Family 2.0 10829 Level 00 Revision 00.99 10830 10831 Trusted Platform Module Library 10833 10834 Part 3: Commands 10835 10836 17.4.2 Command and Response 10837 Table 60 TPM2_HMAC Command 10838 Type 10839 10840 Name 10841 10842 Description 10843 10844 TPMI_ST_COMMAND_TAG 10845 10846 tag 10847 10848 UINT32 10849 10850 commandSize 10851 10852 TPM_CC 10853 10854 commandCode 10855 10856 TPM_CC_HMAC 10857 10858 TPMI_DH_OBJECT 10859 10860 @handle 10861 10862 handle for the symmetric signing key providing the 10863 HMAC key 10864 Auth Index: 1 10865 Auth Role: USER 10866 10867 TPM2B_MAX_BUFFER 10868 10869 buffer 10870 10871 HMAC data 10872 10873 TPMI_ALG_HASH+ 10874 10875 hashAlg 10876 10877 algorithm to use for HMAC 10878 10879 Table 61 TPM2_HMAC Response 10880 Type 10881 10882 Name 10883 10884 Description 10885 10886 TPM_ST 10887 10888 tag 10889 10890 see clause 8 10891 10892 UINT32 10893 10894 responseSize 10895 10896 TPM_RC 10897 10898 responseCode 10899 10900 TPM2B_DIGEST 10901 10902 outHMAC 10903 10904 Family 2.0 10905 Level 00 Revision 00.99 10906 10907 the returned HMAC in a sized buffer 10908 10909 Published 10910 Copyright TCG 2006-2013 10911 10912 Page 123 10913 October 31, 2013 10914 10915 Part 3: Commands 10917 10918 Trusted Platform Module Library 10919 10920 17.4.3 Detailed Actions 10921 1 10922 2 10923 10924 #include "InternalRoutines.h" 10925 #include "HMAC_fp.h" 10926 Error Returns 10927 TPM_RC_ATTRIBUTES 10928 10929 key referenced by handle is not a signing key 10930 10931 TPM_RC_TYPE 10932 10933 key referenced by handle is not an HMAC key 10934 10935 TPM_RC_VALUE 10936 10937 3 10938 4 10939 5 10940 6 10941 7 10942 8 10943 9 10944 10 10945 11 10946 12 10947 13 10948 14 10949 15 10950 16 10951 17 10952 18 10953 19 10954 20 10955 21 10956 22 10957 23 10958 24 10959 25 10960 26 10961 27 10962 28 10963 29 10964 30 10965 31 10966 32 10967 33 10968 34 10969 35 10970 36 10971 37 10972 38 10973 39 10974 40 10975 41 10976 42 10977 43 10978 44 10979 45 10980 46 10981 47 10982 48 10983 49 10984 10985 Meaning 10986 10987 hashAlg specified when the key is restricted is neither 10988 TPM_ALG_NULL not equal to that of the key scheme; or both 10989 hashAlg and the key scheme's algorithm are TPM_ALG_NULL 10990 10991 TPM_RC 10992 TPM2_HMAC( 10993 HMAC_In 10994 HMAC_Out 10995 10996 *in, 10997 *out 10998 10999 // IN: input parameter list 11000 // OUT: output parameter list 11001 11002 HMAC_STATE 11003 OBJECT 11004 TPMI_ALG_HASH 11005 TPMT_PUBLIC 11006 11007 hmacState; 11008 *hmacObject; 11009 hashAlg; 11010 *publicArea; 11011 11012 ) 11013 { 11014 11015 // Input Validation 11016 // Get HMAC key object and public area pointers 11017 hmacObject = ObjectGet(in->handle); 11018 publicArea = &hmacObject->publicArea; 11019 // Make sure that the key is an HMAC signing key 11020 if(publicArea->type != TPM_ALG_KEYEDHASH) 11021 return TPM_RC_TYPE + RC_HMAC_handle; 11022 if(publicArea->objectAttributes.sign != SET) 11023 return TPM_RC_ATTRIBUTES + RC_HMAC_handle; 11024 // Assume that the key default scheme is used 11025 hashAlg = publicArea->parameters.keyedHashDetail.scheme.details.hmac.hashAlg; 11026 // if the key is restricted, then need to use the scheme of the key and the 11027 // input algorithm must be TPM_ALG_NULL or the same as the key scheme 11028 if(publicArea->objectAttributes.restricted == SET) 11029 { 11030 if(in->hashAlg != TPM_ALG_NULL && in->hashAlg != hashAlg) 11031 hashAlg = TPM_ALG_NULL; 11032 } 11033 else 11034 { 11035 // for a non-restricted key, use hashAlg if it is provided; 11036 if(in->hashAlg != TPM_ALG_NULL) 11037 hashAlg = in->hashAlg; 11038 } 11039 // if the hashAlg is TPM_ALG_NULL, then the input hashAlg is not compatible 11040 // with the key scheme or type 11041 if(hashAlg == TPM_ALG_NULL) 11042 return TPM_RC_VALUE + RC_HMAC_hashAlg; 11043 // Command Output 11044 11045 Page 124 11046 October 31, 2013 11047 11048 Published 11049 Copyright TCG 2006-2013 11050 11051 Family 2.0 11052 Level 00 Revision 00.99 11053 11054 Trusted Platform Module Library 11056 50 11057 51 11058 52 11059 53 11060 54 11061 55 11062 56 11063 57 11064 58 11065 59 11066 60 11067 61 11068 11069 Part 3: Commands 11070 11071 // Start HMAC stack 11072 out->outHMAC.t.size = CryptStartHMAC2B(hashAlg, 11073 &hmacObject->sensitive.sensitive.bits.b, 11074 &hmacState); 11075 // Adding HMAC data 11076 CryptUpdateDigest2B(&hmacState, &in->buffer.b); 11077 // Complete HMAC 11078 CryptCompleteHMAC2B(&hmacState, &out->outHMAC.b); 11079 return TPM_RC_SUCCESS; 11080 } 11081 11082 Family 2.0 11083 Level 00 Revision 00.99 11084 11085 Published 11086 Copyright TCG 2006-2013 11087 11088 Page 125 11089 October 31, 2013 11090 11091 Part 3: Commands 11093 11094 18 11095 11096 Trusted Platform Module Library 11097 11098 Random Number Generator 11099 11100 18.1 11101 11102 TPM2_GetRandom 11103 11104 18.1.1 General Description 11105 This command returns the next bytesRequested octets from the random number generator (RNG). 11106 NOTE 1 11107 11108 It is recommended that a TPM implement the RNG in a manner that would allow it to return RNG 11109 octets such that the frequency of bytesRequested being more than the number of octets available is 11110 an infrequent occurrence. 11111 11112 If bytesRequested is more than will fit into a TPM2B_DIGEST on the TPM, no error is returned but the 11113 TPM will only return as much data as will fit into a TPM2B_DIGEST buffer for the TPM. 11114 NOTE 2 11115 11116 TPM2B_DIGEST is large enough to hold the largest digest that may be produced by the TPM. 11117 Because that digest size changes according to the implemented hashes, the maximum amount of 11118 data returned by this command is TPM implementation-dependent. 11119 11120 Page 126 11121 October 31, 2013 11122 11123 Published 11124 Copyright TCG 2006-2013 11125 11126 Family 2.0 11127 Level 00 Revision 00.99 11128 11129 Trusted Platform Module Library 11131 11132 Part 3: Commands 11133 11134 18.1.2 Command and Response 11135 Table 62 TPM2_GetRandom Command 11136 Type 11137 11138 Name 11139 11140 Description 11141 11142 TPMI_ST_COMMAND_TAG 11143 11144 tag 11145 11146 UINT32 11147 11148 commandSize 11149 11150 TPM_CC 11151 11152 commandCode 11153 11154 TPM_CC_GetRandom 11155 11156 UINT16 11157 11158 bytesRequested 11159 11160 number of octets to return 11161 11162 Table 63 TPM2_GetRandom Response 11163 Type 11164 11165 Name 11166 11167 Description 11168 11169 TPM_ST 11170 11171 tag 11172 11173 see clause 8 11174 11175 UINT32 11176 11177 responseSize 11178 11179 TPM_RC 11180 11181 responseCode 11182 11183 TPM2B_DIGEST 11184 11185 randomBytes 11186 11187 Family 2.0 11188 Level 00 Revision 00.99 11189 11190 the random octets 11191 11192 Published 11193 Copyright TCG 2006-2013 11194 11195 Page 127 11196 October 31, 2013 11197 11198 Part 3: Commands 11200 11201 Trusted Platform Module Library 11202 11203 18.1.3 Detailed Actions 11204 1 11205 2 11206 3 11207 4 11208 5 11209 6 11210 7 11211 8 11212 9 11213 10 11214 11 11215 12 11216 13 11217 14 11218 15 11219 16 11220 17 11221 18 11222 19 11223 20 11224 21 11225 11226 #include "InternalRoutines.h" 11227 #include "GetRandom_fp.h" 11228 11229 TPM_RC 11230 TPM2_GetRandom( 11231 GetRandom_In 11232 GetRandom_Out 11233 11234 *in, 11235 *out 11236 11237 // IN: input parameter list 11238 // OUT: output parameter list 11239 11240 ) 11241 { 11242 // Command Output 11243 // if the requested bytes exceed the output buffer size, generates the 11244 // maximum bytes that the output buffer allows 11245 if(in->bytesRequested > sizeof(TPMU_HA)) 11246 out->randomBytes.t.size = sizeof(TPMU_HA); 11247 else 11248 out->randomBytes.t.size = in->bytesRequested; 11249 CryptGenerateRandom(out->randomBytes.t.size, out->randomBytes.t.buffer); 11250 return TPM_RC_SUCCESS; 11251 } 11252 11253 Page 128 11254 October 31, 2013 11255 11256 Published 11257 Copyright TCG 2006-2013 11258 11259 Family 2.0 11260 Level 00 Revision 00.99 11261 11262 Trusted Platform Module Library 11264 11265 18.2 11266 11267 Part 3: Commands 11268 11269 TPM2_StirRandom 11270 11271 18.2.1 General Description 11272 This command is used to add "additional information" to the RNG state. 11273 NOTE 11274 11275 The "additional information" is as defined in SP800 -90A. 11276 11277 The inData parameter may not be larger than 128 octets. 11278 11279 Family 2.0 11280 Level 00 Revision 00.99 11281 11282 Published 11283 Copyright TCG 2006-2013 11284 11285 Page 129 11286 October 31, 2013 11287 11288 Part 3: Commands 11290 11291 Trusted Platform Module Library 11292 11293 18.2.2 Command and Response 11294 Table 64 TPM2_StirRandom Command 11295 Type 11296 11297 Name 11298 11299 Description 11300 11301 TPMI_ST_COMMAND_TAG 11302 11303 tag 11304 11305 UINT32 11306 11307 commandSize 11308 11309 TPM_CC 11310 11311 commandCode 11312 11313 TPM_CC_StirRandom {NV} 11314 11315 TPM2B_SENSITIVE_DATA 11316 11317 inData 11318 11319 additional information 11320 11321 Table 65 TPM2_StirRandom Response 11322 Type 11323 11324 Name 11325 11326 Description 11327 11328 TPM_ST 11329 11330 tag 11331 11332 see clause 8 11333 11334 UINT32 11335 11336 responseSize 11337 11338 TPM_RC 11339 11340 responseCode 11341 11342 Page 130 11343 October 31, 2013 11344 11345 Published 11346 Copyright TCG 2006-2013 11347 11348 Family 2.0 11349 Level 00 Revision 00.99 11350 11351 Trusted Platform Module Library 11353 11354 Part 3: Commands 11355 11356 18.2.3 Detailed Actions 11357 1 11358 2 11359 3 11360 4 11361 5 11362 6 11363 7 11364 8 11365 9 11366 10 11367 11 11368 12 11369 11370 #include "InternalRoutines.h" 11371 #include "StirRandom_fp.h" 11372 11373 TPM_RC 11374 TPM2_StirRandom( 11375 StirRandom_In 11376 *in 11377 // IN: input parameter list 11378 ) 11379 { 11380 // Internal Data Update 11381 CryptStirRandom(in->inData.t.size, in->inData.t.buffer); 11382 return TPM_RC_SUCCESS; 11383 } 11384 11385 Family 2.0 11386 Level 00 Revision 00.99 11387 11388 Published 11389 Copyright TCG 2006-2013 11390 11391 Page 131 11392 October 31, 2013 11393 11394 Part 3: Commands 11396 11397 19 11398 11399 Trusted Platform Module Library 11400 11401 Hash/HMAC/Event Sequences 11402 11403 19.1 11404 11405 Introduction 11406 11407 All of the commands in this group are to support sequences for which an intermediate state must be 11408 maintained. For a description of sequences, see Hash, HMAC, and Event Sequences in Part 1. 11409 19.2 11410 11411 TPM2_HMAC_Start 11412 11413 19.2.1 General Description 11414 This command starts an HMAC sequence. The TPM will create and initialize an HMAC sequence 11415 structure, assign a handle to the sequence, and set the authValue of the sequence object to the value in 11416 auth. 11417 NOTE 1 11418 11419 The structure of a sequence object is vendor -dependent. 11420 11421 The caller shall provide proper authorization for use of handle. 11422 If the sign attribute is not SET in the key referenced by handle then the TPM shall return 11423 TPM_RC_ATTRIBUTES. If the key type is not TPM_ALG_KEYEDHASH then the TPM shall return 11424 TPM_RC_TYPE. 11425 If handle references a restricted key, then the hash algorithm specified in the key's scheme is used as the 11426 hash algorithm for the HMAC and the TPM shall return TPM_RC_VALUE if hashAlg is not 11427 TPM_ALG_NULL or the same algorithm in the key's scheme. 11428 If the key referenced by handle is not restricted, then the TPM will use hashAlg for the HMAC; unless 11429 hashAlg is TPM_ALG_NULL in which case it will use the default scheme of the key. 11430 Table 66 Hash Selection Matrix 11431 handlerestricted 11432 (key's restricted 11433 attribute) 11434 11435 handlescheme 11436 (hash algorithm 11437 from key's scheme) 11438 11439 CLEAR (unrestricted) 11440 11441 TPM_ALG_NULL 11442 11443 CLEAR 11444 11445 dont care 11446 11447 CLEAR 11448 11449 valid hash 11450 11451 hash used 11452 11453 TPM_ALG_NULL 11454 11455 error 11456 11457 valid hash 11458 11459 (1) 11460 11461 hashAlg 11462 11463 hashAlg 11464 11465 (2) 11466 11467 (TPM_RC_SCHEME) 11468 11469 TPM_ALG_NULL 11470 11471 handlescheme 11472 11473 same as handlescheme 11474 11475 handlescheme 11476 11477 (3) 11478 11479 SET 11480 11481 handlescheme 11482 11483 (3) 11484 11485 SET (restricted) 11486 11487 TPM_ALG_NULL 11488 11489 (3) 11490 11491 not same as 11492 handlescheme 11493 11494 error 11495 11496 valid hash 11497 valid hash 11498 11499 SET 11500 11501 valid hash 11502 11503 (4) 11504 11505 (TPM_RC_SCHEME) 11506 11507 NOTES: 11508 1) 11509 11510 The scheme for the handle may only be TPM_ALG_NULL if both sign and decrypt are SET. 11511 11512 2) 11513 11514 A hash algorithm is required for the HMAC. 11515 11516 3) 11517 11518 A restricted key is required to have a scheme with a valid hash algorithm. A restricted key may not have both sign and 11519 decrypt SET. 11520 11521 4) 11522 11523 The scheme for a restricted key cannot be overridden. 11524 11525 Page 132 11526 October 31, 2013 11527 11528 Published 11529 Copyright TCG 2006-2013 11530 11531 Family 2.0 11532 Level 00 Revision 00.99 11533 11534 Trusted Platform Module Library 11536 11537 Part 3: Commands 11538 11539 19.2.2 Command and Response 11540 Table 67 TPM2_HMAC_Start Command 11541 Type 11542 11543 Name 11544 11545 Description 11546 11547 TPMI_ST_COMMAND_TAG 11548 11549 tag 11550 11551 UINT32 11552 11553 commandSize 11554 11555 TPM_CC 11556 11557 commandCode 11558 11559 TPM_CC_HMAC_Start 11560 11561 TPMI_DH_OBJECT 11562 11563 @handle 11564 11565 handle of an HMAC key 11566 Auth Index: 1 11567 Auth Role: USER 11568 11569 TPM2B_AUTH 11570 11571 auth 11572 11573 authorization value for subsequent use of the sequence 11574 11575 TPMI_ALG_HASH+ 11576 11577 hashAlg 11578 11579 the hash algorithm to use for the HMAC 11580 11581 Table 68 TPM2_HMAC_Start Response 11582 Type 11583 11584 Name 11585 11586 Description 11587 11588 TPM_ST 11589 11590 tag 11591 11592 see clause 8 11593 11594 UINT32 11595 11596 responseSize 11597 11598 TPM_RC 11599 11600 responseCode 11601 11602 TPMI_DH_OBJECT 11603 11604 sequenceHandle 11605 11606 Family 2.0 11607 Level 00 Revision 00.99 11608 11609 a handle to reference the sequence 11610 11611 Published 11612 Copyright TCG 2006-2013 11613 11614 Page 133 11615 October 31, 2013 11616 11617 Part 3: Commands 11619 11620 Trusted Platform Module Library 11621 11622 19.2.3 Detailed Actions 11623 1 11624 2 11625 11626 #include "InternalRoutines.h" 11627 #include "HMAC_Start_fp.h" 11628 Error Returns 11629 TPM_RC_ATTRIBUTES 11630 11631 key referenced by handle is not a signing key 11632 11633 TPM_RC_OBJECT_MEMORY 11634 11635 no space to create an internal object 11636 11637 TPM_RC_TYPE 11638 11639 key referenced by handle is not an HMAC key 11640 11641 TPM_RC_VALUE 11642 11643 3 11644 4 11645 5 11646 6 11647 7 11648 8 11649 9 11650 10 11651 11 11652 12 11653 13 11654 14 11655 15 11656 16 11657 17 11658 18 11659 19 11660 20 11661 21 11662 22 11663 23 11664 24 11665 25 11666 26 11667 27 11668 28 11669 29 11670 30 11671 31 11672 32 11673 33 11674 34 11675 35 11676 36 11677 37 11678 38 11679 39 11680 40 11681 41 11682 42 11683 43 11684 44 11685 45 11686 46 11687 47 11688 11689 Meaning 11690 11691 hashAlg specified when the key is restricted is neither 11692 TPM_ALG_NULL not equal to that of the key scheme; or both 11693 hashAlg and the key scheme's algorithm are TPM_ALG_NULL 11694 11695 TPM_RC 11696 TPM2_HMAC_Start( 11697 HMAC_Start_In 11698 HMAC_Start_Out 11699 11700 *in, 11701 *out 11702 11703 // IN: input parameter list 11704 // OUT: output parameter list 11705 11706 ) 11707 { 11708 OBJECT 11709 TPMT_PUBLIC 11710 TPM_ALG_ID 11711 11712 *hmacObject; 11713 *publicArea; 11714 hashAlg; 11715 11716 // Input Validation 11717 // Get HMAC key object and public area pointers 11718 hmacObject = ObjectGet(in->handle); 11719 publicArea = &hmacObject->publicArea; 11720 // Make sure that the key is an HMAC signing key 11721 if(publicArea->type != TPM_ALG_KEYEDHASH) 11722 return TPM_RC_TYPE + RC_HMAC_Start_handle; 11723 if(publicArea->objectAttributes.sign != SET) 11724 return TPM_RC_ATTRIBUTES + RC_HMAC_Start_handle; 11725 // Assume that the key default scheme is used 11726 hashAlg = publicArea->parameters.keyedHashDetail.scheme.details.hmac.hashAlg; 11727 // if the key is restricted, then need to use the scheme of the key and the 11728 // input algorithm must be TPM_ALG_NULL or the same as the key scheme 11729 if(publicArea->objectAttributes.restricted == SET) 11730 { 11731 if(in->hashAlg != TPM_ALG_NULL && in->hashAlg != hashAlg) 11732 hashAlg = TPM_ALG_NULL; 11733 } 11734 else 11735 { 11736 // for a non-restricted key, use hashAlg if it is provided; 11737 if(in->hashAlg != TPM_ALG_NULL) 11738 hashAlg = in->hashAlg; 11739 } 11740 // if the algorithm selection ended up with TPM_ALG_NULL, then either the 11741 // schemes are not compatible or no hash was provided and both conditions 11742 // are errors. 11743 if(hashAlg == TPM_ALG_NULL) 11744 return TPM_RC_VALUE + RC_HMAC_Start_hashAlg; 11745 // Internal Data Update 11746 11747 Page 134 11748 October 31, 2013 11749 11750 Published 11751 Copyright TCG 2006-2013 11752 11753 Family 2.0 11754 Level 00 Revision 00.99 11755 11756 Trusted Platform Module Library 11758 48 11759 49 11760 50 11761 51 11762 52 11763 53 11764 54 11765 55 11766 11767 Part 3: Commands 11768 11769 // Create a HMAC sequence object. A TPM_RC_OBJECT_MEMORY error may be 11770 // returned at this point 11771 return ObjectCreateHMACSequence(hashAlg, 11772 in->handle, 11773 &in->auth, 11774 &out->sequenceHandle); 11775 } 11776 11777 Family 2.0 11778 Level 00 Revision 00.99 11779 11780 Published 11781 Copyright TCG 2006-2013 11782 11783 Page 135 11784 October 31, 2013 11785 11786 Part 3: Commands 11788 11789 19.3 11790 11791 Trusted Platform Module Library 11792 11793 TPM2_HashSequenceStart 11794 11795 19.3.1 General Description 11796 This command starts a hash or an Event sequence. If hashAlg is an implemented hash, then a hash 11797 sequence is started. If hashAlg is TPM_ALG_NULL, then an Event sequence is started. If hashAlg is 11798 neither an implemented algorithm nor TPM_ALG_NULL, then the TPM shall return TPM_RC_HASH. 11799 Depending on hashAlg, the TPM will create and initialize a hash sequence structure or an Event 11800 sequence structure. Additionally, it will assign a handle to the sequence and set the authValue of the 11801 sequence to the value in auth. A sequence structure for an Event (hashAlg = TPM_ALG_NULL) contains 11802 a hash context for each of the PCR banks implemented on the TPM. 11803 11804 Page 136 11805 October 31, 2013 11806 11807 Published 11808 Copyright TCG 2006-2013 11809 11810 Family 2.0 11811 Level 00 Revision 00.99 11812 11813 Trusted Platform Module Library 11815 11816 Part 3: Commands 11817 11818 19.3.2 Command and Response 11819 Table 69 TPM2_HashSequenceStart Command 11820 Type 11821 11822 Name 11823 11824 Description 11825 11826 TPMI_ST_COMMAND_TAG 11827 11828 tag 11829 11830 UINT32 11831 11832 commandSize 11833 11834 TPM_CC 11835 11836 commandCode 11837 11838 TPM_CC_HashSequenceStart 11839 11840 TPM2B_AUTH 11841 11842 auth 11843 11844 authorization value for subsequent use of the sequence 11845 11846 TPMI_ALG_HASH+ 11847 11848 hashAlg 11849 11850 the hash algorithm to use for the hash sequence 11851 An Event sequence starts if this is TPM_ALG_NULL. 11852 11853 Table 70 TPM2_HashSequenceStart Response 11854 Type 11855 11856 Name 11857 11858 Description 11859 11860 TPM_ST 11861 11862 tag 11863 11864 see clause 8 11865 11866 UINT32 11867 11868 responseSize 11869 11870 TPM_RC 11871 11872 responseCode 11873 11874 TPMI_DH_OBJECT 11875 11876 sequenceHandle 11877 11878 Family 2.0 11879 Level 00 Revision 00.99 11880 11881 a handle to reference the sequence 11882 11883 Published 11884 Copyright TCG 2006-2013 11885 11886 Page 137 11887 October 31, 2013 11888 11889 Part 3: Commands 11891 11892 Trusted Platform Module Library 11893 11894 19.3.3 Detailed Actions 11895 1 11896 2 11897 11898 #include "InternalRoutines.h" 11899 #include "HashSequenceStart_fp.h" 11900 Error Returns 11901 TPM_RC_OBJECT_MEMORY 11902 11903 3 11904 4 11905 5 11906 6 11907 7 11908 8 11909 9 11910 10 11911 11 11912 12 11913 13 11914 14 11915 15 11916 16 11917 17 11918 18 11919 19 11920 11921 Meaning 11922 no space to create an internal object 11923 11924 TPM_RC 11925 TPM2_HashSequenceStart( 11926 HashSequenceStart_In 11927 HashSequenceStart_Out 11928 11929 *in, 11930 *out 11931 11932 // IN: input parameter list 11933 // OUT: output parameter list 11934 11935 ) 11936 { 11937 // Internal Data Update 11938 if(in->hashAlg == TPM_ALG_NULL) 11939 // Start a event sequence. A TPM_RC_OBJECT_MEMORY error may be 11940 // returned at this point 11941 return ObjectCreateEventSequence(&in->auth, &out->sequenceHandle); 11942 // Start a hash sequence. A TPM_RC_OBJECT_MEMORY error may be 11943 // returned at this point 11944 return ObjectCreateHashSequence(in->hashAlg, &in->auth, &out->sequenceHandle); 11945 } 11946 11947 Page 138 11948 October 31, 2013 11949 11950 Published 11951 Copyright TCG 2006-2013 11952 11953 Family 2.0 11954 Level 00 Revision 00.99 11955 11956 Trusted Platform Module Library 11958 11959 19.4 11960 11961 Part 3: Commands 11962 11963 TPM2_SequenceUpdate 11964 11965 19.4.1 General Description 11966 This command is used to add data to a hash or HMAC sequence. The amount of data in buffer may be 11967 any size up to the limits of the TPM. 11968 NOTE 11969 11970 In all TPM, a buffer size of 1,024 octets is allowed. 11971 11972 Proper authorization for the sequence object associated with sequenceHandle is required. If an 11973 authorization or audit of this command requires computation of a cpHash and an rpHash, the Name 11974 associated with sequenceHandle will be the Empty Buffer. 11975 If the command does not return TPM_RC_SUCCESS, the state of the sequence is unmodified. 11976 If the sequence is intended to produce a digest that will be signed by a restricted signing key, then the 11977 first block of data shall contain sizeof(TPM_GENERATED) octets and the first octets shall not be 11978 TPM_GENERATED_VALUE. 11979 NOTE 11980 11981 This requirement allows the TPM to validate that the first block is safe to sign without having to 11982 accumulate octets over multiple calls. 11983 11984 Family 2.0 11985 Level 00 Revision 00.99 11986 11987 Published 11988 Copyright TCG 2006-2013 11989 11990 Page 139 11991 October 31, 2013 11992 11993 Part 3: Commands 11995 11996 Trusted Platform Module Library 11997 11998 19.4.2 Command and Response 11999 Table 71 TPM2_SequenceUpdate Command 12000 Type 12001 12002 Name 12003 12004 Description 12005 12006 TPMI_ST_COMMAND_TAG 12007 12008 tag 12009 12010 UINT32 12011 12012 commandSize 12013 12014 TPM_CC 12015 12016 commandCode 12017 12018 TPM_CC_SequenceUpdate 12019 12020 TPMI_DH_OBJECT 12021 12022 @sequenceHandle 12023 12024 handle for the sequence object 12025 Auth Index: 1 12026 Auth Role: USER 12027 12028 TPM2B_MAX_BUFFER 12029 12030 buffer 12031 12032 data to be added to hash 12033 12034 Table 72 TPM2_SequenceUpdate Response 12035 Type 12036 12037 Name 12038 12039 Description 12040 12041 TPM_ST 12042 12043 tag 12044 12045 see clause 8 12046 12047 UINT32 12048 12049 responseSize 12050 12051 TPM_RC 12052 12053 responseCode 12054 12055 Page 140 12056 October 31, 2013 12057 12058 Published 12059 Copyright TCG 2006-2013 12060 12061 Family 2.0 12062 Level 00 Revision 00.99 12063 12064 Trusted Platform Module Library 12066 12067 Part 3: Commands 12068 12069 19.4.3 Detailed Actions 12070 1 12071 2 12072 12073 #include "InternalRoutines.h" 12074 #include "SequenceUpdate_fp.h" 12075 Error Returns 12076 TPM_RC_MODE 12077 12078 3 12079 4 12080 5 12081 6 12082 7 12083 8 12084 9 12085 10 12086 11 12087 12 12088 13 12089 14 12090 15 12091 16 12092 17 12093 18 12094 19 12095 20 12096 21 12097 22 12098 23 12099 24 12100 25 12101 26 12102 27 12103 28 12104 29 12105 30 12106 31 12107 32 12108 33 12109 34 12110 35 12111 36 12112 37 12113 38 12114 39 12115 40 12116 41 12117 42 12118 43 12119 44 12120 45 12121 46 12122 47 12123 48 12124 49 12125 50 12126 51 12127 52 12128 53 12129 12130 Meaning 12131 sequenceHandle does not reference a hash or HMAC sequence 12132 object 12133 12134 TPM_RC 12135 TPM2_SequenceUpdate( 12136 SequenceUpdate_In 12137 12138 *in 12139 12140 // IN: input parameter list 12141 12142 ) 12143 { 12144 OBJECT 12145 12146 *object; 12147 12148 // Input Validation 12149 // Get sequence object pointer 12150 object = ObjectGet(in->sequenceHandle); 12151 // Check that referenced object is a sequence object. 12152 if(!ObjectIsSequence(object)) 12153 return TPM_RC_MODE + RC_SequenceUpdate_sequenceHandle; 12154 // Internal Data Update 12155 if(object->attributes.eventSeq == SET) 12156 { 12157 // Update event sequence object 12158 UINT32 12159 i; 12160 HASH_OBJECT 12161 *hashObject = (HASH_OBJECT *)object; 12162 for(i = 0; i < HASH_COUNT; i++) 12163 { 12164 // Update sequence object 12165 CryptUpdateDigest2B(&hashObject->state.hashState[i], &in->buffer.b); 12166 } 12167 } 12168 else 12169 { 12170 HASH_OBJECT 12171 *hashObject = (HASH_OBJECT *)object; 12172 // Update hash/HMAC sequence object 12173 if(hashObject->attributes.hashSeq == SET) 12174 { 12175 // Is this the first block of the sequence 12176 if(hashObject->attributes.firstBlock == CLEAR) 12177 { 12178 // If so, indicate that first block was received 12179 hashObject->attributes.firstBlock = SET; 12180 // Check the first block to see if the first block can contain 12181 // the TPM_GENERATED_VALUE. If it does, it is not safe for 12182 // a ticket. 12183 if(TicketIsSafe(&in->buffer.b)) 12184 hashObject->attributes.ticketSafe = SET; 12185 } 12186 // Update sequence object hash/HMAC stack 12187 CryptUpdateDigest2B(&hashObject->state.hashState[0], &in->buffer.b); 12188 12189 Family 2.0 12190 Level 00 Revision 00.99 12191 12192 Published 12193 Copyright TCG 2006-2013 12194 12195 Page 141 12196 October 31, 2013 12197 12198 Part 3: Commands 12200 54 12201 55 12202 56 12203 57 12204 58 12205 59 12206 60 12207 61 12208 62 12209 63 12210 64 12211 65 12212 12213 Trusted Platform Module Library 12214 12215 } 12216 else if(object->attributes.hmacSeq == SET) 12217 { 12218 HASH_OBJECT 12219 *hashObject = (HASH_OBJECT *)object; 12220 // Update sequence object hash/HMAC stack 12221 CryptUpdateDigest2B(&hashObject->state.hmacState, &in->buffer.b); 12222 } 12223 } 12224 return TPM_RC_SUCCESS; 12225 } 12226 12227 Page 142 12228 October 31, 2013 12229 12230 Published 12231 Copyright TCG 2006-2013 12232 12233 Family 2.0 12234 Level 00 Revision 00.99 12235 12236 Trusted Platform Module Library 12238 12239 19.5 12240 12241 Part 3: Commands 12242 12243 TPM2_SequenceComplete 12244 12245 19.5.1 General Description 12246 This command adds the last part of data, if any, to a hash/HMAC sequence and returns the result. 12247 NOTE 1 12248 12249 This command is not used to complete an Event sequence. TPM2_EventSequenceComplete() is 12250 used for that purpose. 12251 12252 For a hash sequence, if the results of the hash will be used in a signing operation that uses a restricted 12253 signing key, then the ticket returned by this command can indicate that the hash is safe to sign. 12254 If the digest is not safe to sign, then validation will be a TPMT_TK_HASHCHECK with the hierarchy set to 12255 TPM_RH_NULL and digest set to the Empty Buffer. 12256 NOTE 2 12257 12258 Regardless of the contents of the first octets of the hashed message, if the first buffer sent to the 12259 TPM had fewer than sizeof(TPM_GENERATED) octets, then the TPM will operate as if digest is not 12260 safe to sign. 12261 12262 If sequenceHandle references an Event sequence, then the TPM shall return TPM_RC_MODE. 12263 Proper authorization for the sequence object associated with sequenceHandle is required. If an 12264 authorization or audit of this command requires computation of a cpHash and an rpHash, the Name 12265 associated with sequenceHandle will be the Empty Buffer. 12266 If this command completes successfully, the sequenceHandle object will be flushed. 12267 12268 Family 2.0 12269 Level 00 Revision 00.99 12270 12271 Published 12272 Copyright TCG 2006-2013 12273 12274 Page 143 12275 October 31, 2013 12276 12277 Part 3: Commands 12279 12280 Trusted Platform Module Library 12281 12282 19.5.2 Command and Response 12283 Table 73 TPM2_SequenceComplete Command 12284 Type 12285 12286 Name 12287 12288 Description 12289 12290 TPMI_ST_COMMAND_TAG 12291 12292 tag 12293 12294 UINT32 12295 12296 commandSize 12297 12298 TPM_CC 12299 12300 commandCode 12301 12302 TPM_CC_SequenceComplete {F} 12303 12304 TPMI_DH_OBJECT 12305 12306 @sequenceHandle 12307 12308 authorization for the sequence 12309 Auth Index: 1 12310 Auth Role: USER 12311 12312 TPM2B_MAX_BUFFER 12313 12314 buffer 12315 12316 data to be added to the hash/HMAC 12317 12318 TPMI_RH_HIERARCHY+ 12319 12320 hierarchy 12321 12322 hierarchy of the ticket for a hash 12323 12324 Table 74 TPM2_SequenceComplete Response 12325 Type 12326 12327 Name 12328 12329 Description 12330 12331 TPM_ST 12332 12333 tag 12334 12335 see clause 8 12336 12337 UINT32 12338 12339 responseSize 12340 12341 TPM_RC 12342 12343 responseCode 12344 12345 TPM2B_DIGEST 12346 12347 result 12348 12349 the returned HMAC or digest in a sized buffer 12350 12351 TPMT_TK_HASHCHECK 12352 12353 validation 12354 12355 ticket indicating that the sequence of octets used to 12356 compute outDigest did not start with 12357 TPM_GENERATED_VALUE 12358 This is a NULL Ticket when the session is HMAC. 12359 12360 Page 144 12361 October 31, 2013 12362 12363 Published 12364 Copyright TCG 2006-2013 12365 12366 Family 2.0 12367 Level 00 Revision 00.99 12368 12369 Trusted Platform Module Library 12371 12372 Part 3: Commands 12373 12374 19.5.3 Detailed Actions 12375 1 12376 2 12377 3 12378 12379 #include "InternalRoutines.h" 12380 #include "SequenceComplete_fp.h" 12381 #include <Platform.h> 12382 Error Returns 12383 TPM_RC_TYPE 12384 12385 4 12386 5 12387 6 12388 7 12389 8 12390 9 12391 10 12392 11 12393 12 12394 13 12395 14 12396 15 12397 16 12398 17 12399 18 12400 19 12401 20 12402 21 12403 22 12404 23 12405 24 12406 25 12407 26 12408 27 12409 28 12410 29 12411 30 12412 31 12413 32 12414 33 12415 34 12416 35 12417 36 12418 37 12419 38 12420 39 12421 40 12422 41 12423 42 12424 43 12425 44 12426 45 12427 46 12428 47 12429 48 12430 49 12431 50 12432 51 12433 52 12434 53 12435 12436 Meaning 12437 sequenceHandle does not reference a hash or HMAC sequence 12438 object 12439 12440 TPM_RC 12441 TPM2_SequenceComplete( 12442 SequenceComplete_In 12443 SequenceComplete_Out 12444 12445 *in, 12446 *out 12447 12448 OBJECT 12449 12450 // IN: input parameter list 12451 // OUT: output parameter list 12452 12453 *object; 12454 12455 ) 12456 { 12457 // Input validation 12458 // Get hash object pointer 12459 object = ObjectGet(in->sequenceHandle); 12460 // input handle must be a hash or HMAC sequence object. 12461 if( 12462 object->attributes.hashSeq == CLEAR 12463 && object->attributes.hmacSeq == CLEAR) 12464 return TPM_RC_MODE + RC_SequenceComplete_sequenceHandle; 12465 // Command Output 12466 if(object->attributes.hashSeq == SET) 12467 // sequence object for hash 12468 { 12469 // Update last piece of data 12470 HASH_OBJECT 12471 *hashObject = (HASH_OBJECT *)object; 12472 CryptUpdateDigest2B(&hashObject->state.hashState[0], &in->buffer.b); 12473 // Complete hash 12474 out->result.t.size 12475 = CryptGetHashDigestSize( 12476 CryptGetContextAlg(&hashObject->state.hashState[0])); 12477 CryptCompleteHash2B(&hashObject->state.hashState[0], &out->result.b); 12478 // Check if the first block of the sequence has been received 12479 if(hashObject->attributes.firstBlock == CLEAR) 12480 { 12481 // If not, then this is the first block so see if it is 'safe' 12482 // to sign. 12483 if(TicketIsSafe(&in->buffer.b)) 12484 hashObject->attributes.ticketSafe = SET; 12485 } 12486 // Output ticket 12487 out->validation.tag = TPM_ST_HASHCHECK; 12488 out->validation.hierarchy = in->hierarchy; 12489 if(in->hierarchy == TPM_RH_NULL) 12490 { 12491 // Ticket is not required 12492 out->validation.digest.t.size = 0; 12493 12494 Family 2.0 12495 Level 00 Revision 00.99 12496 12497 Published 12498 Copyright TCG 2006-2013 12499 12500 Page 145 12501 October 31, 2013 12502 12503 Part 3: Commands 12505 54 12506 55 12507 56 12508 57 12509 58 12510 59 12511 60 12512 61 12513 62 12514 63 12515 64 12516 65 12517 66 12518 67 12519 68 12520 69 12521 70 12522 71 12523 72 12524 73 12525 74 12526 75 12527 76 12528 77 12529 78 12530 79 12531 80 12532 81 12533 82 12534 83 12535 84 12536 85 12537 86 12538 87 12539 88 12540 89 12541 90 12542 91 12543 92 12544 12545 Trusted Platform Module Library 12546 12547 } 12548 else if(object->attributes.ticketSafe == CLEAR) 12549 { 12550 // Ticket is not safe to generate 12551 out->validation.hierarchy = TPM_RH_NULL; 12552 out->validation.digest.t.size = 0; 12553 } 12554 else 12555 { 12556 // Compute ticket 12557 TicketComputeHashCheck(out->validation.hierarchy, 12558 &out->result, &out->validation); 12559 } 12560 } 12561 else 12562 { 12563 HASH_OBJECT 12564 12565 *hashObject = (HASH_OBJECT *)object; 12566 12567 // 12568 Update last piece of data 12569 CryptUpdateDigest2B(&hashObject->state.hmacState, &in->buffer.b); 12570 // Complete hash/HMAC 12571 out->result.t.size = 12572 CryptGetHashDigestSize( 12573 CryptGetContextAlg(&hashObject->state.hmacState.hashState)); 12574 CryptCompleteHMAC2B(&(hashObject->state.hmacState), &out->result.b); 12575 // No ticket is generated for HMAC sequence 12576 out->validation.tag = TPM_ST_HASHCHECK; 12577 out->validation.hierarchy = TPM_RH_NULL; 12578 out->validation.digest.t.size = 0; 12579 } 12580 // Internal Data Update 12581 // mark sequence object as evict so it will be flushed on the way out 12582 object->attributes.evict = SET; 12583 return TPM_RC_SUCCESS; 12584 } 12585 12586 Page 146 12587 October 31, 2013 12588 12589 Published 12590 Copyright TCG 2006-2013 12591 12592 Family 2.0 12593 Level 00 Revision 00.99 12594 12595 Trusted Platform Module Library 12597 12598 19.6 12599 12600 Part 3: Commands 12601 12602 TPM2_EventSequenceComplete 12603 12604 19.6.1 General Description 12605 This command adds the last part of data, if any, to an Event sequence and returns the result in a digest 12606 list. If pcrHandle references a PCR and not TPM_RH_NULL, then the returned digest list is processed in 12607 the same manner as the digest list input parameter to TPM2_PCR_Extend() with the pcrHandle in each 12608 bank extended with the associated digest value. 12609 If sequenceHandle references a hash or HMAC sequence, the TPM shall return TPM_RC_MODE. 12610 Proper authorization for the sequence object associated with sequenceHandle is required. If an 12611 authorization or audit of this command requires computation of a cpHash and an rpHash, the Name 12612 associated with sequenceHandle will be the Empty Buffer. 12613 If this command completes successfully, the sequenceHandle object will be flushed. 12614 12615 Family 2.0 12616 Level 00 Revision 00.99 12617 12618 Published 12619 Copyright TCG 2006-2013 12620 12621 Page 147 12622 October 31, 2013 12623 12624 Part 3: Commands 12626 12627 Trusted Platform Module Library 12628 12629 19.6.2 Command and Response 12630 Table 75 TPM2_EventSequenceComplete Command 12631 Type 12632 12633 Name 12634 12635 TPMI_ST_COMMAND_TAG 12636 12637 tag 12638 12639 UINT32 12640 12641 commandSize 12642 12643 TPM_CC 12644 12645 commandCode 12646 12647 TPM_CC_EventSequenceComplete {NV F} 12648 12649 TPMI_DH_PCR+ 12650 12651 @pcrHandle 12652 12653 PCR to be extended with the Event data 12654 Auth Index: 1 12655 Auth Role: USER 12656 12657 TPMI_DH_OBJECT 12658 12659 @sequenceHandle 12660 12661 authorization for the sequence 12662 Auth Index: 2 12663 Auth Role: USER 12664 12665 TPM2B_MAX_BUFFER 12666 12667 buffer 12668 12669 data to be added to the Event 12670 12671 Description 12672 12673 Table 76 TPM2_EventSequenceComplete Response 12674 Type 12675 12676 Name 12677 12678 Description 12679 12680 TPM_ST 12681 12682 tag 12683 12684 see clause 8 12685 12686 UINT32 12687 12688 responseSize 12689 12690 TPM_RC 12691 12692 responseCode 12693 12694 TPML_DIGEST_VALUES 12695 12696 results 12697 12698 Page 148 12699 October 31, 2013 12700 12701 list of digests computed for the PCR 12702 12703 Published 12704 Copyright TCG 2006-2013 12705 12706 Family 2.0 12707 Level 00 Revision 00.99 12708 12709 Trusted Platform Module Library 12711 12712 Part 3: Commands 12713 12714 19.6.3 Detailed Actions 12715 1 12716 2 12717 12718 #include "InternalRoutines.h" 12719 #include "EventSequenceComplete_fp.h" 12720 Error Returns 12721 TPM_RC_LOCALITY 12722 12723 PCR extension is not allowed at the current locality 12724 12725 TPM_RC_MODE 12726 3 12727 4 12728 5 12729 6 12730 7 12731 8 12732 9 12733 10 12734 11 12735 12 12736 13 12737 14 12738 15 12739 16 12740 17 12741 18 12742 19 12743 20 12744 21 12745 22 12746 23 12747 24 12748 25 12749 26 12750 27 12751 28 12752 29 12753 30 12754 31 12755 32 12756 33 12757 34 12758 35 12759 36 12760 37 12761 38 12762 39 12763 40 12764 41 12765 42 12766 43 12767 44 12768 45 12769 46 12770 47 12771 48 12772 49 12773 50 12774 51 12775 52 12776 53 12777 12778 Meaning 12779 12780 input handle is not a valid event sequence object 12781 12782 TPM_RC 12783 TPM2_EventSequenceComplete( 12784 EventSequenceComplete_In 12785 EventSequenceComplete_Out 12786 12787 *in, 12788 *out 12789 12790 // IN: input parameter list 12791 // OUT: output parameter list 12792 12793 ) 12794 { 12795 TPM_RC 12796 HASH_OBJECT 12797 UINT32 12798 TPM_ALG_ID 12799 12800 result; 12801 *hashObject; 12802 i; 12803 hashAlg; 12804 12805 // Input validation 12806 // get the event sequence object pointer 12807 hashObject = (HASH_OBJECT *)ObjectGet(in->sequenceHandle); 12808 // input handle must reference an event sequence object 12809 if(hashObject->attributes.eventSeq != SET) 12810 return TPM_RC_MODE + RC_EventSequenceComplete_sequenceHandle; 12811 // see if a PCR extend is requested in call 12812 if(in->pcrHandle != TPM_RH_NULL) 12813 { 12814 // see if extend of the PCR is allowed at the locality of the command, 12815 if(!PCRIsExtendAllowed(in->pcrHandle)) 12816 return TPM_RC_LOCALITY; 12817 // if an extend is going to take place, then check to see if there has 12818 // been an orderly shutdown. If so, and the selected PCR is one of the 12819 // state saved PCR, then the orderly state has to change. The orderly state 12820 // does not change for PCR that are not preserved. 12821 // NOTE: This doesn't just check for Shutdown(STATE) because the orderly 12822 // state will have to change if this is a state-saved PCR regardless 12823 // of the current state. This is because a subsequent Shutdown(STATE) will 12824 // check to see if there was an orderly shutdown and not do anything if 12825 // there was. So, this must indicate that a future Shutdown(STATE) has 12826 // something to do. 12827 if(gp.orderlyState != SHUTDOWN_NONE && PCRIsStateSaved(in->pcrHandle)) 12828 { 12829 result = NvIsAvailable(); 12830 if(result != TPM_RC_SUCCESS) return result; 12831 g_clearOrderly = TRUE; 12832 } 12833 } 12834 // Command Output 12835 out->results.count = 0; 12836 for(i = 0; i < HASH_COUNT; i++) 12837 { 12838 hashAlg = CryptGetHashAlgByIndex(i); 12839 12840 Family 2.0 12841 Level 00 Revision 00.99 12842 12843 Published 12844 Copyright TCG 2006-2013 12845 12846 Page 149 12847 October 31, 2013 12848 12849 Part 3: Commands 12851 54 12852 55 12853 56 12854 57 12855 58 12856 59 12857 60 12858 61 12859 62 12860 63 12861 64 12862 65 12863 66 12864 67 12865 68 12866 69 12867 70 12868 71 12869 72 12870 73 12871 74 12872 75 12873 76 12874 12875 Trusted Platform Module Library 12876 12877 // Update last piece of data 12878 CryptUpdateDigest2B(&hashObject->state.hashState[i], &in->buffer.b); 12879 // Complete hash 12880 out->results.digests[out->results.count].hashAlg = hashAlg; 12881 CryptCompleteHash(&hashObject->state.hashState[i], 12882 CryptGetHashDigestSize(hashAlg), 12883 (BYTE *) &out->results.digests[out->results.count].digest); 12884 // Extend PCR 12885 if(in->pcrHandle != TPM_RH_NULL) 12886 PCRExtend(in->pcrHandle, hashAlg, 12887 CryptGetHashDigestSize(hashAlg), 12888 (BYTE *) &out->results.digests[out->results.count].digest); 12889 out->results.count++; 12890 } 12891 // Internal Data Update 12892 // mark sequence object as evict so it will be flushed on the way out 12893 hashObject->attributes.evict = SET; 12894 return TPM_RC_SUCCESS; 12895 } 12896 12897 Page 150 12898 October 31, 2013 12899 12900 Published 12901 Copyright TCG 2006-2013 12902 12903 Family 2.0 12904 Level 00 Revision 00.99 12905 12906 Trusted Platform Module Library 12908 12909 Part 3: Commands 12910 12911 Attestation Commands 12912 12913 20 12914 20.1 12915 12916 Introduction 12917 12918 The attestation commands cause the TPM to sign an internally generated data structure. The contents of 12919 the data structure vary according to the command. 12920 For all signing commands, provisions are made for the caller to provide a scheme to be used for the 12921 signing operation. This scheme will be applied only if the scheme of the key is TPM_ALG_NULL. If the 12922 scheme for signHandle is not TPM_ALG_NULL, then inScheme.scheme shall be TPM_ALG_NULL or the 12923 same as scheme in the public area of the key. If the scheme for signHandle is TPM_ALG_NULL, then 12924 inScheme will be used for the signing operation and may not be TPM_ALG_NULL. The TPM shall return 12925 TPM_RC_SCHEME to indicate that the scheme is not appropriate. 12926 For a signing key that is not restricted, the caller may specify the scheme to be used as long as the 12927 scheme is compatible with the family of the key (for example, TPM_ALG_RSAPSS cannot be selected for 12928 an ECC key). If the caller sets scheme to TPM_ALG_NULL, then the default scheme of the key is used. 12929 If the handle for the signing key (signHandle) is TPM_RH_NULL, then all of the actions of the command 12930 are performed and the attestation block is signed with the NULL Signature. 12931 NOTE 1 12932 12933 This mechanism is provided so that additional commands are not required to access the data that 12934 might be in an attestation structure. 12935 12936 NOTE 2 12937 12938 When signHandle is TPM_RH_NULL, scheme is still required to be a valid signing scheme (may be 12939 TPM_ALG_NULL), but the scheme will have no effect on the format of the signature. It will always 12940 be the NULL Signature. 12941 12942 TPM2_NV_Certify() is an attestation command that is documented in 1. The remaining attestation 12943 commands are collected in the remainder of this clause. 12944 Each of the attestation structures contains a TPMS_CLOCK_INFO structure and a firmware version 12945 number. These values may be considered privacy-sensitive, because they would aid in the correlation of 12946 attestations by different keys. To provide improved privacy, the resetCount, restartCount, and 12947 firmwareVersion numbers are obfuscated when the signing key is not in the Endorsement or Platform 12948 hierarchies. 12949 The obfuscation value is computed by: 12950 12951 obfuscation KDFa(signHandlenameAlg, shProof, OBFUSCATE, signHandleQN, 0, 128) (3) 12952 Of the returned 128 bits, 64 bits are added to the versionNumber field of the attestation structure; 32 bits 12953 are added to the clockInfo.resetCount and 32 bits are added to the clockInfo.restartCount. The order in 12954 which the bits are added is implementation-dependent. 12955 NOTE 3 12956 12957 The obfuscation value for each signing key will be unique to that key in a specific location. That is, 12958 each version of a duplicated signing key will have a different obfuscation value. 12959 12960 When the signing key is TPM_RH_NULL, the data structure is produced but not signed; and the values in 12961 the signed data structure are obfuscated. When computing the obfuscation value for TPM_RH_NULL, the 12962 hash used for context integrity is used. 12963 NOTE 4 12964 12965 The QN for TPM_RH_NULL is TPM_RH_NULL. 12966 12967 If the signing scheme of signHandle is an anonymous scheme, then the attestation blocks will not contain 12968 the Qualified Name of the signHandle. 12969 Each of the attestation structures allows the caller to provide some qualifying data (qualifyingData). For 12970 most signing schemes, this value will be placed in the TPMS_ATTEST.extraData parameter that is then 12971 12972 Family 2.0 12973 Level 00 Revision 00.99 12974 12975 Published 12976 Copyright TCG 2006-2013 12977 12978 Page 151 12979 October 31, 2013 12980 12981 Part 3: Commands 12983 12984 Trusted Platform Module Library 12985 12986 hashed and signed. However, for some schemes such as ECDAA, the qualifyingData is used in a 12987 different manner (for details, see ECDAA in Part 1). 12988 12989 Page 152 12990 October 31, 2013 12991 12992 Published 12993 Copyright TCG 2006-2013 12994 12995 Family 2.0 12996 Level 00 Revision 00.99 12997 12998 Trusted Platform Module Library 13000 13001 20.2 13002 13003 Part 3: Commands 13004 13005 TPM2_Certify 13006 13007 20.2.1 General Description 13008 The purpose of this command is to prove that an object with a specific Name is loaded in the TPM. By 13009 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 13010 same Name as a Name certified with this command, then the values in that public area are correct. 13011 NOTE 1 13012 13013 See 20.1 for description of how the signing scheme is selected. 13014 13015 Authorization for objectHandle requires ADMIN role authorization. If performed with a policy session, the 13016 session shall have a policySessioncommandCode set to TPM_CC_Certify. This indicates that the 13017 policy that is being used is a policy that is for certification, and not a policy that would approve another 13018 use. That is, authority to use an object does not grant authority to certify the object. 13019 The object may be any object that is loaded with TPM2_Load() or TPM2_CreatePrimary(). An object that 13020 only has its public area loaded cannot be certified. 13021 NOTE 2 13022 13023 The restriction occurs because the Name is used to identify the object being certified. If the TPM 13024 has not validated that the public area is associated with a matched sensitive area, then the public 13025 area may not represent a valid object a nd cannot be certified. 13026 13027 The certification includes the Name and Qualified Name of the certified object as well as the Name and 13028 the Qualified Name of the certifying object. 13029 13030 Family 2.0 13031 Level 00 Revision 00.99 13032 13033 Published 13034 Copyright TCG 2006-2013 13035 13036 Page 153 13037 October 31, 2013 13038 13039 Part 3: Commands 13041 13042 Trusted Platform Module Library 13043 13044 20.2.2 Command and Response 13045 Table 77 TPM2_Certify Command 13046 Type 13047 13048 Name 13049 13050 TPMI_ST_COMMAND_TAG 13051 13052 tag 13053 13054 UINT32 13055 13056 commandSize 13057 13058 TPM_CC 13059 13060 commandCode 13061 13062 TPM_CC_Certify 13063 13064 TPMI_DH_OBJECT 13065 13066 @objectHandle 13067 13068 handle of the object to be certified 13069 Auth Index: 1 13070 Auth Role: ADMIN 13071 13072 TPMI_DH_OBJECT+ 13073 13074 @signHandle 13075 13076 handle of the key used to sign the attestation structure 13077 Auth Index: 2 13078 Auth Role: USER 13079 13080 TPM2B_DATA 13081 13082 qualifyingData 13083 13084 user provided qualifying data 13085 13086 TPMT_SIG_SCHEME+ 13087 13088 inScheme 13089 13090 signing scheme to use if the scheme for signHandle is 13091 TPM_ALG_NULL 13092 13093 Description 13094 13095 Table 78 TPM2_Certify Response 13096 Type 13097 13098 Name 13099 13100 Description 13101 13102 TPM_ST 13103 13104 tag 13105 13106 see clause 8 13107 13108 UINT32 13109 13110 responseSize 13111 13112 TPM_RC 13113 13114 responseCode 13115 13116 . 13117 13118 TPM2B_ATTEST 13119 13120 certifyInfo 13121 13122 the structure that was signed 13123 13124 TPMT_SIGNATURE 13125 13126 signature 13127 13128 the asymmetric signature over certifyInfo using the key 13129 referenced by signHandle 13130 13131 Page 154 13132 October 31, 2013 13133 13134 Published 13135 Copyright TCG 2006-2013 13136 13137 Family 2.0 13138 Level 00 Revision 00.99 13139 13140 Trusted Platform Module Library 13142 13143 Part 3: Commands 13144 13145 20.2.3 Detailed Actions 13146 1 13147 2 13148 3 13149 13150 #include "InternalRoutines.h" 13151 #include "Attest_spt_fp.h" 13152 #include "Certify_fp.h" 13153 Error Returns 13154 TPM_RC_KEY 13155 13156 key referenced by signHandle is not a signing key 13157 13158 TPM_RC_SCHEME 13159 13160 inScheme is not compatible with signHandle 13161 13162 TPM_RC_VALUE 13163 13164 4 13165 5 13166 6 13167 7 13168 8 13169 9 13170 10 13171 11 13172 12 13173 13 13174 14 13175 15 13176 16 13177 17 13178 18 13179 19 13180 20 13181 21 13182 22 13183 23 13184 24 13185 25 13186 26 13187 27 13188 28 13189 29 13190 30 13191 31 13192 32 13193 33 13194 34 13195 35 13196 36 13197 37 13198 38 13199 39 13200 40 13201 41 13202 42 13203 43 13204 44 13205 45 13206 46 13207 47 13208 48 13209 13210 Meaning 13211 13212 digest generated for inScheme is greater or has larger size than the 13213 modulus of signHandle, or the buffer for the result in signature is too 13214 small (for an RSA key); invalid commit status (for an ECC key with a 13215 split scheme). 13216 13217 TPM_RC 13218 TPM2_Certify( 13219 Certify_In 13220 Certify_Out 13221 13222 *in, 13223 *out 13224 13225 // IN: input parameter list 13226 // OUT: output parameter list 13227 13228 ) 13229 { 13230 TPM_RC 13231 TPMS_ATTEST 13232 13233 result; 13234 certifyInfo; 13235 13236 // Command Output 13237 // Filling in attest information 13238 // Common fields 13239 result = FillInAttestInfo(in->signHandle, 13240 &in->inScheme, 13241 &in->qualifyingData, 13242 &certifyInfo); 13243 if(result != TPM_RC_SUCCESS) 13244 { 13245 if(result == TPM_RC_KEY) 13246 return TPM_RC_KEY + RC_Certify_signHandle; 13247 else 13248 return RcSafeAddToResult(result, RC_Certify_inScheme); 13249 } 13250 // Certify specific fields 13251 // Attestation type 13252 certifyInfo.type = TPM_ST_ATTEST_CERTIFY; 13253 // Certified object name 13254 certifyInfo.attested.certify.name.t.size = 13255 ObjectGetName(in->objectHandle, 13256 &certifyInfo.attested.certify.name.t.name); 13257 // Certified object qualified name 13258 ObjectGetQualifiedName(in->objectHandle, 13259 &certifyInfo.attested.certify.qualifiedName); 13260 // Sign attestation structure. A NULL signature will be returned if 13261 // signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE, 13262 // TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned 13263 // by SignAttestInfo() 13264 result = SignAttestInfo(in->signHandle, 13265 &in->inScheme, 13266 &certifyInfo, 13267 &in->qualifyingData, 13268 &out->certifyInfo, 13269 13270 Family 2.0 13271 Level 00 Revision 00.99 13272 13273 Published 13274 Copyright TCG 2006-2013 13275 13276 Page 155 13277 October 31, 2013 13278 13279 Part 3: Commands 13281 49 13282 50 13283 51 13284 52 13285 53 13286 54 13287 55 13288 56 13289 57 13290 58 13291 59 13292 60 13293 61 13294 62 13295 63 13296 64 13297 13298 Trusted Platform Module Library 13299 &out->signature); 13300 13301 // TPM_RC_ATTRIBUTES cannot be returned here as FillInAttestInfo would already 13302 // have returned TPM_RC_KEY 13303 pAssert(result != TPM_RC_ATTRIBUTES); 13304 if(result != TPM_RC_SUCCESS) 13305 return result; 13306 // orderly state should be cleared because of the reporting of clock info 13307 // if signing happens 13308 if(in->signHandle != TPM_RH_NULL) 13309 g_clearOrderly = TRUE; 13310 return TPM_RC_SUCCESS; 13311 } 13312 13313 Page 156 13314 October 31, 2013 13315 13316 Published 13317 Copyright TCG 2006-2013 13318 13319 Family 2.0 13320 Level 00 Revision 00.99 13321 13322 Trusted Platform Module Library 13324 13325 20.3 13326 13327 Part 3: Commands 13328 13329 TPM2_CertifyCreation 13330 13331 20.3.1 General Description 13332 This command is used to prove the association between an object and its creation data. The TPM will 13333 validate that the ticket was produced by the TPM and that the ticket validates the association between a 13334 loaded public area and the provided hash of the creation data (creationHash). 13335 NOTE 1 13336 13337 See 20.1 for description of how the signing scheme is selected. 13338 13339 The TPM will create a test ticket using the Name associated with objectHandle and creationHash as: 13340 13341 HMAC(proof, (TPM_ST_CREATION || objectHandleName || creationHash)) 13342 13343 (4) 13344 13345 This ticket is then compared to creation ticket. If the tickets are not the same, the TPM shall return 13346 TPM_RC_TICKET. 13347 If the ticket is valid, then the TPM will create a TPMS_ATTEST structure and place creationHash of the 13348 command in the creationHash field of the structure. The Name associated with objectHandle will be 13349 included in the attestation data that is then signed using the key associated with signHandle. 13350 NOTE 2 13351 13352 If signHandle is TPM_RH_NULL, the TPMS_ATTEST structure is returned and signature is a NULL 13353 Signature. 13354 13355 ObjectHandle may be any object that is loaded with TPM2_Load() or TPM2_CreatePrimary(). 13356 13357 Family 2.0 13358 Level 00 Revision 00.99 13359 13360 Published 13361 Copyright TCG 2006-2013 13362 13363 Page 157 13364 October 31, 2013 13365 13366 Part 3: Commands 13368 13369 Trusted Platform Module Library 13370 13371 20.3.2 Command and Response 13372 Table 79 TPM2_CertifyCreation Command 13373 Type 13374 13375 Name 13376 13377 Description 13378 13379 TPMI_ST_COMMAND_TAG 13380 13381 tag 13382 13383 UINT32 13384 13385 commandSize 13386 13387 TPM_CC 13388 13389 commandCode 13390 13391 TPM_CC_CertifyCreation 13392 13393 TPMI_DH_OBJECT+ 13394 13395 @signHandle 13396 13397 handle of the key that will sign the attestation block 13398 Auth Index: 1 13399 Auth Role: USER 13400 13401 TPMI_DH_OBJECT 13402 13403 objectHandle 13404 13405 the object associated with the creation data 13406 Auth Index: None 13407 13408 TPM2B_DATA 13409 13410 qualifyingData 13411 13412 user-provided qualifying data 13413 13414 TPM2B_DIGEST 13415 13416 creationHash 13417 13418 hash of the creation data produced by TPM2_Create() 13419 or TPM2_CreatePrimary() 13420 13421 TPMT_SIG_SCHEME+ 13422 13423 inScheme 13424 13425 signing scheme to use if the scheme for signHandle is 13426 TPM_ALG_NULL 13427 13428 TPMT_TK_CREATION 13429 13430 creationTicket 13431 13432 ticket produced by TPM2_Create() or 13433 TPM2_CreatePrimary() 13434 13435 Table 80 TPM2_CertifyCreation Response 13436 Type 13437 13438 Name 13439 13440 Description 13441 13442 TPM_ST 13443 13444 tag 13445 13446 see clause 8 13447 13448 UINT32 13449 13450 responseSize 13451 13452 TPM_RC 13453 13454 responseCode 13455 13456 TPM2B_ATTEST 13457 13458 certifyInfo 13459 13460 the structure that was signed 13461 13462 TPMT_SIGNATURE 13463 13464 signature 13465 13466 the signature over certifyInfo 13467 13468 Page 158 13469 October 31, 2013 13470 13471 Published 13472 Copyright TCG 2006-2013 13473 13474 Family 2.0 13475 Level 00 Revision 00.99 13476 13477 Trusted Platform Module Library 13479 13480 Part 3: Commands 13481 13482 20.3.3 Detailed Actions 13483 1 13484 2 13485 3 13486 13487 #include "InternalRoutines.h" 13488 #include "Attest_spt_fp.h" 13489 #include "CertifyCreation_fp.h" 13490 Error Returns 13491 TPM_RC_KEY 13492 13493 key referenced by signHandle is not a signing key 13494 13495 TPM_RC_SCHEME 13496 13497 inScheme is not compatible with signHandle 13498 13499 TPM_RC_TICKET 13500 13501 creationTicket does not match objectHandle 13502 13503 TPM_RC_VALUE 13504 13505 4 13506 5 13507 6 13508 7 13509 8 13510 9 13511 10 13512 11 13513 12 13514 13 13515 14 13516 15 13517 16 13518 17 13519 18 13520 19 13521 20 13522 21 13523 22 13524 23 13525 24 13526 25 13527 26 13528 27 13529 28 13530 29 13531 30 13532 31 13533 32 13534 33 13535 34 13536 35 13537 36 13538 37 13539 38 13540 39 13541 40 13542 41 13543 42 13544 43 13545 44 13546 45 13547 46 13548 13549 Meaning 13550 13551 digest generated for inScheme is greater or has larger size than the 13552 modulus of signHandle, or the buffer for the result in signature is too 13553 small (for an RSA key); invalid commit status (for an ECC key with a 13554 split scheme). 13555 13556 TPM_RC 13557 TPM2_CertifyCreation( 13558 CertifyCreation_In 13559 CertifyCreation_Out 13560 13561 *in, 13562 *out 13563 13564 // IN: input parameter list 13565 // OUT: output parameter list 13566 13567 ) 13568 { 13569 TPM_RC 13570 TPM2B_NAME 13571 TPMT_TK_CREATION 13572 TPMS_ATTEST 13573 13574 result; 13575 name; 13576 ticket; 13577 certifyInfo; 13578 13579 // Input Validation 13580 // CertifyCreation specific input validation 13581 // Get certified object name 13582 name.t.size = ObjectGetName(in->objectHandle, &name.t.name); 13583 // Re-compute ticket 13584 TicketComputeCreation(in->creationTicket.hierarchy, &name, 13585 &in->creationHash, &ticket); 13586 // Compare ticket 13587 if(!Memory2BEqual(&ticket.digest.b, &in->creationTicket.digest.b)) 13588 return TPM_RC_TICKET + RC_CertifyCreation_creationTicket; 13589 // Command Output 13590 // Common fields 13591 result = FillInAttestInfo(in->signHandle, &in->inScheme, &in->qualifyingData, 13592 &certifyInfo); 13593 if(result != TPM_RC_SUCCESS) 13594 { 13595 if(result == TPM_RC_KEY) 13596 return TPM_RC_KEY + RC_CertifyCreation_signHandle; 13597 else 13598 return RcSafeAddToResult(result, RC_CertifyCreation_inScheme); 13599 } 13600 // CertifyCreation specific fields 13601 // Attestation type 13602 certifyInfo.type = TPM_ST_ATTEST_CREATION; 13603 certifyInfo.attested.creation.objectName = name; 13604 // Copy the creationHash 13605 certifyInfo.attested.creation.creationHash = in->creationHash; 13606 13607 Family 2.0 13608 Level 00 Revision 00.99 13609 13610 Published 13611 Copyright TCG 2006-2013 13612 13613 Page 159 13614 October 31, 2013 13615 13616 Part 3: Commands 13618 47 13619 48 13620 49 13621 50 13622 51 13623 52 13624 53 13625 54 13626 55 13627 56 13628 57 13629 58 13630 59 13631 60 13632 61 13633 62 13634 63 13635 64 13636 65 13637 66 13638 67 13639 68 13640 69 13641 70 13642 71 13643 13644 Trusted Platform Module Library 13645 13646 // Sign attestation structure. A NULL signature will be returned if 13647 // signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE, 13648 // TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned at 13649 // this point 13650 result = SignAttestInfo(in->signHandle, 13651 &in->inScheme, 13652 &certifyInfo, 13653 &in->qualifyingData, 13654 &out->certifyInfo, 13655 &out->signature); 13656 // TPM_RC_ATTRIBUTES cannot be returned here as FillInAttestInfo would already 13657 // have returned TPM_RC_KEY 13658 pAssert(result != TPM_RC_ATTRIBUTES); 13659 if(result != TPM_RC_SUCCESS) 13660 return result; 13661 // orderly state should be cleared because of the reporting of clock info 13662 // if signing happens 13663 if(in->signHandle != TPM_RH_NULL) 13664 g_clearOrderly = TRUE; 13665 return TPM_RC_SUCCESS; 13666 } 13667 13668 Page 160 13669 October 31, 2013 13670 13671 Published 13672 Copyright TCG 2006-2013 13673 13674 Family 2.0 13675 Level 00 Revision 00.99 13676 13677 Trusted Platform Module Library 13679 13680 20.4 13681 13682 Part 3: Commands 13683 13684 TPM2_Quote 13685 13686 20.4.1 General Description 13687 This command is used to quote PCR values. 13688 NOTE 13689 13690 See 20.1 for description of how the signing scheme is selected. 13691 13692 The TPM will hash the list of PCR selected by PCRselect using the hash algorithm associated with 13693 signHandle (this is the hash algorithm of the signing scheme, not the nameAlg of signHandle). 13694 The digest is computed as the hash of the concatenation of all of the digest values of the selected PCR. 13695 The concatenation of PCR is described in Part 1, Selecting Multiple PCR. 13696 13697 Family 2.0 13698 Level 00 Revision 00.99 13699 13700 Published 13701 Copyright TCG 2006-2013 13702 13703 Page 161 13704 October 31, 2013 13705 13706 Part 3: Commands 13708 13709 Trusted Platform Module Library 13710 13711 20.4.2 Command and Response 13712 Table 81 TPM2_Quote Command 13713 Type 13714 13715 Name 13716 13717 Description 13718 13719 TPMI_ST_COMMAND_TAG 13720 13721 tag 13722 13723 UINT32 13724 13725 commandSize 13726 13727 TPM_CC 13728 13729 commandCode 13730 13731 TPM_CC_Quote 13732 13733 TPMI_DH_OBJECT 13734 13735 @signHandle 13736 13737 handle of key that will perform signature 13738 Auth Index: 1 13739 Auth Role: USER 13740 13741 TPM2B_DATA 13742 13743 qualifyingData 13744 13745 data supplied by the caller 13746 13747 TPMT_SIG_SCHEME+ 13748 13749 inScheme 13750 13751 signing scheme to use if the scheme for signHandle is 13752 TPM_ALG_NULL 13753 13754 TPML_PCR_SELECTION 13755 13756 PCRselect 13757 13758 PCR set to quote 13759 13760 Table 82 TPM2_Quote Response 13761 Type 13762 13763 Name 13764 13765 Description 13766 13767 TPM_ST 13768 13769 tag 13770 13771 see clause 8 13772 13773 UINT32 13774 13775 responseSize 13776 13777 TPM_RC 13778 13779 responseCode 13780 13781 TPM2B_ATTEST 13782 13783 quoted 13784 13785 the quoted information 13786 13787 TPMT_SIGNATURE 13788 13789 signature 13790 13791 the signature over quoted 13792 13793 Page 162 13794 October 31, 2013 13795 13796 Published 13797 Copyright TCG 2006-2013 13798 13799 Family 2.0 13800 Level 00 Revision 00.99 13801 13802 Trusted Platform Module Library 13804 13805 Part 3: Commands 13806 13807 20.4.3 Detailed Actions 13808 1 13809 2 13810 3 13811 13812 #include "InternalRoutines.h" 13813 #include "Attest_spt_fp.h" 13814 #include "Quote_fp.h" 13815 Error Returns 13816 TPM_RC_KEY 13817 13818 signHandle does not reference a signing key; 13819 13820 TPM_RC_SCHEME 13821 13822 4 13823 5 13824 6 13825 7 13826 8 13827 9 13828 10 13829 11 13830 12 13831 13 13832 14 13833 15 13834 16 13835 17 13836 18 13837 19 13838 20 13839 21 13840 22 13841 23 13842 24 13843 25 13844 26 13845 27 13846 28 13847 29 13848 30 13849 31 13850 32 13851 33 13852 34 13853 35 13854 36 13855 37 13856 38 13857 39 13858 40 13859 41 13860 42 13861 43 13862 44 13863 45 13864 46 13865 47 13866 48 13867 49 13868 50 13869 51 13870 13871 Meaning 13872 13873 the scheme is not compatible with sign key type, or input scheme is 13874 not compatible with default scheme, or the chosen scheme is not a 13875 valid sign scheme 13876 13877 TPM_RC 13878 TPM2_Quote( 13879 Quote_In 13880 Quote_Out 13881 13882 *in, 13883 *out 13884 13885 // IN: input parameter list 13886 // OUT: output parameter list 13887 13888 ) 13889 { 13890 TPM_RC 13891 TPMI_ALG_HASH 13892 TPMS_ATTEST 13893 13894 result; 13895 hashAlg; 13896 quoted; 13897 13898 // Command Output 13899 // Filling in attest information 13900 // Common fields 13901 // FillInAttestInfo will return TPM_RC_SCHEME or TPM_RC_KEY 13902 result = FillInAttestInfo(in->signHandle, 13903 &in->inScheme, 13904 &in->qualifyingData, 13905 "ed); 13906 if(result != TPM_RC_SUCCESS) 13907 { 13908 if(result == TPM_RC_KEY) 13909 return TPM_RC_KEY + RC_Quote_signHandle; 13910 else 13911 return RcSafeAddToResult(result, RC_Quote_inScheme); 13912 } 13913 // Quote specific fields 13914 // Attestation type 13915 quoted.type = TPM_ST_ATTEST_QUOTE; 13916 // Get hash algorithm in sign scheme. This hash algorithm is used to 13917 // compute PCR digest. If there is no algorithm, then the PCR cannot 13918 // be digested and this command returns TPM_RC_SCHEME 13919 hashAlg = in->inScheme.details.any.hashAlg; 13920 if(hashAlg == TPM_ALG_NULL) 13921 return TPM_RC_SCHEME + RC_Quote_inScheme; 13922 // Compute PCR digest 13923 PCRComputeCurrentDigest(hashAlg, 13924 &in->PCRselect, 13925 "ed.attested.quote.pcrDigest); 13926 // Copy PCR select. "PCRselect" is modified in PCRComputeCurrentDigest 13927 // function 13928 quoted.attested.quote.pcrSelect = in->PCRselect; 13929 13930 Family 2.0 13931 Level 00 Revision 00.99 13932 13933 Published 13934 Copyright TCG 2006-2013 13935 13936 Page 163 13937 October 31, 2013 13938 13939 Part 3: Commands 13941 52 13942 53 13943 54 13944 55 13945 56 13946 57 13947 58 13948 59 13949 60 13950 61 13951 62 13952 63 13953 64 13954 65 13955 66 13956 67 13957 68 13958 69 13959 70 13960 71 13961 72 13962 73 13963 74 13964 13965 Trusted Platform Module Library 13966 13967 // Sign attestation structure. A NULL signature will be returned if 13968 // signHandle is TPM_RH_NULL. TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES 13969 // error may be returned by SignAttestInfo. 13970 // NOTE: TPM_RC_ATTRIBUTES means that the key is not a signing key but that 13971 // was checked above and TPM_RC_KEY was returned. TPM_RC_VALUE means that the 13972 // value to sign is too large but that means that the digest is too big and 13973 // that can't happen. 13974 result = SignAttestInfo(in->signHandle, 13975 &in->inScheme, 13976 "ed, 13977 &in->qualifyingData, 13978 &out->quoted, 13979 &out->signature); 13980 if(result != TPM_RC_SUCCESS) 13981 return result; 13982 // orderly state should be cleared because of the reporting of clock info 13983 // if signing happens 13984 if(in->signHandle != TPM_RH_NULL) 13985 g_clearOrderly = TRUE; 13986 return TPM_RC_SUCCESS; 13987 } 13988 13989 Page 164 13990 October 31, 2013 13991 13992 Published 13993 Copyright TCG 2006-2013 13994 13995 Family 2.0 13996 Level 00 Revision 00.99 13997 13998 Trusted Platform Module Library 14000 14001 20.5 14002 14003 Part 3: Commands 14004 14005 TPM2_GetSessionAuditDigest 14006 14007 20.5.1 General Description 14008 This command returns a digital signature of the audit session digest. 14009 NOTE 1 14010 14011 See 20.1 for description of how the signing scheme is selected. 14012 14013 If sessionHandle is not an audit session, the TPM shall return TPM_RC_TYPE. 14014 NOTE 2 14015 14016 A session does not become an audit session until the successful completion of the command in 14017 which the session is first used as an audit session. 14018 14019 This command requires authorization from the privacy administrator of the TPM (expressed with 14020 endorsementAuth) as well as authorization to use the key associated with signHandle. 14021 If this command is audited, then the audit digest that is signed will not include the digest of this command 14022 because the audit digest is only updated when the command completes successfully. 14023 This command does not cause the audit session to be closed and does not reset the digest value. 14024 NOTE 3 14025 14026 The audit session digest will be reset if the sessionHandle is used as the audit session for the 14027 command and the auditReset attribute of the session is set; and this command will be the first 14028 command in the audit digest. 14029 14030 NOTE 4 14031 14032 A reason for using 'sessionHahdle' in this command is so that the continueSession attribute may be 14033 CLEAR. This will flush the session at the end of the command. 14034 14035 Family 2.0 14036 Level 00 Revision 00.99 14037 14038 Published 14039 Copyright TCG 2006-2013 14040 14041 Page 165 14042 October 31, 2013 14043 14044 Part 3: Commands 14046 14047 Trusted Platform Module Library 14048 14049 20.5.2 Command and Response 14050 Table 83 TPM2_GetSessionAuditDigest Command 14051 Type 14052 14053 Name 14054 14055 TPMI_ST_COMMAND_TAG 14056 14057 tag 14058 14059 UINT32 14060 14061 commandSize 14062 14063 TPM_CC 14064 14065 commandCode 14066 14067 TPM_CC_GetSessionAuditDigest 14068 14069 TPMI_RH_ENDORSEMENT 14070 14071 @privacyAdminHandle 14072 14073 handle of the privacy administrator 14074 (TPM_RH_ENDORSEMENT) 14075 Auth Index: 1 14076 Auth Role: USER 14077 14078 TPMI_DH_OBJECT+ 14079 14080 @signHandle 14081 14082 handle of the signing key 14083 Auth Index: 2 14084 Auth Role: USER 14085 14086 TPMI_SH_HMAC 14087 14088 sessionHandle 14089 14090 handle of the audit session 14091 Auth Index: None 14092 14093 TPM2B_DATA 14094 14095 qualifyingData 14096 14097 user-provided qualifying data may be zero-length 14098 14099 TPMT_SIG_SCHEME+ 14100 14101 inScheme 14102 14103 signing scheme to use if the scheme for signHandle is 14104 TPM_ALG_NULL 14105 14106 Description 14107 14108 Table 84 TPM2_GetSessionAuditDigest Response 14109 Type 14110 14111 Name 14112 14113 Description 14114 14115 TPM_ST 14116 14117 tag 14118 14119 see clause 8 14120 14121 UINT32 14122 14123 responseSize 14124 14125 TPM_RC 14126 14127 responseCode 14128 14129 TPM2B_ATTEST 14130 14131 auditInfo 14132 14133 the audit information that was signed 14134 14135 TPMT_SIGNATURE 14136 14137 signature 14138 14139 the signature over auditInfo 14140 14141 Page 166 14142 October 31, 2013 14143 14144 Published 14145 Copyright TCG 2006-2013 14146 14147 Family 2.0 14148 Level 00 Revision 00.99 14149 14150 Trusted Platform Module Library 14152 14153 Part 3: Commands 14154 14155 20.5.3 Detailed Actions 14156 1 14157 2 14158 3 14159 14160 #include "InternalRoutines.h" 14161 #include "Attest_spt_fp.h" 14162 #include "GetSessionAuditDigest_fp.h" 14163 Error Returns 14164 TPM_RC_KEY 14165 14166 key referenced by signHandle is not a signing key 14167 14168 TPM_RC_SCHEME 14169 14170 inScheme is incompatible with signHandle type; or both scheme and 14171 key's default scheme are empty; or scheme is empty while key's 14172 default scheme requires explicit input scheme (split signing); or nonempty default key scheme differs from scheme 14173 14174 TPM_RC_TYPE 14175 14176 sessionHandle does not reference an audit session 14177 14178 TPM_RC_VALUE 14179 14180 4 14181 5 14182 6 14183 7 14184 8 14185 9 14186 10 14187 11 14188 12 14189 13 14190 14 14191 15 14192 16 14193 17 14194 18 14195 19 14196 20 14197 21 14198 22 14199 23 14200 24 14201 25 14202 26 14203 27 14204 28 14205 29 14206 30 14207 31 14208 32 14209 33 14210 34 14211 35 14212 36 14213 37 14214 38 14215 39 14216 40 14217 41 14218 42 14219 43 14220 44 14221 14222 Meaning 14223 14224 digest generated for the given scheme is greater than the modulus of 14225 signHandle (for an RSA key); invalid commit status or failed to 14226 generate r value (for an ECC key) 14227 14228 TPM_RC 14229 TPM2_GetSessionAuditDigest( 14230 GetSessionAuditDigest_In 14231 GetSessionAuditDigest_Out 14232 14233 *in, 14234 *out 14235 14236 // IN: input parameter list 14237 // OUT: output parameter list 14238 14239 ) 14240 { 14241 TPM_RC 14242 SESSION 14243 TPMS_ATTEST 14244 14245 result; 14246 *session; 14247 auditInfo; 14248 14249 // Input Validation 14250 // SessionAuditDigest specific input validation 14251 // Get session pointer 14252 session = SessionGet(in->sessionHandle); 14253 // session must be an audit session 14254 if(session->attributes.isAudit == CLEAR) 14255 return TPM_RC_TYPE + RC_GetSessionAuditDigest_sessionHandle; 14256 // Command Output 14257 // Filling in attest information 14258 // Common fields 14259 result = FillInAttestInfo(in->signHandle, 14260 &in->inScheme, 14261 &in->qualifyingData, 14262 &auditInfo); 14263 if(result != TPM_RC_SUCCESS) 14264 { 14265 if(result == TPM_RC_KEY) 14266 return TPM_RC_KEY + RC_GetSessionAuditDigest_signHandle; 14267 else 14268 return RcSafeAddToResult(result, RC_GetSessionAuditDigest_inScheme); 14269 } 14270 // SessionAuditDigest specific fields 14271 // Attestation type 14272 auditInfo.type = TPM_ST_ATTEST_SESSION_AUDIT; 14273 // Copy digest 14274 14275 Family 2.0 14276 Level 00 Revision 00.99 14277 14278 Published 14279 Copyright TCG 2006-2013 14280 14281 Page 167 14282 October 31, 2013 14283 14284 Part 3: Commands 14286 45 14287 46 14288 47 14289 48 14290 49 14291 50 14292 51 14293 52 14294 53 14295 54 14296 55 14297 56 14298 57 14299 58 14300 59 14301 60 14302 61 14303 62 14304 63 14305 64 14306 65 14307 66 14308 67 14309 68 14310 69 14311 70 14312 71 14313 72 14314 14315 Trusted Platform Module Library 14316 14317 auditInfo.attested.sessionAudit.sessionDigest = session->u2.auditDigest; 14318 // Exclusive audit session 14319 if(g_exclusiveAuditSession == in->sessionHandle) 14320 auditInfo.attested.sessionAudit.exclusiveSession = TRUE; 14321 else 14322 auditInfo.attested.sessionAudit.exclusiveSession = FALSE; 14323 // Sign attestation structure. A NULL signature will be returned if 14324 // signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE, 14325 // TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned at 14326 // this point 14327 result = SignAttestInfo(in->signHandle, 14328 &in->inScheme, 14329 &auditInfo, 14330 &in->qualifyingData, 14331 &out->auditInfo, 14332 &out->signature); 14333 if(result != TPM_RC_SUCCESS) 14334 return result; 14335 // orderly state should be cleared because of the reporting of clock info 14336 // if signing happens 14337 if(in->signHandle != TPM_RH_NULL) 14338 g_clearOrderly = TRUE; 14339 return TPM_RC_SUCCESS; 14340 } 14341 14342 Page 168 14343 October 31, 2013 14344 14345 Published 14346 Copyright TCG 2006-2013 14347 14348 Family 2.0 14349 Level 00 Revision 00.99 14350 14351 Trusted Platform Module Library 14353 14354 20.6 14355 14356 Part 3: Commands 14357 14358 TPM2_GetCommandAuditDigest 14359 14360 20.6.1 General Description 14361 This command returns the current value of the command audit digest, a digest of the commands being 14362 audited, and the audit hash algorithm. These values are placed in an attestation structure and signed with 14363 the key referenced by signHandle. 14364 NOTE 1 14365 14366 See 20.1 for description of how the signing scheme is selected. 14367 14368 When this command completes successfully, and signHandle is not TPM_RH_NULL, the audit digest is 14369 cleared. 14370 NOTE 2 14371 14372 The way that the TPM tracks that the digest is clear is vendor -dependent. The reference 14373 implementation resets the size of the digest to zero. 14374 14375 If this command is being audited, then the signed digest produced by the command will not include the 14376 command. At the end of this command, the audit digest will be extended with cpHash and the rpHash of 14377 the command which would change the command audit digest signed by the next invocation of this 14378 command. 14379 This command requires authorization from the privacy administrator of the TPM (expressed with 14380 endorsementAuth) as well as authorization to use the key associated with signHandle. 14381 14382 Family 2.0 14383 Level 00 Revision 00.99 14384 14385 Published 14386 Copyright TCG 2006-2013 14387 14388 Page 169 14389 October 31, 2013 14390 14391 Part 3: Commands 14393 14394 Trusted Platform Module Library 14395 14396 20.6.2 Command and Response 14397 Table 85 TPM2_GetCommandAuditDigest Command 14398 Type 14399 14400 Name 14401 14402 Description 14403 14404 TPMI_ST_COMMAND_TAG 14405 14406 tag 14407 14408 UINT32 14409 14410 commandSize 14411 14412 TPM_CC 14413 14414 commandCode 14415 14416 TPM_CC_GetCommandAuditDigest {NV} 14417 14418 TPMI_RH_ENDORSEMENT 14419 14420 @privacyHandle 14421 14422 handle of the privacy administrator 14423 (TPM_RH_ENDORSEMENT) 14424 Auth Index: 1 14425 Auth Role: USER 14426 14427 TPMI_DH_OBJECT+ 14428 14429 @signHandle 14430 14431 the handle of the signing key 14432 Auth Index: 2 14433 Auth Role: USER 14434 14435 TPM2B_DATA 14436 14437 qualifyingData 14438 14439 other data to associate with this audit digest 14440 14441 TPMT_SIG_SCHEME+ 14442 14443 inScheme 14444 14445 signing scheme to use if the scheme for signHandle is 14446 TPM_ALG_NULL 14447 14448 Table 86 TPM2_GetCommandAuditDigest Response 14449 Type 14450 14451 Name 14452 14453 Description 14454 14455 TPM_ST 14456 14457 tag 14458 14459 see clause 8 14460 14461 UINT32 14462 14463 responseSize 14464 14465 TPM_RC 14466 14467 responseCode 14468 14469 TPM2B_ATTEST 14470 14471 auditInfo 14472 14473 the auditInfo that was signed 14474 14475 TPMT_SIGNATURE 14476 14477 signature 14478 14479 the signature over auditInfo 14480 14481 Page 170 14482 October 31, 2013 14483 14484 Published 14485 Copyright TCG 2006-2013 14486 14487 Family 2.0 14488 Level 00 Revision 00.99 14489 14490 Trusted Platform Module Library 14492 14493 Part 3: Commands 14494 14495 20.6.3 Detailed Actions 14496 1 14497 2 14498 3 14499 14500 #include "InternalRoutines.h" 14501 #include "Attest_spt_fp.h" 14502 #include "GetCommandAuditDigest_fp.h" 14503 Error Returns 14504 TPM_RC_KEY 14505 14506 key referenced by signHandle is not a signing key 14507 14508 TPM_RC_SCHEME 14509 14510 inScheme is incompatible with signHandle type; or both scheme and 14511 key's default scheme are empty; or scheme is empty while key's 14512 default scheme requires explicit input scheme (split signing); or nonempty default key scheme differs from scheme 14513 14514 TPM_RC_VALUE 14515 14516 4 14517 5 14518 6 14519 7 14520 8 14521 9 14522 10 14523 11 14524 12 14525 13 14526 14 14527 15 14528 16 14529 17 14530 18 14531 19 14532 20 14533 21 14534 22 14535 23 14536 24 14537 25 14538 26 14539 27 14540 28 14541 29 14542 30 14543 31 14544 32 14545 33 14546 34 14547 35 14548 36 14549 37 14550 38 14551 39 14552 40 14553 41 14554 42 14555 43 14556 44 14557 45 14558 46 14559 14560 Meaning 14561 14562 digest generated for the given scheme is greater than the modulus of 14563 signHandle (for an RSA key); invalid commit status or failed to 14564 generate r value (for an ECC key) 14565 14566 TPM_RC 14567 TPM2_GetCommandAuditDigest( 14568 GetCommandAuditDigest_In 14569 GetCommandAuditDigest_Out 14570 14571 *in, 14572 *out 14573 14574 // IN: input parameter list 14575 // OUT: output parameter list 14576 14577 ) 14578 { 14579 TPM_RC 14580 TPMS_ATTEST 14581 14582 result; 14583 auditInfo; 14584 14585 // Command Output 14586 // Filling in attest information 14587 // Common fields 14588 result = FillInAttestInfo(in->signHandle, 14589 &in->inScheme, 14590 &in->qualifyingData, 14591 &auditInfo); 14592 if(result != TPM_RC_SUCCESS) 14593 { 14594 if(result == TPM_RC_KEY) 14595 return TPM_RC_KEY + RC_GetCommandAuditDigest_signHandle; 14596 else 14597 return RcSafeAddToResult(result, RC_GetCommandAuditDigest_inScheme); 14598 } 14599 // CommandAuditDigest specific fields 14600 // Attestation type 14601 auditInfo.type = TPM_ST_ATTEST_COMMAND_AUDIT; 14602 // Copy audit hash algorithm 14603 auditInfo.attested.commandAudit.digestAlg = gp.auditHashAlg; 14604 // Copy counter value 14605 auditInfo.attested.commandAudit.auditCounter = gp.auditCounter; 14606 // Copy command audit log 14607 auditInfo.attested.commandAudit.auditDigest = gr.commandAuditDigest; 14608 CommandAuditGetDigest(&auditInfo.attested.commandAudit.commandDigest); 14609 // 14610 // 14611 // 14612 // 14613 14614 Sign attestation structure. A NULL signature will be returned if 14615 signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE, 14616 TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned at 14617 this point 14618 14619 Family 2.0 14620 Level 00 Revision 00.99 14621 14622 Published 14623 Copyright TCG 2006-2013 14624 14625 Page 171 14626 October 31, 2013 14627 14628 Part 3: Commands 14630 47 14631 48 14632 49 14633 50 14634 51 14635 52 14636 53 14637 54 14638 55 14639 56 14640 57 14641 58 14642 59 14643 60 14644 61 14645 62 14646 63 14647 64 14648 65 14649 66 14650 67 14651 68 14652 69 14653 70 14654 14655 Trusted Platform Module Library 14656 14657 result = SignAttestInfo(in->signHandle, 14658 &in->inScheme, 14659 &auditInfo, 14660 &in->qualifyingData, 14661 &out->auditInfo, 14662 &out->signature); 14663 if(result != TPM_RC_SUCCESS) 14664 return result; 14665 // Internal Data Update 14666 if(in->signHandle != TPM_RH_NULL) 14667 { 14668 // Reset log 14669 gr.commandAuditDigest.t.size = 0; 14670 // orderly state should be cleared because of the update in 14671 // commandAuditDigest, as well as the reporting of clock info 14672 g_clearOrderly = TRUE; 14673 } 14674 return TPM_RC_SUCCESS; 14675 } 14676 14677 Page 172 14678 October 31, 2013 14679 14680 Published 14681 Copyright TCG 2006-2013 14682 14683 Family 2.0 14684 Level 00 Revision 00.99 14685 14686 Trusted Platform Module Library 14688 14689 20.7 14690 14691 Part 3: Commands 14692 14693 TPM2_GetTime 14694 14695 20.7.1 General Description 14696 This command returns the current values of Time and Clock. 14697 NOTE 1 14698 14699 See 20.1 for description of how the signing scheme is selected. 14700 14701 The values of Clock, resetCount and restartCount appear in two places in timeInfo: once in 14702 TPMS_ATTEST.clockInfo and again in TPMS_ATTEST.attested.time.clockInfo. The firmware version 14703 number 14704 also 14705 appears 14706 in 14707 two 14708 places 14709 (TPMS_ATTEST.firmwareVersion 14710 and 14711 TPMS_ATTEST.attested.time.firmwareVersion). If signHandle is in the endorsement or platform 14712 hierarchies, both copies of the data will be the same. However, if signHandle is in the storage hierarchy or 14713 is TPM_RH_NULL, the values in TPMS_ATTEST.clockInfo and TPMS_ATTEST.firmwareVersion are 14714 obfuscated but the values in TPM_ATTEST.attested.time are not. 14715 NOTE 2 14716 14717 The purpose of this duplication is to allow an entity who is trusted by the privacy Administrator to 14718 correlate the obfuscated values with the clear -text values. 14719 14720 Family 2.0 14721 Level 00 Revision 00.99 14722 14723 Published 14724 Copyright TCG 2006-2013 14725 14726 Page 173 14727 October 31, 2013 14728 14729 Part 3: Commands 14731 14732 Trusted Platform Module Library 14733 14734 20.7.2 Command and Response 14735 Table 87 TPM2_GetTime Command 14736 Type 14737 14738 Name 14739 14740 TPMI_ST_COMMAND_TAG 14741 14742 tag 14743 14744 UINT32 14745 14746 commandSize 14747 14748 TPM_CC 14749 14750 commandCode 14751 14752 TPM_CC_GetTime 14753 14754 TPMI_RH_ENDORSEMENT 14755 14756 @privacyAdminHandle 14757 14758 handle of the privacy administrator 14759 (TPM_RH_ENDORSEMENT) 14760 Auth Index: 1 14761 Auth Role: USER 14762 14763 TPMI_DH_OBJECT+ 14764 14765 @signHandle 14766 14767 the keyHandle identifier of a loaded key that can 14768 perform digital signatures 14769 Auth Index: 2 14770 Auth Role: USER 14771 14772 TPM2B_DATA 14773 14774 qualifyingData 14775 14776 data to tick stamp 14777 14778 TPMT_SIG_SCHEME+ 14779 14780 inScheme 14781 14782 signing scheme to use if the scheme for signHandle is 14783 TPM_ALG_NULL 14784 14785 Description 14786 14787 Table 88 TPM2_GetTime Response 14788 Type 14789 14790 Name 14791 14792 Description 14793 14794 TPM_ST 14795 14796 tag 14797 14798 see clause 8 14799 14800 UINT32 14801 14802 responseSize 14803 14804 TPM_RC 14805 14806 responseCode 14807 14808 . 14809 14810 TPM2B_ATTEST 14811 14812 timeInfo 14813 14814 standard TPM-generated attestation block 14815 14816 TPMT_SIGNATURE 14817 14818 signature 14819 14820 the signature over timeInfo 14821 14822 Page 174 14823 October 31, 2013 14824 14825 Published 14826 Copyright TCG 2006-2013 14827 14828 Family 2.0 14829 Level 00 Revision 00.99 14830 14831 Trusted Platform Module Library 14833 14834 Part 3: Commands 14835 14836 20.7.3 Detailed Actions 14837 1 14838 2 14839 3 14840 14841 #include "InternalRoutines.h" 14842 #include "Attest_spt_fp.h" 14843 #include "GetTime_fp.h" 14844 Error Returns 14845 TPM_RC_KEY 14846 14847 key referenced by signHandle is not a signing key 14848 14849 TPM_RC_SCHEME 14850 14851 inScheme is incompatible with signHandle type; or both scheme and 14852 key's default scheme are empty; or scheme is empty while key's 14853 default scheme requires explicit input scheme (split signing); or nonempty default key scheme differs from scheme 14854 14855 TPM_RC_VALUE 14856 14857 4 14858 5 14859 6 14860 7 14861 8 14862 9 14863 10 14864 11 14865 12 14866 13 14867 14 14868 15 14869 16 14870 17 14871 18 14872 19 14873 20 14874 21 14875 22 14876 23 14877 24 14878 25 14879 26 14880 27 14881 28 14882 29 14883 30 14884 31 14885 32 14886 33 14887 34 14888 35 14889 36 14890 37 14891 38 14892 39 14893 40 14894 41 14895 42 14896 43 14897 44 14898 45 14899 46 14900 14901 Meaning 14902 14903 digest generated for the given scheme is greater than the modulus of 14904 signHandle (for an RSA key); invalid commit status or failed to 14905 generate r value (for an ECC key) 14906 14907 TPM_RC 14908 TPM2_GetTime( 14909 GetTime_In 14910 GetTime_Out 14911 14912 *in, 14913 *out 14914 14915 // IN: input parameter list 14916 // OUT: output parameter list 14917 14918 ) 14919 { 14920 TPM_RC 14921 TPMS_ATTEST 14922 14923 result; 14924 timeInfo; 14925 14926 // Command Output 14927 // Filling in attest information 14928 // Common fields 14929 result = FillInAttestInfo(in->signHandle, 14930 &in->inScheme, 14931 &in->qualifyingData, 14932 &timeInfo); 14933 if(result != TPM_RC_SUCCESS) 14934 { 14935 if(result == TPM_RC_KEY) 14936 return TPM_RC_KEY + RC_GetTime_signHandle; 14937 else 14938 return RcSafeAddToResult(result, RC_GetTime_inScheme); 14939 } 14940 // GetClock specific fields 14941 // Attestation type 14942 timeInfo.type = TPM_ST_ATTEST_TIME; 14943 // current clock in plain text 14944 timeInfo.attested.time.time.time = g_time; 14945 TimeFillInfo(&timeInfo.attested.time.time.clockInfo); 14946 // Firmware version in plain text 14947 timeInfo.attested.time.firmwareVersion 14948 = ((UINT64) gp.firmwareV1) << 32; 14949 timeInfo.attested.time.firmwareVersion += gp.firmwareV2; 14950 // Sign attestation structure. A NULL signature will be returned if 14951 // signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE, 14952 // TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned at 14953 // this point 14954 result = SignAttestInfo(in->signHandle, 14955 14956 Family 2.0 14957 Level 00 Revision 00.99 14958 14959 Published 14960 Copyright TCG 2006-2013 14961 14962 Page 175 14963 October 31, 2013 14964 14965 Part 3: Commands 14967 47 14968 48 14969 49 14970 50 14971 51 14972 52 14973 53 14974 54 14975 55 14976 56 14977 57 14978 58 14979 59 14980 60 14981 61 14982 14983 Trusted Platform Module Library 14984 14985 &in->inScheme, 14986 &timeInfo, 14987 &in->qualifyingData, 14988 &out->timeInfo, 14989 &out->signature); 14990 if(result != TPM_RC_SUCCESS) 14991 return result; 14992 // orderly state should be cleared because of the reporting of clock info 14993 // if signing happens 14994 if(in->signHandle != TPM_RH_NULL) 14995 g_clearOrderly = TRUE; 14996 return TPM_RC_SUCCESS; 14997 } 14998 14999 Page 176 15000 October 31, 2013 15001 15002 Published 15003 Copyright TCG 2006-2013 15004 15005 Family 2.0 15006 Level 00 Revision 00.99 15007 15008 Trusted Platform Module Library 15010 15011 21 15012 15013 Part 3: Commands 15014 15015 Ephemeral EC Keys 15016 15017 21.1 15018 15019 Introduction 15020 15021 The TPM generates keys that have different lifetimes. TPM keys in a hierarchy can be persistent for as 15022 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 15023 command in which they are created. Examples of this use are TPM2_Duplicate() where an ephemeral 15024 key is created for a single pass key exchange with another TPM. However, there are other cases, such 15025 as anonymous attestation, where the protocol requires two passes where the public part of the ephemeral 15026 key is used outside of the TPM before the final command "consumes" the ephemeral key. 15027 For these uses, TPM2_Commit() or TPM2_EC_Ephemeral() may be used to have the TPM create an 15028 ephemeral EC key and return the public part of the key for external use. Then in a subsequent command, 15029 the caller provides a reference to the ephemeral key so that the TPM can retrieve or recreate the 15030 associated private key. 15031 When an ephemeral EC key is created, it is assigned a number and that number is returned to the caller 15032 as the identifier for the key. This number is not a handle. A handle is assigned to a key that may be 15033 context saved but these ephemeral EC keys may not be saved and do not have a full key context. When 15034 a subsequent command uses the ephemeral key, the caller provides the number of the ephemeral key. 15035 The TPM uses that number to either look up or recompute the associated private key. After the key is 15036 used, the TPM records the fact that the key has been used so that it cannot be used again. 15037 As mentioned, the TPM can keep each assigned private ephemeral key in memory until it is used. 15038 However, this could consume a large amount of memory. To limit the memory size, the TPM is allowed to 15039 restrict the number of pending private keys keys that have been allocated but not used. 15040 NOTE 15041 15042 The minimum number of ephemeral keys is determined by a platform specific specification 15043 15044 To further reduce the memory requirements for the ephemeral private keys, the TPM is allowed to use 15045 pseudo-random values for the ephemeral keys. Instead of keeping the full value of the key in memory, the 15046 TPM can use a counter as input to a KDF. Incrementing the counter will cause the TPM to generate a 15047 new pseudo-random value. 15048 Using the counter to generate pseudo-random private ephemeral keys greatly simplifies tracking of key 15049 usage. When a counter value is used to create a key, a bit in an array may be set to indicate that the key 15050 use is pending. When the ephemeral key is consumed, the bit is cleared. This prevents the key from 15051 being used more than once. 15052 Since the TPM is allowed to restrict the number of pending ephemeral keys, the array size can be limited. 15053 For example, a 128 bit array would allow 128 keys to be "pending". 15054 The management of the array is described in greater detail in the Split Operations clause in Annex C of 15055 part 1. 15056 15057 Family 2.0 15058 Level 00 Revision 00.99 15059 15060 Published 15061 Copyright TCG 2006-2013 15062 15063 Page 177 15064 October 31, 2013 15065 15066 Part 3: Commands 15068 15069 21.2 15070 15071 Trusted Platform Module Library 15072 15073 TPM2_Commit 15074 15075 21.2.1 General Description 15076 TPM2_Commit() performs the first part of an ECC anonymous signing operation. The TPM will perform 15077 the point multiplications on the provided points and return intermediate signing values. The signHandle 15078 parameter shall refer to an ECC key with the sign attribute (TPM_RC_ATTRIBUTES) using an 15079 anonymous signing scheme (TPM_RC_SCHEME). 15080 For this command, p1, s2 and y2 are optional parameters. If s2 is an Empty Buffer, then the TPM shall 15081 return TPM_RC_SIZE if y2 is not an Empty Buffer. If p1, s2, and y2 are all Empty Buffers, the TPM shall 15082 return TPM_RC_NO_RESULT. 15083 In the algorithm below, the following additional values are used in addition to the command parameters: 15084 15085 HnameAlg 15086 15087 hash function using the nameAlg of the key associated with 15088 signHandle 15089 15090 p 15091 15092 field modulus of the curve associated with signHandle 15093 15094 n 15095 15096 order of the curve associated with signHandle 15097 15098 ds 15099 15100 private key associated with signHandle 15101 15102 c 15103 15104 counter that increments each time a TPM2_Commit() is 15105 successfully completed 15106 15107 A[i] 15108 15109 array of bits used to indicate when a value of c has been used in 15110 a signing operation; values of i are 0 to 2n-1 15111 15112 k 15113 15114 nonce that is set to a random value on each TPM Reset; nonce 15115 size is twice the security strength of any ECDAA key supported 15116 by the TPM. 15117 15118 The algorithm is: 15119 a) set K, L, and E to be Empty Buffers. 15120 b) if s2 is not an Empty Buffer, compute x2 HnameAlg (s2) mod p, else skip to step (e) 15121 c) if (x2, y2) is not a point on the curve of signHandle, return TPM_RC_ECC_POINT 15122 d) set K [ds] (x2, y2) 15123 e) generate or derive r (see the "Commit Random Value" clause in Part 1) 15124 f) 15125 15126 set r r mod n 15127 15128 NOTE 1 15129 15130 nLen is the number of bits in n 15131 15132 g) if p1 is an Empty Buffer, skip to step i) 15133 h) if (p1) is not a point on the curve of signHandle, return TPM_RC_ECC_POINT 15134 i) 15135 15136 set E [r] (p1) 15137 15138 j) 15139 15140 if K is not an Empty Buffer, set L [r] (x2, y2) 15141 15142 k) if K, L, or E is the point at infinity, return TPM_RC_NO_RESULT 15143 l) 15144 15145 set counter commitCount 15146 15147 m) set commitCount commitCount + 1 15148 15149 Page 178 15150 October 31, 2013 15151 15152 Published 15153 Copyright TCG 2006-2013 15154 15155 Family 2.0 15156 Level 00 Revision 00.99 15157 15158 Trusted Platform Module Library 15160 NOTE 2 15161 15162 Part 3: Commands 15163 15164 Depending on the method of generating r, it may be necessary to update the tracking array here. 15165 15166 n) output K, L, E and counter 15167 NOTE 3 15168 15169 Depending on the input parameters K and L may be Empty Buffers or E may be an Empty Buffer 15170 15171 Family 2.0 15172 Level 00 Revision 00.99 15173 15174 Published 15175 Copyright TCG 2006-2013 15176 15177 Page 179 15178 October 31, 2013 15179 15180 Part 3: Commands 15182 15183 Trusted Platform Module Library 15184 15185 21.2.2 Command and Response 15186 Table 89 TPM2_Commit Command 15187 Type 15188 15189 Name 15190 15191 TPMI_ST_COMMAND_TAG 15192 15193 tag 15194 15195 UINT32 15196 15197 paramSize 15198 15199 TPM_CC 15200 15201 commandCode 15202 15203 Description 15204 15205 TPM_CC_Commit 15206 handle of the key that will be used in the signing 15207 operation 15208 15209 TPMI_DH_OBJECT 15210 15211 @signHandle 15212 15213 Auth Index: 1 15214 Auth Role: USER 15215 15216 TPM2B_ECC_POINT 15217 15218 P1 15219 15220 a point (M) on the curve used by signHandle 15221 15222 TPM2B_SENSITIVE_DATA 15223 15224 s2 15225 15226 octet array used to derive x-coordinate of a base point 15227 15228 TPM2B_ECC_PARAMETER 15229 15230 y2 15231 15232 y coordinate of the point associated with s2 15233 15234 Table 90 TPM2_Commit Response 15235 Type 15236 15237 Name 15238 15239 Description 15240 15241 TPM_ST 15242 15243 tag 15244 15245 see 8 15246 15247 UINT32 15248 15249 paramSize 15250 15251 TPM_RC 15252 15253 responseCode 15254 15255 TPM2B_ECC_POINT 15256 15257 K 15258 15259 ECC point K [ds](x2, y2) 15260 15261 TPM2B_ECC_POINT 15262 15263 L 15264 15265 ECC point L [r](x2, y2) 15266 15267 TPM2B_ECC_POINT 15268 15269 E 15270 15271 ECC point E [r]P1 15272 15273 UINT16 15274 15275 counter 15276 15277 least-significant 16 bits of commitCount 15278 15279 Page 180 15280 October 31, 2013 15281 15282 Published 15283 Copyright TCG 2006-2013 15284 15285 Family 2.0 15286 Level 00 Revision 00.99 15287 15288 Trusted Platform Module Library 15290 15291 Part 3: Commands 15292 15293 21.2.3 Detailed Actions 15294 1 15295 2 15296 3 15297 15298 #include "InternalRoutines.h" 15299 #include "Commit_fp.h" 15300 #ifdef TPM_ALG_ECC 15301 Error Returns 15302 TPM_RC_ATTRIBUTES 15303 15304 keyHandle references a restricted key that is not a signing key 15305 15306 TPM_RC_ECC_POINT 15307 15308 either P1 or the point derived from s2 is not on the curve of 15309 keyHandle 15310 15311 TPM_RC_HASH 15312 15313 invalid name algorithm in keyHandle 15314 15315 TPM_RC_KEY 15316 15317 keyHandle does not reference an ECC key 15318 15319 TPM_RC_SCHEME 15320 15321 keyHandle references a restricted signing key that does not use and 15322 anonymous scheme 15323 15324 TPM_RC_NO_RESULT 15325 15326 K, L or E was a point at infinity; or failed to generate r value 15327 15328 TPM_RC_SIZE 15329 4 15330 5 15331 6 15332 7 15333 8 15334 9 15335 10 15336 11 15337 12 15338 13 15339 14 15340 15 15341 16 15342 17 15343 18 15344 19 15345 20 15346 21 15347 22 15348 23 15349 24 15350 25 15351 26 15352 27 15353 28 15354 29 15355 30 15356 31 15357 32 15358 33 15359 34 15360 35 15361 36 15362 37 15363 38 15364 39 15365 40 15366 41 15367 42 15368 43 15369 15370 Meaning 15371 15372 s2 is empty but y2 is not or s2 provided but y2 is not 15373 15374 TPM_RC 15375 TPM2_Commit( 15376 Commit_In 15377 Commit_Out 15378 15379 *in, 15380 *out 15381 15382 // IN: input parameter list 15383 // OUT: output parameter list 15384 15385 ) 15386 { 15387 OBJECT 15388 TPMS_ECC_POINT 15389 TPMS_ECC_POINT 15390 TPMS_ECC_POINT 15391 TPM2B_ECC_PARAMETER 15392 TPM2B 15393 TPM_RC 15394 UINT16 15395 15396 *eccKey; 15397 P2; 15398 *pP2 = NULL; 15399 *pP1 = NULL; 15400 r; 15401 *p; 15402 result; 15403 hashResults; 15404 15405 // Input Validation 15406 eccKey = ObjectGet(in->signHandle); 15407 // Input key must be an ECC key 15408 if(eccKey->publicArea.type != TPM_ALG_ECC) 15409 return TPM_RC_KEY + RC_Commit_signHandle; 15410 // if the key is restricted, it must be a signing key using an anonymous scheme 15411 if(eccKey->publicArea.objectAttributes.restricted == SET) 15412 { 15413 if(eccKey->publicArea.objectAttributes.sign != SET) 15414 return TPM_RC_ATTRIBUTES + RC_Commit_signHandle; 15415 if(!CryptIsSchemeAnonymous( 15416 eccKey->publicArea.parameters.eccDetail.scheme.scheme)) 15417 return TPM_RC_SCHEME + RC_Commit_signHandle; 15418 } 15419 else 15420 { 15421 // if not restricted, s2, and y2 must be an Empty Buffer 15422 if(in->s2.t.size) 15423 return TPM_RC_SIZE + RC_Commit_s2; 15424 } 15425 // Make sure that both parts of P2 are present if either is present 15426 if((in->s2.t.size == 0) != (in->y2.t.size == 0)) 15427 15428 Family 2.0 15429 Level 00 Revision 00.99 15430 15431 Published 15432 Copyright TCG 2006-2013 15433 15434 Page 181 15435 October 31, 2013 15436 15437 Part 3: Commands 15439 44 15440 45 15441 46 15442 47 15443 48 15444 49 15445 50 15446 51 15447 52 15448 53 15449 54 15450 55 15451 56 15452 57 15453 58 15454 59 15455 60 15456 61 15457 62 15458 63 15459 64 15460 65 15461 66 15462 67 15463 68 15464 69 15465 70 15466 71 15467 72 15468 73 15469 74 15470 75 15471 76 15472 77 15473 78 15474 79 15475 80 15476 81 15477 82 15478 83 15479 84 15480 85 15481 86 15482 87 15483 88 15484 89 15485 90 15486 91 15487 92 15488 93 15489 94 15490 95 15491 96 15492 97 15493 98 15494 99 15495 100 15496 101 15497 102 15498 103 15499 104 15500 105 15501 106 15502 107 15503 15504 Trusted Platform Module Library 15505 15506 return TPM_RC_SIZE + RC_Commit_y2; 15507 // Get prime modulus for the curve. This is needed later but getting this now 15508 // allows confirmation that the curve exists 15509 p = (TPM2B *)CryptEccGetParameter('p', 15510 eccKey->publicArea.parameters.eccDetail.curveID); 15511 // if no p, then the curve ID is bad 15512 // NOTE: This should never occur if the input unmarshaling code is working 15513 // correctly 15514 if(p == NULL) 15515 return TPM_RC_KEY + RC_Commit_signHandle; 15516 // Get the random value that will be used in the point multiplications 15517 // Note: this does not commit the count. 15518 if(!CryptGenerateR(&r, 15519 NULL, 15520 eccKey->publicArea.parameters.eccDetail.curveID, 15521 &eccKey->name)) 15522 return TPM_RC_NO_RESULT; 15523 // Set up P2 if s2 and Y2 are provided 15524 if(in->s2.t.size != 0) 15525 { 15526 pP2 = &P2; 15527 // copy y2 for P2 15528 MemoryCopy2B(&P2.y.b, &in->y2.b, sizeof(P2.y.t.buffer)); 15529 // Compute x2 HnameAlg(s2) mod p 15530 // 15531 do the hash operation on s2 with the size of curve 'p' 15532 hashResults = CryptHashBlock(eccKey->publicArea.nameAlg, 15533 in->s2.t.size, 15534 in->s2.t.buffer, 15535 p->size, 15536 P2.x.t.buffer); 15537 // If there were error returns in the hash routine, indicate a problem 15538 // with the hash in 15539 if(hashResults == 0) 15540 return TPM_RC_HASH + RC_Commit_signHandle; 15541 // set the size of the X value to the size of the hash 15542 P2.x.t.size = hashResults; 15543 // set p2.x = hash(s2) mod p 15544 if(CryptDivide(&P2.x.b, p, NULL, &P2.x.b) != TPM_RC_SUCCESS) 15545 return TPM_RC_NO_RESULT; 15546 if(!CryptEccIsPointOnCurve(eccKey->publicArea.parameters.eccDetail.curveID, 15547 pP2)) 15548 return TPM_RC_ECC_POINT + RC_Commit_s2; 15549 if(eccKey->attributes.publicOnly == SET) 15550 return TPM_RC_KEY + RC_Commit_signHandle; 15551 } 15552 else 15553 // If there is a P1, make sure that it is on the curve 15554 // NOTE: an "empty" point has two UINT16 values which are the size values 15555 // for each of the coordinates. 15556 if(in->P1.t.size > 4) 15557 { 15558 15559 Page 182 15560 October 31, 2013 15561 15562 Published 15563 Copyright TCG 2006-2013 15564 15565 Family 2.0 15566 Level 00 Revision 00.99 15567 15568 Trusted Platform Module Library 15570 108 15571 109 15572 110 15573 111 15574 112 15575 113 15576 114 15577 115 15578 116 15579 117 15580 118 15581 119 15582 120 15583 121 15584 122 15585 123 15586 124 15587 125 15588 126 15589 127 15590 128 15591 129 15592 130 15593 131 15594 132 15595 133 15596 134 15597 135 15598 136 15599 137 15600 138 15601 139 15602 15603 Part 3: Commands 15604 15605 pP1 = &in->P1.t.point; 15606 if(!CryptEccIsPointOnCurve(eccKey->publicArea.parameters.eccDetail.curveID, 15607 pP1)) 15608 return TPM_RC_ECC_POINT + RC_Commit_P1; 15609 } 15610 // Pass the parameters to CryptCommit. 15611 // The work is not done inline because it does several point multiplies 15612 // with the same curve. There is significant optimization by not 15613 // having to reload the curve parameters multiple times. 15614 result = CryptCommitCompute(&out->K.t.point, 15615 &out->L.t.point, 15616 &out->E.t.point, 15617 eccKey->publicArea.parameters.eccDetail.curveID, 15618 pP1, 15619 pP2, 15620 &eccKey->sensitive.sensitive.ecc, 15621 &r); 15622 if(result != TPM_RC_SUCCESS) 15623 return result; 15624 out->K.t.size = TPMS_ECC_POINT_Marshal(&out->K.t.point, NULL, NULL); 15625 out->L.t.size = TPMS_ECC_POINT_Marshal(&out->L.t.point, NULL, NULL); 15626 out->E.t.size = TPMS_ECC_POINT_Marshal(&out->E.t.point, NULL, NULL); 15627 // The commit computation was successful so complete the commit by setting 15628 // the bit 15629 out->counter = CryptCommit(); 15630 return TPM_RC_SUCCESS; 15631 } 15632 #endif 15633 15634 Family 2.0 15635 Level 00 Revision 00.99 15636 15637 Published 15638 Copyright TCG 2006-2013 15639 15640 Page 183 15641 October 31, 2013 15642 15643 Part 3: Commands 15645 15646 21.3 15647 15648 Trusted Platform Module Library 15649 15650 TPM2_EC_Ephemeral 15651 15652 21.3.1 General Description 15653 TPM2_EC_Ephemeral() creates an ephemeral key for use in a two-phase key exchange protocol. 15654 The TPM will use the commit mechanism to assign an ephemeral key r and compute a public point Q 15655 [r]G where G is the generator point associated with curveID. 15656 15657 Page 184 15658 October 31, 2013 15659 15660 Published 15661 Copyright TCG 2006-2013 15662 15663 Family 2.0 15664 Level 00 Revision 00.99 15665 15666 Trusted Platform Module Library 15668 15669 Part 3: Commands 15670 15671 21.3.2 Command and Response 15672 Table 91 TPM2_EC_Ephemeral Command 15673 Type 15674 15675 Name 15676 15677 Description 15678 15679 TPMI_ST_COMMAND_TAG 15680 15681 tag 15682 15683 UINT32 15684 15685 paramSize 15686 15687 TPM_CC 15688 15689 commandCode 15690 15691 TPM_CC_EC_Ephemeral 15692 15693 TPMI_ECC_CURVE 15694 15695 curveID 15696 15697 The curve for the computed ephemeral point 15698 15699 Table 92 TPM2_EC_Ephemeral Response 15700 Type 15701 15702 Name 15703 15704 Description 15705 15706 TPM_ST 15707 15708 tag 15709 15710 see 8 15711 15712 UINT32 15713 15714 paramSize 15715 15716 TPM_RC 15717 15718 responseCode 15719 15720 TPM2B_ECC_POINT 15721 15722 Q 15723 15724 ephemeral public key Q [r]G 15725 15726 UINT16 15727 15728 counter 15729 15730 least-significant 16 bits of commitCount 15731 15732 Family 2.0 15733 Level 00 Revision 00.99 15734 15735 Published 15736 Copyright TCG 2006-2013 15737 15738 Page 185 15739 October 31, 2013 15740 15741 Part 3: Commands 15743 15744 Trusted Platform Module Library 15745 15746 21.3.3 Detailed Actions 15747 1 15748 2 15749 3 15750 15751 #include "InternalRoutines.h" 15752 #include "EC_Ephemeral_fp.h" 15753 #ifdef TPM_ALG_ECC 15754 Error Returns 15755 none 15756 15757 4 15758 5 15759 6 15760 7 15761 8 15762 9 15763 10 15764 11 15765 12 15766 13 15767 14 15768 15 15769 16 15770 17 15771 18 15772 19 15773 20 15774 21 15775 22 15776 23 15777 24 15778 25 15779 26 15780 27 15781 15782 Meaning 15783 ... 15784 15785 TPM_RC 15786 TPM2_EC_Ephemeral( 15787 EC_Ephemeral_In 15788 EC_Ephemeral_Out 15789 15790 *in, 15791 *out 15792 15793 // IN: input parameter list 15794 // OUT: output parameter list 15795 15796 ) 15797 { 15798 TPM2B_ECC_PARAMETER 15799 15800 r; 15801 15802 // Get the random value that will be used in the point multiplications 15803 // Note: this does not commit the count. 15804 if(!CryptGenerateR(&r, 15805 NULL, 15806 in->curveID, 15807 NULL)) 15808 return TPM_RC_NO_RESULT; 15809 CryptEccPointMultiply(&out->Q.t.point, in->curveID, &r, NULL); 15810 // commit the count value 15811 out->counter = CryptCommit(); 15812 return TPM_RC_SUCCESS; 15813 } 15814 #endif 15815 15816 Page 186 15817 October 31, 2013 15818 15819 Published 15820 Copyright TCG 2006-2013 15821 15822 Family 2.0 15823 Level 00 Revision 00.99 15824 15825 Trusted Platform Module Library 15827 15828 22 15829 15830 Part 3: Commands 15831 15832 Signing and Signature Verification 15833 15834 22.1 15835 15836 TPM2_VerifySignature 15837 15838 22.1.1 General Description 15839 This command uses loaded keys to validate a signature on a message with the message digest passed 15840 to the TPM. 15841 If the signature check succeeds, then the TPM will produce a TPMT_TK_VERIFIED. Otherwise, the TPM 15842 shall return TPM_RC_SIGNATURE. 15843 NOTE 1 15844 15845 A valid ticket may be used in subsequent commands to provide proof to the TPM that the TPM has 15846 validated the signature over the message using the key referenced by keyHandle. 15847 15848 If keyHandle references an asymmetric key, only the public portion of the key needs to be loaded. If 15849 keyHandle references a symmetric key, both the public and private portions need to be loaded. 15850 NOTE 2 15851 15852 The sensitive area of the symmetric object is required to allow verification of the symmetric 15853 signature (the HMAC). 15854 15855 Family 2.0 15856 Level 00 Revision 00.99 15857 15858 Published 15859 Copyright TCG 2006-2013 15860 15861 Page 187 15862 October 31, 2013 15863 15864 Part 3: Commands 15866 15867 Trusted Platform Module Library 15868 15869 22.1.2 Command and Response 15870 Table 93 TPM2_VerifySignature Command 15871 Type 15872 15873 Name 15874 15875 Description 15876 15877 TPMI_ST_COMMAND_TAG 15878 15879 tag 15880 15881 UINT32 15882 15883 commandSize 15884 15885 TPM_CC 15886 15887 commandCode 15888 15889 TPM_CC_VerifySignature 15890 15891 TPMI_DH_OBJECT 15892 15893 keyHandle 15894 15895 handle of public key that will be used in the validation 15896 Auth Index: None 15897 15898 TPM2B_DIGEST 15899 15900 digest 15901 15902 digest of the signed message 15903 15904 TPMT_SIGNATURE 15905 15906 signature 15907 15908 signature to be tested 15909 15910 Table 94 TPM2_VerifySignature Response 15911 Type 15912 15913 Name 15914 15915 Description 15916 15917 TPM_ST 15918 15919 tag 15920 15921 see clause 8 15922 15923 UINT32 15924 15925 responseSize 15926 15927 TPM_RC 15928 15929 responseCode 15930 15931 TPMT_TK_VERIFIED 15932 15933 validation 15934 15935 Page 188 15936 October 31, 2013 15937 15938 Published 15939 Copyright TCG 2006-2013 15940 15941 Family 2.0 15942 Level 00 Revision 00.99 15943 15944 Trusted Platform Module Library 15946 15947 Part 3: Commands 15948 15949 22.1.3 Detailed Actions 15950 1 15951 2 15952 15953 #include "InternalRoutines.h" 15954 #include "VerifySignature_fp.h" 15955 Error Returns 15956 TPM_RC_ATTRIBUTES 15957 15958 keyHandle does not reference a signing key 15959 15960 TPM_RC_SIGNATURE 15961 15962 signature is not genuine 15963 15964 TPM_RC_SCHEME 15965 15966 CryptVerifySignature() 15967 15968 TPM_RC_HANDLE 15969 3 15970 4 15971 5 15972 6 15973 7 15974 8 15975 9 15976 10 15977 11 15978 12 15979 13 15980 14 15981 15 15982 16 15983 17 15984 18 15985 19 15986 20 15987 21 15988 22 15989 23 15990 24 15991 25 15992 26 15993 27 15994 28 15995 29 15996 30 15997 31 15998 32 15999 33 16000 34 16001 35 16002 36 16003 37 16004 38 16005 39 16006 40 16007 41 16008 42 16009 43 16010 44 16011 45 16012 46 16013 47 16014 48 16015 49 16016 16017 Meaning 16018 16019 the input handle is not a sign key with private portion loaded 16020 16021 TPM_RC 16022 TPM2_VerifySignature( 16023 VerifySignature_In 16024 VerifySignature_Out 16025 16026 *in, 16027 *out 16028 16029 // IN: input parameter list 16030 // OUT: output parameter list 16031 16032 TPM_RC 16033 TPM2B_NAME 16034 OBJECT 16035 TPMI_RH_HIERARCHY 16036 16037 result; 16038 name; 16039 *signObject; 16040 hierarchy; 16041 16042 ) 16043 { 16044 16045 // Input Validation 16046 // Get sign object pointer 16047 signObject = ObjectGet(in->keyHandle); 16048 // The object to validate the signature must be a signing key. 16049 if(signObject->publicArea.objectAttributes.sign != SET) 16050 return TPM_RC_ATTRIBUTES + RC_VerifySignature_keyHandle; 16051 // If it doesn't have a sensitive area loaded 16052 // then it can't be a keyed hash signing key 16053 if( 16054 signObject->attributes.publicOnly == SET 16055 && signObject->publicArea.type == TPM_ALG_KEYEDHASH 16056 ) 16057 return TPM_RC_HANDLE + RC_VerifySignature_keyHandle; 16058 // Validate Signature. A TPM_RC_BINDING, TPM_RC_SCHEME or TPM_RC_SIGNATURE 16059 // error may be returned by CryptCVerifySignatrue() 16060 result = CryptVerifySignature(in->keyHandle, &in->digest, &in->signature); 16061 if(result != TPM_RC_SUCCESS) 16062 return RcSafeAddToResult(result, RC_VerifySignature_signature); 16063 // Command Output 16064 hierarchy = ObjectGetHierarchy(in->keyHandle); 16065 if( 16066 hierarchy == TPM_RH_NULL 16067 || signObject->publicArea.nameAlg == TPM_ALG_NULL) 16068 { 16069 // produce empty ticket if hierarchy is TPM_RH_NULL or nameAlg is 16070 // TPM_ALG_NULL 16071 out->validation.tag = TPM_ST_VERIFIED; 16072 out->validation.hierarchy = TPM_RH_NULL; 16073 out->validation.digest.t.size = 0; 16074 } 16075 else 16076 { 16077 16078 Family 2.0 16079 Level 00 Revision 00.99 16080 16081 Published 16082 Copyright TCG 2006-2013 16083 16084 Page 189 16085 October 31, 2013 16086 16087 Part 3: Commands 16089 50 16090 51 16091 52 16092 53 16093 54 16094 55 16095 56 16096 57 16097 16098 Trusted Platform Module Library 16099 16100 // Get object name that verifies the signature 16101 name.t.size = ObjectGetName(in->keyHandle, &name.t.name); 16102 // Compute ticket 16103 TicketComputeVerified(hierarchy, &in->digest, &name, &out->validation); 16104 } 16105 return TPM_RC_SUCCESS; 16106 } 16107 16108 Page 190 16109 October 31, 2013 16110 16111 Published 16112 Copyright TCG 2006-2013 16113 16114 Family 2.0 16115 Level 00 Revision 00.99 16116 16117 Trusted Platform Module Library 16119 16120 22.2 16121 16122 Part 3: Commands 16123 16124 TPM2_Sign 16125 16126 22.2.1 General Description 16127 This command causes the TPM to sign an externally provided hash with the specified asymmetric signing 16128 key. 16129 NOTE 1 16130 16131 Symmetric signing is done with an HMAC. 16132 16133 If keyHandle references a restricted signing key, then validation shall be provided indicating that the TPM 16134 performed the hash of the data and validation shall indicate that hashed data did not start with 16135 TPM_GENERATED_VALUE. 16136 NOTE 2 16137 16138 If the hashed data did start with TPM_GENERATED_VALUE, then the validation will be a NULL 16139 ticket. 16140 16141 If the scheme of keyHandle is not TPM_ALG_NULL, then inScheme shall either be the same scheme as 16142 keyHandle or TPM_ALG_NULL. 16143 If the scheme of keyHandle is TPM_ALG_NULL, the TPM will sign using inScheme; otherwise, it will sign 16144 using the scheme of keyHandle. 16145 NOTE 3 16146 16147 When the signing scheme requires a hash algorithm, the hash is defined in the qualifying data of the 16148 scheme. 16149 16150 If inScheme is not a valid signing scheme for the type of keyHandle (or TPM_ALG_NULL), then the TPM 16151 shall return TPM_RC_SCHEME. 16152 If the scheme of keyHandle is an anonymous scheme, then inScheme shall have the same scheme 16153 algorithm as keyHandle and inScheme will contain a counter value that will be used in the signing 16154 process. 16155 As long as it is no larger than allowed, the digest parameter is not required to have any specific size but 16156 the signature operation may fail if digest is too large for the selected scheme. 16157 If the validation parameter is not the Empty Buffer, then it will be checked even if the key referenced by 16158 keyHandle is not a restricted signing key. 16159 16160 Family 2.0 16161 Level 00 Revision 00.99 16162 16163 Published 16164 Copyright TCG 2006-2013 16165 16166 Page 191 16167 October 31, 2013 16168 16169 Part 3: Commands 16171 16172 Trusted Platform Module Library 16173 16174 22.2.2 Command and Response 16175 Table 95 TPM2_Sign Command 16176 Type 16177 16178 Name 16179 16180 TPMI_ST_COMMAND_TAG 16181 16182 tag 16183 16184 UINT32 16185 16186 commandSize 16187 16188 TPM_CC 16189 16190 commandCode 16191 16192 TPM_CC_Sign 16193 16194 TPMI_DH_OBJECT 16195 16196 @keyHandle 16197 16198 Handle of key that will perform signing 16199 Auth Index: 1 16200 Auth Role: USER 16201 16202 TPM2B_DIGEST 16203 16204 digest 16205 16206 digest to be signed 16207 16208 TPMT_SIG_SCHEME+ 16209 16210 inScheme 16211 16212 signing scheme to use if the scheme for keyHandle is 16213 TPM_ALG_NULL 16214 16215 TPMT_TK_HASHCHECK 16216 16217 validation 16218 16219 proof that digest was created by the TPM 16220 If keyHandle is not a restricted signing key, then this 16221 may be a NULL Ticket with tag = 16222 TPM_ST_CHECKHASH. 16223 16224 Description 16225 16226 Table 96 TPM2_Sign Response 16227 Type 16228 16229 Name 16230 16231 Description 16232 16233 TPM_ST 16234 16235 tag 16236 16237 see clause 8 16238 16239 UINT32 16240 16241 responseSize 16242 16243 TPM_RC 16244 16245 responseCode 16246 16247 TPMT_SIGNATURE 16248 16249 signature 16250 16251 Page 192 16252 October 31, 2013 16253 16254 the signature 16255 16256 Published 16257 Copyright TCG 2006-2013 16258 16259 Family 2.0 16260 Level 00 Revision 00.99 16261 16262 Trusted Platform Module Library 16264 16265 Part 3: Commands 16266 16267 22.2.3 Detailed Actions 16268 1 16269 2 16270 3 16271 16272 #include "InternalRoutines.h" 16273 #include "Sign_fp.h" 16274 #include "Attest_spt_fp.h" 16275 Error Returns 16276 TPM_RC_ATTRIBUTES 16277 16278 key referenced by keHandle is not a signing key 16279 16280 TPM_RC_BINDING 16281 16282 The public and private portions of the key are not properly bound. 16283 16284 TPM_RC_SCHEME 16285 16286 inScheme is not compatible with keyHandle; both inScheme and 16287 key's default scheme are empty; or inScheme is empty while key's 16288 default scheme requires explicit input scheme (split signing); or nonempty default key scheme differs from inScheme 16289 16290 TPM_RC_TICKET 16291 16292 validation is not a valid ticket 16293 16294 TPM_RC_VALUE 16295 4 16296 5 16297 6 16298 7 16299 8 16300 9 16301 10 16302 11 16303 12 16304 13 16305 14 16306 15 16307 16 16308 17 16309 18 16310 19 16311 20 16312 21 16313 22 16314 23 16315 24 16316 25 16317 26 16318 27 16319 28 16320 29 16321 30 16322 31 16323 32 16324 33 16325 34 16326 35 16327 36 16328 37 16329 38 16330 39 16331 40 16332 41 16333 42 16334 43 16335 44 16336 16337 Meaning 16338 16339 the value to sign is larger than allowed for the type of keyHandle 16340 16341 TPM_RC 16342 TPM2_Sign( 16343 Sign_In 16344 Sign_Out 16345 16346 *in, 16347 *out 16348 16349 // IN: input parameter list 16350 // OUT: output parameter list 16351 16352 TPM_RC 16353 TPMT_TK_HASHCHECK 16354 OBJECT 16355 16356 result; 16357 ticket; 16358 *signKey; 16359 16360 ) 16361 { 16362 16363 // Input Validation 16364 // Get sign key pointer 16365 signKey = ObjectGet(in->keyHandle); 16366 // If validation is provided, or the key is restricted, check the ticket 16367 if( 16368 in->validation.digest.t.size != 0 16369 || signKey->publicArea.objectAttributes.restricted == SET) 16370 { 16371 // Compute and compare ticket 16372 TicketComputeHashCheck(in->validation.hierarchy, &in->digest, &ticket); 16373 if(!Memory2BEqual(&in->validation.digest.b, &ticket.digest.b)) 16374 return TPM_RC_TICKET + RC_Sign_validation; 16375 } 16376 // Command Output 16377 // pick a scheme for sign. If the input sign scheme is not compatible with 16378 // the default scheme, return an error. 16379 result = CryptSelectSignScheme(in->keyHandle, &in->inScheme); 16380 if(result != TPM_RC_SUCCESS) 16381 { 16382 if(result == TPM_RC_KEY) 16383 return TPM_RC_KEY + RC_Sign_keyHandle; 16384 else 16385 return RcSafeAddToResult(result, RC_Sign_inScheme); 16386 } 16387 // Sign the hash. A TPM_RC_VALUE, TPM_RC_SCHEME, or TPM_RC_ATTRIBUTES 16388 // error may be returned at this point 16389 result = CryptSign(in->keyHandle, &in->inScheme, &in->digest, &out->signature); 16390 16391 Family 2.0 16392 Level 00 Revision 00.99 16393 16394 Published 16395 Copyright TCG 2006-2013 16396 16397 Page 193 16398 October 31, 2013 16399 16400 Part 3: Commands 16402 45 16403 46 16404 47 16405 16406 Trusted Platform Module Library 16407 16408 return result; 16409 } 16410 16411 Page 194 16412 October 31, 2013 16413 16414 Published 16415 Copyright TCG 2006-2013 16416 16417 Family 2.0 16418 Level 00 Revision 00.99 16419 16420 Trusted Platform Module Library 16422 16423 23 16424 16425 Part 3: Commands 16426 16427 Command Audit 16428 16429 23.1 16430 16431 Introduction 16432 16433 If a command has been selected for command audit, the command audit status will be updated when that 16434 command completes successfully. The digest is updated as: 16435 16436 commandAuditDigestnew HauditAlg(commandAuditDigestold || cpHash || rpHash) 16437 16438 (5) 16439 16440 where 16441 16442 HauditAlg 16443 16444 hash function using the algorithm of the audit sequence 16445 16446 commandAuditDigest 16447 16448 accumulated digest 16449 16450 cpHash 16451 16452 the command parameter hash 16453 16454 rpHash 16455 16456 the response parameter hash 16457 16458 TPM2_Shutdown() cannot be audited but TPM2_Startup() can be audited. If the cpHash of the 16459 TPM2_Startup() is TPM_SU_STATE, that would indicate that a TPM2_Shutdown() had been successfully 16460 executed. 16461 TPM2_SetCommandCodeAuditStatus() is always audited. 16462 If the TPM is in Failure mode, command audit is not functional. 16463 16464 Family 2.0 16465 Level 00 Revision 00.99 16466 16467 Published 16468 Copyright TCG 2006-2013 16469 16470 Page 195 16471 October 31, 2013 16472 16473 Part 3: Commands 16475 16476 23.2 16477 16478 Trusted Platform Module Library 16479 16480 TPM2_SetCommandCodeAuditStatus 16481 16482 23.2.1 General Description 16483 This command may be used by the Privacy Administrator or platform to change the audit status of a 16484 command or to set the hash algorithm used for the audit digest, but not both at the same time. 16485 If the auditAlg parameter is a supported hash algorithm and not the same as the current algorithm, then 16486 the TPM will check both setList and clearList are empty (zero length). If so, then the algorithm is changed, 16487 and the audit digest is cleared. If auditAlg is TPM_ALG_NULL or the same as the current algorithm, then 16488 the algorithm and audit digest are unchanged and the setList and clearList will be processed. 16489 NOTE 1 16490 16491 Because the audit digest is cleared, the audit counter will increment the next time that an audited 16492 command is executed. 16493 16494 Use of TPM2_SetCommandCodeAuditStatus() to change the list of audited commands is an audited 16495 event. If TPM_CC_SetCommandCodeAuditStatus is in clearList, it is ignored. 16496 NOTE 2 16497 16498 Use of this command to change the audit hash algorithm is not audited and the digest is reset when 16499 the command completes. The change in the audit hash algorithm is the evidence that this command 16500 was used to change the algorithm. 16501 16502 The commands in setList indicate the commands that to be added to the list of audited commands and 16503 the commands in clearList indicate the commands that will no longer be audited. It is not an error if a 16504 command in setList is already audited or is not implemented. It is not an error if a command in clearList is 16505 not currently being audited or is not implemented. 16506 If a command code is in both setList and clearList, then it will not be audited (that is, setList shall be 16507 processed first). 16508 16509 Page 196 16510 October 31, 2013 16511 16512 Published 16513 Copyright TCG 2006-2013 16514 16515 Family 2.0 16516 Level 00 Revision 00.99 16517 16518 Trusted Platform Module Library 16520 16521 Part 3: Commands 16522 16523 23.2.2 Command and Response 16524 Table 97 TPM2_SetCommandCodeAuditStatus Command 16525 Type 16526 16527 Name 16528 16529 Description 16530 16531 TPMI_ST_COMMAND_TAG 16532 16533 tag 16534 16535 UINT32 16536 16537 commandSize 16538 16539 TPM_CC 16540 16541 commandCode 16542 16543 TPM_CC_SetCommandCodeAuditStatus {NV} 16544 16545 TPMI_RH_PROVISION 16546 16547 @auth 16548 16549 TPM_RH_ENDORSEMENT or 16550 TPM_RH_PLATFORM+{PP} 16551 Auth Index: 1 16552 Auth Role: USER 16553 16554 TPMI_ALG_HASH+ 16555 16556 auditAlg 16557 16558 hash algorithm for the audit digest; if 16559 TPM_ALG_NULL, then the hash is not changed 16560 16561 TPML_CC 16562 16563 setList 16564 16565 list of commands that will be added to those that will 16566 be audited 16567 16568 TPML_CC 16569 16570 clearList 16571 16572 list of commands that will no longer be audited 16573 16574 Table 98 TPM2_SetCommandCodeAuditStatus Response 16575 Type 16576 16577 Name 16578 16579 Description 16580 16581 TPM_ST 16582 16583 tag 16584 16585 see clause 8 16586 16587 UINT32 16588 16589 responseSize 16590 16591 TPM_RC 16592 16593 responseCode 16594 16595 Family 2.0 16596 Level 00 Revision 00.99 16597 16598 Published 16599 Copyright TCG 2006-2013 16600 16601 Page 197 16602 October 31, 2013 16603 16604 Part 3: Commands 16606 16607 Trusted Platform Module Library 16608 16609 23.2.3 Detailed Actions 16610 1 16611 2 16612 3 16613 4 16614 5 16615 6 16616 7 16617 8 16618 9 16619 10 16620 11 16621 12 16622 13 16623 14 16624 15 16625 16 16626 17 16627 18 16628 19 16629 20 16630 21 16631 22 16632 23 16633 24 16634 25 16635 26 16636 27 16637 28 16638 29 16639 30 16640 31 16641 32 16642 33 16643 34 16644 35 16645 36 16646 37 16647 38 16648 39 16649 40 16650 41 16651 42 16652 43 16653 44 16654 45 16655 46 16656 47 16657 48 16658 49 16659 50 16660 51 16661 52 16662 53 16663 54 16664 55 16665 56 16666 57 16667 58 16668 59 16669 60 16670 16671 #include "InternalRoutines.h" 16672 #include "SetCommandCodeAuditStatus_fp.h" 16673 16674 TPM_RC 16675 TPM2_SetCommandCodeAuditStatus( 16676 SetCommandCodeAuditStatus_In 16677 16678 *in 16679 16680 // IN: input parameter list 16681 16682 ) 16683 { 16684 TPM_RC 16685 UINT32 16686 BOOL 16687 16688 result; 16689 i; 16690 changed = FALSE; 16691 16692 // The command needs NV update. Check if NV is available. 16693 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 16694 // this point 16695 result = NvIsAvailable(); 16696 if(result != TPM_RC_SUCCESS) 16697 return result; 16698 // Internal Data Update 16699 // Update hash algorithm 16700 if( 16701 in->auditAlg != TPM_ALG_NULL 16702 && in->auditAlg != gp.auditHashAlg) 16703 { 16704 // Can't change the algorithm and command list at the same time 16705 if(in->setList.count != 0 || in->clearList.count != 0) 16706 return TPM_RC_VALUE + RC_SetCommandCodeAuditStatus_auditAlg; 16707 // Change the hash algorithm for audit 16708 gp.auditHashAlg = in->auditAlg; 16709 // Set the digest size to a unique value that indicates that the digest 16710 // algorithm has been changed. The size will be cleared to zero in the 16711 // command audit processing on exit. 16712 gr.commandAuditDigest.t.size = 1; 16713 // Save the change of command audit data (this sets g_updateNV so that NV 16714 // will be updagted on exit.) 16715 NvWriteReserved(NV_AUDIT_HASH_ALG, &gp.auditHashAlg); 16716 } else { 16717 // Process set list 16718 for(i = 0; i < in->setList.count; i++) 16719 // If change is made in CommandAuditSet, set changed flag 16720 if(CommandAuditSet(in->setList.commandCodes[i])) 16721 changed = TRUE; 16722 // Process clear list 16723 for(i = 0; i < in->clearList.count; i++) 16724 // If change is made in CommandAuditClear, set changed flag 16725 if(CommandAuditClear(in->clearList.commandCodes[i])) 16726 changed = TRUE; 16727 // if change was made to command list, update NV 16728 if(changed) 16729 // this sets g_updateNV so that NV will be updagted on exit. 16730 NvWriteReserved(NV_AUDIT_COMMANDS, &gp.auditComands); 16731 16732 Page 198 16733 October 31, 2013 16734 16735 Published 16736 Copyright TCG 2006-2013 16737 16738 Family 2.0 16739 Level 00 Revision 00.99 16740 16741 Trusted Platform Module Library 16743 61 16744 62 16745 63 16746 64 16747 16748 Part 3: Commands 16749 16750 } 16751 return TPM_RC_SUCCESS; 16752 } 16753 16754 Family 2.0 16755 Level 00 Revision 00.99 16756 16757 Published 16758 Copyright TCG 2006-2013 16759 16760 Page 199 16761 October 31, 2013 16762 16763 Part 3: Commands 16765 16766 24 16767 16768 Trusted Platform Module Library 16769 16770 Integrity Collection (PCR) 16771 16772 24.1 16773 16774 Introduction 16775 16776 In TPM 1.2, an Event was hashed using SHA-1 and then the 20-octet digest was extended to a PCR 16777 using TPM_Extend(). This specification allows the use of multiple PCR at a given Index, each using a 16778 different hash algorithm. Rather than require that the external software generate multiple hashes of the 16779 Event with each being extended to a different PCR, the Event data may be sent to the TPM for hashing. 16780 This ensures that the resulting digests will properly reflect the algorithms chosen for the PCR even if the 16781 calling software is unable to implement the hash algorithm. 16782 NOTE 1 16783 16784 There is continued support for software hashing of events with TPM2_PCR_Extend(). 16785 16786 To support recording of an Event that is larger than the TPM input buffer, the caller may use the 16787 command sequence described in clause 1. 16788 Change to a PCR requires authorization. The authorization may be with either an authorization value or 16789 an authorization policy. The platform-specific specifications determine which PCR may be controlled by 16790 policy. All other PCR are controlled by authorization. 16791 If a PCR may be associated with a policy, then the algorithm ID of that policy determines whether the 16792 policy is to be applied. If the algorithm ID is not TPM_ALG_NULL, then the policy digest associated with 16793 the PCR must match the policySessionpolicyDigest in a policy session. If the algorithm ID is 16794 TPM_ALG_NULL, then no policy is present and the authorization requires an EmptyAuth. 16795 If a platform-specific specification indicates that PCR are grouped, then all the PCR in the group use the 16796 same authorization policy or authorization value. 16797 PcrUpdateCounter counter will be incremented on the successful completion of any command that 16798 modifies (Extends or resets) a PCR unless the platform-specific specification explicitly excludes the PCR 16799 from being counted. 16800 NOTE 2 16801 16802 If a command causes PCR in multiple banks to change, the PCR Update Counter may be 16803 incremented either once or once for each bank. 16804 16805 A platform-specific specification may designate a set of PCR that are under control of the TCB. These 16806 PCR may not be modified without the proper authorization. Updates of these PCR shall not cause the 16807 PCR Update Counter to increment. 16808 EXAMPLE 16809 16810 Updates of the TCB PCR will not cause the PCR update counter to increment b ecause these PCR 16811 are changed at the whim of the TCB and are not intended to represent the trust state of the platform. 16812 16813 Page 200 16814 October 31, 2013 16815 16816 Published 16817 Copyright TCG 2006-2013 16818 16819 Family 2.0 16820 Level 00 Revision 00.99 16821 16822 Trusted Platform Module Library 16824 16825 24.2 16826 16827 Part 3: Commands 16828 16829 TPM2_PCR_Extend 16830 16831 24.2.1 General Description 16832 This command is used to cause an update to the indicated PCR. The digests parameter contains one or 16833 more tagged digest value identified by an algorithm ID. For each digest, the PCR associated with 16834 pcrHandle is Extended into the bank identified by the tag (hashAlg). 16835 EXAMPLE 16836 16837 A SHA1 digest would be Extended into the SHA1 bank and a SHA256 digest would be Extended into 16838 a SHA256 bank. 16839 16840 For each list entry, the TPM will check to see if pcrNum is implemented for that algorithm. If so, the TPM 16841 shall perform the following operation: 16842 16843 PCR.digestnew [pcrNum][alg] Halg(PCR.digestold [pcrNum][alg] || data[alg].buffer)) 16844 16845 (6) 16846 16847 where 16848 16849 Halg() 16850 16851 hash function using the hash algorithm associated with the PCR 16852 instance 16853 16854 PCR.digest 16855 16856 the digest value in a PCR 16857 16858 pcrNum 16859 16860 the PCR numeric 16861 TPM_RH_PCR0) 16862 16863 alg 16864 16865 the PCR algorithm selector for the digest 16866 16867 data[alg].buffer 16868 16869 the bank-specific data to be extended 16870 16871 selector 16872 16873 (equal 16874 16875 to 16876 16877 pcrHandle 16878 16879 16880 16881 If no digest value is specified for a bank, then the PCR in that bank are not modified. 16882 NOTE 1 16883 16884 This allows consistent operation of the digests list for all of the Event recording commands. 16885 16886 If a digest is present and the PCR in that bank is not implemented, the digest value is not used. 16887 NOTE 2 16888 16889 If the caller includes digests for algorithms that are not implemented, then the TPM will fail the call 16890 because the unmarshalling of digests will fail. Each of the entries in the list is a TPMT_HA which is a 16891 hash algorithm followed by a digest. If the algorithm is not implemented, unmarshalling of the 16892 hashAlg will fail and the TPM will return TPM_RC_HASH. 16893 16894 If the TPM unmarshals the hashAlg of a list entry and the unmarshaled value is not a hash algorithm 16895 implemented on the TPM, the TPM shall return TPM_RC_HASH. 16896 The pcrHandle parameter is allowed to reference TPM_RH_NULL. If so, the input parameters are 16897 processed but no action is taken by the TPM. 16898 NOTE 3 16899 16900 This command allows a list of digests so that PCR in all banks may be updated in a single 16901 command. While the semantics of this command allow multiple extends to a single PCR bank, this is 16902 not the preferred use and the limit on the number of entries in the list make this use somewhat 16903 impractical. 16904 16905 Family 2.0 16906 Level 00 Revision 00.99 16907 16908 Published 16909 Copyright TCG 2006-2013 16910 16911 Page 201 16912 October 31, 2013 16913 16914 Part 3: Commands 16916 16917 Trusted Platform Module Library 16918 16919 24.2.2 Command and Response 16920 Table 99 TPM2_PCR_Extend Command 16921 Type 16922 16923 Name 16924 16925 Description 16926 16927 TPMI_ST_COMMAND_TAG 16928 16929 tag 16930 16931 UINT32 16932 16933 commandSize 16934 16935 TPM_CC 16936 16937 commandCode 16938 16939 TPM_CC_PCR_Extend {NV} 16940 16941 TPMI_DH_PCR+ 16942 16943 @pcrHandle 16944 16945 handle of the PCR 16946 Auth Handle: 1 16947 Auth Role: USER 16948 16949 TPML_DIGEST_VALUES 16950 16951 digests 16952 16953 list of tagged digest values to be extended 16954 16955 Table 100 TPM2_PCR_Extend Response 16956 Type 16957 16958 Name 16959 16960 Description 16961 16962 TPM_ST 16963 16964 tag 16965 16966 see clause 8 16967 16968 UINT32 16969 16970 responseSize 16971 16972 TPM_RC 16973 16974 responseCode 16975 16976 Page 202 16977 October 31, 2013 16978 16979 . 16980 16981 Published 16982 Copyright TCG 2006-2013 16983 16984 Family 2.0 16985 Level 00 Revision 00.99 16986 16987 Trusted Platform Module Library 16989 16990 Part 3: Commands 16991 16992 24.2.3 Detailed Actions 16993 1 16994 2 16995 16996 #include "InternalRoutines.h" 16997 #include "PCR_Extend_fp.h" 16998 Error Returns 16999 TPM_RC_LOCALITY 17000 17001 3 17002 4 17003 5 17004 6 17005 7 17006 8 17007 9 17008 10 17009 11 17010 12 17011 13 17012 14 17013 15 17014 16 17015 17 17016 18 17017 19 17018 20 17019 21 17020 22 17021 23 17022 24 17023 25 17024 26 17025 27 17026 28 17027 29 17028 30 17029 31 17030 32 17031 33 17032 34 17033 35 17034 36 17035 37 17036 38 17037 39 17038 40 17039 41 17040 42 17041 43 17042 44 17043 45 17044 46 17045 47 17046 48 17047 49 17048 17049 Meaning 17050 current command locality is not allowed to extend the PCR 17051 referenced by pcrHandle 17052 17053 TPM_RC 17054 TPM2_PCR_Extend( 17055 PCR_Extend_In 17056 17057 *in 17058 17059 // IN: input parameter list 17060 17061 ) 17062 { 17063 TPM_RC 17064 UINT32 17065 17066 result; 17067 i; 17068 17069 // Input Validation 17070 // 17071 // 17072 // 17073 // 17074 // 17075 // 17076 // 17077 17078 NOTE: This function assumes that the unmarshaling function for 'digests' will 17079 have validated that all of the indicated hash algorithms are valid. If the 17080 hash algorithms are correct, the unmarshaling code will unmarshal a digest 17081 of the size indicated by the hash algorithm. If the overall size is not 17082 consistent, the unmarshaling code will run out of input data or have input 17083 data left over. In either case, it will cause an unmarshaling error and this 17084 function will not be called. 17085 17086 // For NULL handle, do nothing and return success 17087 if(in->pcrHandle == TPM_RH_NULL) 17088 return TPM_RC_SUCCESS; 17089 // Check if the extend operation is allowed by the current command locality 17090 if(!PCRIsExtendAllowed(in->pcrHandle)) 17091 return TPM_RC_LOCALITY; 17092 // If PCR is state saved and we need to update orderlyState, check NV 17093 // availability 17094 if(PCRIsStateSaved(in->pcrHandle) && gp.orderlyState != SHUTDOWN_NONE) 17095 { 17096 result = NvIsAvailable(); 17097 if(result != TPM_RC_SUCCESS) return result; 17098 g_clearOrderly = TRUE; 17099 } 17100 // Internal Data Update 17101 // Iterate input digest list to extend 17102 for(i = 0; i < in->digests.count; i++) 17103 { 17104 PCRExtend(in->pcrHandle, in->digests.digests[i].hashAlg, 17105 CryptGetHashDigestSize(in->digests.digests[i].hashAlg), 17106 (BYTE *) &in->digests.digests[i].digest); 17107 } 17108 return TPM_RC_SUCCESS; 17109 } 17110 17111 Family 2.0 17112 Level 00 Revision 00.99 17113 17114 Published 17115 Copyright TCG 2006-2013 17116 17117 Page 203 17118 October 31, 2013 17119 17120 Part 3: Commands 17122 17123 24.3 17124 17125 Trusted Platform Module Library 17126 17127 TPM2_PCR_Event 17128 17129 24.3.1 General Description 17130 This command is used to cause an update to the indicated PCR. 17131 The data in eventData is hashed using the hash algorithm associated with each bank in which the 17132 indicated PCR has been allocated. After the data is hashed, the digests list is returned. If the pcrHandle 17133 references an implemented PCR and not TPM_ALG_NULL, digests list is processed as in 17134 TPM2_PCR_Extend(). 17135 A TPM shall support an Event.size of zero through 1,024 inclusive (Event.size is an octet count). An 17136 Event.size of zero indicates that there is no data but the indicated operations will still occur, 17137 EXAMPLE 1 17138 17139 If the command implements PCR[2] in a SHA1 bank and a SHA256 bank, then an extend to PCR[2] 17140 will cause eventData to be hashed twice, once with SHA1 and once with SHA256. The SHA1 hash of 17141 eventData will be Extended to PCR[2] in the SHA1 bank and the SHA256 hash of eventData will be 17142 Extended to PCR[2] of the SHA256 bank. 17143 17144 On successful command completion, digests will contain the list of tagged digests of eventData that was 17145 computed in preparation for extending the data into the PCR. At the option of the TPM, the list may 17146 contain a digest for each bank, or it may only contain a digest for each bank in which pcrHandle is extant. 17147 EXAMPLE 2 17148 17149 Assume a TPM that implements a SHA1 bank and a SHA256 bank and that PCR[22] is only 17150 implemented in the SHA1 bank. If pcrHandle references PCR[22], then digests may contain either a 17151 SHA1 and a SHA256 digest or just a SHA1 digest. 17152 17153 Page 204 17154 October 31, 2013 17155 17156 Published 17157 Copyright TCG 2006-2013 17158 17159 Family 2.0 17160 Level 00 Revision 00.99 17161 17162 Trusted Platform Module Library 17164 17165 Part 3: Commands 17166 17167 24.3.2 Command and Response 17168 Table 101 TPM2_PCR_Event Command 17169 Type 17170 17171 Name 17172 17173 Description 17174 17175 TPMI_ST_COMMAND_TAG 17176 17177 tag 17178 17179 UINT32 17180 17181 commandSize 17182 17183 TPM_CC 17184 17185 commandCode 17186 17187 TPM_CC_PCR_Event {NV} 17188 17189 TPMI_DH_PCR+ 17190 17191 @pcrHandle 17192 17193 Handle of the PCR 17194 Auth Handle: 1 17195 Auth Role: USER 17196 17197 TPM2B_EVENT 17198 17199 eventData 17200 17201 Event data in sized buffer 17202 17203 Table 102 TPM2_PCR_Event Response 17204 Type 17205 17206 Name 17207 17208 Description 17209 17210 TPM_ST 17211 17212 tag 17213 17214 see clause 8 17215 17216 UINT32 17217 17218 responseSize 17219 17220 TPM_RC 17221 17222 responseCode 17223 17224 TPML_DIGEST_VALUES 17225 17226 digests 17227 17228 Family 2.0 17229 Level 00 Revision 00.99 17230 17231 . 17232 17233 Published 17234 Copyright TCG 2006-2013 17235 17236 Page 205 17237 October 31, 2013 17238 17239 Part 3: Commands 17241 17242 Trusted Platform Module Library 17243 17244 24.3.3 Detailed Actions 17245 1 17246 2 17247 17248 #include "InternalRoutines.h" 17249 #include "PCR_Event_fp.h" 17250 Error Returns 17251 TPM_RC_LOCALITY 17252 17253 3 17254 4 17255 5 17256 6 17257 7 17258 8 17259 9 17260 10 17261 11 17262 12 17263 13 17264 14 17265 15 17266 16 17267 17 17268 18 17269 19 17270 20 17271 21 17272 22 17273 23 17274 24 17275 25 17276 26 17277 27 17278 28 17279 29 17280 30 17281 31 17282 32 17283 33 17284 34 17285 35 17286 36 17287 37 17288 38 17289 39 17290 40 17291 41 17292 42 17293 43 17294 44 17295 45 17296 46 17297 47 17298 48 17299 49 17300 50 17301 51 17302 52 17303 17304 Meaning 17305 current command locality is not allowed to extend the PCR 17306 referenced by pcrHandle 17307 17308 TPM_RC 17309 TPM2_PCR_Event( 17310 PCR_Event_In 17311 PCR_Event_Out 17312 17313 *in, 17314 *out 17315 17316 // IN: input parameter list 17317 // OUT: output parameter list 17318 17319 ) 17320 { 17321 TPM_RC 17322 HASH_STATE 17323 UINT32 17324 UINT16 17325 17326 result; 17327 hashState; 17328 i; 17329 size; 17330 17331 // Input Validation 17332 // If a PCR extend is required 17333 if(in->pcrHandle != TPM_RH_NULL) 17334 { 17335 // If the PCR is not allow to extend, return error 17336 if(!PCRIsExtendAllowed(in->pcrHandle)) 17337 return TPM_RC_LOCALITY; 17338 // If PCR is state saved and we need to update orderlyState, check NV 17339 // availability 17340 if(PCRIsStateSaved(in->pcrHandle) && gp.orderlyState != SHUTDOWN_NONE) 17341 { 17342 result = NvIsAvailable(); 17343 if(result != TPM_RC_SUCCESS) return result; 17344 g_clearOrderly = TRUE; 17345 } 17346 } 17347 // Internal Data Update 17348 out->digests.count = HASH_COUNT; 17349 // Iterate supported PCR bank algorithms to extend 17350 for(i = 0; i < HASH_COUNT; i++) 17351 { 17352 TPM_ALG_ID hash = CryptGetHashAlgByIndex(i); 17353 out->digests.digests[i].hashAlg = hash; 17354 size = CryptStartHash(hash, &hashState); 17355 CryptUpdateDigest2B(&hashState, &in->eventData.b); 17356 CryptCompleteHash(&hashState, size, 17357 (BYTE *) &out->digests.digests[i].digest); 17358 if(in->pcrHandle != TPM_RH_NULL) 17359 PCRExtend(in->pcrHandle, hash, size, 17360 (BYTE *) &out->digests.digests[i].digest); 17361 } 17362 return TPM_RC_SUCCESS; 17363 } 17364 17365 Page 206 17366 October 31, 2013 17367 17368 Published 17369 Copyright TCG 2006-2013 17370 17371 Family 2.0 17372 Level 00 Revision 00.99 17373 17374 Trusted Platform Module Library 17376 17377 24.4 17378 17379 Part 3: Commands 17380 17381 TPM2_PCR_Read 17382 17383 24.4.1 General Description 17384 This command returns the values of all PCR specified in pcrSelect. 17385 The TPM will process the list of TPMS_PCR_SELECTION in pcrSelectionIn in order. Within each 17386 TPMS_PCR_SELECTION, the TPM will process the bits in the pcrSelect array in ascending PCR order 17387 (see Part 2 for definition of the PCR order). If a bit is SET, and the indicated PCR is present, then the 17388 TPM will add the digest of the PCR to the list of values to be returned in pcrValue. 17389 The TPM will continue processing bits until all have been processed or until pcrValues would be too large 17390 to fit into the output buffer if additional values were added. 17391 The returned pcrSelectionOut will have a bit SET in its pcrSelect structures for each value present in 17392 pcrValues. 17393 The current value of the PCR Update Counter is returned in pcrUpdateCounter. 17394 The returned list may be empty if none of the selected PCR are implemented. 17395 NOTE 17396 17397 If no PCR are returned from a bank, the selector for the bank will be present in pcrSelectionOut. 17398 17399 No authorization is required to read a PCR and any implemented PCR may be read from any locality. 17400 17401 Family 2.0 17402 Level 00 Revision 00.99 17403 17404 Published 17405 Copyright TCG 2006-2013 17406 17407 Page 207 17408 October 31, 2013 17409 17410 Part 3: Commands 17412 17413 Trusted Platform Module Library 17414 17415 24.4.2 Command and Response 17416 Table 103 TPM2_PCR_Read Command 17417 Type 17418 17419 Name 17420 17421 Description 17422 17423 TPMI_ST_COMMAND_TAG 17424 17425 tag 17426 17427 UINT32 17428 17429 commandSize 17430 17431 TPM_CC 17432 17433 commandCode 17434 17435 TPM_CC_PCR_Read 17436 17437 TPML_PCR_SELECTION 17438 17439 pcrSelectionIn 17440 17441 The selection of PCR to read 17442 17443 Table 104 TPM2_PCR_Read Response 17444 Type 17445 17446 Name 17447 17448 Description 17449 17450 TPM_ST 17451 17452 tag 17453 17454 see clause 8 17455 17456 UINT32 17457 17458 responseSize 17459 17460 TPM_RC 17461 17462 responseCode 17463 17464 UINT32 17465 17466 pcrUpdateCounter 17467 17468 the current value of the PCR update counter 17469 17470 TPML_PCR_SELECTION 17471 17472 pcrSelectionOut 17473 17474 the PCR in the returned list 17475 17476 TPML_DIGEST 17477 17478 pcrValues 17479 17480 the contents of the PCR indicated in pcrSelect as 17481 tagged digests 17482 17483 Page 208 17484 October 31, 2013 17485 17486 Published 17487 Copyright TCG 2006-2013 17488 17489 Family 2.0 17490 Level 00 Revision 00.99 17491 17492 Trusted Platform Module Library 17494 17495 Part 3: Commands 17496 17497 24.4.3 Detailed Actions 17498 1 17499 2 17500 3 17501 4 17502 5 17503 6 17504 7 17505 8 17506 9 17507 10 17508 11 17509 12 17510 13 17511 14 17512 15 17513 16 17514 17 17515 18 17516 17517 #include "InternalRoutines.h" 17518 #include "PCR_Read_fp.h" 17519 17520 TPM_RC 17521 TPM2_PCR_Read( 17522 PCR_Read_In 17523 PCR_Read_Out 17524 17525 *in, 17526 *out 17527 17528 // IN: input parameter list 17529 // OUT: output parameter list 17530 17531 ) 17532 { 17533 // Command Output 17534 // Call PCR read function. input pcrSelectionIn parameter could be changed 17535 // to reflect the actual PCR being returned 17536 PCRRead(&in->pcrSelectionIn, &out->pcrValues, &out->pcrUpdateCounter); 17537 out->pcrSelectionOut = in->pcrSelectionIn; 17538 return TPM_RC_SUCCESS; 17539 } 17540 17541 Family 2.0 17542 Level 00 Revision 00.99 17543 17544 Published 17545 Copyright TCG 2006-2013 17546 17547 Page 209 17548 October 31, 2013 17549 17550 Part 3: Commands 17552 17553 24.5 17554 17555 Trusted Platform Module Library 17556 17557 TPM2_PCR_Allocate 17558 17559 24.5.1 General Description 17560 This command is used to set the desired PCR allocation of PCR and algorithms. This command requires 17561 platformAuth. 17562 The TPM will evaluate the request and, if sufficient memory is available for the requested allocation, the 17563 TPM will store the allocation request for use during the next TPM2_Startup(TPM_SU_CLEAR) operation. 17564 The PCR allocation in place when this command is executed will be retained until the next 17565 TPM2_Startup(TPM_SU_CLEAR). 17566 If no allocation is specified for a bank, then no PCR will be allocated to that bank. If a bank is listed more 17567 than once, then the last selection in the pcrAllocation list is the one that the TPM will attempt to allocate. 17568 This command shall not allocate more PCR in any bank than there are PCR attribute definitions. The 17569 PCR attribute definitions indicate how a PCR is to be managed if it is resettable, the locality for update, 17570 etc. In the response to this command, the TPM returns the maximum number of PCR allowed for any 17571 bank. 17572 If the command is properly authorized, it will return SUCCESS even though the request fails. This is to 17573 allow the TPM to return information about the size needed for the requested allocation and the size 17574 available. If the sizeNeeded parameter in the return is less than or equal to the sizeAvailable parameter, 17575 then the allocationSuccess parameter will be YES. 17576 After this command, TPM2_Shutdown() is only allowed to have a startupType equal to TPM_SU_CLEAR. 17577 NOTE 17578 17579 Even if this command does not cause the PCR allocation to change, the TPM cannot have its state 17580 saved. This is done in order to simplify the implementation. There is no need to optimize this 17581 command as it is not expected to be used more than once in the lifetime of the TPM (it can be used 17582 any number of times but there is no justification for optimization) . 17583 17584 Page 210 17585 October 31, 2013 17586 17587 Published 17588 Copyright TCG 2006-2013 17589 17590 Family 2.0 17591 Level 00 Revision 00.99 17592 17593 Trusted Platform Module Library 17595 17596 Part 3: Commands 17597 17598 24.5.2 Command and Response 17599 Table 105 TPM2_PCR_Allocate Command 17600 Type 17601 17602 Name 17603 17604 Description 17605 17606 TPMI_ST_COMMAND_TAG 17607 17608 tag 17609 17610 UINT32 17611 17612 commandSize 17613 17614 TPM_CC 17615 17616 commandCode 17617 17618 TPM_CC_PCR_Allocate {NV} 17619 17620 TPMI_RH_PLATFORM 17621 17622 @authHandle 17623 17624 TPM_RH_PLATFORM+{PP} 17625 Auth Index: 1 17626 Auth Role: USER 17627 17628 TPML_PCR_SELECTION 17629 17630 pcrAllocation 17631 17632 the requested allocation 17633 17634 Table 106 TPM2_PCR_Allocate Response 17635 Type 17636 17637 Name 17638 17639 Description 17640 17641 TPM_ST 17642 17643 tag 17644 17645 see clause 8 17646 17647 UINT32 17648 17649 responseSize 17650 17651 TPM_RC 17652 17653 responseCode 17654 17655 TPMI_YES_NO 17656 17657 allocationSuccess 17658 17659 YES if the allocation succeeded 17660 17661 UINT32 17662 17663 maxPCR 17664 17665 maximum number of PCR that may be in a bank 17666 17667 UINT32 17668 17669 sizeNeeded 17670 17671 number of octets required to satisfy the request 17672 17673 UINT32 17674 17675 sizeAvailable 17676 17677 Number of octets available. Computed before the 17678 allocation. 17679 17680 Family 2.0 17681 Level 00 Revision 00.99 17682 17683 Published 17684 Copyright TCG 2006-2013 17685 17686 Page 211 17687 October 31, 2013 17688 17689 Part 3: Commands 17691 17692 Trusted Platform Module Library 17693 17694 24.5.3 Detailed Actions 17695 1 17696 2 17697 3 17698 4 17699 5 17700 6 17701 7 17702 8 17703 9 17704 10 17705 11 17706 12 17707 13 17708 14 17709 15 17710 16 17711 17 17712 18 17713 19 17714 20 17715 21 17716 22 17717 23 17718 24 17719 25 17720 26 17721 27 17722 28 17723 29 17724 30 17725 31 17726 32 17727 33 17728 34 17729 17730 #include "InternalRoutines.h" 17731 #include "PCR_Allocate_fp.h" 17732 17733 TPM_RC 17734 TPM2_PCR_Allocate( 17735 PCR_Allocate_In 17736 PCR_Allocate_Out 17737 17738 *in, 17739 *out 17740 17741 // IN: input parameter list 17742 // OUT: output parameter list 17743 17744 ) 17745 { 17746 TPM_RC 17747 17748 result; 17749 17750 // The command needs NV update. Check if NV is available. 17751 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 17752 // this point. 17753 // Note: These codes are not listed in the return values above because it is 17754 // an implementation choice to check in this routine rather than in a common 17755 // function that is called before these actions are called. These return values 17756 // are described in the Response Code section of Part 3. 17757 result = NvIsAvailable(); 17758 if(result != TPM_RC_SUCCESS) 17759 return result; 17760 // Command Output 17761 // Call PCR Allocation function. 17762 out->allocationSuccess = PCRAllocate(&in->pcrAllocation, &out->maxPCR, 17763 &out->sizeNeeded, &out->sizeAvailable); 17764 // if re-configuration succeeds, set the flag to indicate PCR configuration is 17765 // going to be changed in next boot 17766 if(out->allocationSuccess == YES) 17767 g_pcrReConfig = TRUE; 17768 return TPM_RC_SUCCESS; 17769 } 17770 17771 Page 212 17772 October 31, 2013 17773 17774 Published 17775 Copyright TCG 2006-2013 17776 17777 Family 2.0 17778 Level 00 Revision 00.99 17779 17780 Trusted Platform Module Library 17782 17783 24.6 17784 17785 Part 3: Commands 17786 17787 TPM2_PCR_SetAuthPolicy 17788 17789 24.6.1 General Description 17790 This command is used to associate a policy with a PCR or group of PCR. The policy determines the 17791 conditions under which a PCR may be extended or reset. 17792 A policy may only be associated with a PCR that has been defined by a platform-specific specification as 17793 allowing a policy. If the TPM implementation does not allow a policy for pcrNum, the TPM shall return 17794 TPM_RC_VALUE. 17795 A platform-specific specification may group PCR so that they share a common policy. In such case, a 17796 pcrNum that selects any of the PCR in the group will change the policy for all PCR in the group. 17797 The policy setting is persistent and may only be changed by TPM2_PCR_SetAuthPolicy() or by 17798 TPM2_ChangePPS(). 17799 Before this command is first executed on a TPM or after TPM2_ChangePPS(), the access control on the 17800 PCR will be set to the default value defined in the platform-specific specification. 17801 NOTE 1 17802 17803 It is expected that the typical default will be with the policy hash set to TPM_ALG_NULL and an 17804 Empty Buffer for the authPolicy value. This will allow an EmptyAuth to be used as the authorization 17805 value. 17806 17807 If the size of the data buffer in authPolicy is not the size of a digest produced by hashAlg, the TPM shall 17808 return TPM_RC_SIZE. 17809 NOTE 2 17810 17811 If hashAlg is TPM_ALG_NULL, then the size is required to be zero. 17812 17813 This command requires platformAuth/platformPolicy. 17814 NOTE 3 17815 17816 If the PCR is in multiple policy sets, the policy will be changed in only one set. The set that is 17817 changed will be implementation dependent. 17818 17819 Family 2.0 17820 Level 00 Revision 00.99 17821 17822 Published 17823 Copyright TCG 2006-2013 17824 17825 Page 213 17826 October 31, 2013 17827 17828 Part 3: Commands 17830 17831 Trusted Platform Module Library 17832 17833 24.6.2 Command and Response 17834 Table 107 TPM2_PCR_SetAuthPolicy Command 17835 Type 17836 17837 Name 17838 17839 Description 17840 17841 TPMI_ST_COMMAND_TAG 17842 17843 tag 17844 17845 UINT32 17846 17847 commandSize 17848 17849 TPM_CC 17850 17851 commandCode 17852 17853 TPM_CC_PCR_SetAuthPolicy {NV} 17854 17855 TPMI_RH_PLATFORM 17856 17857 @authHandle 17858 17859 TPM_RH_PLATFORM+{PP} 17860 Auth Index: 1 17861 Auth Role: USER 17862 17863 TPM2B_DIGEST 17864 17865 authPolicy 17866 17867 the desired authPolicy 17868 17869 TPMI_ALG_HASH+ 17870 17871 policyDigest 17872 17873 the digest of the policy 17874 17875 TPMI_DH_PCR 17876 17877 pcrNum 17878 17879 the PCR for which the policy is to be set 17880 17881 Table 108 TPM2_PCR_SetAuthPolicy Response 17882 Type 17883 17884 Name 17885 17886 Description 17887 17888 TPM_ST 17889 17890 tag 17891 17892 see clause 8 17893 17894 UINT32 17895 17896 responseSize 17897 17898 TPM_RC 17899 17900 responseCode 17901 17902 Page 214 17903 October 31, 2013 17904 17905 Published 17906 Copyright TCG 2006-2013 17907 17908 Family 2.0 17909 Level 00 Revision 00.99 17910 17911 Trusted Platform Module Library 17913 17914 Part 3: Commands 17915 17916 24.6.3 Detailed Actions 17917 1 17918 2 17919 17920 #include "InternalRoutines.h" 17921 #include "PCR_SetAuthPolicy_fp.h" 17922 Error Returns 17923 TPM_RC_SIZE 17924 17925 size of authPolicy is not the size of a digest produced by policyDigest 17926 17927 TPM_RC_VALUE 17928 3 17929 4 17930 5 17931 6 17932 7 17933 8 17934 9 17935 10 17936 11 17937 12 17938 13 17939 14 17940 15 17941 16 17942 17 17943 18 17944 19 17945 20 17946 21 17947 22 17948 23 17949 24 17950 25 17951 26 17952 27 17953 28 17954 29 17955 30 17956 31 17957 32 17958 33 17959 34 17960 35 17961 36 17962 37 17963 38 17964 17965 Meaning 17966 17967 PCR referenced by pcrNum is not a member of a PCR policy group 17968 17969 TPM_RC 17970 TPM2_PCR_SetAuthPolicy( 17971 PCR_SetAuthPolicy_In 17972 17973 *in 17974 17975 // IN: input parameter list 17976 17977 ) 17978 { 17979 UINT32 17980 17981 groupIndex; 17982 17983 TPM_RC 17984 17985 result; 17986 17987 // The command needs NV update. Check if NV is available. 17988 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 17989 // this point 17990 result = NvIsAvailable(); 17991 if(result != TPM_RC_SUCCESS) return result; 17992 // Input Validation: 17993 // Check the authPolicy consistent with hash algorithm 17994 if(in->authPolicy.t.size != CryptGetHashDigestSize(in->policyDigest)) 17995 return TPM_RC_SIZE + RC_PCR_SetAuthPolicy_authPolicy; 17996 // If PCR does not belong to a policy group, return TPM_RC_VALUE 17997 if(!PCRBelongsPolicyGroup(in->pcrNum, &groupIndex)) 17998 return TPM_RC_VALUE + RC_PCR_SetAuthPolicy_pcrNum; 17999 // Internal Data Update 18000 // Set PCR policy 18001 gp.pcrPolicies.hashAlg[groupIndex] = in->policyDigest; 18002 gp.pcrPolicies.policy[groupIndex] = in->authPolicy; 18003 // Save new policy to NV 18004 NvWriteReserved(NV_PCR_POLICIES, &gp.pcrPolicies); 18005 return TPM_RC_SUCCESS; 18006 } 18007 18008 Family 2.0 18009 Level 00 Revision 00.99 18010 18011 Published 18012 Copyright TCG 2006-2013 18013 18014 Page 215 18015 October 31, 2013 18016 18017 Part 3: Commands 18019 18020 24.7 18021 18022 Trusted Platform Module Library 18023 18024 TPM2_PCR_SetAuthValue 18025 18026 24.7.1 General Description 18027 This command changes the authValue of a PCR or group of PCR. 18028 An authValue may only be associated with a PCR that has been defined by a platform-specific 18029 specification as allowing an authorization value. If the TPM implementation does not allow an 18030 authorization for pcrNum, the TPM shall return TPM_RC_VALUE. A platform-specific specification may 18031 group PCR so that they share a common authorization value. In such case, a pcrNum that selects any of 18032 the PCR in the group will change the authValue value for all PCR in the group. 18033 The authorization setting is set to EmptyAuth on each STARTUP(CLEAR) or by TPM2_Clear(). The 18034 authorization setting is preserved by SHUTDOWN(STATE). 18035 18036 Page 216 18037 October 31, 2013 18038 18039 Published 18040 Copyright TCG 2006-2013 18041 18042 Family 2.0 18043 Level 00 Revision 00.99 18044 18045 Trusted Platform Module Library 18047 18048 Part 3: Commands 18049 18050 24.7.2 Command and Response 18051 Table 109 TPM2_PCR_SetAuthValue Command 18052 Type 18053 18054 Name 18055 18056 Description 18057 18058 TPMI_ST_COMMAND_TAG 18059 18060 tag 18061 18062 UINT32 18063 18064 commandSize 18065 18066 TPM_CC 18067 18068 commandCode 18069 18070 TPM_CC_PCR_SetAuthValue 18071 18072 TPMI_DH_PCR 18073 18074 @pcrHandle 18075 18076 handle for a PCR that may have an authorization value 18077 set 18078 Auth Index: 1 18079 Auth Role: USER 18080 18081 TPM2B_DIGEST 18082 18083 auth 18084 18085 the desired authorization value 18086 18087 Table 110 TPM2_PCR_SetAuthValue Response 18088 Type 18089 18090 Name 18091 18092 Description 18093 18094 TPM_ST 18095 18096 tag 18097 18098 see clause 8 18099 18100 UINT32 18101 18102 responseSize 18103 18104 TPM_RC 18105 18106 responseCode 18107 18108 Family 2.0 18109 Level 00 Revision 00.99 18110 18111 Published 18112 Copyright TCG 2006-2013 18113 18114 Page 217 18115 October 31, 2013 18116 18117 Part 3: Commands 18119 18120 Trusted Platform Module Library 18121 18122 24.7.3 Detailed Actions 18123 1 18124 2 18125 18126 #include "InternalRoutines.h" 18127 #include "PCR_SetAuthValue_fp.h" 18128 Error Returns 18129 TPM_RC_VALUE 18130 18131 3 18132 4 18133 5 18134 6 18135 7 18136 8 18137 9 18138 10 18139 11 18140 12 18141 13 18142 14 18143 15 18144 16 18145 17 18146 18 18147 19 18148 20 18149 21 18150 22 18151 23 18152 24 18153 25 18154 26 18155 27 18156 28 18157 29 18158 30 18159 31 18160 32 18161 33 18162 34 18163 18164 Meaning 18165 PCR referenced by pcrHandle is not a member of a PCR 18166 authorization group 18167 18168 TPM_RC 18169 TPM2_PCR_SetAuthValue( 18170 PCR_SetAuthValue_In 18171 18172 *in 18173 18174 // IN: input parameter list 18175 18176 ) 18177 { 18178 UINT32 18179 TPM_RC 18180 18181 groupIndex; 18182 result; 18183 18184 // Input Validation: 18185 // If PCR does not belong to an auth group, return TPM_RC_VALUE 18186 if(!PCRBelongsAuthGroup(in->pcrHandle, &groupIndex)) 18187 return TPM_RC_VALUE; 18188 // The command may cause the orderlyState to be cleared due to the update of 18189 // state clear data. If this is the case, Check if NV is available. 18190 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 18191 // this point 18192 if(gp.orderlyState != SHUTDOWN_NONE) 18193 { 18194 result = NvIsAvailable(); 18195 if(result != TPM_RC_SUCCESS) return result; 18196 g_clearOrderly = TRUE; 18197 } 18198 // Internal Data Update 18199 // Set PCR authValue 18200 gc.pcrAuthValues.auth[groupIndex] = in->auth; 18201 return TPM_RC_SUCCESS; 18202 } 18203 18204 Page 218 18205 October 31, 2013 18206 18207 Published 18208 Copyright TCG 2006-2013 18209 18210 Family 2.0 18211 Level 00 Revision 00.99 18212 18213 Trusted Platform Module Library 18215 18216 24.8 18217 18218 Part 3: Commands 18219 18220 TPM2_PCR_Reset 18221 18222 24.8.1 General Description 18223 If the attribute of a PCR allows the PCR to be reset and proper authorization is provided, then this 18224 command may be used to set the PCR to zero. The attributes of the PCR may restrict the locality that can 18225 perform the reset operation. 18226 NOTE 1 18227 18228 The definition of TPMI_DH_PCR in Part 2 indicates that if pcrHandle is out of the allowed range for 18229 PCR, then the appropriate return value is TPM_RC_VALUE. 18230 18231 If pcrHandle references a PCR that cannot be reset, the TPM shall return TPM_RC_LOCALITY. 18232 NOTE 2 18233 18234 TPM_RC_LOCALITY is returned because the reset attributes are defined on a per -locality basis. 18235 18236 Family 2.0 18237 Level 00 Revision 00.99 18238 18239 Published 18240 Copyright TCG 2006-2013 18241 18242 Page 219 18243 October 31, 2013 18244 18245 Part 3: Commands 18247 18248 Trusted Platform Module Library 18249 18250 24.8.2 Command and Response 18251 Table 111 TPM2_PCR_Reset Command 18252 Type 18253 18254 Name 18255 18256 Description 18257 18258 TPMI_ST_COMMAND_TAG 18259 18260 tag 18261 18262 UINT32 18263 18264 commandSize 18265 18266 TPM_CC 18267 18268 commandCode 18269 18270 TPM_CC_PCR_Reset {NV} 18271 18272 TPMI_DH_PCR 18273 18274 @pcrHandle 18275 18276 the PCR to reset 18277 Auth Index: 1 18278 Auth Role: USER 18279 18280 Table 112 TPM2_PCR_Reset Response 18281 Type 18282 18283 Name 18284 18285 Description 18286 18287 TPM_ST 18288 18289 tag 18290 18291 see clause 8 18292 18293 UINT32 18294 18295 responseSize 18296 18297 TPM_RC 18298 18299 responseCode 18300 18301 Page 220 18302 October 31, 2013 18303 18304 Published 18305 Copyright TCG 2006-2013 18306 18307 Family 2.0 18308 Level 00 Revision 00.99 18309 18310 Trusted Platform Module Library 18312 18313 Part 3: Commands 18314 18315 24.8.3 Detailed Actions 18316 1 18317 2 18318 18319 #include "InternalRoutines.h" 18320 #include "PCR_Reset_fp.h" 18321 Error Returns 18322 TPM_RC_LOCALITY 18323 18324 3 18325 4 18326 5 18327 6 18328 7 18329 8 18330 9 18331 10 18332 11 18333 12 18334 13 18335 14 18336 15 18337 16 18338 17 18339 18 18340 19 18341 20 18342 21 18343 22 18344 23 18345 24 18346 25 18347 26 18348 27 18349 28 18350 29 18351 30 18352 31 18353 32 18354 33 18355 34 18356 35 18357 36 18358 18359 Meaning 18360 current command locality is not allowed to reset the PCR referenced 18361 by pcrHandle 18362 18363 TPM_RC 18364 TPM2_PCR_Reset( 18365 PCR_Reset_In 18366 18367 *in 18368 18369 // IN: input parameter list 18370 18371 ) 18372 { 18373 TPM_RC 18374 18375 result; 18376 18377 // Input Validation 18378 // Check if the reset operation is allowed by the current command locality 18379 if(!PCRIsResetAllowed(in->pcrHandle)) 18380 return TPM_RC_LOCALITY; 18381 // If PCR is state saved and we need to update orderlyState, check NV 18382 // availability 18383 if(PCRIsStateSaved(in->pcrHandle) && gp.orderlyState != SHUTDOWN_NONE) 18384 { 18385 result = NvIsAvailable(); 18386 if(result != TPM_RC_SUCCESS) 18387 return result; 18388 g_clearOrderly = TRUE; 18389 } 18390 // Internal Data Update 18391 // Reset seleccted PCR in all banks to 0 18392 PCRSetValue(in->pcrHandle, 0); 18393 // Indicate that the PCR changed so that pcrCounter will be incremented if 18394 // necessary. 18395 PCRChanged(in->pcrHandle); 18396 return TPM_RC_SUCCESS; 18397 } 18398 18399 Family 2.0 18400 Level 00 Revision 00.99 18401 18402 Published 18403 Copyright TCG 2006-2013 18404 18405 Page 221 18406 October 31, 2013 18407 18408 Part 3: Commands 18410 18411 24.9 18412 18413 Trusted Platform Module Library 18414 18415 _TPM_Hash_Start 18416 18417 24.9.1 Description 18418 This indication from the TPM interface indicates the start of a dynamic Core Root of Trust for 18419 Measurement (D-CRTM) measurement sequence. On receipt of this indication, the TPM will initialize an 18420 Event sequence context. 18421 If no object memory is available for creation of the sequence context, the TPM will flush the context of an 18422 object so that creation of the Event sequence context will always succeed. 18423 A platform-specific specification may allow this indication before TPM2_Startup(). 18424 NOTE 18425 18426 If this indication occurs after TPM2_Startup(), it is the responsibility of software to ensure that an 18427 object context slot is available or to deal with the consequences of having the TPM select an 18428 arbitrary object to be flushed. If this indication occurs before TPM2_Startup() then all context slots 18429 are available. 18430 18431 Page 222 18432 October 31, 2013 18433 18434 Published 18435 Copyright TCG 2006-2013 18436 18437 Family 2.0 18438 Level 00 Revision 00.99 18439 18440 Trusted Platform Module Library 18442 18443 Part 3: Commands 18444 18445 24.9.2 Detailed Actions 18446 1 18447 18448 #include "InternalRoutines.h" 18449 18450 This function is called to process a _TPM_Hash_Start() indication. 18451 2 18452 3 18453 4 18454 5 18455 6 18456 7 18457 8 18458 9 18459 10 18460 11 18461 12 18462 13 18463 14 18464 15 18465 16 18466 17 18467 18 18468 19 18469 20 18470 21 18471 22 18472 23 18473 24 18474 25 18475 26 18476 27 18477 28 18478 29 18479 30 18480 31 18481 32 18482 33 18483 34 18484 35 18485 36 18486 37 18487 38 18488 39 18489 40 18490 41 18491 42 18492 43 18493 44 18494 45 18495 46 18496 47 18497 48 18498 49 18499 50 18500 18501 void 18502 _TPM_Hash_Start(void) 18503 { 18504 TPM_RC 18505 TPMI_DH_OBJECT 18506 18507 result; 18508 handle; 18509 18510 // If a DRTM sequence object exists, terminate it. 18511 if(g_DRTMHandle != TPM_RH_UNASSIGNED) 18512 ObjectTerminateEvent(); 18513 // Create an event sequence object and store the handle in global 18514 // g_DRTMHandle. A TPM_RC_OBJECT_MEMORY error may be returned at this point 18515 // The null value for the 'auth' parameter will cause the sequence structure to 18516 // be allocated without being set as present. This keeps the sequence from 18517 // being left behind if the sequence is terminated early. 18518 result = ObjectCreateEventSequence(NULL, &g_DRTMHandle); 18519 // If a free slot was not available, then free up a slot. 18520 if(result != TPM_RC_SUCCESS) 18521 { 18522 // An implementation does not need to have a fixed relationship between 18523 // slot numbers and handle numbers. To handle the general case, scan for 18524 // a handle that is assigned an free it for the DRTM sequence. 18525 // In the reference implementation, the relationship between handles and 18526 // slots is fixed. So, if the call to ObjectCreateEvenSequence() 18527 // failed indicating that all slots are occupied, then the first handle we 18528 // are going to check (TRANSIENT_FIRST) will be occupied. It will be freed 18529 // so that it can be assigned for use as the DRTM sequence object. 18530 for(handle = TRANSIENT_FIRST; handle < TRANSIENT_LAST; handle++) 18531 { 18532 // try to flush the first object 18533 if(ObjectIsPresent(handle)) 18534 break; 18535 } 18536 // If the first call to find a slot fails but none of the slots is occupied 18537 // then there's a big problem 18538 pAssert(handle < TRANSIENT_LAST); 18539 // Free the slot 18540 ObjectFlush(handle); 18541 // Try to create an event sequence object again. This time, we must 18542 // succeed. 18543 result = ObjectCreateEventSequence(NULL, &g_DRTMHandle); 18544 pAssert(result == TPM_RC_SUCCESS); 18545 } 18546 return; 18547 } 18548 18549 Family 2.0 18550 Level 00 Revision 00.99 18551 18552 Published 18553 Copyright TCG 2006-2013 18554 18555 Page 223 18556 October 31, 2013 18557 18558 Part 3: Commands 18560 18561 Trusted Platform Module Library 18562 18563 24.10 _TPM_Hash_Data 18564 24.10.1 18565 18566 Description 18567 18568 This indication from the TPM interface indicates arrival of one or more octets of data that are to be 18569 included in the Core Root of Trust for Measurement (CRTM) sequence context created by the 18570 _TPM_Hash_Start indication. The context holds data for each hash algorithm for each PCR bank 18571 implemented on the TPM. 18572 If no DRTM Event Sequence context exists, this indication is discarded and no other action is performed. 18573 18574 Page 224 18575 October 31, 2013 18576 18577 Published 18578 Copyright TCG 2006-2013 18579 18580 Family 2.0 18581 Level 00 Revision 00.99 18582 18583 Trusted Platform Module Library 18585 18586 24.10.2 18587 1 18588 2 18589 18590 Part 3: Commands 18591 18592 Detailed Actions 18593 18594 #include "InternalRoutines.h" 18595 #include "Platform.h" 18596 18597 This function is called to process a _TPM_Hash_Data() indication. 18598 3 18599 4 18600 5 18601 6 18602 7 18603 8 18604 9 18605 10 18606 11 18607 12 18608 13 18609 14 18610 15 18611 16 18612 17 18613 18 18614 19 18615 20 18616 21 18617 22 18618 23 18619 24 18620 25 18621 26 18622 27 18623 28 18624 29 18625 30 18626 31 18627 18628 void 18629 _TPM_Hash_Data( 18630 UINT32 18631 BYTE 18632 18633 dataSize, 18634 *data 18635 18636 UINT32 18637 HASH_OBJECT 18638 18639 // IN: size of data to be extend 18640 // IN: data buffer 18641 18642 i; 18643 *hashObject; 18644 18645 ) 18646 { 18647 18648 // If there is no DRTM sequence object, then _TPM_Hash_Start 18649 // was not called so this function returns without doing 18650 // anything. 18651 if(g_DRTMHandle == TPM_RH_UNASSIGNED) 18652 return; 18653 hashObject = (HASH_OBJECT *)ObjectGet(g_DRTMHandle); 18654 pAssert(hashObject->attributes.eventSeq); 18655 // For each of the implemented hash algorithms, update the digest with the 18656 // data provided. NOTE: the implementation could be done such that the TPM 18657 // only computes the hash for the banks that contain the DRTM PCR. 18658 for(i = 0; i < HASH_COUNT; i++) 18659 { 18660 // Update sequence object 18661 CryptUpdateDigest(&hashObject->state.hashState[i], dataSize, data); 18662 } 18663 return; 18664 } 18665 18666 Family 2.0 18667 Level 00 Revision 00.99 18668 18669 Published 18670 Copyright TCG 2006-2013 18671 18672 Page 225 18673 October 31, 2013 18674 18675 Part 3: Commands 18677 18678 Trusted Platform Module Library 18679 18680 24.11 _TPM_Hash_End 18681 24.11.1 18682 18683 Description 18684 18685 This indication from the TPM interface indicates the end of the CRTM measurement. This indication is 18686 discarded and no other action performed if the TPM does not contain a CRTM Event sequence context. 18687 NOTE 18688 18689 A CRTM Event Sequence context is created by _TPM_Hash_Start(). 18690 18691 If the CRTM Event sequence occurs after TPM2_Startup(), the TPM will set all of the PCR designated in 18692 the platform-specific specifications as resettable by this event to the value indicated in the platform 18693 specific specification, and increment restartCount. The TPM will then Extend the Event Sequence 18694 digest/digests into the designated, DRTM PCR. 18695 PCR[DRTM][hashAlg] HhashAlg (initial_value || HhashAlg (hash_data)) 18696 18697 (7) 18698 18699 where 18700 DRTM 18701 18702 index for CRTM PCR designated by a platform-specific 18703 specification 18704 18705 hashAlg 18706 18707 hash algorithm associated with a bank of PCR 18708 18709 initial_value 18710 18711 initialization value specified in the platform-specific specification 18712 (should be 00) 18713 18714 hash_data 18715 18716 all the octets of data received in _TPM_Hash_Data indications 18717 18718 A _TPM_Hash_End indication that occurs after TPM2_Startup() will increment pcrUpdateCounter unless 18719 a platform-specific specification excludes modifications of PCR[DRTM] from causing an increment. 18720 A platform-specific specification may allow an H-CRTM Event Sequence before TPM2_Startup(). If so, 18721 _TPM_Hash_End will complete the digest, initialize PCR[0] with a digest-size value of 4, and then extend 18722 the H-CRTM Event Sequence data into PCR[0]. 18723 PCR[0][hashAlg] HhashAlg (004 || HhashAlg (hash_data)) 18724 NOTE 18725 18726 (8) 18727 18728 The entire sequence of _TPM_Hash_Start, _TPM_Hash_Data, and _TPM_Hash_End are required to 18729 complete before TPM2_Startup() or the sequence will have no effect on the TPM. 18730 18731 Page 226 18732 October 31, 2013 18733 18734 Published 18735 Copyright TCG 2006-2013 18736 18737 Family 2.0 18738 Level 00 Revision 00.99 18739 18740 Trusted Platform Module Library 18742 18743 24.11.2 18744 1 18745 18746 Part 3: Commands 18747 18748 Detailed Actions 18749 18750 #include "InternalRoutines.h" 18751 18752 This function is called to process a _TPM_Hash_End() indication. 18753 2 18754 3 18755 4 18756 5 18757 6 18758 7 18759 8 18760 9 18761 10 18762 11 18763 12 18764 13 18765 14 18766 15 18767 16 18768 17 18769 18 18770 19 18771 20 18772 21 18773 22 18774 23 18775 24 18776 25 18777 26 18778 27 18779 28 18780 29 18781 30 18782 31 18783 32 18784 33 18785 34 18786 35 18787 36 18788 37 18789 38 18790 39 18791 40 18792 41 18793 42 18794 43 18795 44 18796 45 18797 46 18798 47 18799 48 18800 49 18801 50 18802 51 18803 52 18804 53 18805 54 18806 55 18807 56 18808 57 18809 18810 void 18811 _TPM_Hash_End(void) 18812 { 18813 UINT32 18814 TPM2B_DIGEST 18815 HASH_OBJECT 18816 TPMI_DH_PCR 18817 18818 i; 18819 digest; 18820 *hashObject; 18821 pcrHandle; 18822 18823 // If the DRTM handle is not being used, then either _TPM_Hash_Start has not 18824 // been called, _TPM_Hash_End was previously called, or some other command 18825 // was executed and the sequence was aborted. 18826 if(g_DRTMHandle == TPM_RH_UNASSIGNED) 18827 return; 18828 // Get DRTM sequence object 18829 hashObject = (HASH_OBJECT *)ObjectGet(g_DRTMHandle); 18830 // Is this _TPM_Hash_End after Startup or before 18831 if(TPMIsStarted()) 18832 { 18833 // After 18834 // Reset the DRTM PCR 18835 PCRResetDynamics(); 18836 // Extend the DRTM_PCR. 18837 pcrHandle = PCR_FIRST + DRTM_PCR; 18838 // DRTM sequence increments restartCount 18839 gr.restartCount++; 18840 } 18841 else 18842 { 18843 pcrHandle = PCR_FIRST + HCRTM_PCR; 18844 } 18845 // Complete hash and extend PCR, or if this is an HCRTM, complete 18846 // the hash and write the PCR 18847 for(i = 0; i < HASH_COUNT; i++) 18848 { 18849 TPMI_ALG_HASH 18850 hash = CryptGetHashAlgByIndex(i); 18851 // Complete hash 18852 digest.t.size = CryptGetHashDigestSize(hash); 18853 CryptCompleteHash2B(&hashObject->state.hashState[i], &digest.b); 18854 // If this is DRTM, extend to zeroed PCR 18855 // If this is H-DRTM, copy to HCRM PCR 18856 if(TPMIsStarted()) 18857 // Extend PCR 18858 PCRExtend(pcrHandle, hash, digest.t.size, digest.t.buffer); 18859 else 18860 PcrWrite(pcrHandle, hash, &digest); 18861 18862 Family 2.0 18863 Level 00 Revision 00.99 18864 18865 Published 18866 Copyright TCG 2006-2013 18867 18868 Page 227 18869 October 31, 2013 18870 18871 Part 3: Commands 18873 58 18874 59 18875 60 18876 61 18877 62 18878 63 18879 64 18880 65 18881 66 18882 67 18883 68 18884 18885 Trusted Platform Module Library 18886 18887 } 18888 // Flush sequence object. 18889 ObjectFlush(g_DRTMHandle); 18890 g_DRTMHandle = TPM_RH_UNASSIGNED; 18891 g_DrtmPreStartup = TRUE; 18892 return; 18893 } 18894 18895 Page 228 18896 October 31, 2013 18897 18898 Published 18899 Copyright TCG 2006-2013 18900 18901 Family 2.0 18902 Level 00 Revision 00.99 18903 18904 Trusted Platform Module Library 18906 18907 25 18908 18909 Part 3: Commands 18910 18911 Enhanced Authorization (EA) Commands 18912 18913 25.1 18914 18915 Introduction 18916 18917 The commands in this clause 1 are used for policy evaluation. When successful, each command will 18918 update the policySessionpolicyDigest in a policy session context in order to establish that the 18919 authorizations required to use an object have been provided. Many of the commands will also modify 18920 other parts of a policy context so that the caller may constrain the scope of the authorization that is 18921 provided. 18922 NOTE 1 18923 18924 Many of the terms used in this clause are described in detail i n Part 1 and are not redefined in this 18925 clause. 18926 18927 The policySession parameter of the command is the handle of the policy session context to be modified 18928 by the command. 18929 If the policySession parameter indicates a trial policy session, then the policySessionpolicyDigest will 18930 be updated and the indicated validations are not performed. 18931 NOTE 2 18932 18933 A policy session is a trial policy by TPM2_StartAuthSession( sessionType = TPM_SE_TRIAL). 18934 18935 NOTE 3 18936 18937 Unless there is an unmarshaling error in the parameters of the command, these commands will 18938 return TPM_RC_SUCCESS when policySession references a trial session. 18939 18940 NOTE 4 18941 18942 Policy context other than the policySessionpolicyDigest may be updated for a trial policy but it is 18943 not required. 18944 18945 Family 2.0 18946 Level 00 Revision 00.99 18947 18948 Published 18949 Copyright TCG 2006-2013 18950 18951 Page 229 18952 October 31, 2013 18953 18954 Part 3: Commands 18956 18957 25.2 18958 18959 Trusted Platform Module Library 18960 18961 Signed Authorization Actions 18962 18963 25.2.1 Introduction 18964 The TPM2_PolicySigned, TPM_PolicySecret, and TPM2_PolicyTicket commands use many of the same 18965 functions. This clause consolidates those functions to simplify the document and to ensure uniformity of 18966 the operations. 18967 25.2.2 Policy Parameter Checks 18968 These parameter checks will be performed when indicated in the description of each of the commands: 18969 a) nonceTPM If this parameter is not the Empty Buffer, and 18970 policySessionnonceTPM, then the TPM shall return TPM_RC_VALUE. 18971 18972 it 18973 18974 does 18975 18976 not 18977 18978 match 18979 18980 b) expiration If this parameter is not zero, then its absolute value is compared to the time in seconds 18981 since the policySessionnonceTPM was generated. If more time has passed than indicted in 18982 expiration, the TPM shall return TPM_RC_EXPIRED. If nonceTPM is the Empty buffer, and expiration 18983 is non-zero, then the TPM shall return TPM_RC_EXPIRED. 18984 c) timeout This parameter is compared to the current TPM time. If policySessiontimeout is in the 18985 past, then the TPM shall return TPM_RC_EXPIRED. 18986 NOTE 1 18987 18988 The expiration parameter is present in the TPM2_PolicySigned and TPM2_PolicySecret 18989 command and timeout is the analogous parameter in the TPM2_PolicyTicket command. 18990 18991 d) cpHashA If this parameter is not an Empty Buffer 18992 NOTE 2 18993 18994 CpHashA is the hash of the command to be executed using this policy session in the 18995 authorization. The algorithm used to compute this hash is required to be the algorithm of the 18996 policy session. 18997 18998 1) the TPM shall return TPM_RC_CPHASH if policySessioncpHash does not have its default 18999 value or the contents of policySessioncpHash are not the same as cpHashA; or 19000 NOTE 3 19001 19002 CpHash is the expected cpHash value held in the policy session context. 19003 19004 2) the TPM shall return TPM_RC_SIZE 19005 policySessionpolicyDigest. 19006 NOTE 4 19007 19008 Page 230 19009 October 31, 2013 19010 19011 if 19012 19013 cpHashA 19014 19015 is 19016 19017 not 19018 19019 the 19020 19021 same 19022 19023 size 19024 19025 as 19026 19027 PolicySessionpolicyDigest is the size of the digest produced by the hash algorithm used to 19028 compute policyDigest. 19029 19030 Published 19031 Copyright TCG 2006-2013 19032 19033 Family 2.0 19034 Level 00 Revision 00.99 19035 19036 Trusted Platform Module Library 19038 19039 Part 3: Commands 19040 19041 25.2.3 PolicyDigest Update Function (PolicyUpdate()) 19042 This is the update process for policySessionpolicyDigest used by TPM2_PolicySigned(), 19043 TPM2_PolicySecret(), TPM2_PolicyTicket(), and TPM2_PolicyAuthorize(). The function prototype for the 19044 update function is: 19045 19046 PolicyUpdate(commandCode, arg2, arg3) 19047 19048 (9) 19049 19050 where 19051 19052 arg2 19053 19054 a TPM2B_NAME 19055 19056 arg3 19057 19058 a TPM2B 19059 19060 These parameters are used to update policySessionpolicyDigest by 19061 19062 policyDigestnew HpolicyAlg(policyDigestold || commandCode || arg2.name) 19063 19064 (10) 19065 19066 policyDigestnew+1 HpolicyAlg(policyDigestnew || arg3.buffer) 19067 19068 (11) 19069 19070 followed by 19071 19072 where 19073 19074 HpolicyAlg() 19075 19076 the hash algorithm chosen when the policy session was started 19077 19078 NOTE 1 19079 19080 If arg3 is a TPM2B_NAME, then arg3.buffer will actually be an arg3.name. 19081 19082 NOTE 2 19083 19084 The arg2.size and arg3.size fields are not included in the hashes. 19085 19086 NOTE 3 19087 19088 PolicyUpdate() uses two hashes because arg2 and arg3 are variable-sized and the concatenation of 19089 arg2 and arg3 in a single hash could produce the same digest even though arg2 and arg3 are 19090 different. Processing of the arguments separately in different Extend operation insures that the 19091 digest produced by PolicyUpdate() will be different if arg2 and arg3 are different. 19092 19093 Family 2.0 19094 Level 00 Revision 00.99 19095 19096 Published 19097 Copyright TCG 2006-2013 19098 19099 Page 231 19100 October 31, 2013 19101 19102 Part 3: Commands 19104 19105 Trusted Platform Module Library 19106 19107 25.2.4 Policy Context Updates 19108 When a policy command modifies some part of the policy session context other than the 19109 policySessionpolicyDigest, the following rules apply. 19110 19111 19112 cpHash this parameter may only be changed if it contains its initialization value (an Empty String). 19113 If cpHash is not the Empty String when a policy command attempts to update it, the TPM will return 19114 an error (TPM_RC_CPHASH) if the current and update values are not the same. 19115 19116 19117 19118 timeOut this parameter may only be changed to a smaller value. If a command attempts to update 19119 this value with a larger value (longer into the future), the TPM will discard the update value. This is 19120 not an error condition. 19121 19122 19123 19124 commandCode once set by a policy command, this value may not be change except by 19125 TPM2_PolicyRestart(). If a policy command tries to change this to a different value, an error is 19126 returned (TPM_RC_POLICY_CC). 19127 19128 19129 19130 pcrUpdateCounter this parameter is updated by TPM2_PolicyPCR(). This value may only be set 19131 once during a policy. Each time TPM2_PolicyPCR() executes, it checks to see if 19132 policySessionpcrUpdateCounter has its default state indicating that this is the first 19133 TPM2_PolicyPCR(). If it has its default value, then policySessionpcrUpdateCounter is set to the 19134 current value of pcrUpdateCounter. If policySessionpcrUpdateCounter does not have its default 19135 value and its value is not the same as pcrUpdateCounter, the TPM shall return 19136 TPM_RC_PCR_CHANGED. 19137 NOTE 19138 19139 If this parameter and pcrUpdateCounter are not the same, it indicates that PCR have changed 19140 since checked by the previous TPM2_PolicyPCR(). Since they have changed, the previous PCR 19141 validation is no longer valid. 19142 19143 19144 19145 commandLocality this parameter is the logical AND of all enabled localities. All localities are 19146 enabled for a policy when the policy session is created. TPM2_PolicyLocalities() selectively disables 19147 localities. Once use of a policy for a locality has been disabled, it cannot be enabled except by 19148 TPM2_PolicyRestart(). 19149 19150 19151 19152 isPPRequired once SET, this parameter may only be CLEARed by TPM2_PolicyRestart(). 19153 19154 19155 19156 isAuthValueNeeded once SET, this parameter may only be CLEARed by TPM2_PolicyPassword() 19157 or TPM2_PolicyRestart(). 19158 19159 19160 19161 isPasswordNeeded once SET, this parameter may only be CLEARed by TPM2_PolicyAuthValue() 19162 or TPM2_PolicyRestart(), 19163 19164 NOTE 19165 19166 Both TPM2_PolicyAuthValue() and TPM2_PolicyPassword() change policySessionpolicyDigest in 19167 the same way. The different commands simply indicate to the TPM the format used for the authValue 19168 (HMAC or clear text). Both commands could be in the same policy. The final instance of these 19169 commands determines the format. 19170 19171 Page 232 19172 October 31, 2013 19173 19174 Published 19175 Copyright TCG 2006-2013 19176 19177 Family 2.0 19178 Level 00 Revision 00.99 19179 19180 Trusted Platform Module Library 19182 19183 Part 3: Commands 19184 19185 25.2.5 Policy Ticket Creation 19186 If for TPM2_PolicySigned() or TPM2_PolicySecret() the caller specified a negative value for expiration, 19187 and the policy update succeeds, then the TPM will return a ticket that includes a value indicating when 19188 the authorization expires. The required computation for the digest in the authorization ticket is: 19189 19190 HMAC(proof, HpolicyAlg(ticketType || timeout || cpHashA || policyRef || authObjectName)) (12) 19191 where 19192 19193 proof 19194 19195 secret associated with the storage primary seed (SPS) of the 19196 TPM 19197 19198 HpolicyAlg 19199 19200 hash function using the hash algorithm associated with the policy 19201 session 19202 19203 ticketType 19204 19205 either TPM_ST_AUTH_SECRET or TPM_ST_AUTH_SIGNED, 19206 used to indicate type of the ticket 19207 19208 NOTE 1 19209 19210 If 19211 the 19212 ticket 19213 is 19214 produced 19215 by 19216 TPM2_PolicySecret() 19217 then 19218 ticketType 19219 is 19220 TPM_ST_AUTH_SECRET and if produced by TPM2_PolicySigned() then ticketType is 19221 TPM_ST_AUTH_SIGNED. 19222 19223 timeout 19224 19225 NOTE 2 19226 19227 implementation-specific representation of the expiration time of 19228 the ticket; required to be the implementation equivalent of 19229 policySessionstartTime plus the absolute value of expiration 19230 Timeout is not the same as expiration. The expiration value in the aHash is a relative time, 19231 using the creation time of the authorization session (TPM2_StartAuthSession()) as its 19232 reference. The timeout parameter is an absolute time, using TPM Clock as the reference. 19233 19234 cpHashA 19235 19236 the command parameter digest for the command being 19237 authorized; computed using the hash algorithm of the policy 19238 session 19239 19240 policyRef 19241 19242 the commands that use this function have a policyRef parameter 19243 and the value of that parameter is used here 19244 19245 authObjectName 19246 19247 Name associated with the authObject parameter 19248 19249 Family 2.0 19250 Level 00 Revision 00.99 19251 19252 Published 19253 Copyright TCG 2006-2013 19254 19255 Page 233 19256 October 31, 2013 19257 19258 Part 3: Commands 19260 25.3 19261 19262 Trusted Platform Module Library 19263 19264 TPM2_PolicySigned 19265 19266 25.3.1 General Description 19267 This command includes a signed authorization in a policy. The command ties the policy to a signing key 19268 by including the Name of the signing key in the policyDigest 19269 If policySession is a trial session, the TPM will not check the signature and will update 19270 policySessionpolicyDigest as described in 25.2.3 as if a properly signed authorization was received; but 19271 no ticket will be produced. 19272 If policySession is not a trial session, the TPM will validate auth and only perform the update if it is a valid 19273 signature over the fields of the command. 19274 The authorizing object will sign a digest of the authorization qualifiers: nonceTPM, expiration, cpHashA, 19275 and policyRef. The digest is computed as: 19276 19277 aHash HauthAlg(nonceTPM || expiration || cpHashA || policyRef) 19278 19279 (13) 19280 19281 where 19282 19283 HauthAlg() 19284 NOTE 1 19285 19286 the hash associated with the auth parameter of this command 19287 Each signature and key combination indicates the scheme and each scheme has an 19288 associated hash. 19289 19290 nonceTPM 19291 19292 the nonceTPM parameter from the TPM2_StartAuthSession() 19293 response. If the authorization is not limited to this session, the 19294 size of this value is zero. 19295 19296 expiration 19297 19298 time limit on authorization set by authorizing object. This 32-bit 19299 value is set to zero if the expiration time is not being set. 19300 19301 cpHashA 19302 19303 digest of the command parameters for the command being 19304 approved using the hash algorithm of the policy session. Set to 19305 an EmptyAuth if the authorization is not limited to a specific 19306 command. 19307 19308 NOTE 2 19309 19310 This is not the cpHash of this TPM2_PolicySigned() command. 19311 19312 policyRef 19313 EXAMPLE 19314 19315 an opaque value determined by the authorizing entity. Set to the 19316 Empty Buffer if no value is present. 19317 19318 The computation for an aHash if there are no restrictions is: 19319 19320 aHash HauthAlg(00 00 00 0016) 19321 which is the hash of an expiration time of zero. 19322 19323 The aHash is signed by the private key associated with key. The signature and signing parameters are 19324 combined to create the auth parameter. 19325 The TPM will perform the parameter checks listed in 25.2.2 19326 If the parameter checks succeed, the TPM will construct a test digest (tHash) over the provided 19327 parameters using the same formulation a shown in equation (13) above. 19328 If tHash does not match the digest of the signed aHash, then the authorization fails and the TPM shall 19329 return TPM_RC_POLICY_FAIL and make no change to policySessionpolicyDigest. 19330 19331 Page 234 19332 October 31, 2013 19333 19334 Published 19335 Copyright TCG 2006-2013 19336 19337 Family 2.0 19338 Level 00 Revision 00.99 19339 19340 Trusted Platform Module Library 19342 19343 Part 3: Commands 19344 19345 When all validations have succeeded, policySessionpolicyDigest is updated by PolicyUpdate() (see 19346 25.2.3). 19347 19348 PolicyUpdate(TPM_CC_PolicySigned, authObjectName, policyRef) 19349 19350 (14) 19351 19352 If the cpHashA parameter is not an Empty Buffer, it is copied to policySessioncpHash. 19353 The TPM will optionally produce a ticket as described in 25.2.5. 19354 Authorization to use authObject is not required. 19355 19356 Family 2.0 19357 Level 00 Revision 00.99 19358 19359 Published 19360 Copyright TCG 2006-2013 19361 19362 Page 235 19363 October 31, 2013 19364 19365 Part 3: Commands 19367 19368 Trusted Platform Module Library 19369 19370 25.3.2 Command and Response 19371 Table 113 TPM2_PolicySigned Command 19372 Type 19373 19374 Name 19375 19376 TPMI_ST_COMMAND_TAG 19377 19378 tag 19379 19380 UINT32 19381 19382 commandSize 19383 19384 TPM_CC 19385 19386 commandCode 19387 19388 TPM_CC_PolicySigned 19389 19390 TPMI_DH_OBJECT 19391 19392 authObject 19393 19394 handle for a public key that will validate the signature 19395 Auth Index: None 19396 19397 TPMI_SH_POLICY 19398 19399 policySession 19400 19401 handle for the policy session being extended 19402 Auth Index: None 19403 19404 TPM2B_NONCE 19405 19406 nonceTPM 19407 19408 the policy nonce for the session 19409 If the nonce is not included in the authorization 19410 qualification, this field is the Empty Buffer. 19411 19412 TPM2B_DIGEST 19413 19414 cpHashA 19415 19416 digest of the command parameters to which this 19417 authorization is limited 19418 This is not the cpHash for this command but the cpHash 19419 for the command to which this policy session will be 19420 applied. If it is not limited, the parameter will be the 19421 Empty Buffer. 19422 19423 TPM2B_NONCE 19424 19425 policyRef 19426 19427 a reference to a policy relating to the authorization 19428 may be the Empty Buffer 19429 Size is limited to be no larger than the nonce size 19430 supported on the TPM. 19431 19432 INT32 19433 19434 expiration 19435 19436 time when authorization will expire, measured in 19437 seconds from the time that nonceTPM was generated 19438 If expiration is zero, a NULL Ticket is returned. 19439 19440 TPMT_SIGNATURE 19441 19442 auth 19443 19444 signed authorization (not optional) 19445 19446 Description 19447 19448 Table 114 TPM2_PolicySigned Response 19449 Type 19450 19451 Name 19452 19453 Description 19454 19455 TPM_ST 19456 19457 tag 19458 19459 see clause 8 19460 19461 UINT32 19462 19463 responseSize 19464 19465 TPM_RC 19466 19467 responseCode 19468 19469 TPM2B_TIMEOUT 19470 19471 timeout 19472 19473 TPMT_TK_AUTH 19474 19475 policyTicket 19476 19477 Page 236 19478 October 31, 2013 19479 19480 implementation-specific time value, used to indicate to 19481 the TPM when the ticket expires 19482 NOTE 19483 19484 If policyTicket is a NULL Ticket, then this shall be 19485 the Empty Buffer. 19486 19487 produced if the command succeeds and expiration in 19488 the command was non-zero; this ticket will use the 19489 TPMT_ST_AUTH_SIGNED structure tag 19490 19491 Published 19492 Copyright TCG 2006-2013 19493 19494 Family 2.0 19495 Level 00 Revision 00.99 19496 19497 Trusted Platform Module Library 19499 19500 Part 3: Commands 19501 19502 25.3.3 Detailed Actions 19503 1 19504 2 19505 3 19506 19507 #include "InternalRoutines.h" 19508 #include "Policy_spt_fp.h" 19509 #include "PolicySigned_fp.h" 19510 Error Returns 19511 TPM_RC_CPHASH 19512 19513 cpHash was previously set to a different value 19514 19515 TPM_RC_EXPIRED 19516 19517 expiration indicates a time in the past or expiration is non-zero but no 19518 nonceTPM is present 19519 19520 TPM_RC_HANDLE 19521 19522 authObject need to have sensitive portion loaded 19523 19524 TPM_RC_KEY 19525 19526 authObject is not a signing scheme 19527 19528 TPM_RC_NONCE 19529 19530 nonceTPM is not the nonce associated with the policySession 19531 19532 TPM_RC_SCHEME 19533 19534 the signing scheme of auth is not supported by the TPM 19535 19536 TPM_RC_SIGNATURE 19537 19538 the signature is not genuine 19539 19540 TPM_RC_SIZE 19541 19542 input cpHash has wrong size 19543 19544 TPM_RC_VALUE 19545 19546 4 19547 5 19548 6 19549 7 19550 8 19551 9 19552 10 19553 11 19554 12 19555 13 19556 14 19557 15 19558 16 19559 17 19560 18 19561 19 19562 20 19563 21 19564 22 19565 23 19566 24 19567 25 19568 26 19569 27 19570 28 19571 29 19572 30 19573 31 19574 32 19575 33 19576 34 19577 35 19578 36 19579 37 19580 38 19581 39 19582 19583 Meaning 19584 19585 input policyID or expiration does not match the internal data in policy 19586 session 19587 19588 TPM_RC 19589 TPM2_PolicySigned( 19590 PolicySigned_In 19591 PolicySigned_Out 19592 19593 *in, 19594 *out 19595 19596 // IN: input parameter list 19597 // OUT: output parameter list 19598 19599 TPM_RC 19600 SESSION 19601 OBJECT 19602 TPM2B_NAME 19603 TPM2B_DIGEST 19604 HASH_STATE 19605 UINT32 19606 19607 result = TPM_RC_SUCCESS; 19608 *session; 19609 *authObject; 19610 entityName; 19611 authHash; 19612 hashState; 19613 expiration = (in->expiration < 0) 19614 ? -(in->expiration) : in->expiration; 19615 authTimeout = 0; 19616 19617 ) 19618 { 19619 19620 UINT64 19621 // Input Validation 19622 19623 // Set up local pointers 19624 session = SessionGet(in->policySession); 19625 authObject = ObjectGet(in->authObject); 19626 19627 // the session structure 19628 // pointer for the object 19629 // 19630 providing authorization 19631 // 19632 signature 19633 19634 // Only do input validation if this is not a trial policy session 19635 if(session->attributes.isTrialPolicy == CLEAR) 19636 { 19637 if(expiration != 0) 19638 authTimeout = expiration * 1000 + session->startTime; 19639 result = PolicyParameterChecks(session, authTimeout, 19640 &in->cpHashA, &in->nonceTPM, 19641 RC_PolicySigned_nonceTPM, 19642 RC_PolicySigned_cpHashA, 19643 RC_PolicySigned_expiration); 19644 if(result != TPM_RC_SUCCESS) 19645 19646 Family 2.0 19647 Level 00 Revision 00.99 19648 19649 Published 19650 Copyright TCG 2006-2013 19651 19652 Page 237 19653 October 31, 2013 19654 19655 Part 3: Commands 19657 40 19658 41 19659 42 19660 43 19661 44 19662 45 19663 46 19664 47 19665 48 19666 49 19667 50 19668 51 19669 52 19670 53 19671 54 19672 55 19673 56 19674 57 19675 58 19676 59 19677 60 19678 61 19679 62 19680 63 19681 64 19682 65 19683 66 19684 67 19685 68 19686 69 19687 70 19688 71 19689 72 19690 73 19691 74 19692 75 19693 76 19694 77 19695 78 19696 79 19697 80 19698 81 19699 82 19700 83 19701 84 19702 85 19703 86 19704 87 19705 88 19706 89 19707 90 19708 91 19709 92 19710 93 19711 94 19712 95 19713 96 19714 97 19715 98 19716 99 19717 100 19718 101 19719 102 19720 103 19721 19722 Trusted Platform Module Library 19723 19724 return result; 19725 // Re-compute the digest being signed 19726 /*(See part 3 specification) 19727 // The digest is computed as: 19728 // 19729 aHash := hash ( nonceTPM | expiration | cpHashA | policyRef) 19730 // where: 19731 // 19732 hash() 19733 the hash associated with the signed auth 19734 // 19735 nonceTPM 19736 the nonceTPM value from the TPM2_StartAuthSession . 19737 // 19738 response If the authorization is not limited to this 19739 // 19740 session, the size of this value is zero. 19741 // 19742 expiration time limit on authorization set by authorizing object. 19743 // 19744 This 32-bit value is set to zero if the expiration 19745 // 19746 time is not being set. 19747 // 19748 cpHashA 19749 hash of the command parameters for the command being 19750 // 19751 approved using the hash algorithm of the PSAP session. 19752 // 19753 Set to NULLauth if the authorization is not limited 19754 // 19755 to a specific command. 19756 // 19757 policyRef 19758 hash of an opaque value determined by the authorizing 19759 // 19760 object. Set to the NULLdigest if no hash is present. 19761 */ 19762 // Start hash 19763 authHash.t.size = CryptStartHash(CryptGetSignHashAlg(&in->auth), 19764 &hashState); 19765 // add nonceTPM 19766 CryptUpdateDigest2B(&hashState, &in->nonceTPM.b); 19767 // add expiration 19768 CryptUpdateDigestInt(&hashState, sizeof(UINT32), (BYTE*) &in->expiration); 19769 // add cpHashA 19770 CryptUpdateDigest2B(&hashState, &in->cpHashA.b); 19771 // add policyRef 19772 CryptUpdateDigest2B(&hashState, &in->policyRef.b); 19773 // Complete digest 19774 CryptCompleteHash2B(&hashState, &authHash.b); 19775 // Validate Signature. A TPM_RC_SCHEME, TPM_RC_TYPE or TPM_RC_SIGNATURE 19776 // error may be returned at this point 19777 result = CryptVerifySignature(in->authObject, &authHash, &in->auth); 19778 if(result != TPM_RC_SUCCESS) 19779 return RcSafeAddToResult(result, RC_PolicySigned_auth); 19780 } 19781 // Internal Data Update 19782 // Need the Name of the signing entity 19783 entityName.t.size = EntityGetName(in->authObject, &entityName.t.name); 19784 // Update policy with input policyRef and name of auth key 19785 // These values are updated even if the session is a trial session 19786 PolicyContextUpdate(TPM_CC_PolicySigned, &entityName, &in->policyRef, 19787 &in->cpHashA, authTimeout, session); 19788 // Command Output 19789 // Create ticket and timeout buffer if in->expiration < 0 and this is not 19790 // a trial session. 19791 // NOTE: PolicyParameterChecks() makes sure that nonceTPM is present 19792 // when expiration is non-zero. 19793 if( 19794 in->expiration < 0 19795 && session->attributes.isTrialPolicy == CLEAR 19796 ) 19797 19798 Page 238 19799 October 31, 2013 19800 19801 Published 19802 Copyright TCG 2006-2013 19803 19804 Family 2.0 19805 Level 00 Revision 00.99 19806 19807 Trusted Platform Module Library 19809 104 19810 105 19811 106 19812 107 19813 108 19814 109 19815 110 19816 111 19817 112 19818 113 19819 114 19820 115 19821 116 19822 117 19823 118 19824 119 19825 120 19826 121 19827 122 19828 123 19829 124 19830 125 19831 126 19832 127 19833 128 19834 129 19835 130 19836 131 19837 132 19838 19839 Part 3: Commands 19840 19841 { 19842 // Generate timeout buffer. The format of output timeout buffer is 19843 // TPM-specific. 19844 // Note: can't do a direct copy because the output buffer is a byte 19845 // array and it may not be aligned to accept a 64-bit value. The method 19846 // used has the side-effect of making the returned value a big-endian, 19847 // 64-bit value that is byte aligned. 19848 out->timeout.t.size = sizeof(UINT64); 19849 UINT64_TO_BYTE_ARRAY(authTimeout, out->timeout.t.buffer); 19850 // Compute policy ticket 19851 TicketComputeAuth(TPM_ST_AUTH_SIGNED, EntityGetHierarchy(in->authObject), 19852 authTimeout, &in->cpHashA, &in->policyRef, &entityName, 19853 &out->policyTicket); 19854 } 19855 else 19856 { 19857 // Generate a null ticket. 19858 // timeout buffer is null 19859 out->timeout.t.size = 0; 19860 // auth ticket is null 19861 out->policyTicket.tag = TPM_ST_AUTH_SIGNED; 19862 out->policyTicket.hierarchy = TPM_RH_NULL; 19863 out->policyTicket.digest.t.size = 0; 19864 } 19865 return TPM_RC_SUCCESS; 19866 } 19867 19868 Family 2.0 19869 Level 00 Revision 00.99 19870 19871 Published 19872 Copyright TCG 2006-2013 19873 19874 Page 239 19875 October 31, 2013 19876 19877 Part 3: Commands 19879 19880 25.4 19881 19882 Trusted Platform Module Library 19883 19884 TPM2_PolicySecret 19885 19886 25.4.1 General Description 19887 This command includes a secret-based authorization to a policy. The caller proves knowledge of the 19888 secret value using an authorization session using the authValue associated with authHandle. A 19889 password session, an HMAC session, or a policy session containing TPM2_PolicyAuthValue() or 19890 TPM2_PolicyPassword() will satisfy this requirement. 19891 If a policy session is used and use of the authValue of authHandle is not required, the TPM will return 19892 TPM_RC_MODE. 19893 The secret is the authValue of authObject, which may be any TPM entity with a handle and an associated 19894 authValue. This includes the reserved handles (for example, Platform, Storage, and Endorsement), NV 19895 Indexes, and loaded objects. 19896 NOTE 1 19897 19898 The authorization value for a hierarchy cannot be used in th is command if the hierarchy is disabled. 19899 19900 If the authorization check fails, then the normal dictionary attack logic is invoked. 19901 If the authorization provided by the authorization session is valid, the command parameters are checked 19902 as described in 25.2.2. 19903 When all validations have succeeded, policySessionpolicyDigest is updated by PolicyUpdate() (see 19904 25.2.3). 19905 19906 PolicyUpdate(TPM_CC_PolicySecret, authObjectName, policyRef) 19907 19908 (15) 19909 19910 If the cpHashA command parameter is not an Empty Buffer, it is copied to cpHash in the session context. 19911 The TPM will optionally produce a ticket as described in 25.2.5. 19912 If the session is a trial session, policySessionpolicyDigest is updated as if the authorization is valid but 19913 no check is performed. 19914 NOTE 2 19915 19916 If an HMAC is used to convey the authorization, a separate session is needed for the authorization. 19917 Because the HMAC in that authorization will include a nonce that prevents replay of the 19918 authorization, the value of the nonceTPM parameter in this command is limited. It is retained mostly 19919 to provide processing consistency with TPM2_PolicySigned(). 19920 19921 Page 240 19922 October 31, 2013 19923 19924 Published 19925 Copyright TCG 2006-2013 19926 19927 Family 2.0 19928 Level 00 Revision 00.99 19929 19930 Trusted Platform Module Library 19932 19933 Part 3: Commands 19934 19935 25.4.2 Command and Response 19936 Table 115 TPM2_PolicySecret Command 19937 Type 19938 19939 Name 19940 19941 Description 19942 19943 TPMI_ST_COMMAND_TAG 19944 19945 tag 19946 19947 see clause 8 19948 19949 UINT32 19950 19951 commandSize 19952 19953 TPM_CC 19954 19955 commandCode 19956 19957 TPM_CC_PolicySecret 19958 19959 TPMI_DH_ENTITY 19960 19961 @authHandle 19962 19963 handle for an entity providing the authorization 19964 Auth Index: 1 19965 Auth Role: USER 19966 19967 TPMI_SH_POLICY 19968 19969 policySession 19970 19971 handle for the policy session being extended 19972 Auth Index: None 19973 19974 TPM2B_NONCE 19975 19976 nonceTPM 19977 19978 the policy nonce for the session 19979 If the nonce is not included in the authorization 19980 qualification, this field is the Empty Buffer. 19981 19982 TPM2B_DIGEST 19983 19984 cpHashA 19985 19986 digest of the command parameters to which this 19987 authorization is limited 19988 This not the cpHash for this command but the cpHash 19989 for the command to which this policy session will be 19990 applied. If it is not limited, the parameter will be the 19991 Empty Buffer. 19992 19993 TPM2B_NONCE 19994 19995 policyRef 19996 19997 a reference to a policy relating to the authorization 19998 may be the Empty Buffer 19999 Size is limited to be no larger than the nonce size 20000 supported on the TPM. 20001 20002 INT32 20003 20004 expiration 20005 20006 time when authorization will expire, measured in 20007 seconds from the time that nonceTPM was generated 20008 If expiration is zero, a NULL Ticket is returned. 20009 20010 Table 116 TPM2_PolicySecret Response 20011 Type 20012 20013 Name 20014 20015 Description 20016 20017 TPM_ST 20018 20019 tag 20020 20021 see clause 8 20022 20023 UINT32 20024 20025 responseSize 20026 20027 TPM_RC 20028 20029 responseCode 20030 20031 TPM2B_TIMEOUT 20032 20033 timeout 20034 20035 implementation-specific time value used to indicate to 20036 the TPM when the ticket expires; this ticket will use the 20037 TPMT_ST_AUTH_SECRET structure tag 20038 20039 TPMT_TK_AUTH 20040 20041 policyTicket 20042 20043 produced if the command succeeds and expiration in 20044 the command was non-zero 20045 20046 Family 2.0 20047 Level 00 Revision 00.99 20048 20049 Published 20050 Copyright TCG 2006-2013 20051 20052 Page 241 20053 October 31, 2013 20054 20055 Part 3: Commands 20057 20058 Trusted Platform Module Library 20059 20060 25.4.3 Detailed Actions 20061 1 20062 2 20063 3 20064 20065 #include "InternalRoutines.h" 20066 #include "PolicySecret_fp.h" 20067 #include "Policy_spt_fp.h" 20068 Error Returns 20069 TPM_RC_CPHASH 20070 20071 cpHash for policy was previously set to a value that is not the same 20072 as cpHashA 20073 20074 TPM_RC_EXPIRED 20075 20076 expiration indicates a time in the past 20077 20078 TPM_RC_NONCE 20079 20080 nonceTPM does not match the nonce associated with policySession 20081 20082 TPM_RC_SIZE 20083 20084 cpHashA is not the size of a digest for the hash associated with 20085 policySession 20086 20087 TPM_RC_VALUE 20088 20089 4 20090 5 20091 6 20092 7 20093 8 20094 9 20095 10 20096 11 20097 12 20098 13 20099 14 20100 15 20101 16 20102 17 20103 18 20104 19 20105 20 20106 21 20107 22 20108 23 20109 24 20110 25 20111 26 20112 27 20113 28 20114 29 20115 30 20116 31 20117 32 20118 33 20119 34 20120 35 20121 36 20122 37 20123 38 20124 39 20125 40 20126 41 20127 42 20128 43 20129 44 20130 20131 Meaning 20132 20133 input policyID or expiration does not match the internal data in policy 20134 session 20135 20136 TPM_RC 20137 TPM2_PolicySecret( 20138 PolicySecret_In 20139 PolicySecret_Out 20140 20141 *in, 20142 *out 20143 20144 // IN: input parameter list 20145 // OUT: output parameter list 20146 20147 TPM_RC 20148 SESSION 20149 TPM2B_NAME 20150 UINT32 20151 20152 result; 20153 *session; 20154 entityName; 20155 expiration = (in->expiration < 0) 20156 ? -(in->expiration) : in->expiration; 20157 authTimeout = 0; 20158 20159 ) 20160 { 20161 20162 UINT64 20163 // Input Validation 20164 20165 // Get pointer to the session structure 20166 session = SessionGet(in->policySession); 20167 //Only do input validation if this is not a trial policy session 20168 if(session->attributes.isTrialPolicy == CLEAR) 20169 { 20170 if(expiration != 0) 20171 authTimeout = expiration * 1000 + session->startTime; 20172 result = PolicyParameterChecks(session, authTimeout, 20173 &in->cpHashA, &in->nonceTPM, 20174 RC_PolicySecret_nonceTPM, 20175 RC_PolicySecret_cpHashA, 20176 RC_PolicySecret_expiration); 20177 if(result != TPM_RC_SUCCESS) 20178 return result; 20179 } 20180 // Internal Data Update 20181 // Need the name of the authorizing entity 20182 entityName.t.size = EntityGetName(in->authHandle, &entityName.t.name); 20183 // Update policy context with input policyRef and name of auth key 20184 // This value is computed even for trial sessions. Possibly update the cpHash 20185 PolicyContextUpdate(TPM_CC_PolicySecret, &entityName, &in->policyRef, 20186 20187 Page 242 20188 October 31, 2013 20189 20190 Published 20191 Copyright TCG 2006-2013 20192 20193 Family 2.0 20194 Level 00 Revision 00.99 20195 20196 Trusted Platform Module Library 20198 45 20199 46 20200 47 20201 48 20202 49 20203 50 20204 51 20205 52 20206 53 20207 54 20208 55 20209 56 20210 57 20211 58 20212 59 20213 60 20214 61 20215 62 20216 63 20217 64 20218 65 20219 66 20220 67 20221 68 20222 69 20223 70 20224 71 20225 72 20226 73 20227 74 20228 75 20229 76 20230 77 20231 78 20232 79 20233 80 20234 81 20235 82 20236 83 20237 20238 Part 3: Commands 20239 20240 &in->cpHashA, authTimeout, session); 20241 // Command Output 20242 // Create ticket and timeout buffer if in->expiration < 0 and this is not 20243 // a trial session. 20244 // NOTE: PolicyParameterChecks() makes sure that nonceTPM is present 20245 // when expiration is non-zero. 20246 if( 20247 in->expiration < 0 20248 && session->attributes.isTrialPolicy == CLEAR 20249 ) 20250 { 20251 // Generate timeout buffer. The format of output timeout buffer is 20252 // TPM-specific. 20253 // Note: can't do a direct copy because the output buffer is a byte 20254 // array and it may not be aligned to accept a 64-bit value. The method 20255 // used has the side-effect of making the returned value a big-endian, 20256 // 64-bit value that is byte aligned. 20257 out->timeout.t.size = sizeof(UINT64); 20258 UINT64_TO_BYTE_ARRAY(authTimeout, out->timeout.t.buffer); 20259 // Compute policy ticket 20260 TicketComputeAuth(TPM_ST_AUTH_SECRET, EntityGetHierarchy(in->authHandle), 20261 authTimeout, &in->cpHashA, &in->policyRef, 20262 &entityName, &out->policyTicket); 20263 } 20264 else 20265 { 20266 // timeout buffer is null 20267 out->timeout.t.size = 0; 20268 // auth ticket is null 20269 out->policyTicket.tag = TPM_ST_AUTH_SECRET; 20270 out->policyTicket.hierarchy = TPM_RH_NULL; 20271 out->policyTicket.digest.t.size = 0; 20272 } 20273 return TPM_RC_SUCCESS; 20274 } 20275 20276 Family 2.0 20277 Level 00 Revision 00.99 20278 20279 Published 20280 Copyright TCG 2006-2013 20281 20282 Page 243 20283 October 31, 2013 20284 20285 Part 3: Commands 20287 20288 25.5 20289 20290 Trusted Platform Module Library 20291 20292 TPM2_PolicyTicket 20293 20294 25.5.1 General Description 20295 This command is similar to TPM2_PolicySigned() except that it takes a ticket instead of a signed 20296 authorization. The ticket represents a validated authorization that had an expiration time associated with 20297 it. 20298 The parameters of this command are checked as described in 25.2.2. 20299 If the checks succeed, the TPM uses the timeout, cpHashA, policyRef, and keyName to construct a ticket 20300 to compare with the value in ticket. If these tickets match, then the TPM will create a TPM2B_NAME 20301 (objectName) using authName and update the context of policySession by PolicyUpdate() (see 25.2.3). 20302 20303 PolicyUpdate(commandCode, authName, policyRef) 20304 20305 (16) 20306 20307 If the structure tag of ticket is TPM_ST_AUTH_SECRET, then commandCode will be 20308 TPM_CC_PolicySecret. If the structure tag of ticket is TPM_ST_AUTH_SIGNED, then commandCode will 20309 be TPM_CC_PolicySIgned. 20310 If the cpHashA command parameter is not an Empty Buffer, it may be copied to cpHash in the session 20311 context.as described in 25.2.1. 20312 20313 Page 244 20314 October 31, 2013 20315 20316 Published 20317 Copyright TCG 2006-2013 20318 20319 Family 2.0 20320 Level 00 Revision 00.99 20321 20322 Trusted Platform Module Library 20324 20325 Part 3: Commands 20326 20327 25.5.2 Command and Response 20328 Table 117 TPM2_PolicyTicket Command 20329 Type 20330 20331 Name 20332 20333 Description 20334 20335 TPMI_ST_COMMAND_TAG 20336 20337 tag 20338 20339 see clause 8 20340 20341 UINT32 20342 20343 commandSize 20344 20345 TPM_CC 20346 20347 commandCode 20348 20349 TPM_CC_PolicyTicket 20350 20351 TPMI_SH_POLICY 20352 20353 policySession 20354 20355 handle for the policy session being extended 20356 Auth Index: None 20357 20358 TPM2B_TIMEOUT 20359 20360 timeout 20361 20362 time when authorization will expire 20363 The contents are TPM specific. This shall be the value 20364 returned when ticket was produced. 20365 20366 TPM2B_DIGEST 20367 20368 cpHashA 20369 20370 digest of the command parameters to which this 20371 authorization is limited 20372 If it is not limited, the parameter will be the Empty 20373 Buffer. 20374 20375 TPM2B_NONCE 20376 20377 policyRef 20378 20379 reference to a qualifier for the policy may be the 20380 Empty Buffer 20381 20382 TPM2B_NAME 20383 20384 authName 20385 20386 name of the object that provided the authorization 20387 20388 TPMT_TK_AUTH 20389 20390 ticket 20391 20392 an authorization ticket returned by the TPM in response 20393 to a TPM2_PolicySigned() or TPM2_PolicySecret() 20394 20395 Table 118 TPM2_PolicyTicket Response 20396 Type 20397 20398 Name 20399 20400 Description 20401 20402 TPM_ST 20403 20404 tag 20405 20406 see clause 8 20407 20408 UINT32 20409 20410 responseSize 20411 20412 TPM_RC 20413 20414 responseCode 20415 20416 Family 2.0 20417 Level 00 Revision 00.99 20418 20419 Published 20420 Copyright TCG 2006-2013 20421 20422 Page 245 20423 October 31, 2013 20424 20425 Part 3: Commands 20427 20428 Trusted Platform Module Library 20429 20430 25.5.3 Detailed Actions 20431 1 20432 2 20433 3 20434 20435 #include "InternalRoutines.h" 20436 #include "PolicyTicket_fp.h" 20437 #include "Policy_spt_fp.h" 20438 Error Returns 20439 TPM_RC_CPHASH 20440 20441 policy's cpHash was previously set to a different value 20442 20443 TPM_RC_EXPIRED 20444 20445 timeout value in the ticket is in the past and the ticket has expired 20446 20447 TPM_RC_SIZE 20448 20449 timeout or cpHash has invalid size for the 20450 20451 TPM_RC_TICKET 20452 4 20453 5 20454 6 20455 7 20456 8 20457 9 20458 10 20459 11 20460 12 20461 13 20462 14 20463 15 20464 16 20465 17 20466 18 20467 19 20468 20 20469 21 20470 22 20471 23 20472 24 20473 25 20474 26 20475 27 20476 28 20477 29 20478 30 20479 31 20480 32 20481 33 20482 34 20483 35 20484 36 20485 37 20486 38 20487 39 20488 40 20489 41 20490 42 20491 43 20492 44 20493 45 20494 46 20495 47 20496 48 20497 49 20498 20499 Meaning 20500 20501 ticket is not valid 20502 20503 TPM_RC 20504 TPM2_PolicyTicket( 20505 PolicyTicket_In 20506 20507 *in 20508 20509 // IN: input parameter list 20510 20511 TPM_RC 20512 SESSION 20513 UINT64 20514 TPMT_TK_AUTH 20515 TPM_CC 20516 20517 result; 20518 *session; 20519 timeout; 20520 ticketToCompare; 20521 commandCode = TPM_CC_PolicySecret; 20522 20523 ) 20524 { 20525 20526 // Input Validation 20527 // Get pointer to the session structure 20528 session = SessionGet(in->policySession); 20529 // NOTE: A trial policy session is not allowed to use this command. 20530 // A ticket is used in place of a previously given authorization. Since 20531 // a trial policy doesn't actually authenticate, the validated 20532 // ticket is not necessary and, in place of using a ticket, one 20533 // should use the intended authorization for which the ticket 20534 // would be a subsitute. 20535 if(session->attributes.isTrialPolicy) 20536 return TPM_RCS_ATTRIBUTES + RC_PolicyTicket_policySession; 20537 // Restore timeout data. The format of timeout buffer is TPM-specific. 20538 // In this implementation, we simply copy the value of timeout to the 20539 // buffer. 20540 if(in->timeout.t.size != sizeof(UINT64)) 20541 return TPM_RC_SIZE + RC_PolicyTicket_timeout; 20542 timeout = BYTE_ARRAY_TO_UINT64(in->timeout.t.buffer); 20543 // Do the normal checks on the cpHashA and timeout values 20544 result = PolicyParameterChecks(session, timeout, 20545 &in->cpHashA, NULL, 20546 0, 20547 // no bad nonce return 20548 RC_PolicyTicket_cpHashA, 20549 RC_PolicyTicket_timeout); 20550 if(result != TPM_RC_SUCCESS) 20551 return result; 20552 // Validate Ticket 20553 // Re-generate policy ticket by input parameters 20554 TicketComputeAuth(in->ticket.tag, in->ticket.hierarchy, timeout, &in->cpHashA, 20555 &in->policyRef, &in->authName, &ticketToCompare); 20556 20557 Page 246 20558 October 31, 2013 20559 20560 Published 20561 Copyright TCG 2006-2013 20562 20563 Family 2.0 20564 Level 00 Revision 00.99 20565 20566 Trusted Platform Module Library 20568 50 20569 51 20570 52 20571 53 20572 54 20573 55 20574 56 20575 57 20576 58 20577 59 20578 60 20579 61 20580 62 20581 63 20582 64 20583 65 20584 66 20585 67 20586 68 20587 69 20588 70 20589 71 20590 72 20591 73 20592 20593 Part 3: Commands 20594 20595 // Compare generated digest with input ticket digest 20596 if(!Memory2BEqual(&in->ticket.digest.b, &ticketToCompare.digest.b)) 20597 return TPM_RC_TICKET + RC_PolicyTicket_ticket; 20598 // Internal Data Update 20599 // Is this ticket to take the place of a TPM2_PolicySigned() or 20600 // a TPM2_PolicySecret()? 20601 if(in->ticket.tag == TPM_ST_AUTH_SIGNED) 20602 commandCode = TPM_CC_PolicySigned; 20603 else if(in->ticket.tag == TPM_ST_AUTH_SECRET) 20604 commandCode = TPM_CC_PolicySecret; 20605 else 20606 // There could only be two possible tag values. Any other value should 20607 // be caught by the ticket validation process. 20608 pAssert(FALSE); 20609 // Update policy context 20610 PolicyContextUpdate(commandCode, &in->authName, &in->policyRef, 20611 &in->cpHashA, timeout, session); 20612 return TPM_RC_SUCCESS; 20613 } 20614 20615 Family 2.0 20616 Level 00 Revision 00.99 20617 20618 Published 20619 Copyright TCG 2006-2013 20620 20621 Page 247 20622 October 31, 2013 20623 20624 Part 3: Commands 20626 20627 25.6 20628 20629 Trusted Platform Module Library 20630 20631 TPM2_PolicyOR 20632 20633 25.6.1 General Description 20634 This command allows options in authorizations without requiring that the TPM evaluate all of the options. 20635 If a policy may be satisfied by different sets of conditions, the TPM need only evaluate one set that 20636 satisfies the policy. This command will indicate that one of the required sets of conditions has been 20637 satisfied. 20638 PolicySessionpolicyDigest is compared against the list of provided values. If the current 20639 policySessionpolicyDigest does not match any value in the list, the TPM shall return TPM_RC_VALUE. 20640 Otherwise, it will replace policySessionpolicyDigest with the digest of the concatenation of all of the 20641 digests and return TPM_RC_SUCCESS. 20642 If policySession is a trial session, the TPM will assume that policySessionpolicyDigest matches one of 20643 the list entries and compute the new value of policyDigest. 20644 The algorithm for computing the new value for policyDigest of policySession is: 20645 a) Concatenate all the digest values in pHashList: 20646 20647 digests pHashList.digests[1].buffer || || pHashList.digests[n].buffer 20648 NOTE 1 20649 20650 (17) 20651 20652 The TPM makes no check to see if the size of an entry matches the size of the digest of the 20653 policy. 20654 20655 b) Reset policyDigest to a Zero Digest. 20656 c) Extend the command code and the hashes computed in step a) above: 20657 20658 policyDigestnew HpolicyAlg(policyDigestold || TPM_CC_PolicyOR || digests) 20659 NOTE 2 20660 20661 (18) 20662 20663 The computation in b) and c) above is equivalent to: 20664 20665 policyDigestnew HpolicyAlg(00 || TPM_CC_PolicyOR || digests) 20666 20667 A TPM shall support a list with at least eight tagged digest values. 20668 NOTE 3 20669 20670 If policies are to be portable between TPMs, then they should not use more than eight values. 20671 20672 Page 248 20673 October 31, 2013 20674 20675 Published 20676 Copyright TCG 2006-2013 20677 20678 Family 2.0 20679 Level 00 Revision 00.99 20680 20681 Trusted Platform Module Library 20683 20684 Part 3: Commands 20685 20686 25.6.2 Command and Response 20687 Table 119 TPM2_PolicyOR Command 20688 Type 20689 20690 Name 20691 20692 Description 20693 20694 TPMI_ST_COMMAND_TAG 20695 20696 tag 20697 20698 UINT32 20699 20700 commandSize 20701 20702 TPM_CC 20703 20704 commandCode 20705 20706 TPM_CC_PolicyOR. 20707 20708 TPMI_SH_POLICY 20709 20710 policySession 20711 20712 handle for the policy session being extended 20713 Auth Index: None 20714 20715 TPML_DIGEST 20716 20717 pHashList 20718 20719 the list of hashes to check for a match 20720 20721 Table 120 TPM2_PolicyOR Response 20722 Type 20723 20724 Name 20725 20726 Description 20727 20728 TPM_ST 20729 20730 tag 20731 20732 see clause 8 20733 20734 UINT32 20735 20736 responseSize 20737 20738 TPM_RC 20739 20740 responseCode 20741 20742 Family 2.0 20743 Level 00 Revision 00.99 20744 20745 Published 20746 Copyright TCG 2006-2013 20747 20748 Page 249 20749 October 31, 2013 20750 20751 Part 3: Commands 20753 20754 Trusted Platform Module Library 20755 20756 25.6.3 Detailed Actions 20757 1 20758 2 20759 3 20760 20761 #include "InternalRoutines.h" 20762 #include "PolicyOR_fp.h" 20763 #include "Policy_spt_fp.h" 20764 Error Returns 20765 TPM_RC_VALUE 20766 20767 4 20768 5 20769 6 20770 7 20771 8 20772 9 20773 10 20774 11 20775 12 20776 13 20777 14 20778 15 20779 16 20780 17 20781 18 20782 19 20783 20 20784 21 20785 22 20786 23 20787 24 20788 25 20789 26 20790 27 20791 28 20792 29 20793 30 20794 31 20795 32 20796 33 20797 34 20798 35 20799 36 20800 37 20801 38 20802 39 20803 40 20804 41 20805 42 20806 43 20807 44 20808 45 20809 46 20810 47 20811 48 20812 49 20813 50 20814 51 20815 52 20816 53 20817 20818 Meaning 20819 no digest in pHashList matched the current value of policyDigest for 20820 policySession 20821 20822 TPM_RC 20823 TPM2_PolicyOR( 20824 PolicyOR_In *in 20825 20826 // IN: input parameter list 20827 20828 ) 20829 { 20830 SESSION 20831 UINT32 20832 20833 *session; 20834 i; 20835 20836 // Input Validation and Update 20837 // Get pointer to the session structure 20838 session = SessionGet(in->policySession); 20839 // Compare and Update Internal Session policy if match 20840 for(i = 0; i < in->pHashList.count; i++) 20841 { 20842 if( 20843 session->attributes.isTrialPolicy == SET 20844 || (Memory2BEqual(&session->u2.policyDigest.b, 20845 &in->pHashList.digests[i].b)) 20846 ) 20847 { 20848 // Found a match 20849 HASH_STATE 20850 hashState; 20851 TPM_CC 20852 commandCode = TPM_CC_PolicyOR; 20853 // Start hash 20854 session->u2.policyDigest.t.size = CryptStartHash(session->authHashAlg, 20855 &hashState); 20856 // Set policyDigest to 0 string and add it to hash 20857 MemorySet(session->u2.policyDigest.t.buffer, 0, 20858 session->u2.policyDigest.t.size); 20859 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 20860 // add command code 20861 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 20862 // Add each of the hashes in the list 20863 for(i = 0; i < in->pHashList.count; i++) 20864 { 20865 // Extend policyDigest 20866 CryptUpdateDigest2B(&hashState, &in->pHashList.digests[i].b); 20867 } 20868 // Complete digest 20869 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 20870 return TPM_RC_SUCCESS; 20871 } 20872 } 20873 // None of the values in the list matched the current policyDigest 20874 return TPM_RC_VALUE + RC_PolicyOR_pHashList; 20875 20876 Page 250 20877 October 31, 2013 20878 20879 Published 20880 Copyright TCG 2006-2013 20881 20882 Family 2.0 20883 Level 00 Revision 00.99 20884 20885 Trusted Platform Module Library 20887 54 20888 20889 Part 3: Commands 20890 20891 } 20892 20893 Family 2.0 20894 Level 00 Revision 00.99 20895 20896 Published 20897 Copyright TCG 2006-2013 20898 20899 Page 251 20900 October 31, 2013 20901 20902 Part 3: Commands 20904 20905 25.7 20906 20907 Trusted Platform Module Library 20908 20909 TPM2_PolicyPCR 20910 20911 25.7.1 General Description 20912 This command is used to cause conditional gating of a policy based on PCR. This allows one group of 20913 authorizations to occur when PCR are in one state and a different set of authorizations when the PCR are 20914 in a different state. If this command is used for a trial policySession, policySessionpolicyDigest will be 20915 updated using the values from the command rather than the values from digest of the TPM PCR. 20916 The TPM will modify the pcrs parameter so that bits that correspond to unimplemented PCR are CLEAR. 20917 If policySession is not a trial policy session, the TPM will use the modified value of pcrs to select PCR 20918 values to hash according to Part 1, Selecting Multiple PCR. The hash algorithm of the policy session is 20919 used to compute a digest (digestTPM) of the selected PCR. If pcrDigest does not have a length of zero, 20920 then it is compared to digestTPM; and if the values do not match, the TPM shall return TPM_RC_VALUE 20921 and make no change to policySessionpolicyDigest. If the values match, or if the length of pcrDigest is 20922 zero, then policySessionpolicyDigest is extended by: 20923 20924 policyDigestnew HpolicyAlg(policyDigestold || TPM_CC_PolicyPCR || pcrs || digestTPM) 20925 20926 (19) 20927 20928 where 20929 20930 pcrs 20931 20932 the pcrs parameter with bits corresponding to unimplemented 20933 PCR set to 0 20934 20935 digestTPM 20936 20937 the digest of the selected PCR using the hash algorithm of the 20938 policy session 20939 20940 NOTE 1 20941 20942 If the caller provides the expected PCR value, the intention is that the policy evaluation stop at that 20943 point if the PCR do not match. If the caller does not provide the expected PCR value, then the 20944 validity of the settings will not be determined until an attempt is made to use the policy for 20945 authorization. If the policy is constructed such that the PCR check comes before user authorization 20946 checks, this early termination would allow software to avoid unnecessary prompts for user input to 20947 satisfy a policy that would fail later due to incorr ect PCR values. 20948 20949 After this command completes successfully, the TPM shall return TPM_RC_PCR_CHANGED if the policy 20950 session is used for authorization and the PCR are not known to be correct. 20951 The TPM uses a generation number (pcrUpdateCounter) that is incremented each time PCR are 20952 updated (unless the PCR being changed is specified not to cause a change to this counter). The value of 20953 this counter is stored in the policy session context (policySessionpcrUpdateCounter) when this 20954 command is executed. When the policy is used for authorization, the current value of the counter is 20955 compared to the value in the policy session context and the authorization will fail if the values are not the 20956 same. 20957 When this command is executed, policySessionpcrUpdateCounter is checked to see if it has been 20958 previously set (in the reference implementation, it has a value of zero if not previously set). If it has been 20959 set, it will be compared with the current value of pcrUpdateCounter to determine if any PCR changes 20960 have occurred. If the values are different, the TPM shall return TPM_RC_PCR_CHANGED. If 20961 policySessionpcrUpdateCounter has not been set, then it is set to the current value of 20962 pcrUpdateCounter. 20963 If policySession is a trial policy session, the TPM will not check any PCR and will compute: 20964 20965 policyDigestnew HpolicyAlg(policyDigestold || TPM_CC_PolicyPCR || pcrs || pcrDigest) 20966 20967 (20) 20968 20969 In this computation, pcrs is the input parameter without modification. 20970 NOTE 2 20971 20972 The pcrs parameter is expected to match the configuration of the TPM for which the policy is being 20973 computed which may not be the same as the TPM on which the trial policy is being computed. 20974 20975 Page 252 20976 October 31, 2013 20977 20978 Published 20979 Copyright TCG 2006-2013 20980 20981 Family 2.0 20982 Level 00 Revision 00.99 20983 20984 Trusted Platform Module Library 20986 20987 Part 3: Commands 20988 20989 25.7.2 Command and Response 20990 Table 121 TPM2_PolicyPCR Command 20991 Type 20992 20993 Name 20994 20995 Description 20996 20997 TPMI_ST_COMMAND_TAG 20998 20999 tag 21000 21001 UINT32 21002 21003 commandSize 21004 21005 TPM_CC 21006 21007 commandCode 21008 21009 TPM_CC_PolicyPCR 21010 21011 TPMI_SH_POLICY 21012 21013 policySession 21014 21015 handle for the policy session being extended 21016 Auth Index: None 21017 21018 TPM2B_DIGEST 21019 21020 pcrDigest 21021 21022 expected digest value of the selected PCR using the 21023 hash algorithm of the session; may be zero length 21024 21025 TPML_PCR_SELECTION 21026 21027 pcrs 21028 21029 the PCR to include in the check digest 21030 21031 Table 122 TPM2_PolicyPCR Response 21032 Type 21033 21034 Name 21035 21036 Description 21037 21038 TPM_ST 21039 21040 tag 21041 21042 see clause 8 21043 21044 UINT32 21045 21046 responseSize 21047 21048 TPM_RC 21049 21050 responseCode 21051 21052 Family 2.0 21053 Level 00 Revision 00.99 21054 21055 Published 21056 Copyright TCG 2006-2013 21057 21058 Page 253 21059 October 31, 2013 21060 21061 Part 3: Commands 21063 21064 Trusted Platform Module Library 21065 21066 25.7.3 Detailed Actions 21067 1 21068 2 21069 21070 #include "InternalRoutines.h" 21071 #include "PolicyPCR_fp.h" 21072 Error Returns 21073 TPM_RC_VALUE 21074 21075 if provided, pcrDigest does not match the current PCR settings 21076 21077 TPM_RC_PCR_CHANGED 21078 3 21079 4 21080 5 21081 6 21082 7 21083 8 21084 9 21085 10 21086 11 21087 12 21088 13 21089 14 21090 15 21091 16 21092 17 21093 18 21094 19 21095 20 21096 21 21097 22 21098 23 21099 24 21100 25 21101 26 21102 27 21103 28 21104 29 21105 30 21106 31 21107 32 21108 33 21109 34 21110 35 21111 36 21112 37 21113 38 21114 39 21115 40 21116 41 21117 42 21118 43 21119 44 21120 45 21121 46 21122 47 21123 48 21124 49 21125 50 21126 51 21127 52 21128 53 21129 21130 Meaning 21131 21132 a previous TPM2_PolicyPCR() set pcrCounter and it has changed 21133 21134 TPM_RC 21135 TPM2_PolicyPCR( 21136 PolicyPCR_In 21137 21138 *in 21139 21140 // IN: input parameter list 21141 21142 SESSION 21143 TPM2B_DIGEST 21144 BYTE 21145 UINT32 21146 BYTE 21147 TPM_CC 21148 HASH_STATE 21149 21150 *session; 21151 pcrDigest; 21152 pcrs[sizeof(TPML_PCR_SELECTION)]; 21153 pcrSize; 21154 *buffer; 21155 commandCode = TPM_CC_PolicyPCR; 21156 hashState; 21157 21158 ) 21159 { 21160 21161 // Input Validation 21162 // Get pointer to the session structure 21163 session = SessionGet(in->policySession); 21164 // Do validation for non trial session 21165 if(session->attributes.isTrialPolicy == CLEAR) 21166 { 21167 // Make sure that this is not going to invalidate a previous PCR check 21168 if(session->pcrCounter != 0 && session->pcrCounter != gr.pcrCounter) 21169 return TPM_RC_PCR_CHANGED; 21170 // Compute current PCR digest 21171 PCRComputeCurrentDigest(session->authHashAlg, &in->pcrs, &pcrDigest); 21172 // If the caller specified the PCR digest and it does not 21173 // match the current PCR settings, return an error.. 21174 if(in->pcrDigest.t.size != 0) 21175 { 21176 if(!Memory2BEqual(&in->pcrDigest.b, &pcrDigest.b)) 21177 return TPM_RC_VALUE + RC_PolicyPCR_pcrDigest; 21178 } 21179 } 21180 else 21181 { 21182 // For trial session, just use the input PCR digest 21183 pcrDigest = in->pcrDigest; 21184 } 21185 // Internal Data Update 21186 // Update policy hash 21187 // policyDigestnew = hash( 21188 policyDigestold || TPM_CC_PolicyPCR 21189 // 21190 || pcrs || pcrDigest) 21191 // Start hash 21192 CryptStartHash(session->authHashAlg, &hashState); 21193 // add old digest 21194 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 21195 21196 Page 254 21197 October 31, 2013 21198 21199 Published 21200 Copyright TCG 2006-2013 21201 21202 Family 2.0 21203 Level 00 Revision 00.99 21204 21205 Trusted Platform Module Library 21207 54 21208 55 21209 56 21210 57 21211 58 21212 59 21213 60 21214 61 21215 62 21216 63 21217 64 21218 65 21219 66 21220 67 21221 68 21222 69 21223 70 21224 71 21225 72 21226 73 21227 74 21228 75 21229 76 21230 21231 Part 3: Commands 21232 21233 // add commandCode 21234 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 21235 // add PCRS 21236 buffer = pcrs; 21237 pcrSize = TPML_PCR_SELECTION_Marshal(&in->pcrs, &buffer, NULL); 21238 CryptUpdateDigest(&hashState, pcrSize, pcrs); 21239 // add PCR digest 21240 CryptUpdateDigest2B(&hashState, &pcrDigest.b); 21241 // complete the hash and get the results 21242 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 21243 // update pcrCounter in session context for non trial session 21244 if(session->attributes.isTrialPolicy == CLEAR) 21245 { 21246 session->pcrCounter = gr.pcrCounter; 21247 } 21248 return TPM_RC_SUCCESS; 21249 } 21250 21251 Family 2.0 21252 Level 00 Revision 00.99 21253 21254 Published 21255 Copyright TCG 2006-2013 21256 21257 Page 255 21258 October 31, 2013 21259 21260 Part 3: Commands 21262 21263 25.8 21264 21265 Trusted Platform Module Library 21266 21267 TPM2_PolicyLocality 21268 21269 25.8.1 General Description 21270 This command indicates that the authorization will be limited to a specific locality. 21271 policySessioncommandLocality is a parameter kept in the session context. It is initialized when the 21272 policy session is started to allow the policy to apply to any locality. 21273 If locality has a value greater than 31, then an extended locality is indicated. For an extended locality, the 21274 TPM will validate that policySessioncommandLocality is has not previously been set or that the current 21275 value of policySessioncommandLocality is the same as locality (TPM_RC_RANGE). 21276 When locality is not an extended locality, the TPM will validate that the policySessioncommandLocality 21277 is not set or is not set to an extended locality value (TPM_RC_RANGE). If not the TPM will disable any 21278 locality not SET in the locality parameter. If the result of disabling localities results in no locality being 21279 enabled, the TPM will return TPM_RC_RANGE. 21280 If no error occurred in the validation of locality, policySessionpolicyDigest is extended with 21281 21282 policyDigestnew HpolicyAlg(policyDigestold || TPM_CC_PolicyLocality || locality) 21283 21284 (21) 21285 21286 Then policySessioncommandLocality is updated to indicate which localities are still allowed after 21287 execution of TPM2_PolicyLocality(). 21288 When the policy session is used to authorize a command, the authorization will fail if the locality used for 21289 the command is not one of the enabled localities in policySessioncommandLocality. 21290 21291 Page 256 21292 October 31, 2013 21293 21294 Published 21295 Copyright TCG 2006-2013 21296 21297 Family 2.0 21298 Level 00 Revision 00.99 21299 21300 Trusted Platform Module Library 21302 21303 Part 3: Commands 21304 21305 25.8.2 Command and Response 21306 Table 123 TPM2_PolicyLocality Command 21307 Type 21308 21309 Name 21310 21311 Description 21312 21313 TPMI_ST_COMMAND_TAG 21314 21315 tag 21316 21317 UINT32 21318 21319 commandSize 21320 21321 TPM_CC 21322 21323 commandCode 21324 21325 TPM_CC_PolicyLocality 21326 21327 TPMI_SH_POLICY 21328 21329 policySession 21330 21331 handle for the policy session being extended 21332 Auth Index: None 21333 21334 TPMA_LOCALITY 21335 21336 locality 21337 21338 the allowed localities for the policy 21339 21340 Table 124 TPM2_PolicyLocality Response 21341 Type 21342 21343 Name 21344 21345 Description 21346 21347 TPM_ST 21348 21349 tag 21350 21351 see clause 8 21352 21353 UINT32 21354 21355 responseSize 21356 21357 TPM_RC 21358 21359 responseCode 21360 21361 Family 2.0 21362 Level 00 Revision 00.99 21363 21364 Published 21365 Copyright TCG 2006-2013 21366 21367 Page 257 21368 October 31, 2013 21369 21370 Part 3: Commands 21372 21373 Trusted Platform Module Library 21374 21375 25.8.3 Detailed Actions 21376 1 21377 2 21378 21379 #include "InternalRoutines.h" 21380 #include "PolicyLocality_fp.h" 21381 21382 Limit a policy to a specific locality 21383 Error Returns 21384 TPM_RC_RANGE 21385 21386 3 21387 4 21388 5 21389 6 21390 7 21391 8 21392 9 21393 10 21394 11 21395 12 21396 13 21397 14 21398 15 21399 16 21400 17 21401 18 21402 19 21403 20 21404 21 21405 22 21406 23 21407 24 21408 25 21409 26 21410 27 21411 28 21412 29 21413 30 21414 31 21415 32 21416 33 21417 34 21418 35 21419 36 21420 37 21421 38 21422 39 21423 40 21424 41 21425 42 21426 43 21427 44 21428 45 21429 46 21430 47 21431 48 21432 49 21433 50 21434 51 21435 52 21436 21437 Meaning 21438 all the locality values selected by locality have been disabled by 21439 previous TPM2_PolicyLocality() calls. 21440 21441 TPM_RC 21442 TPM2_PolicyLocality( 21443 PolicyLocality_In 21444 21445 *in 21446 21447 // IN: input parameter list 21448 21449 ) 21450 { 21451 SESSION 21452 BYTE 21453 BYTE 21454 UINT32 21455 BYTE 21456 TPM_CC 21457 HASH_STATE 21458 21459 *session; 21460 marshalBuffer[sizeof(TPMA_LOCALITY)]; 21461 prevSetting[sizeof(TPMA_LOCALITY)]; 21462 marshalSize; 21463 *buffer; 21464 commandCode = TPM_CC_PolicyLocality; 21465 hashState; 21466 21467 // Input Validation 21468 // Get pointer to the session structure 21469 session = SessionGet(in->policySession); 21470 // Get new locality setting in canonical form 21471 buffer = marshalBuffer; 21472 marshalSize = TPMA_LOCALITY_Marshal(&in->locality, &buffer, NULL); 21473 // Its an error if the locality parameter is zero 21474 if(marshalBuffer[0] == 0) 21475 return TPM_RC_RANGE + RC_PolicyLocality_locality; 21476 // Get existing locality setting in canonical form 21477 buffer = prevSetting; 21478 TPMA_LOCALITY_Marshal(&session->commandLocality, &buffer, NULL); 21479 // If the locality has been previously set, then it needs to be the same 21480 // tye as the input locality (i.e. both extended or both normal 21481 if(prevSetting[0] != 0 && ((prevSetting[0] <= 0) != (marshalBuffer[0] <= 0))) 21482 return TPM_RC_RANGE + RC_PolicyLocality_locality; 21483 // See if the input is a regular or extended locality 21484 if(marshalBuffer[0] < 32) 21485 { 21486 // For regular locality 21487 // The previous setting must not be an extended locality 21488 if(prevSetting[0] > 31) 21489 return TPM_RC_RANGE + RC_PolicyLocality_locality; 21490 // if there was no previous setting, start with all normal localities 21491 // enabled 21492 if(prevSetting[0] == 0) 21493 prevSetting[0] = 0x1F; 21494 // AND the new setting with the previous setting and store it in prevSetting 21495 21496 Page 258 21497 October 31, 2013 21498 21499 Published 21500 Copyright TCG 2006-2013 21501 21502 Family 2.0 21503 Level 00 Revision 00.99 21504 21505 Trusted Platform Module Library 21507 53 21508 54 21509 55 21510 56 21511 57 21512 58 21513 59 21514 60 21515 61 21516 62 21517 63 21518 64 21519 65 21520 66 21521 67 21522 68 21523 69 21524 70 21525 71 21526 72 21527 73 21528 74 21529 75 21530 76 21531 77 21532 78 21533 79 21534 80 21535 81 21536 82 21537 83 21538 84 21539 85 21540 86 21541 87 21542 88 21543 89 21544 90 21545 91 21546 92 21547 93 21548 94 21549 95 21550 96 21551 97 21552 21553 Part 3: Commands 21554 21555 prevSetting[0] &= marshalBuffer[0]; 21556 // The result setting can not be 0 21557 if(prevSetting[0] == 0) 21558 return TPM_RC_RANGE + RC_PolicyLocality_locality; 21559 } 21560 else 21561 { 21562 // for extended locality 21563 // if the locality has already been set, then it must match the 21564 if(prevSetting[0] != 0 && prevSetting[0] != marshalBuffer[0]) 21565 return TPM_RC_RANGE + RC_PolicyLocality_locality; 21566 // Setting is OK 21567 prevSetting[0] = marshalBuffer[0]; 21568 } 21569 // Internal Data Update 21570 // Update policy hash 21571 // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyLocality || locality) 21572 // Start hash 21573 CryptStartHash(session->authHashAlg, &hashState); 21574 // add old digest 21575 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 21576 // add commandCode 21577 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 21578 // add input locality 21579 CryptUpdateDigest(&hashState, marshalSize, marshalBuffer); 21580 // complete the digest 21581 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 21582 // update session locality by unmarshal function. The function must succeed 21583 // because both input and existing locality setting have been validated. 21584 buffer = prevSetting; 21585 TPMA_LOCALITY_Unmarshal(&session->commandLocality, &buffer, 21586 (INT32 *) &marshalSize); 21587 return TPM_RC_SUCCESS; 21588 } 21589 21590 Family 2.0 21591 Level 00 Revision 00.99 21592 21593 Published 21594 Copyright TCG 2006-2013 21595 21596 Page 259 21597 October 31, 2013 21598 21599 Part 3: Commands 21601 21602 25.9 21603 21604 Trusted Platform Module Library 21605 21606 TPM2_PolicyNV 21607 21608 25.9.1 General Description 21609 This command is used to cause conditional gating of a policy based on the contents of an NV Index. 21610 If policySession is a trial policy session, the TPM will update policySessionpolicyDigest as shown in 21611 equations (22) and (23) below and return TPM_RC_SUCCESS. It will not perform any validation. The 21612 remainder of this general description would apply only if policySession is not a trial policy session. 21613 An authorization session providing authorization to read the NV Index shall be provided. 21614 NOTE 1 21615 21616 If read access is controlled by policy, the policy should include a branch that authorizes a 21617 TPM2_PolicyNV(). 21618 21619 If TPMA_NV_WRITTEN is not SET in the NV Index, the TPM shall return TPM_RC_NV_UNINITIALIZED. 21620 The TPM will validate that the size of operandB plus offset is not greater than the size of the NV Index. If 21621 it is, the TPM shall return TPM_RC_SIZE. 21622 The TPM will perform the indicated arithmetic check on the indicated portion of the selected NV Index. If 21623 the check fails, the TPM shall return TPM_RC_POLICY and not change policySessionpolicyDigest. If 21624 the check succeeds, the TPM will hash the arguments: 21625 21626 args HpolicyAlg(operand.buffer || offset || operation) 21627 21628 (22) 21629 21630 where 21631 21632 HpolicyAlg() 21633 21634 hash function using the algorithm of the policy session 21635 21636 operandB 21637 21638 the value used for the comparison 21639 21640 offset 21641 21642 offset from the start of the NV Index data to start the comparison 21643 21644 operation 21645 21646 the operation parameter indicating the comparison being 21647 performed 21648 21649 The value of args and the Name of the NV Index are extended to policySessionpolicyDigest by 21650 21651 policyDigestnew HpolicyAlg(policyDigestold || TPM_CC_PolicyNV || args || nvIndexName) 21652 21653 (23) 21654 21655 where 21656 21657 HpolicyAlg() 21658 21659 hash function using the algorithm of the policy session 21660 21661 args 21662 21663 value computed in equation (22) 21664 21665 nvIndexName 21666 21667 the Name of the NV Index 21668 21669 The signed arithmetic operations are performed using twos-compliment. 21670 Magnitude comparisons assume that the octet at offset zero in the referenced NV location and in 21671 operandB contain the most significant octet of the data. 21672 NOTE 2 21673 21674 When an Index is written, it has a different authorization name than an Index that has not been 21675 written. It is possible to use this change in the NV Index to create a write-once Index. 21676 21677 Page 260 21678 October 31, 2013 21679 21680 Published 21681 Copyright TCG 2006-2013 21682 21683 Family 2.0 21684 Level 00 Revision 00.99 21685 21686 Trusted Platform Module Library 21688 21689 Part 3: Commands 21690 21691 25.9.2 Command and Response 21692 Table 125 TPM2_PolicyNV Command 21693 Type 21694 21695 Name 21696 21697 Description 21698 21699 TPMI_ST_COMMAND_TAG 21700 21701 tag 21702 21703 UINT32 21704 21705 commandSize 21706 21707 TPM_CC 21708 21709 commandCode 21710 21711 TPM_CC_PolicyNV 21712 21713 TPMI_RH_NV_AUTH 21714 21715 @authHandle 21716 21717 handle indicating the source of the authorization value 21718 Auth Index: 1 21719 Auth Role: USER 21720 21721 TPMI_RH_NV_INDEX 21722 21723 nvIndex 21724 21725 the NV Index of the area to read 21726 Auth Index: None 21727 21728 TPMI_SH_POLICY 21729 21730 policySession 21731 21732 handle for the policy session being extended 21733 Auth Index: None 21734 21735 TPM2B_OPERAND 21736 21737 operandB 21738 21739 the second operand 21740 21741 UINT16 21742 21743 offset 21744 21745 the offset in the NV Index for the start of operand A 21746 21747 TPM_EO 21748 21749 operation 21750 21751 the comparison to make 21752 21753 Table 126 TPM2_PolicyNV Response 21754 Type 21755 21756 Name 21757 21758 Description 21759 21760 TPM_ST 21761 21762 tag 21763 21764 see clause 8 21765 21766 UINT32 21767 21768 responseSize 21769 21770 TPM_RC 21771 21772 responseCode 21773 21774 Family 2.0 21775 Level 00 Revision 00.99 21776 21777 Published 21778 Copyright TCG 2006-2013 21779 21780 Page 261 21781 October 31, 2013 21782 21783 Part 3: Commands 21785 21786 Trusted Platform Module Library 21787 21788 25.9.3 Detailed Actions 21789 1 21790 2 21791 3 21792 4 21793 21794 #include 21795 #include 21796 #include 21797 #include 21798 21799 "InternalRoutines.h" 21800 "PolicyNV_fp.h" 21801 "Policy_spt_fp.h" 21802 "NV_spt_fp.h" 21803 21804 // Include NV support routine for read access check 21805 21806 Error Returns 21807 TPM_RC_AUTH_TYPE 21808 21809 NV index authorization type is not correct 21810 21811 TPM_RC_NV_LOCKED 21812 21813 NV index read locked 21814 21815 TPM_RC_NV_UNINITIALIZED 21816 21817 the NV index has not been initialized 21818 21819 TPM_RC_POLICY 21820 21821 the comparison to the NV contents failed 21822 21823 TPM_RC_SIZE 21824 21825 5 21826 6 21827 7 21828 8 21829 9 21830 10 21831 11 21832 12 21833 13 21834 14 21835 15 21836 16 21837 17 21838 18 21839 19 21840 20 21841 21 21842 22 21843 23 21844 24 21845 25 21846 26 21847 27 21848 28 21849 29 21850 30 21851 31 21852 32 21853 33 21854 34 21855 35 21856 36 21857 37 21858 38 21859 39 21860 40 21861 41 21862 42 21863 43 21864 44 21865 45 21866 46 21867 21868 Meaning 21869 21870 the size of nvIndex data starting at offset is less than the size of 21871 operandB 21872 21873 TPM_RC 21874 TPM2_PolicyNV( 21875 PolicyNV_In 21876 21877 *in 21878 21879 // IN: input parameter list 21880 21881 TPM_RC 21882 SESSION 21883 NV_INDEX 21884 BYTE 21885 TPM2B_NAME 21886 TPM_CC 21887 HASH_STATE 21888 TPM2B_DIGEST 21889 21890 result; 21891 *session; 21892 nvIndex; 21893 nvBuffer[sizeof(in->operandB.t.buffer)]; 21894 nvName; 21895 commandCode = TPM_CC_PolicyNV; 21896 hashState; 21897 argHash; 21898 21899 ) 21900 { 21901 21902 // Input Validation 21903 // Get NV index information 21904 NvGetIndexInfo(in->nvIndex, &nvIndex); 21905 // Get pointer to the session structure 21906 session = SessionGet(in->policySession); 21907 //If this is a trial policy, skip all validations and the operation 21908 if(session->attributes.isTrialPolicy == CLEAR) 21909 { 21910 // NV Read access check. NV index should be allowed for read. A 21911 // TPM_RC_AUTH_TYPE or TPM_RC_NV_LOCKED error may be return at this 21912 // point 21913 result = NvReadAccessChecks(in->authHandle, in->nvIndex); 21914 if(result != TPM_RC_SUCCESS) return result; 21915 // Valid NV data size should not be smaller than input operandB size 21916 if((nvIndex.publicArea.dataSize - in->offset) < in->operandB.t.size) 21917 return TPM_RC_SIZE + RC_PolicyNV_operandB; 21918 // Arithmetic Comparison 21919 // Get NV data. The size of NV data equals the input operand B size 21920 NvGetIndexData(in->nvIndex, &nvIndex, in->offset, 21921 in->operandB.t.size, nvBuffer); 21922 switch(in->operation) 21923 21924 Page 262 21925 October 31, 2013 21926 21927 Published 21928 Copyright TCG 2006-2013 21929 21930 Family 2.0 21931 Level 00 Revision 00.99 21932 21933 Trusted Platform Module Library 21935 47 21936 48 21937 49 21938 50 21939 51 21940 52 21941 53 21942 54 21943 55 21944 56 21945 57 21946 58 21947 59 21948 60 21949 61 21950 62 21951 63 21952 64 21953 65 21954 66 21955 67 21956 68 21957 69 21958 70 21959 71 21960 72 21961 73 21962 74 21963 75 21964 76 21965 77 21966 78 21967 79 21968 80 21969 81 21970 82 21971 83 21972 84 21973 85 21974 86 21975 87 21976 88 21977 89 21978 90 21979 91 21980 92 21981 93 21982 94 21983 95 21984 96 21985 97 21986 98 21987 99 21988 100 21989 101 21990 102 21991 103 21992 104 21993 105 21994 106 21995 107 21996 108 21997 109 21998 110 21999 22000 Part 3: Commands 22001 22002 { 22003 case TPM_EO_EQ: 22004 // compare A = B 22005 if(CryptCompare(in->operandB.t.size, nvBuffer, 22006 in->operandB.t.size, in->operandB.t.buffer) 22007 return TPM_RC_POLICY; 22008 break; 22009 case TPM_EO_NEQ: 22010 // compare A != B 22011 if(CryptCompare(in->operandB.t.size, nvBuffer, 22012 in->operandB.t.size, in->operandB.t.buffer) 22013 return TPM_RC_POLICY; 22014 break; 22015 case TPM_EO_SIGNED_GT: 22016 // compare A > B signed 22017 if(CryptCompareSigned(in->operandB.t.size, nvBuffer, 22018 in->operandB.t.size, in->operandB.t.buffer) 22019 return TPM_RC_POLICY; 22020 break; 22021 case TPM_EO_UNSIGNED_GT: 22022 // compare A > B unsigned 22023 if(CryptCompare(in->operandB.t.size, nvBuffer, 22024 in->operandB.t.size, in->operandB.t.buffer) 22025 return TPM_RC_POLICY; 22026 break; 22027 case TPM_EO_SIGNED_LT: 22028 // compare A < B signed 22029 if(CryptCompareSigned(in->operandB.t.size, nvBuffer, 22030 in->operandB.t.size, in->operandB.t.buffer) 22031 return TPM_RC_POLICY; 22032 break; 22033 case TPM_EO_UNSIGNED_LT: 22034 // compare A < B unsigned 22035 if(CryptCompare(in->operandB.t.size, nvBuffer, 22036 in->operandB.t.size, in->operandB.t.buffer) 22037 return TPM_RC_POLICY; 22038 break; 22039 case TPM_EO_SIGNED_GE: 22040 // compare A >= B signed 22041 if(CryptCompareSigned(in->operandB.t.size, nvBuffer, 22042 in->operandB.t.size, in->operandB.t.buffer) 22043 return TPM_RC_POLICY; 22044 break; 22045 case TPM_EO_UNSIGNED_GE: 22046 // compare A >= B unsigned 22047 if(CryptCompare(in->operandB.t.size, nvBuffer, 22048 in->operandB.t.size, in->operandB.t.buffer) 22049 return TPM_RC_POLICY; 22050 break; 22051 case TPM_EO_SIGNED_LE: 22052 // compare A <= B signed 22053 if(CryptCompareSigned(in->operandB.t.size, nvBuffer, 22054 in->operandB.t.size, in->operandB.t.buffer) 22055 return TPM_RC_POLICY; 22056 break; 22057 case TPM_EO_UNSIGNED_LE: 22058 // compare A <= B unsigned 22059 if(CryptCompare(in->operandB.t.size, nvBuffer, 22060 in->operandB.t.size, in->operandB.t.buffer) 22061 return TPM_RC_POLICY; 22062 break; 22063 case TPM_EO_BITSET: 22064 // All bits SET in B are SET in A. ((A&B)=B) 22065 { 22066 22067 Family 2.0 22068 Level 00 Revision 00.99 22069 22070 Published 22071 Copyright TCG 2006-2013 22072 22073 != 0) 22074 22075 == 0) 22076 22077 <= 0) 22078 22079 <= 0) 22080 22081 >= 0) 22082 22083 >= 0) 22084 22085 < 0) 22086 22087 < 0) 22088 22089 > 0) 22090 22091 > 0) 22092 22093 Page 263 22094 October 31, 2013 22095 22096 Part 3: Commands 22098 111 22099 112 22100 113 22101 114 22102 115 22103 116 22104 117 22105 118 22106 119 22107 120 22108 121 22109 122 22110 123 22111 124 22112 125 22113 126 22114 127 22115 128 22116 129 22117 130 22118 131 22119 132 22120 133 22121 134 22122 135 22123 136 22124 137 22125 138 22126 139 22127 140 22128 141 22129 142 22130 143 22131 144 22132 145 22133 146 22134 147 22135 148 22136 149 22137 150 22138 151 22139 152 22140 153 22141 154 22142 155 22143 156 22144 157 22145 158 22146 159 22147 160 22148 161 22149 162 22150 163 22151 164 22152 165 22153 166 22154 167 22155 168 22156 169 22157 170 22158 171 22159 22160 Trusted Platform Module Library 22161 22162 UINT32 i; 22163 for (i = 0; i < in->operandB.t.size; i++) 22164 if((nvBuffer[i] & in->operandB.t.buffer[i]) 22165 != in->operandB.t.buffer[i]) 22166 return TPM_RC_POLICY; 22167 } 22168 break; 22169 case TPM_EO_BITCLEAR: 22170 // All bits SET in B are CLEAR in A. ((A&B)=0) 22171 { 22172 UINT32 i; 22173 for (i = 0; i < in->operandB.t.size; i++) 22174 if((nvBuffer[i] & in->operandB.t.buffer[i]) != 0) 22175 return TPM_RC_POLICY; 22176 } 22177 break; 22178 default: 22179 pAssert(FALSE); 22180 break; 22181 } 22182 } 22183 // Internal Data Update 22184 // Start argument hash 22185 argHash.t.size = CryptStartHash(session->authHashAlg, &hashState); 22186 // add operandB 22187 CryptUpdateDigest2B(&hashState, &in->operandB.b); 22188 // add offset 22189 CryptUpdateDigestInt(&hashState, sizeof(UINT16), &in->offset); 22190 // add operation 22191 CryptUpdateDigestInt(&hashState, sizeof(TPM_EO), &in->operation); 22192 // complete argument digest 22193 CryptCompleteHash2B(&hashState, &argHash.b); 22194 // Update policyDigest 22195 // Start digest 22196 CryptStartHash(session->authHashAlg, &hashState); 22197 // add old digest 22198 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 22199 // add commandCode 22200 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 22201 // add argument digest 22202 CryptUpdateDigest2B(&hashState, &argHash.b); 22203 // Adding nvName 22204 nvName.t.size = EntityGetName(in->nvIndex, &nvName.t.name); 22205 CryptUpdateDigest2B(&hashState, &nvName.b); 22206 // complete the digest 22207 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 22208 return TPM_RC_SUCCESS; 22209 } 22210 22211 Page 264 22212 October 31, 2013 22213 22214 Published 22215 Copyright TCG 2006-2013 22216 22217 Family 2.0 22218 Level 00 Revision 00.99 22219 22220 Trusted Platform Module Library 22222 22223 Part 3: Commands 22224 22225 25.10 TPM2_PolicyCounterTimer 22226 25.10.1 22227 22228 General Description 22229 22230 This command is used to cause conditional gating of a policy based on the contents of the 22231 TPMS_TIME_INFO structure. 22232 If policySession is a trial policy session, the TPM will update policySessionpolicyDigest as shown in 22233 equations (24) and (25) below and return TPM_RC_SUCCESS. It will not perform any validation. The 22234 remainder of this general description would apply only if policySession is not a trial policy session. 22235 The TPM will perform the indicated arithmetic check on the indicated portion of the TPMS_TIME_INFO 22236 structure. If the check fails, the TPM shall return TPM_RC_POLICY and not change 22237 policySessionpolicyDigest. If the check succeeds, the TPM will hash the arguments: 22238 22239 args HpolicyAlg(operandB.buffer || offset || operation) 22240 22241 (24) 22242 22243 where 22244 22245 HpolicyAlg() 22246 22247 hash function using the algorithm of the policy session 22248 22249 operandB.buffer 22250 22251 the value used for the comparison 22252 22253 offset 22254 22255 offset from the start of the TPMS_TIME_INFO structure at which 22256 the comparison starts 22257 22258 operation 22259 22260 the operation parameter indicating the comparison being 22261 performed 22262 22263 The value of args is extended to policySessionpolicyDigest by 22264 22265 policyDigestnew HpolicyAlg(policyDigestold || TPM_CC_PolicyCounterTimer || args) 22266 22267 (25) 22268 22269 where 22270 22271 HpolicyAlg() 22272 22273 hash function using the algorithm of the policy session 22274 22275 args 22276 22277 value computed in equation (24) 22278 22279 The signed arithmetic operations are performed using twos-compliment. 22280 Magnitude comparisons assume that the octet at offset zero in the referenced location and in operandB 22281 contain the most significant octet of the data. 22282 22283 Family 2.0 22284 Level 00 Revision 00.99 22285 22286 Published 22287 Copyright TCG 2006-2013 22288 22289 Page 265 22290 October 31, 2013 22291 22292 Part 3: Commands 22294 22295 25.10.2 22296 22297 Trusted Platform Module Library 22298 22299 Command and Response 22300 Table 127 TPM2_PolicyCounterTimer Command 22301 22302 Type 22303 22304 Name 22305 22306 Description 22307 22308 TPMI_ST_COMMAND_TAG 22309 22310 tag 22311 22312 UINT32 22313 22314 commandSize 22315 22316 TPM_CC 22317 22318 commandCode 22319 22320 TPM_CC_PolicyCounterTimer 22321 22322 TPMI_SH_POLICY 22323 22324 policySession 22325 22326 handle for the policy session being extended 22327 Auth Index: None 22328 22329 TPM2B_OPERAND 22330 22331 operandB 22332 22333 the second operand 22334 22335 UINT16 22336 22337 offset 22338 22339 the offset in TPMS_TIME_INFO structure for the start of 22340 operand A 22341 22342 TPM_EO 22343 22344 operation 22345 22346 the comparison to make 22347 22348 Table 128 TPM2_PolicyCounterTimer Response 22349 Type 22350 22351 Name 22352 22353 Description 22354 22355 TPM_ST 22356 22357 tag 22358 22359 see clause 8 22360 22361 UINT32 22362 22363 responseSize 22364 22365 TPM_RC 22366 22367 responseCode 22368 22369 Page 266 22370 October 31, 2013 22371 22372 Published 22373 Copyright TCG 2006-2013 22374 22375 Family 2.0 22376 Level 00 Revision 00.99 22377 22378 Trusted Platform Module Library 22380 22381 25.10.3 22382 1 22383 2 22384 3 22385 22386 Part 3: Commands 22387 22388 Detailed Actions 22389 22390 #include "InternalRoutines.h" 22391 #include "PolicyCounterTimer_fp.h" 22392 #include "Policy_spt_fp.h" 22393 Error Returns 22394 TPM_RC_POLICY 22395 22396 the comparison of the selected portion of the TPMS_TIME_INFO with 22397 operandB failed 22398 22399 TPM_RC_RANGE 22400 4 22401 5 22402 6 22403 7 22404 8 22405 9 22406 10 22407 11 22408 12 22409 13 22410 14 22411 15 22412 16 22413 17 22414 18 22415 19 22416 20 22417 21 22418 22 22419 23 22420 24 22421 25 22422 26 22423 27 22424 28 22425 29 22426 30 22427 31 22428 32 22429 33 22430 34 22431 35 22432 36 22433 37 22434 38 22435 39 22436 40 22437 41 22438 42 22439 43 22440 44 22441 45 22442 46 22443 47 22444 48 22445 49 22446 50 22447 51 22448 52 22449 22450 Meaning 22451 22452 offset + size exceed size of TPMS_TIME_INFO structure 22453 22454 TPM_RC 22455 TPM2_PolicyCounterTimer( 22456 PolicyCounterTimer_In 22457 22458 *in 22459 22460 // IN: input parameter list 22461 22462 ) 22463 { 22464 TPM_RC 22465 SESSION 22466 TIME_INFO 22467 TPM_CC 22468 HASH_STATE 22469 TPM2B_DIGEST 22470 22471 result; 22472 *session; 22473 infoData; 22474 // data buffer of TPMS_TIME_INFO 22475 commandCode = TPM_CC_PolicyCounterTimer; 22476 hashState; 22477 argHash; 22478 22479 // Input Validation 22480 // If the command is going to use any part of the counter or timer, need 22481 // to verify that time is advancing. 22482 // The time and clock vales are the first two 64-bit values in the clock 22483 if(in->offset < <K>sizeof(UINT64) + sizeof(UINT64)) 22484 { 22485 // Using Clock or Time so see if clock is running. Clock doesn't run while 22486 // NV is unavailable. 22487 // TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned here. 22488 result = NvIsAvailable(); 22489 if(result != TPM_RC_SUCCESS) 22490 return result; 22491 } 22492 // Get pointer to the session structure 22493 session = SessionGet(in->policySession); 22494 //If this is a trial policy, skip all validations and the operation 22495 if(session->attributes.isTrialPolicy == CLEAR) 22496 { 22497 // Get time data info. The size of time info data equals the input 22498 // operand B size. A TPM_RC_RANGE error may be returned at this point 22499 result = TimeGetRange(in->offset, in->operandB.t.size, &infoData); 22500 if(result != TPM_RC_SUCCESS) return result; 22501 // Arithmetic Comparison 22502 switch(in->operation) 22503 { 22504 case TPM_EO_EQ: 22505 // compare A = B 22506 if(CryptCompare(in->operandB.t.size, infoData, 22507 in->operandB.t.size, in->operandB.t.buffer) != 0) 22508 return TPM_RC_POLICY; 22509 break; 22510 case TPM_EO_NEQ: 22511 // compare A != B 22512 if(CryptCompare(in->operandB.t.size, infoData, 22513 22514 Family 2.0 22515 Level 00 Revision 00.99 22516 22517 Published 22518 Copyright TCG 2006-2013 22519 22520 Page 267 22521 October 31, 2013 22522 22523 Part 3: Commands 22525 53 22526 54 22527 55 22528 56 22529 57 22530 58 22531 59 22532 60 22533 61 22534 62 22535 63 22536 64 22537 65 22538 66 22539 67 22540 68 22541 69 22542 70 22543 71 22544 72 22545 73 22546 74 22547 75 22548 76 22549 77 22550 78 22551 79 22552 80 22553 81 22554 82 22555 83 22556 84 22557 85 22558 86 22559 87 22560 88 22561 89 22562 90 22563 91 22564 92 22565 93 22566 94 22567 95 22568 96 22569 97 22570 98 22571 99 22572 100 22573 101 22574 102 22575 103 22576 104 22577 105 22578 106 22579 107 22580 108 22581 109 22582 110 22583 111 22584 112 22585 113 22586 114 22587 115 22588 116 22589 22590 Trusted Platform Module Library 22591 22592 in->operandB.t.size, in->operandB.t.buffer) 22593 return TPM_RC_POLICY; 22594 break; 22595 case TPM_EO_SIGNED_GT: 22596 // compare A > B signed 22597 if(CryptCompareSigned(in->operandB.t.size, infoData, 22598 in->operandB.t.size, in->operandB.t.buffer) 22599 return TPM_RC_POLICY; 22600 break; 22601 case TPM_EO_UNSIGNED_GT: 22602 // compare A > B unsigned 22603 if(CryptCompare(in->operandB.t.size, infoData, 22604 in->operandB.t.size, in->operandB.t.buffer) 22605 return TPM_RC_POLICY; 22606 break; 22607 case TPM_EO_SIGNED_LT: 22608 // compare A < B signed 22609 if(CryptCompareSigned(in->operandB.t.size, infoData, 22610 in->operandB.t.size, in->operandB.t.buffer) 22611 return TPM_RC_POLICY; 22612 break; 22613 case TPM_EO_UNSIGNED_LT: 22614 // compare A < B unsigned 22615 if(CryptCompare(in->operandB.t.size, infoData, 22616 in->operandB.t.size, in->operandB.t.buffer) 22617 return TPM_RC_POLICY; 22618 break; 22619 case TPM_EO_SIGNED_GE: 22620 // compare A >= B signed 22621 if(CryptCompareSigned(in->operandB.t.size, infoData, 22622 in->operandB.t.size, in->operandB.t.buffer) 22623 return TPM_RC_POLICY; 22624 break; 22625 case TPM_EO_UNSIGNED_GE: 22626 // compare A >= B unsigned 22627 if(CryptCompare(in->operandB.t.size, infoData, 22628 in->operandB.t.size, in->operandB.t.buffer) 22629 return TPM_RC_POLICY; 22630 break; 22631 case TPM_EO_SIGNED_LE: 22632 // compare A <= B signed 22633 if(CryptCompareSigned(in->operandB.t.size, infoData, 22634 in->operandB.t.size, in->operandB.t.buffer) 22635 return TPM_RC_POLICY; 22636 break; 22637 case TPM_EO_UNSIGNED_LE: 22638 // compare A <= B unsigned 22639 if(CryptCompare(in->operandB.t.size, infoData, 22640 in->operandB.t.size, in->operandB.t.buffer) 22641 return TPM_RC_POLICY; 22642 break; 22643 case TPM_EO_BITSET: 22644 // All bits SET in B are SET in A. ((A&B)=B) 22645 { 22646 UINT32 i; 22647 for (i = 0; i < in->operandB.t.size; i++) 22648 if( 22649 (infoData[i] & in->operandB.t.buffer[i]) 22650 != in->operandB.t.buffer[i]) 22651 return TPM_RC_POLICY; 22652 } 22653 break; 22654 case TPM_EO_BITCLEAR: 22655 // All bits SET in B are CLEAR in A. ((A&B)=0) 22656 { 22657 22658 Page 268 22659 October 31, 2013 22660 22661 Published 22662 Copyright TCG 2006-2013 22663 22664 == 0) 22665 22666 <= 0) 22667 22668 <= 0) 22669 22670 >= 0) 22671 22672 >= 0) 22673 22674 < 0) 22675 22676 < 0) 22677 22678 > 0) 22679 22680 > 0) 22681 22682 Family 2.0 22683 Level 00 Revision 00.99 22684 22685 Trusted Platform Module Library 22687 117 22688 118 22689 119 22690 120 22691 121 22692 122 22693 123 22694 124 22695 125 22696 126 22697 127 22698 128 22699 129 22700 130 22701 131 22702 132 22703 133 22704 134 22705 135 22706 136 22707 137 22708 138 22709 139 22710 140 22711 141 22712 142 22713 143 22714 144 22715 145 22716 146 22717 147 22718 148 22719 149 22720 150 22721 151 22722 152 22723 153 22724 154 22725 155 22726 156 22727 157 22728 158 22729 159 22730 22731 Part 3: Commands 22732 22733 UINT32 i; 22734 for (i = 0; i < in->operandB.t.size; i++) 22735 if((infoData[i] & in->operandB.t.buffer[i]) != 0) 22736 return TPM_RC_POLICY; 22737 } 22738 break; 22739 default: 22740 pAssert(FALSE); 22741 break; 22742 } 22743 } 22744 // Internal Data Update 22745 // Start argument list hash 22746 argHash.t.size = CryptStartHash(session->authHashAlg, &hashState); 22747 // add operandB 22748 CryptUpdateDigest2B(&hashState, &in->operandB.b); 22749 // add offset 22750 CryptUpdateDigestInt(&hashState, sizeof(UINT16), &in->offset); 22751 // add operation 22752 CryptUpdateDigestInt(&hashState, sizeof(TPM_EO), &in->operation); 22753 // complete argument hash 22754 CryptCompleteHash2B(&hashState, &argHash.b); 22755 // update policyDigest 22756 // start hash 22757 CryptStartHash(session->authHashAlg, &hashState); 22758 // add old digest 22759 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 22760 // add commandCode 22761 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 22762 // add argument digest 22763 CryptUpdateDigest2B(&hashState, &argHash.b); 22764 // complete the digest 22765 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 22766 return TPM_RC_SUCCESS; 22767 } 22768 22769 Family 2.0 22770 Level 00 Revision 00.99 22771 22772 Published 22773 Copyright TCG 2006-2013 22774 22775 Page 269 22776 October 31, 2013 22777 22778 Part 3: Commands 22780 22781 Trusted Platform Module Library 22782 22783 25.11 TPM2_PolicyCommandCode 22784 25.11.1 22785 22786 General Description 22787 22788 This command indicates that the authorization will be limited to a specific command code. 22789 If policySessioncommandCode has its default value, then it will be set to code. If 22790 policySessioncommandCode does not have its default value, then the TPM will return 22791 TPM_RC_VALUE if the two values are not the same. 22792 If code is not implemented, the TPM will return TPM_RC_POLICY_CC. 22793 If the TPM does not return an error, it will update policySessionpolicyDigest by 22794 22795 policyDigestnew HpolicyAlg(policyDigestold || TPM_CC_PolicyCommandCode || code) 22796 22797 (26) 22798 22799 NOTE 1 22800 22801 If a previous TPM2_PolicyCommandCode() had been executed, then it is probable that the policy 22802 expression is improperly formed but the TPM does not return an error. 22803 22804 NOTE 2 22805 22806 A TPM2_PolicyOR() would be used to allow an authorization to be used for multiple commands. 22807 22808 When the policy session is used to authorize a command, the TPM will fail the command if the 22809 commandCode of that command does not match policySessioncommandCode. 22810 This command, or TPM2_PolicyDuplicationSelect(), is required to enable the policy to be used for ADMIN 22811 role authorization. 22812 EXAMPLE 22813 22814 Before TPM2_Certify() can 22815 TPM_CC_Certify is required. 22816 22817 Page 270 22818 October 31, 2013 22819 22820 be 22821 22822 executed, 22823 22824 TPM2_PolicyCommandCode() 22825 22826 Published 22827 Copyright TCG 2006-2013 22828 22829 with 22830 22831 code 22832 22833 set 22834 22835 to 22836 22837 Family 2.0 22838 Level 00 Revision 00.99 22839 22840 Trusted Platform Module Library 22842 22843 25.11.2 22844 22845 Part 3: Commands 22846 22847 Command and Response 22848 Table 129 TPM2_PolicyCommandCode Command 22849 22850 Type 22851 22852 Name 22853 22854 Description 22855 22856 TPMI_ST_COMMAND_TAG 22857 22858 tag 22859 22860 UINT32 22861 22862 commandSize 22863 22864 TPM_CC 22865 22866 commandCode 22867 22868 TPM_CC_PolicyCommandCode 22869 22870 TPMI_SH_POLICY 22871 22872 policySession 22873 22874 handle for the policy session being extended 22875 Auth Index: None 22876 22877 TPM_CC 22878 22879 code 22880 22881 the allowed commandCode 22882 22883 Table 130 TPM2_PolicyCommandCode Response 22884 Type 22885 22886 Name 22887 22888 Description 22889 22890 TPM_ST 22891 22892 tag 22893 22894 see clause 8 22895 22896 UINT32 22897 22898 responseSize 22899 22900 TPM_RC 22901 22902 responseCode 22903 22904 Family 2.0 22905 Level 00 Revision 00.99 22906 22907 Published 22908 Copyright TCG 2006-2013 22909 22910 Page 271 22911 October 31, 2013 22912 22913 Part 3: Commands 22915 22916 25.11.3 22917 1 22918 2 22919 22920 Trusted Platform Module Library 22921 22922 Detailed Actions 22923 22924 #include "InternalRoutines.h" 22925 #include "PolicyCommandCode_fp.h" 22926 Error Returns 22927 TPM_RC_VALUE 22928 22929 3 22930 4 22931 5 22932 6 22933 7 22934 8 22935 9 22936 10 22937 11 22938 12 22939 13 22940 14 22941 15 22942 16 22943 17 22944 18 22945 19 22946 20 22947 21 22948 22 22949 23 22950 24 22951 25 22952 26 22953 27 22954 28 22955 29 22956 30 22957 31 22958 32 22959 33 22960 34 22961 35 22962 36 22963 37 22964 38 22965 39 22966 40 22967 41 22968 42 22969 43 22970 44 22971 22972 Meaning 22973 commandCode of policySession previously set to a different value 22974 22975 TPM_RC 22976 TPM2_PolicyCommandCode( 22977 PolicyCommandCode_In *in 22978 22979 // IN: input parameter list 22980 22981 ) 22982 { 22983 SESSION 22984 TPM_CC 22985 HASH_STATE 22986 22987 *session; 22988 commandCode = TPM_CC_PolicyCommandCode; 22989 hashState; 22990 22991 // Input validation 22992 // Get pointer to the session structure 22993 session = SessionGet(in->policySession); 22994 if(session->commandCode != 0 && session->commandCode != in->code) 22995 return TPM_RC_VALUE + RC_PolicyCommandCode_code; 22996 if(!CommandIsImplemented(in->code)) 22997 return TPM_RC_POLICY_CC + RC_PolicyCommandCode_code; 22998 // Internal Data Update 22999 // Update policy hash 23000 // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyCommandCode || code) 23001 // Start hash 23002 CryptStartHash(session->authHashAlg, &hashState); 23003 // add old digest 23004 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 23005 // add commandCode 23006 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 23007 // add input commandCode 23008 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &in->code); 23009 // complete the hash and get the results 23010 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 23011 // update commandCode value in session context 23012 session->commandCode = in->code; 23013 return TPM_RC_SUCCESS; 23014 } 23015 23016 Page 272 23017 October 31, 2013 23018 23019 Published 23020 Copyright TCG 2006-2013 23021 23022 Family 2.0 23023 Level 00 Revision 00.99 23024 23025 Trusted Platform Module Library 23027 23028 Part 3: Commands 23029 23030 25.12 TPM2_PolicyPhysicalPresence 23031 25.12.1 23032 23033 General Description 23034 23035 This command indicates that physical presence will need to be asserted at the time the authorization is 23036 performed. 23037 If this command is successful, policySessionisPPRequired will be SET to indicate that this check is 23038 required when the policy is used for authorization. Additionally, policySessionpolicyDigest is extended 23039 with 23040 23041 policyDigestnew HpolicyAlg(policyDigestold || TPM_CC_PolicyPhysicalPresence) 23042 23043 Family 2.0 23044 Level 00 Revision 00.99 23045 23046 Published 23047 Copyright TCG 2006-2013 23048 23049 (27) 23050 23051 Page 273 23052 October 31, 2013 23053 23054 Part 3: Commands 23056 23057 25.12.2 23058 23059 Trusted Platform Module Library 23060 23061 Command and Response 23062 Table 131 TPM2_PolicyPhysicalPresence Command 23063 23064 Type 23065 23066 Name 23067 23068 Description 23069 23070 TPMI_ST_COMMAND_TAG 23071 23072 tag 23073 23074 UINT32 23075 23076 commandSize 23077 23078 TPM_CC 23079 23080 commandCode 23081 23082 TPM_CC_PolicyPhysicalPresence 23083 23084 TPMI_SH_POLICY 23085 23086 policySession 23087 23088 handle for the policy session being extended 23089 Auth Index: None 23090 23091 Table 132 TPM2_PolicyPhysicalPresence Response 23092 Type 23093 23094 Name 23095 23096 Description 23097 23098 TPM_ST 23099 23100 tag 23101 23102 see clause 8 23103 23104 UINT32 23105 23106 responseSize 23107 23108 TPM_RC 23109 23110 responseCode 23111 23112 Page 274 23113 October 31, 2013 23114 23115 Published 23116 Copyright TCG 2006-2013 23117 23118 Family 2.0 23119 Level 00 Revision 00.99 23120 23121 Trusted Platform Module Library 23123 23124 25.12.3 23125 1 23126 2 23127 3 23128 4 23129 5 23130 6 23131 7 23132 8 23133 9 23134 10 23135 11 23136 12 23137 13 23138 14 23139 15 23140 16 23141 17 23142 18 23143 19 23144 20 23145 21 23146 22 23147 23 23148 24 23149 25 23150 26 23151 27 23152 28 23153 29 23154 30 23155 31 23156 32 23157 33 23158 34 23159 35 23160 23161 Part 3: Commands 23162 23163 Detailed Actions 23164 23165 #include "InternalRoutines.h" 23166 #include "PolicyPhysicalPresence_fp.h" 23167 23168 TPM_RC 23169 TPM2_PolicyPhysicalPresence( 23170 PolicyPhysicalPresence_In *in 23171 23172 // IN: input parameter list 23173 23174 ) 23175 { 23176 SESSION 23177 TPM_CC 23178 HASH_STATE 23179 23180 *session; 23181 commandCode = TPM_CC_PolicyPhysicalPresence; 23182 hashState; 23183 23184 // Internal Data Update 23185 // Get pointer to the session structure 23186 session = SessionGet(in->policySession); 23187 // Update policy hash 23188 // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyPhysicalPresence) 23189 // Start hash 23190 CryptStartHash(session->authHashAlg, &hashState); 23191 // add old digest 23192 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 23193 // add commandCode 23194 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 23195 // complete the digest 23196 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 23197 // update session attribute 23198 session->attributes.isPPRequired = SET; 23199 return TPM_RC_SUCCESS; 23200 } 23201 23202 Family 2.0 23203 Level 00 Revision 00.99 23204 23205 Published 23206 Copyright TCG 2006-2013 23207 23208 Page 275 23209 October 31, 2013 23210 23211 Part 3: Commands 23213 23214 Trusted Platform Module Library 23215 23216 25.13 TPM2_PolicyCpHash 23217 25.13.1 23218 23219 General Description 23220 23221 This command is used to allow a policy to be bound to a specific command and command parameters. 23222 TPM2_PolicySigned(), TPM2_PolicySecret(), and TPM2_PolicyTIcket() are designed to allow an 23223 authorizing entity to execute an arbitrary command as the cpHashA parameter of those commands is not 23224 included in policySessionpolicyDigest. TPM2_PolicyCommandCode() allows the policy to be bound to a 23225 specific Command Code so that only certain entities may authorize specific command codes. This 23226 command allows the policy to be restricted such that an entity may only authorize a command with a 23227 specific set of parameters. 23228 If policySessioncpHash is already set and not the same as cpHashA, then the TPM shall return 23229 TPM_RC_VALUE. If cpHashA does not have the size of the policySessionpolicyDigest, the TPM shall 23230 return TPM_RC_SIZE. 23231 If the cpHashA checks succeed, policySessioncpHash 23232 policySessionpolicyDigest is updated with 23233 23234 is 23235 23236 set 23237 23238 to 23239 23240 cpHashA 23241 23242 policyDigestnew HpolicyAlg(policyDigestold || TPM_CC_PolicyCpHash || cpHashA) 23243 23244 Page 276 23245 October 31, 2013 23246 23247 Published 23248 Copyright TCG 2006-2013 23249 23250 and 23251 (28) 23252 23253 Family 2.0 23254 Level 00 Revision 00.99 23255 23256 Trusted Platform Module Library 23258 23259 25.13.2 23260 23261 Part 3: Commands 23262 23263 Command and Response 23264 Table 133 TPM2_PolicyCpHash Command 23265 23266 Type 23267 23268 Name 23269 23270 Description 23271 23272 TPMI_ST_COMMAND_TAG 23273 23274 tag 23275 23276 UINT32 23277 23278 commandSize 23279 23280 TPM_CC 23281 23282 commandCode 23283 23284 TPM_CC_PolicyCpHash 23285 23286 TPMI_SH_POLICY 23287 23288 policySession 23289 23290 handle for the policy session being extended 23291 Auth Index: None 23292 23293 TPM2B_DIGEST 23294 23295 cpHashA 23296 23297 the cpHash added to the policy 23298 23299 Table 134 TPM2_PolicyCpHash Response 23300 Type 23301 23302 Name 23303 23304 Description 23305 23306 TPM_ST 23307 23308 tag 23309 23310 see clause 8 23311 23312 UINT32 23313 23314 responseSize 23315 23316 TPM_RC 23317 23318 responseCode 23319 23320 Family 2.0 23321 Level 00 Revision 00.99 23322 23323 Published 23324 Copyright TCG 2006-2013 23325 23326 Page 277 23327 October 31, 2013 23328 23329 Part 3: Commands 23331 23332 25.13.3 23333 1 23334 2 23335 23336 Trusted Platform Module Library 23337 23338 Detailed Actions 23339 23340 #include "InternalRoutines.h" 23341 #include "PolicyCpHash_fp.h" 23342 Error Returns 23343 TPM_RC_CPHASH 23344 23345 cpHash of policySession has previously been set to a different value 23346 23347 TPM_RC_SIZE 23348 23349 3 23350 4 23351 5 23352 6 23353 7 23354 8 23355 9 23356 10 23357 11 23358 12 23359 13 23360 14 23361 15 23362 16 23363 17 23364 18 23365 19 23366 20 23367 21 23368 22 23369 23 23370 24 23371 25 23372 26 23373 27 23374 28 23375 29 23376 30 23377 31 23378 32 23379 33 23380 34 23381 35 23382 36 23383 37 23384 38 23385 39 23386 40 23387 41 23388 42 23389 43 23390 44 23391 45 23392 46 23393 47 23394 48 23395 49 23396 50 23397 51 23398 52 23399 23400 Meaning 23401 23402 cpHashA is not the size of a digest produced by the hash algorithm 23403 associated with policySession 23404 23405 TPM_RC 23406 TPM2_PolicyCpHash( 23407 PolicyCpHash_In *in 23408 23409 // IN: input parameter list 23410 23411 ) 23412 { 23413 SESSION 23414 TPM_CC 23415 HASH_STATE 23416 23417 *session; 23418 commandCode = TPM_CC_PolicyCpHash; 23419 hashState; 23420 23421 // Input Validation 23422 // Get pointer to the session structure 23423 session = SessionGet(in->policySession); 23424 // A new cpHash is given in input parameter, but cpHash in session context 23425 // is not empty, or is not the same as the new cpHash 23426 if( 23427 in->cpHashA.t.size != 0 23428 && session->u1.cpHash.t.size != 0 23429 && !Memory2BEqual(&in->cpHashA.b, &session->u1.cpHash.b) 23430 ) 23431 return TPM_RC_CPHASH; 23432 // A valid cpHash must have the same size as session hash digest 23433 if(in->cpHashA.t.size != CryptGetHashDigestSize(session->authHashAlg)) 23434 return TPM_RC_SIZE + RC_PolicyCpHash_cpHashA; 23435 // Internal Data Update 23436 // Update policy hash 23437 // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyCpHash || cpHashA) 23438 // Start hash 23439 CryptStartHash(session->authHashAlg, &hashState); 23440 // add old digest 23441 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 23442 // add commandCode 23443 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 23444 // add cpHashA 23445 CryptUpdateDigest2B(&hashState, &in->cpHashA.b); 23446 // complete the digest and get the results 23447 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 23448 // update cpHash in session context 23449 session->u1.cpHash = in->cpHashA; 23450 session->attributes.iscpHashDefined = SET; 23451 return TPM_RC_SUCCESS; 23452 23453 Page 278 23454 October 31, 2013 23455 23456 Published 23457 Copyright TCG 2006-2013 23458 23459 Family 2.0 23460 Level 00 Revision 00.99 23461 23462 Trusted Platform Module Library 23464 53 23465 23466 Part 3: Commands 23467 23468 } 23469 23470 Family 2.0 23471 Level 00 Revision 00.99 23472 23473 Published 23474 Copyright TCG 2006-2013 23475 23476 Page 279 23477 October 31, 2013 23478 23479 Part 3: Commands 23481 23482 Trusted Platform Module Library 23483 23484 25.14 TPM2_PolicyNameHash 23485 25.14.1 23486 23487 General Description 23488 23489 This command allows a policy to be bound to a specific set of TPM entities without being bound to the 23490 parameters of the command. This is most useful for commands such as TPM2_Duplicate() and for 23491 TPM2_PCR_Event() when the referenced PCR requires a policy. 23492 The nameHash parameter should contain the digest of the Names associated with the handles to be used 23493 in the authorized command. 23494 EXAMPLE 23495 23496 For the TPM2_Duplicate() command, two handles are provided. One is the handle of the object 23497 being duplicated and the other is the handle of the new parent. For that command, nameHash would 23498 contain: 23499 23500 nameHash H policyAlg (objectHandleName || newParentHandleName) 23501 23502 If policySessioncpHash is already set, the TPM shall return TPM_RC_VALUE. If the size of nameHash 23503 is not the size of policySessionpolicyDigest, the TPM shall return TPM_RC_SIZE. Otherwise, 23504 policySessioncpHash is set to nameHash. 23505 If this command completes successfully, the cpHash of the authorized command will not be used for 23506 validation. Only the digest of the Names associated with the handles in the command will be used. 23507 NOTE 1 23508 23509 This allows the space normally 23510 policySessionnameHash instead. 23511 23512 used 23513 23514 to 23515 23516 hold 23517 23518 policySessioncpHash 23519 23520 to 23521 23522 be 23523 23524 used 23525 23526 for 23527 23528 The policySessionpolicyDigest will be updated with 23529 23530 policyDigestnew HpolicyAlg(policyDigestold || TPM_CC_PolicyNameHash || nameHash) 23531 NOTE 2 23532 23533 (29) 23534 23535 This command will often be used with TPM2_PolicyAuthorize() where the owner of the object being 23536 duplicated provides approval for their object to be migrated to a specific new parent. 23537 23538 Page 280 23539 October 31, 2013 23540 23541 Published 23542 Copyright TCG 2006-2013 23543 23544 Family 2.0 23545 Level 00 Revision 00.99 23546 23547 Trusted Platform Module Library 23549 23550 25.14.2 23551 23552 Part 3: Commands 23553 23554 Command and Response 23555 Table 135 TPM2_PolicyNameHash Command 23556 23557 Type 23558 23559 Name 23560 23561 Description 23562 23563 TPMI_ST_COMMAND_TAG 23564 23565 tag 23566 23567 UINT32 23568 23569 commandSize 23570 23571 TPM_CC 23572 23573 commandCode 23574 23575 TPM_CC_PolicyNameHash 23576 23577 TPMI_SH_POLICY 23578 23579 policySession 23580 23581 handle for the policy session being extended 23582 Auth Index: None 23583 23584 TPM2B_DIGEST 23585 23586 nameHash 23587 23588 the digest to be added to the policy 23589 23590 Table 136 TPM2_PolicyNameHash Response 23591 Type 23592 23593 Name 23594 23595 Description 23596 23597 TPM_ST 23598 23599 tag 23600 23601 see clause 8 23602 23603 UINT32 23604 23605 responseSize 23606 23607 TPM_RC 23608 23609 responseCode 23610 23611 Family 2.0 23612 Level 00 Revision 00.99 23613 23614 Published 23615 Copyright TCG 2006-2013 23616 23617 Page 281 23618 October 31, 2013 23619 23620 Part 3: Commands 23622 23623 25.14.3 23624 1 23625 2 23626 23627 Trusted Platform Module Library 23628 23629 Detailed Actions 23630 23631 #include "InternalRoutines.h" 23632 #include "PolicyNameHash_fp.h" 23633 Error Returns 23634 TPM_RC_CPHASH 23635 23636 nameHash has been previously set to a different value 23637 23638 TPM_RC_SIZE 23639 23640 3 23641 4 23642 5 23643 6 23644 7 23645 8 23646 9 23647 10 23648 11 23649 12 23650 13 23651 14 23652 15 23653 16 23654 17 23655 18 23656 19 23657 20 23658 21 23659 22 23660 23 23661 24 23662 25 23663 26 23664 27 23665 28 23666 29 23667 30 23668 31 23669 32 23670 33 23671 34 23672 35 23673 36 23674 37 23675 38 23676 39 23677 40 23678 41 23679 42 23680 43 23681 44 23682 45 23683 46 23684 47 23685 48 23686 49 23687 50 23688 51 23689 52 23690 23691 Meaning 23692 23693 nameHash is not the size of the digest produced by the hash 23694 algorithm associated with policySession 23695 23696 TPM_RC 23697 TPM2_PolicyNameHash( 23698 PolicyNameHash_In 23699 23700 *in 23701 23702 // IN: input parameter list 23703 23704 SESSION 23705 TPM_CC 23706 HASH_STATE 23707 23708 *session; 23709 commandCode = TPM_CC_PolicyNameHash; 23710 hashState; 23711 23712 ) 23713 { 23714 23715 // Input Validation 23716 // Get pointer to the session structure 23717 session = SessionGet(in->policySession); 23718 // A new nameHash is given in input parameter, but cpHash in session context 23719 // is not empty 23720 if(in->nameHash.t.size != 0 && session->u1.cpHash.t.size != 0) 23721 return TPM_RC_CPHASH; 23722 // A valid nameHash must have the same size as session hash digest 23723 if(in->nameHash.t.size != CryptGetHashDigestSize(session->authHashAlg)) 23724 return TPM_RC_SIZE + RC_PolicyNameHash_nameHash; 23725 // Internal Data Update 23726 // Update policy hash 23727 // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyNameHash || nameHash) 23728 // Start hash 23729 CryptStartHash(session->authHashAlg, &hashState); 23730 // add old digest 23731 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 23732 // add commandCode 23733 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 23734 // add nameHash 23735 CryptUpdateDigest2B(&hashState, &in->nameHash.b); 23736 // complete the digest 23737 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 23738 // clear iscpHashDefined bit to indicate now this field contains a nameHash 23739 session->attributes.iscpHashDefined = CLEAR; 23740 // update nameHash in session context 23741 session->u1.cpHash = in->nameHash; 23742 return TPM_RC_SUCCESS; 23743 } 23744 23745 Page 282 23746 October 31, 2013 23747 23748 Published 23749 Copyright TCG 2006-2013 23750 23751 Family 2.0 23752 Level 00 Revision 00.99 23753 23754 Trusted Platform Module Library 23756 23757 Part 3: Commands 23758 23759 25.15 TPM2_PolicyDuplicationSelect 23760 25.15.1 23761 23762 General Description 23763 23764 This command allows qualification of duplication to allow duplication to a selected new parent. 23765 If this command not used in conjunction with TPM2_PolicyAuthorize(), then only the new parent is 23766 selected. 23767 EXAMPLE 23768 23769 When an object is created when the list of allowed duplication targets is known, the policy would be 23770 created with includeObject CLEAR. 23771 23772 NOTE 1 23773 23774 Only the new parent may be selected because, without TPM2_PolicyAuthorize() , the Name of the 23775 Object to be duplicated would need to be known at the time that Object's policy is created. However, 23776 since the Name of the Object includes its policy, the Name is not known. 23777 23778 If used in conjunction with TPM2_PolicyAuthorize(), then the authorizer of the new policy has the option 23779 of selecting just the new parent or of selecting both the new parent and the duplication Object.. 23780 NOTE 2 23781 23782 If the authorizing entity for an TPM2_PolicyAuthorize() only specifies the new parent, then that 23783 authorization may be applied to the duplication of any number of other Objects. If the authorizing 23784 entity specifies both a new parent and the duplicated Object, then the authorization only applies to 23785 that pairing of Object and new parent. 23786 23787 If either policySessioncpHash or policySessionnameHash has been previously set, the TPM shall 23788 return TPM_RC_CPHASH. Otherwise, policySessionnameHash will be set to: 23789 23790 nameHash HpolicyAlg(objectName || newParentName) 23791 23792 (30) 23793 23794 It is allowed that policySesionnameHash and policySessioncpHash share the same memory 23795 space. 23796 23797 NOTE 3 23798 23799 The policySessionpolicyDigest will be updated according to the setting of includeObject. If equal to 23800 YES, policySessionpolicyDigest is updated by: 23801 23802 policyDigestnew HpolicyAlg(policyDigestold || TPM_CC_PolicyDuplicationSelect || 23803 objectName || newParentName || includeObject) 23804 23805 (31) 23806 23807 If includeObject is NO, policySessionpolicyDigest is updated by: 23808 23809 policyDigestnew HpolicyAlg(policyDigestold || TPM_CC_PolicyDuplicationSelect || 23810 newParentName || includeObject) 23811 NOTE 4 23812 23813 (32) 23814 23815 PolicySessionCpHash receives the digest of both Names so that the check performed in 23816 TPM2_Duplicate() may be the same regardless of which Names are included in 23817 policySessionpolicyDigest. This means that, when TPM2_PolicyDuplicationSelect() is executed, it 23818 is only valid for a specific pair of duplication object and new parent. 23819 23820 If the command succeeds, commandCode in the policy session context is set to TPM_CC_Duplicate. 23821 NOTE 5 23822 23823 The normal use of this command is before a TPM2_PolicyAuthorize(). An authorized entity would 23824 approve a policyDigest that allowed duplication to a specific new parent. The authorizing entity may 23825 want to limit the authorization so that the approval allows only a specific object to be duplicated to 23826 the new parent. In that case, the authorizing entity would approve the policyDigest of equation (31). 23827 23828 Family 2.0 23829 Level 00 Revision 00.99 23830 23831 Published 23832 Copyright TCG 2006-2013 23833 23834 Page 283 23835 October 31, 2013 23836 23837 Part 3: Commands 23839 23840 25.15.2 23841 23842 Trusted Platform Module Library 23843 23844 Command and Response 23845 Table 137 TPM2_PolicyDuplicationSelect Command 23846 23847 Type 23848 23849 Name 23850 23851 Description 23852 23853 TPMI_ST_COMMAND_TAG 23854 23855 tag 23856 23857 UINT32 23858 23859 commandSize 23860 23861 TPM_CC 23862 23863 commandCode 23864 23865 TPM_CC_PolicyDuplicationSelect 23866 23867 TPMI_SH_POLICY 23868 23869 policySession 23870 23871 handle for the policy session being extended 23872 Auth Index: None 23873 23874 TPM2B_NAME 23875 23876 objectName 23877 23878 the Name of the object to be duplicated 23879 23880 TPM2B_NAME 23881 23882 newParentName 23883 23884 the Name of the new parent 23885 23886 TPMI_YES_NO 23887 23888 includeObject 23889 23890 if YES, the objectName will be included in the value in 23891 policySessionpolicyDigest 23892 23893 Table 138 TPM2_PolicyDuplicationSelect Response 23894 Type 23895 23896 Name 23897 23898 Description 23899 23900 TPM_ST 23901 23902 tag 23903 23904 see clause 8 23905 23906 UINT32 23907 23908 responseSize 23909 23910 TPM_RC 23911 23912 responseCode 23913 23914 Page 284 23915 October 31, 2013 23916 23917 Published 23918 Copyright TCG 2006-2013 23919 23920 Family 2.0 23921 Level 00 Revision 00.99 23922 23923 Trusted Platform Module Library 23925 23926 25.15.3 23927 1 23928 2 23929 23930 Part 3: Commands 23931 23932 Detailed Actions 23933 23934 #include "InternalRoutines.h" 23935 #include "PolicyDuplicationSelect_fp.h" 23936 Error Returns 23937 TPM_RC_COMMAND_CODE 23938 23939 commandCode of 'policySession; is not empty 23940 23941 TPM_RC_CPHASH 23942 3 23943 4 23944 5 23945 6 23946 7 23947 8 23948 9 23949 10 23950 11 23951 12 23952 13 23953 14 23954 15 23955 16 23956 17 23957 18 23958 19 23959 20 23960 21 23961 22 23962 23 23963 24 23964 25 23965 26 23966 27 23967 28 23968 29 23969 30 23970 31 23971 32 23972 33 23973 34 23974 35 23975 36 23976 37 23977 38 23978 39 23979 40 23980 41 23981 42 23982 43 23983 44 23984 45 23985 46 23986 47 23987 48 23988 49 23989 50 23990 51 23991 52 23992 53 23993 23994 Meaning 23995 23996 cpHash of policySession is not empty 23997 23998 TPM_RC 23999 TPM2_PolicyDuplicationSelect( 24000 PolicyDuplicationSelect_In *in 24001 24002 // IN: input parameter list 24003 24004 ) 24005 { 24006 SESSION 24007 HASH_STATE 24008 TPM_CC 24009 24010 *session; 24011 hashState; 24012 commandCode = TPM_CC_PolicyDuplicationSelect; 24013 24014 // Input Validation 24015 // Get pointer to the session structure 24016 session = SessionGet(in->policySession); 24017 // cpHash in session context must be empty 24018 if(session->u1.cpHash.t.size != 0) 24019 return TPM_RC_CPHASH; 24020 // commandCode in session context must be empty 24021 if(session->commandCode != 0) 24022 return TPM_RC_COMMAND_CODE; 24023 // Internal Data Update 24024 // Update name hash 24025 session->u1.cpHash.t.size = CryptStartHash(session->authHashAlg, &hashState); 24026 // add objectName 24027 CryptUpdateDigest2B(&hashState, &in->objectName.b); 24028 // add new parent name 24029 CryptUpdateDigest2B(&hashState, &in->newParentName.b); 24030 // complete hash 24031 CryptCompleteHash2B(&hashState, &session->u1.cpHash.b); 24032 // update policy hash 24033 // Old policyDigest size should be the same as the new policyDigest size since 24034 // they are using the same hash algorithm 24035 session->u2.policyDigest.t.size 24036 = CryptStartHash(session->authHashAlg, &hashState); 24037 // add old policy 24038 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 24039 // add command code 24040 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 24041 // add objectName 24042 if(in->includeObject == YES) 24043 CryptUpdateDigest2B(&hashState, &in->objectName.b); 24044 24045 Family 2.0 24046 Level 00 Revision 00.99 24047 24048 Published 24049 Copyright TCG 2006-2013 24050 24051 Page 285 24052 October 31, 2013 24053 24054 Part 3: Commands 24056 54 24057 55 24058 56 24059 57 24060 58 24061 59 24062 60 24063 61 24064 62 24065 63 24066 64 24067 65 24068 66 24069 67 24070 68 24071 69 24072 70 24073 71 24074 24075 Trusted Platform Module Library 24076 24077 // add new parent name 24078 CryptUpdateDigest2B(&hashState, &in->newParentName.b); 24079 // add includeObject 24080 CryptUpdateDigestInt(&hashState, sizeof(TPMI_YES_NO), &in->includeObject); 24081 // complete digest 24082 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 24083 // clear iscpHashDefined bit to indicate now this field contains a nameHash 24084 session->attributes.iscpHashDefined = CLEAR; 24085 // set commandCode in session context 24086 session->commandCode = TPM_CC_Duplicate; 24087 return TPM_RC_SUCCESS; 24088 } 24089 24090 Page 286 24091 October 31, 2013 24092 24093 Published 24094 Copyright TCG 2006-2013 24095 24096 Family 2.0 24097 Level 00 Revision 00.99 24098 24099 Trusted Platform Module Library 24101 24102 Part 3: Commands 24103 24104 25.16 TPM2_PolicyAuthorize 24105 25.16.1 24106 24107 General Description 24108 24109 This command allows policies to change. If a policy were static, then it would be difficult to add users to a 24110 policy. This command lets a policy authority sign a new policy so that it may be used in an existing policy. 24111 The authorizing entity signs a structure that contains 24112 24113 aHash HaHashAlg(approvedPolicy || policyRef) 24114 24115 (33) 24116 24117 The aHashAlg is required to be the nameAlg of the key used to sign the aHash. The aHash value is then 24118 signed (symmetric or asymmetric) by keySign. That signature is then checked by the TPM in 24119 TPM2_VerifySignature() which produces a ticket by 24120 24121 HMAC(proof, (TPM_ST_VERIFIED || aHash || keySignName)) 24122 NOTE 24123 24124 (34) 24125 24126 The reason for the validation is because of the expectation that the policy will be used multiple times 24127 and it is more efficient to check a ticket than to load an object each time to chec k a signature. 24128 24129 The ticket is then used in TPM2_PolicyAuthorize() to validate the parameters. 24130 The keySign parameter is required to be a valid object name using nameAlg other than TPM_ALG_NULL. 24131 If the first two octets of keySign are not a valid hash algorithm, the TPM shall return TPM_RC_HASH. If 24132 the remainder of the Name is not the size of the indicated digest, the TPM shall return TPM_RC_SIZE. 24133 The TPM validates that the approvedPolicy matches the current value of policySessionpolicyDigest and 24134 if not, shall return TPM_RC_VALUE. 24135 The TPM then validates that the parameters to TPM2_PolicyAuthorize() match the values used to 24136 generate the ticket. If so, the TPM will reset policySessionpolicyDigest to a Zero Digest. Then it will 24137 create a TPM2B_NAME (keyName) using keySign and update policySessionpolicyDigest with 24138 PolicyUpdate() (see 25.2.3). 24139 24140 PolicyUpdate(TPM_CC_PolicyAuthorize, keyName, policyRef) 24141 24142 (35) 24143 24144 If the ticket is not valid, the TPM shall return TPM_RC_POLICY. 24145 If policySession is a trial session, policySessionpolicyDigest is extended as if the ticket is valid without 24146 actual verification. 24147 NOTE 24148 24149 The unmarshaling process requires that a proper TPMT_TK_VERIFIED be provided for checkTicket 24150 but it may be a NULL Ticket. 24151 24152 Family 2.0 24153 Level 00 Revision 00.99 24154 24155 Published 24156 Copyright TCG 2006-2013 24157 24158 Page 287 24159 October 31, 2013 24160 24161 Part 3: Commands 24163 24164 25.16.2 24165 24166 Trusted Platform Module Library 24167 24168 Command and Response 24169 Table 139 TPM2_PolicyAuthorize Command 24170 24171 Type 24172 24173 Name 24174 24175 Description 24176 24177 TPMI_ST_COMMAND_TAG 24178 24179 tag 24180 24181 UINT32 24182 24183 commandSize 24184 24185 TPM_CC 24186 24187 commandCode 24188 24189 TPM_CC_PolicyAuthorize 24190 24191 TPMI_SH_POLICY 24192 24193 policySession 24194 24195 handle for the policy session being extended 24196 Auth Index: None 24197 24198 TPM2B_DIGEST 24199 24200 approvedPolicy 24201 24202 digest of the policy being approved 24203 24204 TPM2B_NONCE 24205 24206 policyRef 24207 24208 a policy qualifier 24209 24210 TPM2B_NAME 24211 24212 keySign 24213 24214 Name of a key that can sign a policy addition 24215 24216 TPMT_TK_VERIFIED 24217 24218 checkTicket 24219 24220 ticket validating that approvedPolicy and policyRef were 24221 signed by keySign 24222 24223 Table 140 TPM2_PolicyAuthorize Response 24224 Type 24225 24226 Name 24227 24228 Description 24229 24230 TPM_ST 24231 24232 tag 24233 24234 see clause 8 24235 24236 UINT32 24237 24238 responseSize 24239 24240 TPM_RC 24241 24242 responseCode 24243 24244 Page 288 24245 October 31, 2013 24246 24247 Published 24248 Copyright TCG 2006-2013 24249 24250 Family 2.0 24251 Level 00 Revision 00.99 24252 24253 Trusted Platform Module Library 24255 24256 25.16.3 24257 1 24258 2 24259 3 24260 24261 Part 3: Commands 24262 24263 Detailed Actions 24264 24265 #include "InternalRoutines.h" 24266 #include "PolicyAuthorize_fp.h" 24267 #include "Policy_spt_fp.h" 24268 Error Returns 24269 TPM_RC_HASH 24270 24271 hash algorithm in keyName is not supported 24272 24273 TPM_RC_SIZE 24274 24275 keyName is not the correct size for its hash algorithm 24276 24277 TPM_RC_VALUE 24278 24279 4 24280 5 24281 6 24282 7 24283 8 24284 9 24285 10 24286 11 24287 12 24288 13 24289 14 24290 15 24291 16 24292 17 24293 18 24294 19 24295 20 24296 21 24297 22 24298 23 24299 24 24300 25 24301 26 24302 27 24303 28 24304 29 24305 30 24306 31 24307 32 24308 33 24309 34 24310 35 24311 36 24312 37 24313 38 24314 39 24315 40 24316 41 24317 42 24318 43 24319 44 24320 45 24321 46 24322 47 24323 48 24324 49 24325 50 24326 24327 Meaning 24328 24329 the current policyDigest of policySession does not match 24330 approvedPolicy; or checkTicket doesn't match the provided values 24331 24332 TPM_RC 24333 TPM2_PolicyAuthorize( 24334 PolicyAuthorize_In 24335 24336 *in 24337 24338 // IN: input parameter list 24339 24340 SESSION 24341 TPM2B_DIGEST 24342 HASH_STATE 24343 TPMT_TK_VERIFIED 24344 TPM_ALG_ID 24345 UINT16 24346 24347 *session; 24348 authHash; 24349 hashState; 24350 ticket; 24351 hashAlg; 24352 digestSize; 24353 24354 ) 24355 { 24356 24357 // Input Validation 24358 // Get pointer to the session structure 24359 session = SessionGet(in->policySession); 24360 // Extract from the Name of the key, the algorithm used to compute it's Name 24361 hashAlg = BYTE_ARRAY_TO_UINT16(in->keySign.t.name); 24362 // 'keySign' parameter needs to use a supported hash algorithm, otherwise 24363 // can't tell how large the digest should be 24364 digestSize = CryptGetHashDigestSize(hashAlg); 24365 if(digestSize == 0) 24366 return TPM_RC_HASH + RC_PolicyAuthorize_keySign; 24367 if(digestSize != (in->keySign.t.size - 2)) 24368 return TPM_RC_SIZE + RC_PolicyAuthorize_keySign; 24369 //If this is a trial policy, skip all validations 24370 if(session->attributes.isTrialPolicy == CLEAR) 24371 { 24372 // Check that "approvedPolicy" matches the current value of the 24373 // policyDigest in policy session 24374 if(!Memory2BEqual(&session->u2.policyDigest.b, 24375 &in->approvedPolicy.b)) 24376 return TPM_RC_VALUE + RC_PolicyAuthorize_approvedPolicy; 24377 // Validate ticket TPMT_TK_VERIFIED 24378 // Compute aHash. The authorizing object sign a digest 24379 // aHash := hash(approvedPolicy || policyRef). 24380 // Start hash 24381 authHash.t.size = CryptStartHash(hashAlg, &hashState); 24382 // add approvedPolicy 24383 CryptUpdateDigest2B(&hashState, &in->approvedPolicy.b); 24384 24385 Family 2.0 24386 Level 00 Revision 00.99 24387 24388 Published 24389 Copyright TCG 2006-2013 24390 24391 Page 289 24392 October 31, 2013 24393 24394 Part 3: Commands 24396 51 24397 52 24398 53 24399 54 24400 55 24401 56 24402 57 24403 58 24404 59 24405 60 24406 61 24407 62 24408 63 24409 64 24410 65 24411 66 24412 67 24413 68 24414 69 24415 70 24416 71 24417 72 24418 73 24419 74 24420 75 24421 76 24422 77 24423 78 24424 24425 Trusted Platform Module Library 24426 24427 // add policyRef 24428 CryptUpdateDigest2B(&hashState, &in->policyRef.b); 24429 // complete hash 24430 CryptCompleteHash2B(&hashState, &authHash.b); 24431 // re-compute TPMT_TK_VERIFIED 24432 TicketComputeVerified(in->checkTicket.hierarchy, &authHash, 24433 &in->keySign, &ticket); 24434 // Compare ticket digest. If not match, return error 24435 if(!Memory2BEqual(&in->checkTicket.digest.b, &ticket.digest.b)) 24436 return TPM_RC_VALUE+ RC_PolicyAuthorize_checkTicket; 24437 } 24438 // Internal Data Update 24439 // Set policyDigest to zero digest 24440 MemorySet(session->u2.policyDigest.t.buffer, 0, 24441 session->u2.policyDigest.t.size); 24442 // Update policyDigest 24443 PolicyContextUpdate(TPM_CC_PolicyAuthorize, &in->keySign, &in->policyRef, 24444 NULL, 0, session); 24445 return TPM_RC_SUCCESS; 24446 } 24447 24448 Page 290 24449 October 31, 2013 24450 24451 Published 24452 Copyright TCG 2006-2013 24453 24454 Family 2.0 24455 Level 00 Revision 00.99 24456 24457 Trusted Platform Module Library 24459 24460 Part 3: Commands 24461 24462 25.17 TPM2_PolicyAuthValue 24463 25.17.1 24464 24465 General Description 24466 24467 This command allows a policy to be bound to the authorization value of the authorized object. 24468 When this command completes successfully, policySessionisAuthValueNeeded is SET to indicate that 24469 the authValue will be included in hmacKey when the authorization HMAC is computed for this session. 24470 Additionally, policySessionisPasswordNeeded will be CLEAR. 24471 NOTE 24472 24473 If a policy does not use this command, then the hmacKey for the authorized command would only 24474 use sessionKey. If sessionKey is not present, then the hmacKey is an Empty Buffer and no HMAC 24475 would be computed. 24476 24477 If successful, policySessionpolicyDigest will be updated with 24478 24479 policyDigestnew HpolicyAlg(policyDigestold || TPM_CC_PolicyAuthValue) 24480 24481 Family 2.0 24482 Level 00 Revision 00.99 24483 24484 Published 24485 Copyright TCG 2006-2013 24486 24487 (36) 24488 24489 Page 291 24490 October 31, 2013 24491 24492 Part 3: Commands 24494 24495 25.17.2 24496 24497 Trusted Platform Module Library 24498 24499 Command and Response 24500 Table 141 TPM2_PolicyAuthValue Command 24501 24502 Type 24503 24504 Name 24505 24506 Description 24507 24508 TPMI_ST_COMMAND_TAG 24509 24510 tag 24511 24512 UINT32 24513 24514 commandSize 24515 24516 TPM_CC 24517 24518 commandCode 24519 24520 TPM_CC_PolicyAuthValue 24521 24522 TPMI_SH_POLICY 24523 24524 policySession 24525 24526 handle for the policy session being extended 24527 Auth Index: None 24528 24529 Table 142 TPM2_PolicyAuthValue Response 24530 Type 24531 24532 Name 24533 24534 Description 24535 24536 TPM_ST 24537 24538 tag 24539 24540 see clause 8 24541 24542 UINT32 24543 24544 responseSize 24545 24546 TPM_RC 24547 24548 responseCode 24549 24550 Page 292 24551 October 31, 2013 24552 24553 Published 24554 Copyright TCG 2006-2013 24555 24556 Family 2.0 24557 Level 00 Revision 00.99 24558 24559 Trusted Platform Module Library 24561 24562 25.17.3 24563 1 24564 2 24565 3 24566 4 24567 5 24568 6 24569 7 24570 8 24571 9 24572 10 24573 11 24574 12 24575 13 24576 14 24577 15 24578 16 24579 17 24580 18 24581 19 24582 20 24583 21 24584 22 24585 23 24586 24 24587 25 24588 26 24589 27 24590 28 24591 29 24592 30 24593 31 24594 32 24595 33 24596 34 24597 35 24598 36 24599 37 24600 24601 Part 3: Commands 24602 24603 Detailed Actions 24604 24605 #include "InternalRoutines.h" 24606 #include "PolicyAuthValue_fp.h" 24607 #include "Policy_spt_fp.h" 24608 24609 TPM_RC 24610 TPM2_PolicyAuthValue( 24611 PolicyAuthValue_In 24612 24613 *in 24614 24615 // IN: input parameter list 24616 24617 SESSION 24618 TPM_CC 24619 HASH_STATE 24620 24621 *session; 24622 commandCode = TPM_CC_PolicyAuthValue; 24623 hashState; 24624 24625 ) 24626 { 24627 24628 // Internal Data Update 24629 // Get pointer to the session structure 24630 session = SessionGet(in->policySession); 24631 // Update policy hash 24632 // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyAuthValue) 24633 // 24634 Start hash 24635 CryptStartHash(session->authHashAlg, &hashState); 24636 // add old digest 24637 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 24638 // add commandCode 24639 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 24640 // complete the hash and get the results 24641 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 24642 // update isAuthValueNeeded bit in the session context 24643 session->attributes.isAuthValueNeeded = SET; 24644 session->attributes.isPasswordNeeded = CLEAR; 24645 return TPM_RC_SUCCESS; 24646 } 24647 24648 Family 2.0 24649 Level 00 Revision 00.99 24650 24651 Published 24652 Copyright TCG 2006-2013 24653 24654 Page 293 24655 October 31, 2013 24656 24657 Part 3: Commands 24659 24660 Trusted Platform Module Library 24661 24662 25.18 TPM2_PolicyPassword 24663 25.18.1 24664 24665 General Description 24666 24667 This command allows a policy to be bound to the authorization value of the authorized object. 24668 When this command completes successfully, policySessionisPasswordNeeded is SET to indicate that 24669 authValue of the authorized object will be checked when the session is used for authorization. The caller 24670 will provide the authValue in clear text in the hmac parameter of the authorization. The comparison of 24671 hmac to authValue is performed as if the authorization is a password. 24672 NOTE 1 24673 24674 The parameter field in the policy session where the authorization value is provided is called hmac. If 24675 TPM2_PolicyPassword() is part of the sequence, then the field will contain a password and not an 24676 HMAC. 24677 24678 If successful, policySessionpolicyDigest will be updated with 24679 24680 policyDigestnew HpolicyAlg(policyDigestold || TPM_CC_PolicyAuthValue) 24681 NOTE 2 24682 24683 (37) 24684 24685 This is the same extend value as used with TPM2_PolicyAuthValue so that the evaluation may be 24686 done using either an HMAC or a password with no change to the authPolicy of the object. The 24687 reason that two commands are present is to indicate to the TPM if the hmac field in the authorization 24688 will contain an HMAC or a password value. 24689 24690 When this command is successful, policySessionisAuthValueNeeded will be CLEAR. 24691 24692 Page 294 24693 October 31, 2013 24694 24695 Published 24696 Copyright TCG 2006-2013 24697 24698 Family 2.0 24699 Level 00 Revision 00.99 24700 24701 Trusted Platform Module Library 24703 24704 25.18.2 24705 24706 Part 3: Commands 24707 24708 Command and Response 24709 Table 143 TPM2_PolicyPassword Command 24710 24711 Type 24712 24713 Name 24714 24715 Description 24716 24717 TPMI_ST_COMMAND_TAG 24718 24719 tag 24720 24721 UINT32 24722 24723 commandSize 24724 24725 TPM_CC 24726 24727 commandCode 24728 24729 TPM_CC_PolicyPassword 24730 24731 TPMI_SH_POLICY 24732 24733 policySession 24734 24735 handle for the policy session being extended 24736 Auth Index: None 24737 24738 Table 144 TPM2_PolicyPassword Response 24739 Type 24740 24741 Name 24742 24743 Description 24744 24745 TPM_ST 24746 24747 tag 24748 24749 see clause 8 24750 24751 UINT32 24752 24753 responseSize 24754 24755 TPM_RC 24756 24757 responseCode 24758 24759 Family 2.0 24760 Level 00 Revision 00.99 24761 24762 Published 24763 Copyright TCG 2006-2013 24764 24765 Page 295 24766 October 31, 2013 24767 24768 Part 3: Commands 24770 24771 25.18.3 24772 1 24773 2 24774 3 24775 4 24776 5 24777 6 24778 7 24779 8 24780 9 24781 10 24782 11 24783 12 24784 13 24785 14 24786 15 24787 16 24788 17 24789 18 24790 19 24791 20 24792 21 24793 22 24794 23 24795 24 24796 25 24797 26 24798 27 24799 28 24800 29 24801 30 24802 31 24803 32 24804 33 24805 34 24806 35 24807 36 24808 37 24809 24810 Trusted Platform Module Library 24811 24812 Detailed Actions 24813 24814 #include "InternalRoutines.h" 24815 #include "PolicyPassword_fp.h" 24816 #include "Policy_spt_fp.h" 24817 24818 TPM_RC 24819 TPM2_PolicyPassword( 24820 PolicyPassword_In 24821 24822 *in 24823 24824 // IN: input parameter list 24825 24826 SESSION 24827 TPM_CC 24828 HASH_STATE 24829 24830 *session; 24831 commandCode = TPM_CC_PolicyAuthValue; 24832 hashState; 24833 24834 ) 24835 { 24836 24837 // Internal Data Update 24838 // Get pointer to the session structure 24839 session = SessionGet(in->policySession); 24840 // Update policy hash 24841 // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyAuthValue) 24842 // Start hash 24843 CryptStartHash(session->authHashAlg, &hashState); 24844 // add old digest 24845 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 24846 // add commandCode 24847 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 24848 // complete the digest 24849 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 24850 // Update isPasswordNeeded bit 24851 session->attributes.isPasswordNeeded = SET; 24852 session->attributes.isAuthValueNeeded = CLEAR; 24853 return TPM_RC_SUCCESS; 24854 } 24855 24856 Page 296 24857 October 31, 2013 24858 24859 Published 24860 Copyright TCG 2006-2013 24861 24862 Family 2.0 24863 Level 00 Revision 00.99 24864 24865 Trusted Platform Module Library 24867 24868 Part 3: Commands 24869 24870 25.19 TPM2_PolicyGetDigest 24871 25.19.1 24872 24873 General Description 24874 24875 This command returns the current policyDigest of the session. This command allows the TPM to be used 24876 to perform the actions required to pre-compute the authPolicy for an object. 24877 24878 Family 2.0 24879 Level 00 Revision 00.99 24880 24881 Published 24882 Copyright TCG 2006-2013 24883 24884 Page 297 24885 October 31, 2013 24886 24887 Part 3: Commands 24889 24890 25.19.2 24891 24892 Trusted Platform Module Library 24893 24894 Command and Response 24895 Table 145 TPM2_PolicyGetDigest Command 24896 24897 Type 24898 24899 Name 24900 24901 Description 24902 24903 TPMI_ST_COMMAND_TAG 24904 24905 tag 24906 24907 UINT32 24908 24909 commandSize 24910 24911 TPM_CC 24912 24913 commandCode 24914 24915 TPM_CC_PolicyGetDigest 24916 24917 TPMI_SH_POLICY 24918 24919 policySession 24920 24921 handle for the policy session 24922 Auth Index: None 24923 24924 Table 146 TPM2_PolicyGetDigest Response 24925 Type 24926 24927 Name 24928 24929 Description 24930 24931 TPM_ST 24932 24933 tag 24934 24935 see clause 8 24936 24937 UINT32 24938 24939 responseSize 24940 24941 TPM_RC 24942 24943 responseCode 24944 24945 TPM2B_DIGEST 24946 24947 policyDigest 24948 24949 Page 298 24950 October 31, 2013 24951 24952 the current value of the policySessionpolicyDigest 24953 24954 Published 24955 Copyright TCG 2006-2013 24956 24957 Family 2.0 24958 Level 00 Revision 00.99 24959 24960 Trusted Platform Module Library 24962 24963 25.19.3 24964 1 24965 2 24966 3 24967 4 24968 5 24969 6 24970 7 24971 8 24972 9 24973 10 24974 11 24975 12 24976 13 24977 14 24978 15 24979 16 24980 17 24981 18 24982 19 24983 24984 Part 3: Commands 24985 24986 Detailed Actions 24987 24988 #include "InternalRoutines.h" 24989 #include "PolicyGetDigest_fp.h" 24990 24991 TPM_RC 24992 TPM2_PolicyGetDigest( 24993 PolicyGetDigest_In 24994 PolicyGetDigest_Out 24995 24996 *in, 24997 *out 24998 24999 // IN: input parameter list 25000 // OUT: output parameter list 25001 25002 ) 25003 { 25004 SESSION 25005 25006 *session; 25007 25008 // Command Output 25009 // Get pointer to the session structure 25010 session = SessionGet(in->policySession); 25011 out->policyDigest = session->u2.policyDigest; 25012 return TPM_RC_SUCCESS; 25013 } 25014 25015 Family 2.0 25016 Level 00 Revision 00.99 25017 25018 Published 25019 Copyright TCG 2006-2013 25020 25021 Page 299 25022 October 31, 2013 25023 25024 Part 3: Commands 25026 25027 Trusted Platform Module Library 25028 25029 25.20 TPM2_PolicyNvWritten 25030 25.20.1 25031 25032 General Description 25033 25034 This command allows a policy to be bound to the TPMA_NV_WRITTEN attributes. This is a deferred 25035 assertion. Values are stored in the policy session context and checked when the policy is used for 25036 authorization. 25037 If policySessioncheckNVWritten is CLEAR, it is SET and policySessionnvWrittenState is set to 25038 writtenSet. 25039 If policySessioncheckNVWritten is SET, the TPM will return TPM_RC_VALUE if 25040 policySessionnvWrittenState and writtenSet are not the same. 25041 If the TPM does not return and error, it will update policySessionpolicyDigest by 25042 25043 policyDigestnew HpolicyAlg(policyDigestold || TPM_CC_PolicyNvWritten || writtenSet) 25044 25045 (38) 25046 25047 When the policy session is used to authorize a command, the TPM will fail the command if 25048 policySessioncheckNVWritten is SET and nvIndexattributesTPMA_NV_WRITTEN does not match 25049 policySessionnvWrittenState. 25050 NOTE 25051 25052 A typical use case is a simple policy for the first write during manufacturing provisioning that would 25053 require TPMA_NV_WRITTEN CLEAR and a more complex policy for later use that would require 25054 TPMA_NV_WRITTEN SET. 25055 25056 Page 300 25057 October 31, 2013 25058 25059 Published 25060 Copyright TCG 2006-2013 25061 25062 Family 2.0 25063 Level 00 Revision 00.99 25064 25065 Trusted Platform Module Library 25067 25068 25.20.2 25069 25070 Part 3: Commands 25071 25072 Command and Response 25073 Table 147 TPM2_PolicyNvWritten Command 25074 25075 Type 25076 25077 Name 25078 25079 Description 25080 25081 TPMI_ST_COMMAND_TAG 25082 25083 Tag 25084 25085 UINT32 25086 25087 commandSize 25088 25089 TPM_CC 25090 25091 commandCode 25092 25093 TPM_CC_PolicyNVWritten 25094 25095 TPMI_SH_POLICY 25096 25097 policySession 25098 25099 handle for the policy session being extended 25100 Auth Index: None 25101 25102 TPMI_YES_NO 25103 25104 writtenSet 25105 25106 YES if NV Index is required to have been written 25107 NO if NV Index is required not to have been written 25108 25109 Table 148 TPM2_PolicyNvWritten Response 25110 Type 25111 25112 Name 25113 25114 Description 25115 25116 TPM_ST 25117 25118 Tag 25119 25120 see clause 8 25121 25122 UINT32 25123 25124 responseSize 25125 25126 TPM_RC 25127 25128 responseCode 25129 25130 Family 2.0 25131 Level 00 Revision 00.99 25132 25133 Published 25134 Copyright TCG 2006-2013 25135 25136 Page 301 25137 October 31, 2013 25138 25139 Part 3: Commands 25141 25142 25.20.3 25143 1 25144 2 25145 25146 Trusted Platform Module Library 25147 25148 Detailed Actions 25149 25150 #include "InternalRoutines.h" 25151 #include "PolicyNvWritten_fp.h" 25152 25153 Make an NV Index policy dependent on the state of the TPMA_NV_WRITTEN attribute of the index. 25154 Error Returns 25155 TPM_RC_VALUE 25156 3 25157 4 25158 5 25159 6 25160 7 25161 8 25162 9 25163 10 25164 11 25165 12 25166 13 25167 14 25168 15 25169 16 25170 17 25171 18 25172 19 25173 20 25174 21 25175 22 25176 23 25177 24 25178 25 25179 26 25180 27 25181 28 25182 29 25183 30 25184 31 25185 32 25186 33 25187 34 25188 35 25189 36 25190 37 25191 38 25192 39 25193 40 25194 41 25195 42 25196 43 25197 44 25198 45 25199 46 25200 47 25201 48 25202 49 25203 50 25204 51 25205 52 25206 25207 Meaning 25208 a conflicting request for the attribute has already been processed 25209 25210 TPM_RC 25211 TPM2_PolicyNvWritten( 25212 PolicyNvWritten_In 25213 25214 *in 25215 25216 // IN: input parameter list 25217 25218 ) 25219 { 25220 SESSION 25221 TPM_CC 25222 HASH_STATE 25223 25224 *session; 25225 commandCode = TPM_CC_PolicyNvWritten; 25226 hashState; 25227 25228 // Input Validation 25229 // Get pointer to the session structure 25230 session = SessionGet(in->policySession); 25231 // If already set is this a duplicate (the same setting)? If it 25232 // is a conflicting setting, it is an error 25233 if(session->attributes.checkNvWritten == SET) 25234 { 25235 if(( 25236 (session->attributes.nvWrittenState == SET) 25237 != (in->writtenSet == YES))) 25238 return TPM_RC_VALUE + RC_PolicyNvWritten_writtenSet; 25239 } 25240 // Internal Data Update 25241 // Set session attributes so that the NV Index needs to be checked 25242 session->attributes.checkNvWritten = SET; 25243 session->attributes.nvWrittenState = (in->writtenSet == YES); 25244 // Update policy hash 25245 // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyNvWritten 25246 // 25247 || writtenSet) 25248 // Start hash 25249 CryptStartHash(session->authHashAlg, &hashState); 25250 // add old digest 25251 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); 25252 // add commandCode 25253 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); 25254 // add the byte of writtenState 25255 CryptUpdateDigestInt(&hashState, sizeof(TPMI_YES_NO), &in->writtenSet); 25256 // complete the digest 25257 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); 25258 return TPM_RC_SUCCESS; 25259 } 25260 25261 Page 302 25262 October 31, 2013 25263 25264 Published 25265 Copyright TCG 2006-2013 25266 25267 Family 2.0 25268 Level 00 Revision 00.99 25269 25270 Trusted Platform Module Library 25272 25273 Family 2.0 25274 Level 00 Revision 00.99 25275 25276 Part 3: Commands 25277 25278 Published 25279 Copyright TCG 2006-2013 25280 25281 Page 303 25282 October 31, 2013 25283 25284 Part 3: Commands 25286 25287 26 25288 25289 Trusted Platform Module Library 25290 25291 Hierarchy Commands 25292 25293 26.1 25294 25295 TPM2_CreatePrimary 25296 25297 26.1.1 General Description 25298 This command is used to create a Primary Object under one of the Primary Seeds or a Temporary Object 25299 under TPM_RH_NULL. The command uses a TPM2B_PUBLIC as a template for the object to be created. 25300 The command will create and load a Primary Object. The sensitive area is not returned. 25301 NOTE: 25302 25303 Since the sensitive data is not returned, the key cannot be reloaded. 25304 persistent or it can be recreated. 25305 25306 It can either be made 25307 25308 Any type of object and attributes combination that is allowed by TPM2_Create() may be created by this 25309 command. The constraints on templates and parameters are the same as TPM2_Create() except that a 25310 Primary Storage Key and a Temporary Storage Key are not constrained to use the algorithms of their 25311 parents. 25312 For setting of the attributes of the created object, fixedParent, fixedTPM, userWithAuth, adminWithPolicy, 25313 encrypt, and restricted are implied to be SET in the parent (a Permanent Handle). The remaining 25314 attributes are implied to be CLEAR. 25315 The TPM will derive the object from the Primary Seed indicated in primaryHandle using an approved 25316 KDF. All of the bits of the template are used in the creation of the Primary Key. Methods for creating a 25317 Primary Object from a Primary Seed are described in Part 1 of this specification and implemented in Part 25318 4. 25319 If this command is called multiple times with the same inPublic parameter, inSensitive.data, and Primary 25320 Seed, the TPM shall produce the same Primary Object. 25321 NOTE 25322 25323 If the Primary Seed is changed, the Primary Objects generated with the new seed shall be 25324 statistically unique even if the parameters of the call are the same. 25325 25326 This command requires authorization. Authorization for a Primary Object attached to the Platform Primary 25327 Seed (PPS) shall be provided by platformAuth or platformPolicy. Authorization for a Primary Object 25328 attached to the Storage Primary Seed (SPS) shall be provided by ownerAuth or ownerPolicy. 25329 Authorization for a Primary Key attached to the Endorsement Primary Seed (EPS) shall be provided by 25330 endorsementAuth or endorsementPolicy. 25331 25332 Page 304 25333 October 31, 2013 25334 25335 Published 25336 Copyright TCG 2006-2013 25337 25338 Family 2.0 25339 Level 00 Revision 00.99 25340 25341 Trusted Platform Module Library 25343 25344 Part 3: Commands 25345 25346 26.1.2 Command and Response 25347 Table 149 TPM2_CreatePrimary Command 25348 Type 25349 25350 Name 25351 25352 Description 25353 25354 TPMI_ST_COMMAND_TAG 25355 25356 tag 25357 25358 UINT32 25359 25360 commandSize 25361 25362 TPM_CC 25363 25364 commandCode 25365 25366 TPM_CC_CreatePrimary 25367 25368 TPMI_RH_HIERARCHY+ 25369 25370 @primaryHandle 25371 25372 TPM_RH_ENDORSEMENT, TPM_RH_OWNER, 25373 TPM_RH_PLATFORM+{PP}, or TPM_RH_NULL 25374 Auth Index: 1 25375 Auth Role: USER 25376 25377 TPM2B_SENSITIVE_CREATE 25378 25379 inSensitive 25380 25381 the sensitive data, see Part 1 Sensitive Values 25382 25383 TPM2B_PUBLIC 25384 25385 inPublic 25386 25387 the public template 25388 25389 TPM2B_DATA 25390 25391 outsideInfo 25392 25393 data that will be included in the creation data for this 25394 object to provide permanent, verifiable linkage between 25395 this object and some object owner data 25396 25397 TPML_PCR_SELECTION 25398 25399 creationPCR 25400 25401 PCR that will be used in creation data 25402 25403 Table 150 TPM2_CreatePrimary Response 25404 Type 25405 25406 Name 25407 25408 Description 25409 25410 TPM_ST 25411 25412 tag 25413 25414 see clause 8 25415 25416 UINT32 25417 25418 responseSize 25419 25420 TPM_RC 25421 25422 responseCode 25423 25424 TPM_HANDLE 25425 25426 objectHandle 25427 25428 Handle for created Primary Object 25429 25430 TPM2B_PUBLIC 25431 25432 outPublic 25433 25434 the public portion of the created object 25435 25436 TPM2B_CREATION_DATA 25437 25438 creationData 25439 25440 contains a TPMT_CREATION_DATA 25441 25442 TPM2B_DIGEST 25443 25444 creationHash 25445 25446 digest of creationData using nameAlg of outPublic 25447 25448 TPMT_TK_CREATION 25449 25450 creationTicket 25451 25452 ticket used by TPM2_CertifyCreation() to validate that 25453 the creation data was produced by the TPM 25454 25455 TPM2B_NAME 25456 25457 name 25458 25459 the name of the created object 25460 25461 Family 2.0 25462 Level 00 Revision 00.99 25463 25464 Published 25465 Copyright TCG 2006-2013 25466 25467 Page 305 25468 October 31, 2013 25469 25470 Part 3: Commands 25472 25473 Trusted Platform Module Library 25474 25475 26.1.3 Detailed Actions 25476 1 25477 2 25478 3 25479 4 25480 25481 #include 25482 #include 25483 #include 25484 #include 25485 25486 "InternalRoutines.h" 25487 "CreatePrimary_fp.h" 25488 "Object_spt_fp.h" 25489 <Platform.h> 25490 25491 Error Returns 25492 TPM_RC_ATTRIBUTES 25493 25494 sensitiveDataOrigin is CLEAR when 'sensitive. data' is an Empty 25495 Buffer, or is SET when 'sensitive. data' is not empty; fixedTPM, 25496 fixedParent, or encryptedDuplication attributes are inconsistent 25497 between themselves or with those of the parent object; inconsistent 25498 restricted, decrypt and sign attributes; attempt to inject sensitive data 25499 for an asymmetric key; attempt to create a symmetric cipher key that 25500 is not a decryption key 25501 25502 TPM_RC_KDF 25503 25504 incorrect KDF specified for decrypting keyed hash object 25505 25506 TPM_RC_OBJECT_MEMORY 25507 25508 there is no free slot for the object 25509 25510 TPM_RC_SCHEME 25511 25512 inconsistent attributes decrypt, sign, restricted and key's scheme ID; 25513 or hash algorithm is inconsistent with the scheme ID for keyed hash 25514 object 25515 25516 TPM_RC_SIZE 25517 25518 size of public auth policy or sensitive auth value does not match 25519 digest size of the name algorithm sensitive data size for the keyed 25520 hash object is larger than is allowed for the scheme 25521 25522 TPM_RC_SYMMETRIC 25523 25524 a storage key with no symmetric algorithm specified; or non-storage 25525 key with symmetric algorithm different from TPM_ALG_NULL 25526 25527 TPM_RC_TYPE 25528 5 25529 6 25530 7 25531 8 25532 9 25533 10 25534 11 25535 12 25536 13 25537 14 25538 15 25539 16 25540 17 25541 18 25542 19 25543 20 25544 21 25545 22 25546 23 25547 24 25548 25 25549 26 25550 27 25551 28 25552 29 25553 30 25554 31 25555 32 25556 33 25557 25558 Meaning 25559 25560 unknown object type; 25561 25562 TPM_RC 25563 TPM2_CreatePrimary( 25564 CreatePrimary_In 25565 CreatePrimary_Out 25566 ) 25567 { 25568 // Local variables 25569 TPM_RC 25570 TPMT_SENSITIVE 25571 25572 *in, 25573 *out 25574 25575 // IN: input parameter list 25576 // OUT: output parameter list 25577 25578 result = TPM_RC_SUCCESS; 25579 sensitive; 25580 25581 // Input Validation 25582 // The sensitiveDataOrigin attribute must be consistent with the setting of 25583 // the size of the data object in inSensitive. 25584 if( 25585 (in->inPublic.t.publicArea.objectAttributes.sensitiveDataOrigin == SET) 25586 != (in->inSensitive.t.sensitive.data.t.size == 0 )) 25587 // Mismatch between the object attributes and the parameter. 25588 return TPM_RC_ATTRIBUTES + RC_CreatePrimary_inSensitive; 25589 // Check attributes in input public area. TPM_RC_ATTRIBUTES, TPM_RC_KDF, 25590 // TPM_RC_SCHEME, TPM_RC_SIZE, TPM_RC_SYMMETRIC, or TPM_RC_TYPE error may 25591 // be returned at this point. 25592 result = PublicAttributesValidation(FALSE, in->primaryHandle, 25593 &in->inPublic.t.publicArea); 25594 if(result != TPM_RC_SUCCESS) 25595 return RcSafeAddToResult(result, RC_CreatePrimary_inPublic); 25596 // Validate the sensitive area values 25597 if( MemoryRemoveTrailingZeros(&in->inSensitive.t.sensitive.userAuth) 25598 > CryptGetHashDigestSize(in->inPublic.t.publicArea.nameAlg)) 25599 25600 Page 306 25601 October 31, 2013 25602 25603 Published 25604 Copyright TCG 2006-2013 25605 25606 Family 2.0 25607 Level 00 Revision 00.99 25608 25609 Trusted Platform Module Library 25611 34 25612 35 25613 36 25614 37 25615 38 25616 39 25617 40 25618 41 25619 42 25620 43 25621 44 25622 45 25623 46 25624 47 25625 48 25626 49 25627 50 25628 51 25629 52 25630 53 25631 54 25632 55 25633 56 25634 57 25635 58 25636 59 25637 60 25638 61 25639 62 25640 63 25641 64 25642 65 25643 66 25644 67 25645 68 25646 69 25647 25648 Part 3: Commands 25649 25650 return TPM_RC_SIZE + RC_CreatePrimary_inSensitive; 25651 // Command output 25652 // Generate Primary Object 25653 // The primary key generation process uses the Name of the input public 25654 // template to compute the key. The keys are generated from the template 25655 // before anything in the template is allowed to be changed. 25656 // A TPM_RC_KDF, TPM_RC_SIZE error may be returned at this point 25657 result = CryptCreateObject(in->primaryHandle, &in->inPublic.t.publicArea, 25658 &in->inSensitive.t.sensitive,&sensitive); 25659 if(result != TPM_RC_SUCCESS) 25660 return result; 25661 // Fill in creation data 25662 FillInCreationData(in->primaryHandle, in->inPublic.t.publicArea.nameAlg, 25663 &in->creationPCR, &in->outsideInfo, &out->creationData, 25664 &out->creationHash); 25665 // Copy public area 25666 out->outPublic = in->inPublic; 25667 // Fill in private area for output 25668 ObjectComputeName(&(out->outPublic.t.publicArea), &out->name); 25669 // Compute creation ticket 25670 TicketComputeCreation(EntityGetHierarchy(in->primaryHandle), &out->name, 25671 &out->creationHash, &out->creationTicket); 25672 // Create a internal object. A TPM_RC_OBJECT_MEMORY error may be returned 25673 // at this point. 25674 result = ObjectLoad(in->primaryHandle, &in->inPublic.t.publicArea, &sensitive, 25675 &out->name, in->primaryHandle, TRUE, &out->objectHandle); 25676 return result; 25677 } 25678 25679 Family 2.0 25680 Level 00 Revision 00.99 25681 25682 Published 25683 Copyright TCG 2006-2013 25684 25685 Page 307 25686 October 31, 2013 25687 25688 Part 3: Commands 25690 25691 26.2 25692 25693 Trusted Platform Module Library 25694 25695 TPM2_HierarchyControl 25696 25697 26.2.1 General Description 25698 This command enables and disables use of a hierarchy and its associated NV storage. The command 25699 allows phEnable, phEnableNV, shEnable, and ehEnable to be changed when the proper authorization is 25700 provided. 25701 This command may be used to CLEAR phEnable and phEnableNV if platformAuth/platformPolicy is 25702 provided. phEnable may not be SET using this command. 25703 This command may be used to CLEAR shEnable if either platformAuth/platformPolicy 25704 ownerAuth/ownerPolicy is provided. shEnable may be SET if platformAuth/platformPolicy is provided. 25705 25706 or 25707 25708 This command may be used to CLEAR ehEnable if either platformAuth/platformPolicy or 25709 endorsementAuth/endorsementPolicy is provided. ehEnable may be SET if platformAuth/platformPolicy is 25710 provided. 25711 When this command is used to CLEAR phEnable, shEnable, or ehEnable, the TPM will disable use of 25712 any persistent entity associated with the disabled hierarchy and will flush any transient objects associated 25713 with the disabled hierarchy. 25714 When this command is used to CLEAR shEnable, the TPM will disable access to any NV index that has 25715 TPMA_NV_PLATFORMCREATE CLEAR (indicating that the NV Index was defined using ownerAuth). As 25716 long as shEnable is CLEAR, the TPM will return an error in response to any command that attempts to 25717 operate upon an NV index that has TPMA_NV_PLATFORMCREATE CLEAR. 25718 When this command is used to CLEAR phEnableNV, the TPM will disable access to any NV index that 25719 has TPMA_NV_PLATFORMCREATE SET (indicating that the NV Index was defined using platformAuth). 25720 As long as phEnableNV is CLEAR, the TPM will return an error in response to any command that 25721 attempts to operate upon an NV index that has TPMA_NV_PLATFORMCREATE SET. 25722 25723 Page 308 25724 October 31, 2013 25725 25726 Published 25727 Copyright TCG 2006-2013 25728 25729 Family 2.0 25730 Level 00 Revision 00.99 25731 25732 Trusted Platform Module Library 25734 25735 Part 3: Commands 25736 25737 26.2.2 Command and Response 25738 Table 151 TPM2_HierarchyControl Command 25739 Type 25740 25741 Name 25742 25743 Description 25744 25745 TPMI_ST_COMMAND_TAG 25746 25747 tag 25748 25749 UINT32 25750 25751 commandSize 25752 25753 TPM_CC 25754 25755 commandCode 25756 25757 TPM_CC_HierarchyControl {NV E} 25758 25759 TPMI_RH_HIERARCHY 25760 25761 @authHandle 25762 25763 TPM_RH_ENDORSEMENT, TPM_RH_OWNER or 25764 TPM_RH_PLATFORM+{PP} 25765 Auth Index: 1 25766 Auth Role: USER 25767 25768 TPMI_RH_ENABLES 25769 25770 enable 25771 25772 the enable being modified 25773 TPM_RH_ENDORSEMENT, TPM_RH_OWNER, 25774 TPM_RH_PLATFORM, or TPM_RH_PLATFORM_NV 25775 25776 TPMI_YES_NO 25777 25778 state 25779 25780 YES if the enable should be SET, NO if the enable 25781 should be CLEAR 25782 25783 Table 152 TPM2_HierarchyControl Response 25784 Type 25785 25786 Name 25787 25788 Description 25789 25790 TPM_ST 25791 25792 tag 25793 25794 see clause 8 25795 25796 UINT32 25797 25798 responseSize 25799 25800 TPM_RC 25801 25802 responseCode 25803 25804 Family 2.0 25805 Level 00 Revision 00.99 25806 25807 Published 25808 Copyright TCG 2006-2013 25809 25810 Page 309 25811 October 31, 2013 25812 25813 Part 3: Commands 25815 25816 Trusted Platform Module Library 25817 25818 26.2.3 Detailed Actions 25819 1 25820 2 25821 25822 #include "InternalRoutines.h" 25823 #include "HierarchyControl_fp.h" 25824 Error Returns 25825 TPM_RC_AUTH_TYPE 25826 25827 3 25828 4 25829 5 25830 6 25831 7 25832 8 25833 9 25834 10 25835 11 25836 12 25837 13 25838 14 25839 15 25840 16 25841 17 25842 18 25843 19 25844 20 25845 21 25846 22 25847 23 25848 24 25849 25 25850 26 25851 27 25852 28 25853 29 25854 30 25855 31 25856 32 25857 33 25858 34 25859 35 25860 36 25861 37 25862 38 25863 39 25864 40 25865 41 25866 42 25867 43 25868 44 25869 45 25870 46 25871 47 25872 48 25873 49 25874 50 25875 51 25876 52 25877 53 25878 54 25879 25880 Meaning 25881 authHandle is not applicable to hierarchy in its current state 25882 25883 TPM_RC 25884 TPM2_HierarchyControl( 25885 HierarchyControl_In 25886 25887 *in 25888 25889 // IN: input parameter list 25890 25891 ) 25892 { 25893 TPM_RC 25894 BOOL 25895 BOOL 25896 25897 result; 25898 select = (in->state == YES); 25899 *selected = NULL; 25900 25901 // Input Validation 25902 switch(in->enable) 25903 { 25904 // Platform hierarchy has to be disabled by platform auth 25905 // If the platform hierarchy has already been disabled, only a reboot 25906 // can enable it again 25907 case TPM_RH_PLATFORM: 25908 case TPM_RH_PLATFORM_NV: 25909 if(in->authHandle != TPM_RH_PLATFORM) 25910 return TPM_RC_AUTH_TYPE; 25911 break; 25912 // ShEnable may be disabled if PlatformAuth/PlatformPolicy or 25913 // OwnerAuth/OwnerPolicy is provided. If ShEnable is disabled, then it 25914 // may only be enabled if PlatformAuth/PlatformPolicy is provided. 25915 case TPM_RH_OWNER: 25916 if( 25917 in->authHandle != TPM_RH_PLATFORM 25918 && in->authHandle != TPM_RH_OWNER) 25919 return TPM_RC_AUTH_TYPE; 25920 if( 25921 gc.shEnable == FALSE && in->state == YES 25922 && in->authHandle != TPM_RH_PLATFORM) 25923 return TPM_RC_AUTH_TYPE; 25924 break; 25925 // EhEnable may be disabled if either PlatformAuth/PlatformPolicy or 25926 // EndosementAuth/EndorsementPolicy is provided. If EhEnable is disabled, 25927 // then it may only be enabled if PlatformAuth/PlatformPolicy is 25928 // provided. 25929 case TPM_RH_ENDORSEMENT: 25930 if( 25931 in->authHandle != TPM_RH_PLATFORM 25932 && in->authHandle != TPM_RH_ENDORSEMENT) 25933 return TPM_RC_AUTH_TYPE; 25934 if( 25935 gc.ehEnable == FALSE && in->state == YES 25936 && in->authHandle != TPM_RH_PLATFORM) 25937 return TPM_RC_AUTH_TYPE; 25938 break; 25939 default: 25940 pAssert(FALSE); 25941 break; 25942 } 25943 // Internal Data Update 25944 25945 Page 310 25946 October 31, 2013 25947 25948 Published 25949 Copyright TCG 2006-2013 25950 25951 Family 2.0 25952 Level 00 Revision 00.99 25953 25954 Trusted Platform Module Library 25956 55 25957 56 25958 57 25959 58 25960 59 25961 60 25962 61 25963 62 25964 63 25965 64 25966 65 25967 66 25968 67 25969 68 25970 69 25971 70 25972 71 25973 72 25974 73 25975 74 25976 75 25977 76 25978 77 25979 78 25980 79 25981 80 25982 81 25983 82 25984 83 25985 84 25986 85 25987 86 25988 87 25989 88 25990 89 25991 90 25992 91 25993 92 25994 93 25995 94 25996 95 25997 96 25998 97 25999 98 26000 99 26001 100 26002 101 26003 102 26004 103 26005 104 26006 105 26007 106 26008 107 26009 26010 Part 3: Commands 26011 26012 // Enable or disable the selected hierarchy 26013 // Note: the authorization processing for this command may keep these 26014 // command actions from being executed. For example, if phEnable is 26015 // CLEAR, then platformAuth cannot be used for authorization. This 26016 // means that would not be possible to use platformAuth to change the 26017 // state of phEnable from CLEAR to SET. 26018 // If it is decided that platformPolicy can still be used when phEnable 26019 // is CLEAR, then this code could SET phEnable when proper platform 26020 // policy is provided. 26021 switch(in->enable) 26022 { 26023 case TPM_RH_OWNER: 26024 selected = &gc.shEnable; 26025 break; 26026 case TPM_RH_ENDORSEMENT: 26027 selected = &gc.ehEnable; 26028 break; 26029 case TPM_RH_PLATFORM: 26030 selected = &g_phEnable; 26031 break; 26032 case TPM_RH_PLATFORM_NV: 26033 selected = &gc.phEnableNV; 26034 break; 26035 default: 26036 pAssert(FALSE); 26037 break; 26038 } 26039 if(selected != NULL && *selected != select) 26040 { 26041 // Before changing the internal state, make sure that NV is available. 26042 // Only need to update NV if changing the orderly state 26043 if(gp.orderlyState != SHUTDOWN_NONE) 26044 { 26045 // The command needs NV update. Check if NV is available. 26046 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 26047 // this point 26048 result = NvIsAvailable(); 26049 if(result != TPM_RC_SUCCESS) 26050 return result; 26051 } 26052 // state is changing and NV is available so modify 26053 *selected = select; 26054 // If a hierarchy was just disabled, flush it 26055 if(select == CLEAR && in->enable != TPM_RH_PLATFORM_NV) 26056 // Flush hierarchy 26057 ObjectFlushHierarchy(in->enable); 26058 // orderly state should be cleared because of the update to state clear data 26059 // This gets processed in ExecuteCommand() on the way out. 26060 g_clearOrderly = TRUE; 26061 } 26062 return TPM_RC_SUCCESS; 26063 } 26064 26065 Family 2.0 26066 Level 00 Revision 00.99 26067 26068 Published 26069 Copyright TCG 2006-2013 26070 26071 Page 311 26072 October 31, 2013 26073 26074 Part 3: Commands 26076 26077 26.3 26078 26079 Trusted Platform Module Library 26080 26081 TPM2_SetPrimaryPolicy 26082 26083 26.3.1 General Description 26084 This command allows setting of the authorization policy for the platform hierarchy (platformPolicy), the 26085 storage hierarchy (ownerPolicy), and the endorsement hierarchy (endorsementPolicy). 26086 The command requires an authorization session. The session shall use the current authValue or satisfy 26087 the current authPolicy for the referenced hierarchy. 26088 The policy that is changed is the policy associated with authHandle. 26089 If the enable associated with authHandle is not SET, then the associated authorization values (authValue 26090 or authPolicy) may not be used. 26091 26092 Page 312 26093 October 31, 2013 26094 26095 Published 26096 Copyright TCG 2006-2013 26097 26098 Family 2.0 26099 Level 00 Revision 00.99 26100 26101 Trusted Platform Module Library 26103 26104 Part 3: Commands 26105 26106 26.3.2 Command and Response 26107 Table 153 TPM2_SetPrimaryPolicy Command 26108 Type 26109 26110 Name 26111 26112 Description 26113 26114 TPMI_ST_COMMAND_TAG 26115 26116 tag 26117 26118 UINT32 26119 26120 commandSize 26121 26122 TPM_CC 26123 26124 commandCode 26125 26126 TPM_CC_SetPrimaryPolicy {NV} 26127 26128 TPMI_RH_HIERARCHY 26129 26130 @authHandle 26131 26132 TPM_RH_ENDORSEMENT, TPM_RH_OWNER or 26133 TPM_RH_PLATFORM+{PP} 26134 Auth Index: 1 26135 Auth Role: USER 26136 26137 TPM2B_DIGEST 26138 26139 authPolicy 26140 26141 an authorization policy digest; may be the Empty Buffer 26142 If hashAlg is TPM_ALG_NULL, then this shall be an 26143 Empty Buffer. 26144 26145 TPMI_ALG_HASH+ 26146 26147 hashAlg 26148 26149 the hash algorithm to use for the policy 26150 If the authPolicy is an Empty Buffer, then this field shall 26151 be TPM_ALG_NULL. 26152 26153 Table 154 TPM2_SetPrimaryPolicy Response 26154 Type 26155 26156 Name 26157 26158 Description 26159 26160 TPM_ST 26161 26162 tag 26163 26164 see clause 8 26165 26166 UINT32 26167 26168 responseSize 26169 26170 TPM_RC 26171 26172 responseCode 26173 26174 Family 2.0 26175 Level 00 Revision 00.99 26176 26177 Published 26178 Copyright TCG 2006-2013 26179 26180 Page 313 26181 October 31, 2013 26182 26183 Part 3: Commands 26185 26186 Trusted Platform Module Library 26187 26188 26.3.3 Detailed Actions 26189 1 26190 2 26191 26192 #include "InternalRoutines.h" 26193 #include "SetPrimaryPolicy_fp.h" 26194 Error Returns 26195 TPM_RC_SIZE 26196 26197 3 26198 4 26199 5 26200 6 26201 7 26202 8 26203 9 26204 10 26205 11 26206 12 26207 13 26208 14 26209 15 26210 16 26211 17 26212 18 26213 19 26214 20 26215 21 26216 22 26217 23 26218 24 26219 25 26220 26 26221 27 26222 28 26223 29 26224 30 26225 31 26226 32 26227 33 26228 34 26229 35 26230 36 26231 37 26232 38 26233 39 26234 40 26235 41 26236 42 26237 43 26238 44 26239 45 26240 46 26241 47 26242 48 26243 49 26244 50 26245 51 26246 52 26247 53 26248 54 26249 26250 Meaning 26251 size of input authPolicy is not consistent with input hash algorithm 26252 26253 TPM_RC 26254 TPM2_SetPrimaryPolicy( 26255 SetPrimaryPolicy_In 26256 26257 *in 26258 26259 // IN: input parameter list 26260 26261 ) 26262 { 26263 TPM_RC 26264 26265 result; 26266 26267 // Input Validation 26268 // Check the authPolicy consistent with hash algorithm 26269 if( 26270 in->authPolicy.t.size != 0 26271 && in->authPolicy.t.size != CryptGetHashDigestSize(in->hashAlg)) 26272 return TPM_RC_SIZE + RC_SetPrimaryPolicy_authPolicy; 26273 // The command need NV update for OWNER and ENDORSEMENT hierarchy, and 26274 // might need orderlyState update for PLATFROM hierarchy. 26275 // Check if NV is available. A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE 26276 // error may be returned at this point 26277 result = NvIsAvailable(); 26278 if(result != TPM_RC_SUCCESS) 26279 return result; 26280 // Internal Data Update 26281 // Set hierarchy policy 26282 switch(in->authHandle) 26283 { 26284 case TPM_RH_OWNER: 26285 gp.ownerAlg = in->hashAlg; 26286 gp.ownerPolicy = in->authPolicy; 26287 NvWriteReserved(NV_OWNER_ALG, &gp.ownerAlg); 26288 NvWriteReserved(NV_OWNER_POLICY, &gp.ownerPolicy); 26289 break; 26290 case TPM_RH_ENDORSEMENT: 26291 gp.endorsementAlg = in->hashAlg; 26292 gp.endorsementPolicy = in->authPolicy; 26293 NvWriteReserved(NV_ENDORSEMENT_ALG, &gp.endorsementAlg); 26294 NvWriteReserved(NV_ENDORSEMENT_POLICY, &gp.endorsementPolicy); 26295 break; 26296 case TPM_RH_PLATFORM: 26297 gc.platformAlg = in->hashAlg; 26298 gc.platformPolicy = in->authPolicy; 26299 // need to update orderly state 26300 g_clearOrderly = TRUE; 26301 break; 26302 default: 26303 pAssert(FALSE); 26304 break; 26305 } 26306 return TPM_RC_SUCCESS; 26307 } 26308 26309 Page 314 26310 October 31, 2013 26311 26312 Published 26313 Copyright TCG 2006-2013 26314 26315 Family 2.0 26316 Level 00 Revision 00.99 26317 26318 Trusted Platform Module Library 26320 26321 26.4 26322 26323 Part 3: Commands 26324 26325 TPM2_ChangePPS 26326 26327 26.4.1 General Description 26328 This replaces the current PPS with a value from the RNG and sets platformPolicy to the default 26329 initialization value (the Empty Buffer). 26330 NOTE 1 26331 26332 A policy that is the Empty Buffer can match no policy. 26333 26334 NOTE 2 26335 26336 platformAuth is not changed. 26337 26338 All loaded transient and persistent objects in the Platform hierarchy are flushed. 26339 Saved contexts in the Platform hierarchy that were created under the old PPS will no longer be able to be 26340 loaded. 26341 The policy hash algorithm for PCR is reset to TPM_ALG_NULL. 26342 This command does not clear any NV Index values. 26343 NOTE 3 26344 26345 Index values belonging to the Platform are preserved because the indexes may have configuration 26346 information that will be the same after the PPS changes. The Platform may remove the indexes that 26347 are no longer needed using TPM2_NV_UndefineSpace(). 26348 26349 This command requires platformAuth. 26350 26351 Family 2.0 26352 Level 00 Revision 00.99 26353 26354 Published 26355 Copyright TCG 2006-2013 26356 26357 Page 315 26358 October 31, 2013 26359 26360 Part 3: Commands 26362 26363 Trusted Platform Module Library 26364 26365 26.4.2 Command and Response 26366 Table 155 TPM2_ChangePPS Command 26367 Type 26368 26369 Name 26370 26371 TPMI_ST_COMMAND_TAG 26372 26373 tag 26374 26375 UINT32 26376 26377 commandSize 26378 26379 TPM_CC 26380 26381 commandCode 26382 26383 TPM_CC_ChangePPS {NV E} 26384 26385 TPMI_RH_PLATFORM 26386 26387 @authHandle 26388 26389 TPM_RH_PLATFORM+{PP} 26390 Auth Index: 1 26391 Auth Role: USER 26392 26393 Description 26394 26395 Table 156 TPM2_ChangePPS Response 26396 Type 26397 26398 Name 26399 26400 Description 26401 26402 TPM_ST 26403 26404 tag 26405 26406 see clause 8 26407 26408 UINT32 26409 26410 responseSize 26411 26412 TPM_RC 26413 26414 responseCode 26415 26416 Page 316 26417 October 31, 2013 26418 26419 Published 26420 Copyright TCG 2006-2013 26421 26422 Family 2.0 26423 Level 00 Revision 00.99 26424 26425 Trusted Platform Module Library 26427 26428 Part 3: Commands 26429 26430 26.4.3 Detailed Actions 26431 1 26432 2 26433 3 26434 4 26435 5 26436 6 26437 7 26438 8 26439 9 26440 10 26441 11 26442 12 26443 13 26444 14 26445 15 26446 16 26447 17 26448 18 26449 19 26450 20 26451 21 26452 22 26453 23 26454 24 26455 25 26456 26 26457 27 26458 28 26459 29 26460 30 26461 31 26462 32 26463 33 26464 34 26465 35 26466 36 26467 37 26468 38 26469 39 26470 40 26471 41 26472 42 26473 43 26474 44 26475 45 26476 46 26477 47 26478 48 26479 49 26480 50 26481 51 26482 52 26483 53 26484 54 26485 26486 #include "InternalRoutines.h" 26487 #include "ChangePPS_fp.h" 26488 26489 TPM_RC 26490 TPM2_ChangePPS( 26491 ChangePPS_In 26492 26493 *in 26494 26495 // IN: input parameter list 26496 26497 ) 26498 { 26499 UINT32 26500 TPM_RC 26501 26502 i; 26503 result; 26504 26505 // Check if NV is available. A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE 26506 // error may be returned at this point 26507 result = NvIsAvailable(); 26508 if(result != TPM_RC_SUCCESS) return result; 26509 // Input parameter is not reference in command action 26510 in = NULL; 26511 // Internal Data Update 26512 // Reset platform hierarchy seed from RNG 26513 CryptGenerateRandom(PRIMARY_SEED_SIZE, gp.PPSeed.t.buffer); 26514 // Create a new phProof value from RNG to prevent the saved platform 26515 // hierarchy contexts being loaded 26516 CryptGenerateRandom(PROOF_SIZE, gp.phProof.t.buffer); 26517 // Set platform authPolicy to null 26518 gc.platformAlg = TPM_ALG_NULL; 26519 gc.platformPolicy.t.size = 0; 26520 // Flush loaded object in platform hierarchy 26521 ObjectFlushHierarchy(TPM_RH_PLATFORM); 26522 // Flush platform evict object and index in NV 26523 NvFlushHierarchy(TPM_RH_PLATFORM); 26524 // Save hierarchy changes to NV 26525 NvWriteReserved(NV_PP_SEED, &gp.PPSeed); 26526 NvWriteReserved(NV_PH_PROOF, &gp.phProof); 26527 // Re-initialize PCR policies 26528 for(i = 0; i < NUM_POLICY_PCR_GROUP; i++) 26529 { 26530 gp.pcrPolicies.hashAlg[i] = TPM_ALG_NULL; 26531 gp.pcrPolicies.policy[i].t.size = 0; 26532 } 26533 NvWriteReserved(NV_PCR_POLICIES, &gp.pcrPolicies); 26534 // orderly state should be cleared because of the update to state clear data 26535 g_clearOrderly = TRUE; 26536 return TPM_RC_SUCCESS; 26537 } 26538 26539 Family 2.0 26540 Level 00 Revision 00.99 26541 26542 Published 26543 Copyright TCG 2006-2013 26544 26545 Page 317 26546 October 31, 2013 26547 26548 Part 3: Commands 26550 26551 26.5 26552 26553 Trusted Platform Module Library 26554 26555 TPM2_ChangeEPS 26556 26557 26.5.1 General Description 26558 This replaces the current EPS with a value from the RNG and sets the Endorsement hierarchy controls to 26559 their default initialization values: ehEnable is SET, endorsementAuth and endorsementPolicy both equal 26560 to the Empty Buffer. It will flush any loaded objects in the EPS hierarchy and not allow objects in the 26561 hierarchy associated with the previous EPS to be loaded. 26562 NOTE 26563 26564 In the reference implementation, ehProof is a non-volatile value from the RNG. It is allowed that the 26565 ehProof be generated by a KDF using both the EPS and SPS as inputs. If generated with a KDF, the 26566 ehProof can be generated on an as-needed basis or made a non-volatile value. 26567 26568 This command requires platformAuth. 26569 26570 Page 318 26571 October 31, 2013 26572 26573 Published 26574 Copyright TCG 2006-2013 26575 26576 Family 2.0 26577 Level 00 Revision 00.99 26578 26579 Trusted Platform Module Library 26581 26582 Part 3: Commands 26583 26584 26.5.2 Command and Response 26585 Table 157 TPM2_ChangeEPS Command 26586 Type 26587 26588 Name 26589 26590 TPMI_ST_COMMAND_TAG 26591 26592 tag 26593 26594 UINT32 26595 26596 commandSize 26597 26598 TPM_CC 26599 26600 commandCode 26601 26602 TPM_CC_ChangeEPS {NV E} 26603 26604 TPMI_RH_PLATFORM 26605 26606 @authHandle 26607 26608 TPM_RH_PLATFORM+{PP} 26609 Auth Handle: 1 26610 Auth Role: USER 26611 26612 Description 26613 26614 Table 158 TPM2_ChangeEPS Response 26615 Type 26616 26617 Name 26618 26619 Description 26620 26621 TPM_ST 26622 26623 tag 26624 26625 see clause 8 26626 26627 UINT32 26628 26629 responseSize 26630 26631 TPM_RC 26632 26633 responseCode 26634 26635 Family 2.0 26636 Level 00 Revision 00.99 26637 26638 Published 26639 Copyright TCG 2006-2013 26640 26641 Page 319 26642 October 31, 2013 26643 26644 Part 3: Commands 26646 26647 Trusted Platform Module Library 26648 26649 26.5.3 Detailed Actions 26650 1 26651 2 26652 3 26653 4 26654 5 26655 6 26656 7 26657 8 26658 9 26659 10 26660 11 26661 12 26662 13 26663 14 26664 15 26665 16 26666 17 26667 18 26668 19 26669 20 26670 21 26671 22 26672 23 26673 24 26674 25 26675 26 26676 27 26677 28 26678 29 26679 30 26680 31 26681 32 26682 33 26683 34 26684 35 26685 36 26686 37 26687 38 26688 39 26689 40 26690 41 26691 42 26692 43 26693 44 26694 45 26695 46 26696 47 26697 48 26698 49 26699 50 26700 51 26701 52 26702 53 26703 54 26704 55 26705 56 26706 26707 #include "InternalRoutines.h" 26708 #include "ChangeEPS_fp.h" 26709 26710 TPM_RC 26711 TPM2_ChangeEPS( 26712 ChangeEPS_In 26713 26714 *in 26715 26716 // IN: input parameter list 26717 26718 ) 26719 { 26720 TPM_RC 26721 26722 result; 26723 26724 // The command needs NV update. Check if NV is available. 26725 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 26726 // this point 26727 result = NvIsAvailable(); 26728 if(result != TPM_RC_SUCCESS) return result; 26729 // Input parameter is not reference in command action 26730 in = NULL; 26731 // Internal Data Update 26732 // Reset endorsement hierarchy seed from RNG 26733 CryptGenerateRandom(PRIMARY_SEED_SIZE, gp.EPSeed.t.buffer); 26734 // Create new ehProof value from RNG 26735 CryptGenerateRandom(PROOF_SIZE, gp.ehProof.t.buffer); 26736 // Enable endorsement hierarchy 26737 gc.ehEnable = TRUE; 26738 // set authValue buffer to zeros 26739 MemorySet(gp.endorsementAuth.t.buffer, 0, gp.endorsementAuth.t.size); 26740 // Set endorsement authValue to null 26741 gp.endorsementAuth.t.size = 0; 26742 // Set endorsement authPolicy to null 26743 gp.endorsementAlg = TPM_ALG_NULL; 26744 gp.endorsementPolicy.t.size = 0; 26745 // Flush loaded object in endorsement hierarchy 26746 ObjectFlushHierarchy(TPM_RH_ENDORSEMENT); 26747 // Flush evict object of endorsement hierarchy stored in NV 26748 NvFlushHierarchy(TPM_RH_ENDORSEMENT); 26749 // Save hierarchy changes to NV 26750 NvWriteReserved(NV_EP_SEED, &gp.EPSeed); 26751 NvWriteReserved(NV_EH_PROOF, &gp.ehProof); 26752 NvWriteReserved(NV_ENDORSEMENT_AUTH, &gp.endorsementAuth); 26753 NvWriteReserved(NV_ENDORSEMENT_ALG, &gp.endorsementAlg); 26754 NvWriteReserved(NV_ENDORSEMENT_POLICY, &gp.endorsementPolicy); 26755 // orderly state should be cleared because of the update to state clear data 26756 g_clearOrderly = TRUE; 26757 return TPM_RC_SUCCESS; 26758 } 26759 26760 Page 320 26761 October 31, 2013 26762 26763 Published 26764 Copyright TCG 2006-2013 26765 26766 Family 2.0 26767 Level 00 Revision 00.99 26768 26769 Trusted Platform Module Library 26771 26772 26.6 26773 26774 Part 3: Commands 26775 26776 TPM2_Clear 26777 26778 26.6.1 General Description 26779 This command removes all TPM context associated with a specific Owner. 26780 The clear operation will: 26781 26782 26783 flush loaded objects (persistent and volatile) in the Storage and Endorsement hierarchies; 26784 26785 26786 26787 delete any NV Index with TPMA_NV_PLATFORMCREATE == CLEAR; 26788 26789 26790 26791 change the SPS to a new value from the TPMs random number generator (RNG), 26792 26793 26794 26795 change shProof and ehProof, 26796 NOTE 26797 26798 The proof values may be set from the RNG or derived from the associated new Primary Seed. If 26799 derived from the Primary Seeds, the derivation of ehProof shall use both the SPS and EPS. The 26800 computation shall use the SPS as an HMAC key and the derived value may then be a parameter 26801 in a second HMAC in which the EPS is the HMAC key. The reference design uses values from 26802 the RNG. 26803 26804 26805 26806 SET shEnable and ehEnable; 26807 26808 26809 26810 set ownerAuth, endorsementAuth, and lockoutAuth to the Empty Buffer; 26811 26812 26813 26814 set ownerPolicy and endorsementPolicy to the Empty Buffer; 26815 26816 26817 26818 set Clock to zero; 26819 26820 26821 26822 set resetCount to zero; 26823 26824 26825 26826 set restartCount to zero; and 26827 26828 26829 26830 set Safe to YES. 26831 26832 This command requires platformAuth or lockoutAuth. If TPM2_ClearControl() has disabled this command, 26833 the TPM shall return TPM_RC_DISABLED. 26834 If this command is authorized using lockoutAuth, the HMAC in the response shall use the new 26835 lockoutAuth value (that is, the Empty Buffer) when computing response HMAC. 26836 26837 Family 2.0 26838 Level 00 Revision 00.99 26839 26840 Published 26841 Copyright TCG 2006-2013 26842 26843 Page 321 26844 October 31, 2013 26845 26846 Part 3: Commands 26848 26849 Trusted Platform Module Library 26850 26851 26.6.2 Command and Response 26852 Table 159 TPM2_Clear Command 26853 Type 26854 26855 Name 26856 26857 TPMI_ST_COMMAND_TAG 26858 26859 tag 26860 26861 UINT32 26862 26863 commandSize 26864 26865 TPM_CC 26866 26867 commandCode 26868 26869 TPM_CC_Clear {NV E} 26870 26871 TPMI_RH_CLEAR 26872 26873 @authHandle 26874 26875 TPM_RH_LOCKOUT or TPM_RH_PLATFORM+{PP} 26876 Auth Handle: 1 26877 Auth Role: USER 26878 26879 Description 26880 26881 Table 160 TPM2_Clear Response 26882 Type 26883 26884 Name 26885 26886 Description 26887 26888 TPM_ST 26889 26890 tag 26891 26892 see clause 8 26893 26894 UINT32 26895 26896 responseSize 26897 26898 TPM_RC 26899 26900 responseCode 26901 26902 Page 322 26903 October 31, 2013 26904 26905 Published 26906 Copyright TCG 2006-2013 26907 26908 Family 2.0 26909 Level 00 Revision 00.99 26910 26911 Trusted Platform Module Library 26913 26914 Part 3: Commands 26915 26916 26.6.3 Detailed Actions 26917 1 26918 2 26919 26920 #include "InternalRoutines.h" 26921 #include "Clear_fp.h" 26922 Error Returns 26923 TPM_RC_DISABLED 26924 26925 3 26926 4 26927 5 26928 6 26929 7 26930 8 26931 9 26932 10 26933 11 26934 12 26935 13 26936 14 26937 15 26938 16 26939 17 26940 18 26941 19 26942 20 26943 21 26944 22 26945 23 26946 24 26947 25 26948 26 26949 27 26950 28 26951 29 26952 30 26953 31 26954 32 26955 33 26956 34 26957 35 26958 36 26959 37 26960 38 26961 39 26962 40 26963 41 26964 42 26965 43 26966 44 26967 45 26968 46 26969 47 26970 48 26971 49 26972 50 26973 51 26974 52 26975 53 26976 54 26977 26978 Meaning 26979 Clear command has been disabled 26980 26981 TPM_RC 26982 TPM2_Clear( 26983 Clear_In 26984 26985 *in 26986 26987 // IN: input parameter list 26988 26989 ) 26990 { 26991 TPM_RC 26992 26993 result; 26994 26995 // Input parameter is not reference in command action 26996 in = NULL; 26997 // The command needs NV update. Check if NV is available. 26998 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 26999 // this point 27000 result = NvIsAvailable(); 27001 if(result != TPM_RC_SUCCESS) return result; 27002 // Input Validation 27003 // If Clear command is disabled, return an error 27004 if(gp.disableClear) 27005 return TPM_RC_DISABLED; 27006 // Internal Data Update 27007 // Reset storage hierarchy seed from RNG 27008 CryptGenerateRandom(PRIMARY_SEED_SIZE, gp.SPSeed.t.buffer); 27009 // Create new shProof and ehProof value from RNG 27010 CryptGenerateRandom(PROOF_SIZE, gp.shProof.t.buffer); 27011 CryptGenerateRandom(PROOF_SIZE, gp.ehProof.t.buffer); 27012 // Enable storage and endorsement hierarchy 27013 gc.shEnable = gc.ehEnable = TRUE; 27014 // set the authValue buffers to zero 27015 MemorySet(gp.ownerAuth.t.buffer, 0, gp.ownerAuth.t.size); 27016 MemorySet(gp.endorsementAuth.t.buffer, 0, gp.endorsementAuth.t.size); 27017 MemorySet(gp.lockoutAuth.t.buffer, 0, gp.lockoutAuth.t.size); 27018 // Set storage, endorsement and lockout authValue to null 27019 gp.ownerAuth.t.size = gp.endorsementAuth.t.size = gp.lockoutAuth.t.size = 0; 27020 // Set storage and endorsement authPolicy to null 27021 gp.ownerAlg = gp.endorsementAlg = TPM_ALG_NULL; 27022 gp.ownerPolicy.t.size = gp.endorsementPolicy.t.size = 0; 27023 // Flush loaded object in storage and endorsement hierarchy 27024 ObjectFlushHierarchy(TPM_RH_OWNER); 27025 ObjectFlushHierarchy(TPM_RH_ENDORSEMENT); 27026 // Flush owner and endorsement object and owner index in NV 27027 NvFlushHierarchy(TPM_RH_OWNER); 27028 NvFlushHierarchy(TPM_RH_ENDORSEMENT); 27029 27030 Family 2.0 27031 Level 00 Revision 00.99 27032 27033 Published 27034 Copyright TCG 2006-2013 27035 27036 Page 323 27037 October 31, 2013 27038 27039 Part 3: Commands 27041 55 27042 56 27043 57 27044 58 27045 59 27046 60 27047 61 27048 62 27049 63 27050 64 27051 65 27052 66 27053 67 27054 68 27055 69 27056 70 27057 71 27058 72 27059 73 27060 74 27061 75 27062 76 27063 77 27064 78 27065 79 27066 80 27067 81 27068 82 27069 83 27070 84 27071 85 27072 86 27073 87 27074 88 27075 27076 Trusted Platform Module Library 27077 27078 // Save hierarchy changes to NV 27079 NvWriteReserved(NV_SP_SEED, &gp.SPSeed); 27080 NvWriteReserved(NV_SH_PROOF, &gp.shProof); 27081 NvWriteReserved(NV_EH_PROOF, &gp.ehProof); 27082 NvWriteReserved(NV_OWNER_AUTH, &gp.ownerAuth); 27083 NvWriteReserved(NV_ENDORSEMENT_AUTH, &gp.endorsementAuth); 27084 NvWriteReserved(NV_LOCKOUT_AUTH, &gp.lockoutAuth); 27085 NvWriteReserved(NV_OWNER_ALG, &gp.ownerAlg); 27086 NvWriteReserved(NV_ENDORSEMENT_ALG, &gp.endorsementAlg); 27087 NvWriteReserved(NV_OWNER_POLICY, &gp.ownerPolicy); 27088 NvWriteReserved(NV_ENDORSEMENT_POLICY, &gp.endorsementPolicy); 27089 // Initialize dictionary attack parameters 27090 DAPreInstall_Init(); 27091 // Reset clock 27092 go.clock = 0; 27093 go.clockSafe = YES; 27094 // Update the DRBG state whenever writing orderly state to NV 27095 CryptDrbgGetPutState(GET_STATE); 27096 NvWriteReserved(NV_ORDERLY_DATA, &go); 27097 // Reset counters 27098 gp.resetCount = gr.restartCount = gr.clearCount = 0; 27099 gp.auditCounter = 0; 27100 NvWriteReserved(NV_RESET_COUNT, &gp.resetCount); 27101 NvWriteReserved(NV_AUDIT_COUNTER, &gp.auditCounter); 27102 // orderly state should be cleared because of the update to state clear data 27103 g_clearOrderly = TRUE; 27104 return TPM_RC_SUCCESS; 27105 } 27106 27107 Page 324 27108 October 31, 2013 27109 27110 Published 27111 Copyright TCG 2006-2013 27112 27113 Family 2.0 27114 Level 00 Revision 00.99 27115 27116 Trusted Platform Module Library 27118 27119 26.7 27120 27121 Part 3: Commands 27122 27123 TPM2_ClearControl 27124 27125 26.7.1 General Description 27126 TPM2_ClearControl() disables and enables the execution of TPM2_Clear(). 27127 The TPM will SET the TPMs TPMA_PERMANENT.disableClear attribute if disable is YES and will 27128 CLEAR the attribute if disable is NO. When the attribute is SET, TPM2_Clear() may not be executed. 27129 NOTE 27130 27131 This is to simplify the logic of TPM2_Clear(). TPM2_ClearControl() can be called using platformAuth 27132 to CLEAR the disableClear attribute and then execute TPM2_Clear(). 27133 27134 LockoutAuth may be used to SET disableClear but not to CLEAR it. 27135 PlatformAuth may be used to SET or CLEAR disableClear. 27136 27137 Family 2.0 27138 Level 00 Revision 00.99 27139 27140 Published 27141 Copyright TCG 2006-2013 27142 27143 Page 325 27144 October 31, 2013 27145 27146 Part 3: Commands 27148 27149 Trusted Platform Module Library 27150 27151 26.7.2 Command and Response 27152 Table 161 TPM2_ClearControl Command 27153 Type 27154 27155 Name 27156 27157 Description 27158 27159 TPMI_ST_COMMAND_TAG 27160 27161 tag 27162 27163 UINT32 27164 27165 commandSize 27166 27167 TPM_CC 27168 27169 commandCode 27170 27171 TPM_CC_ClearControl {NV} 27172 27173 TPMI_RH_CLEAR 27174 27175 @auth 27176 27177 TPM_RH_LOCKOUT or TPM_RH_PLATFORM+{PP} 27178 Auth Handle: 1 27179 Auth Role: USER 27180 27181 TPMI_YES_NO 27182 27183 disable 27184 27185 YES if the disableOwnerClear flag is to be SET, NO if 27186 the flag is to be CLEAR. 27187 27188 Table 162 TPM2_ClearControl Response 27189 Type 27190 27191 Name 27192 27193 Description 27194 27195 TPM_ST 27196 27197 tag 27198 27199 see clause 8 27200 27201 UINT32 27202 27203 responseSize 27204 27205 TPM_RC 27206 27207 responseCode 27208 27209 Page 326 27210 October 31, 2013 27211 27212 Published 27213 Copyright TCG 2006-2013 27214 27215 Family 2.0 27216 Level 00 Revision 00.99 27217 27218 Trusted Platform Module Library 27220 27221 Part 3: Commands 27222 27223 26.7.3 Detailed Actions 27224 1 27225 2 27226 27227 #include "InternalRoutines.h" 27228 #include "ClearControl_fp.h" 27229 Error Returns 27230 TPM_RC_AUTH_FAIL 27231 27232 3 27233 4 27234 5 27235 6 27236 7 27237 8 27238 9 27239 10 27240 11 27241 12 27242 13 27243 14 27244 15 27245 16 27246 17 27247 18 27248 19 27249 20 27250 21 27251 22 27252 23 27253 24 27254 25 27255 26 27256 27 27257 28 27258 29 27259 30 27260 31 27261 32 27262 33 27263 27264 Meaning 27265 authorization is not properly given 27266 27267 TPM_RC 27268 TPM2_ClearControl( 27269 ClearControl_In 27270 27271 *in 27272 27273 // IN: input parameter list 27274 27275 ) 27276 { 27277 TPM_RC 27278 27279 result; 27280 27281 // The command needs NV update. Check if NV is available. 27282 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 27283 // this point 27284 result = NvIsAvailable(); 27285 if(result != TPM_RC_SUCCESS) return result; 27286 // Input Validation 27287 // LockoutAuth may be used to set disableLockoutClear to TRUE but not to FALSE 27288 if(in->auth == TPM_RH_LOCKOUT && in->disable == NO) 27289 return TPM_RC_AUTH_FAIL; 27290 // Internal Data Update 27291 if(in->disable == YES) 27292 gp.disableClear = TRUE; 27293 else 27294 gp.disableClear = FALSE; 27295 // Record the change to NV 27296 NvWriteReserved(NV_DISABLE_CLEAR, &gp.disableClear); 27297 return TPM_RC_SUCCESS; 27298 } 27299 27300 Family 2.0 27301 Level 00 Revision 00.99 27302 27303 Published 27304 Copyright TCG 2006-2013 27305 27306 Page 327 27307 October 31, 2013 27308 27309 Part 3: Commands 27311 27312 26.8 27313 27314 Trusted Platform Module Library 27315 27316 TPM2_HierarchyChangeAuth 27317 27318 26.8.1 General Description 27319 This command allows the authorization secret for a hierarchy or lockout to be changed using the current 27320 authorization value as the command authorization. 27321 If authHandle is TPM_RH_PLATFORM, then platformAuth is changed. If authHandle is 27322 TPM_RH_OWNER, then ownerAuth is changed. If authHandle is TPM_RH_ENDORSEMENT, then 27323 endorsementAuth is changed. If authHandle is TPM_RH_LOCKOUT, then lockoutAuth is changed. 27324 If authHandle is TPM_RH_PLATFORM, then Physical Presence may need to be asserted for this 27325 command to succeed (see 28.2, TPM2_PP_Commands). 27326 The authorization value may be no larger than the digest produced by the hash algorithm used for context 27327 integrity. 27328 EXAMPLE 27329 27330 If SHA384 is used in the computation of the integrity values for saved contexts, then the largest 27331 authorization value is 48 octets. 27332 27333 Page 328 27334 October 31, 2013 27335 27336 Published 27337 Copyright TCG 2006-2013 27338 27339 Family 2.0 27340 Level 00 Revision 00.99 27341 27342 Trusted Platform Module Library 27344 27345 Part 3: Commands 27346 27347 26.8.2 Command and Response 27348 Table 163 TPM2_HierarchyChangeAuth Command 27349 Type 27350 27351 Name 27352 27353 Description 27354 27355 TPMI_ST_COMMAND_TAG 27356 27357 tag 27358 27359 UINT32 27360 27361 commandSize 27362 27363 TPM_CC 27364 27365 commandCode 27366 27367 TPM_CC_HierarchyChangeAuth {NV} 27368 27369 TPMI_RH_HIERARCHY_AUTH 27370 27371 @authHandle 27372 27373 TPM_RH_LOCKOUT, TPM_RH_ENDORSEMENT, 27374 TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} 27375 Auth Index: 1 27376 Auth Role: USER 27377 27378 TPM2B_AUTH 27379 27380 newAuth 27381 27382 new authorization value 27383 27384 Table 164 TPM2_HierarchyChangeAuth Response 27385 Type 27386 27387 Name 27388 27389 Description 27390 27391 TPM_ST 27392 27393 tag 27394 27395 see clause 8 27396 27397 UINT32 27398 27399 responseSize 27400 27401 TPM_RC 27402 27403 responseCode 27404 27405 Family 2.0 27406 Level 00 Revision 00.99 27407 27408 Published 27409 Copyright TCG 2006-2013 27410 27411 Page 329 27412 October 31, 2013 27413 27414 Part 3: Commands 27416 27417 Trusted Platform Module Library 27418 27419 26.8.3 Detailed Actions 27420 1 27421 2 27422 3 27423 27424 #include "InternalRoutines.h" 27425 #include "HierarchyChangeAuth_fp.h" 27426 #include "Object_spt_fp.h" 27427 Error Returns 27428 TPM_RC_SIZE 27429 27430 4 27431 5 27432 6 27433 7 27434 8 27435 9 27436 10 27437 11 27438 12 27439 13 27440 14 27441 15 27442 16 27443 17 27444 18 27445 19 27446 20 27447 21 27448 22 27449 23 27450 24 27451 25 27452 26 27453 27 27454 28 27455 29 27456 30 27457 31 27458 32 27459 33 27460 34 27461 35 27462 36 27463 37 27464 38 27465 39 27466 40 27467 41 27468 42 27469 43 27470 44 27471 45 27472 46 27473 47 27474 48 27475 49 27476 50 27477 51 27478 27479 Meaning 27480 newAuth size is greater than that of integrity hash digest 27481 27482 TPM_RC 27483 TPM2_HierarchyChangeAuth( 27484 HierarchyChangeAuth_In 27485 27486 *in 27487 27488 // IN: input parameter list 27489 27490 ) 27491 { 27492 TPM_RC 27493 27494 result; 27495 27496 // The command needs NV update. Check if NV is available. 27497 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 27498 // this point 27499 result = NvIsAvailable(); 27500 if(result != TPM_RC_SUCCESS) return result; 27501 // Make sure the the auth value is a reasonable size (not larger than 27502 // the size of the digest produced by the integrity hash. The integrity 27503 // hash is assumed to produce the longest digest of any hash implemented 27504 // on the TPM. 27505 if( MemoryRemoveTrailingZeros(&in->newAuth) 27506 > CryptGetHashDigestSize(CONTEXT_INTEGRITY_HASH_ALG)) 27507 return TPM_RC_SIZE + RC_HierarchyChangeAuth_newAuth; 27508 // Set hierarchy authValue 27509 switch(in->authHandle) 27510 { 27511 case TPM_RH_OWNER: 27512 gp.ownerAuth = in->newAuth; 27513 NvWriteReserved(NV_OWNER_AUTH, &gp.ownerAuth); 27514 break; 27515 case TPM_RH_ENDORSEMENT: 27516 gp.endorsementAuth = in->newAuth; 27517 NvWriteReserved(NV_ENDORSEMENT_AUTH, &gp.endorsementAuth); 27518 break; 27519 case TPM_RH_PLATFORM: 27520 gc.platformAuth = in->newAuth; 27521 // orderly state should be cleared 27522 g_clearOrderly = TRUE; 27523 break; 27524 case TPM_RH_LOCKOUT: 27525 gp.lockoutAuth = in->newAuth; 27526 NvWriteReserved(NV_LOCKOUT_AUTH, &gp.lockoutAuth); 27527 break; 27528 default: 27529 pAssert(FALSE); 27530 break; 27531 } 27532 return TPM_RC_SUCCESS; 27533 } 27534 27535 Page 330 27536 October 31, 2013 27537 27538 Published 27539 Copyright TCG 2006-2013 27540 27541 Family 2.0 27542 Level 00 Revision 00.99 27543 27544 Trusted Platform Module Library 27546 27547 27 27548 27549 Part 3: Commands 27550 27551 Dictionary Attack Functions 27552 27553 27.1 27554 27555 Introduction 27556 27557 A TPM is required to have support for logic that will help prevent a dictionary attack on an authorization 27558 value. The protection is provided by a counter that increments when a password authorization or an 27559 HMAC authorization fails. When the counter reaches a predefined value, the TPM will not accept, for 27560 some time interval, further requests that require authorization and the TPM is in Lockout mode. While the 27561 TPM is in Lockout mode, the TPM will return TPM_RC_LOCKED if the command requires use of an 27562 objects or Indexs authValue unless the authorization applies to an entry in the Platform hierarchy. 27563 NOTE 27564 27565 Authorizations for objects and NV Index values in the Platform hierarchy are never locked out. 27566 However, a command that requires multiple authorizations will not be accepted when the TPM is in 27567 Lockout mode unless all of the authorizations reference objects and indexes in the Platform 27568 hierarchy. 27569 27570 If the TPM is continuously powered for the duration of newRecoveryTime and no authorization failures 27571 occur, the authorization failure counter will be decremented by one. This property is called self-healing. 27572 Self-healing shall not cause the count of failed attempts to decrement below zero. 27573 The count of failed attempts, the lockout interval, and self-healing interval are settable using 27574 TPM2_DictionaryAttackParameters(). The lockout parameters and the current value of the lockout 27575 counter can be read with TPM2_GetCapability(). 27576 Dictionary attack protection does not apply to an entity associated with a permanent handle (handle type 27577 == TPM_HT_PERMANENT). 27578 27.2 27579 27580 TPM2_DictionaryAttackLockReset 27581 27582 27.2.1 General Description 27583 This command cancels the effect of a TPM lockout due to a number of successive authorization failures. 27584 If this command is properly authorized, the lockout counter is set to zero. 27585 Only one authorization failure is allowed for this command during a lockoutRecovery interval (set using 27586 TPM2_DictionaryAttackParameters(). 27587 27588 Family 2.0 27589 Level 00 Revision 00.99 27590 27591 Published 27592 Copyright TCG 2006-2013 27593 27594 Page 331 27595 October 31, 2013 27596 27597 Part 3: Commands 27599 27600 Trusted Platform Module Library 27601 27602 27.2.2 Command and Response 27603 Table 165 TPM2_DictionaryAttackLockReset Command 27604 Type 27605 27606 Name 27607 27608 TPMI_ST_COMMAND_TAG 27609 27610 tag 27611 27612 UINT32 27613 27614 commandSize 27615 27616 TPM_CC 27617 27618 commandCode 27619 27620 TPM_CC_DictionaryAttackLockReset {NV} 27621 27622 TPMI_RH_LOCKOUT 27623 27624 @lockHandle 27625 27626 TPM_RH_LOCKOUT 27627 Auth Index: 1 27628 Auth Role: USER 27629 27630 Description 27631 27632 Table 166 TPM2_DictionaryAttackLockReset Response 27633 Type 27634 27635 Name 27636 27637 Description 27638 27639 TPM_ST 27640 27641 tag 27642 27643 see clause 8 27644 27645 UINT32 27646 27647 responseSize 27648 27649 TPM_RC 27650 27651 responseCode 27652 27653 Page 332 27654 October 31, 2013 27655 27656 Published 27657 Copyright TCG 2006-2013 27658 27659 Family 2.0 27660 Level 00 Revision 00.99 27661 27662 Trusted Platform Module Library 27664 27665 Part 3: Commands 27666 27667 27.2.3 Detailed Actions 27668 1 27669 2 27670 3 27671 4 27672 5 27673 6 27674 7 27675 8 27676 9 27677 10 27678 11 27679 12 27680 13 27681 14 27682 15 27683 16 27684 17 27685 18 27686 19 27687 20 27688 21 27689 22 27690 23 27691 24 27692 25 27693 26 27694 27 27695 28 27696 27697 #include "InternalRoutines.h" 27698 #include "DictionaryAttackLockReset_fp.h" 27699 27700 TPM_RC 27701 TPM2_DictionaryAttackLockReset( 27702 DictionaryAttackLockReset_In 27703 27704 *in 27705 27706 // IN: input parameter list 27707 27708 ) 27709 { 27710 TPM_RC 27711 27712 result; 27713 27714 // Input parameter is not reference in command action 27715 in = NULL; 27716 // The command needs NV update. Check if NV is available. 27717 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 27718 // this point 27719 result = NvIsAvailable(); 27720 if(result != TPM_RC_SUCCESS) return result; 27721 // Internal Data Update 27722 // Set failed tries to 0 27723 gp.failedTries = 0; 27724 // Record the changes to NV 27725 NvWriteReserved(NV_FAILED_TRIES, &gp.failedTries); 27726 return TPM_RC_SUCCESS; 27727 } 27728 27729 Family 2.0 27730 Level 00 Revision 00.99 27731 27732 Published 27733 Copyright TCG 2006-2013 27734 27735 Page 333 27736 October 31, 2013 27737 27738 Part 3: Commands 27740 27741 27.3 27742 27743 Trusted Platform Module Library 27744 27745 TPM2_DictionaryAttackParameters 27746 27747 27.3.1 General Description 27748 This command changes the lockout parameters. 27749 The command requires lockoutAuth. 27750 The timeout parameters (newRecoveryTime and lockoutRecovery) indicate values that are measured with 27751 respect to the Time and not Clock. 27752 NOTE 27753 27754 Use of Time means that the TPM shall be continuously powered for the duration of a timeout. 27755 27756 If newRecoveryTime is zero, then DA protection is disabled. Authorizations are checked but authorization 27757 failures will not cause the TPM to enter lockout. 27758 If newMaxTries is zero, the TPM will be in lockout and use of DA protected entities will be disabled. 27759 If lockoutRecovery is zero, then the recovery interval is a boot cycle (_TPM_Init followed by 27760 Startup(CLEAR). 27761 This command will set the authorization failure count (failedTries) to zero. 27762 Only one authorization failure is allowed for this command during a lockoutRecovery interval. 27763 27764 Page 334 27765 October 31, 2013 27766 27767 Published 27768 Copyright TCG 2006-2013 27769 27770 Family 2.0 27771 Level 00 Revision 00.99 27772 27773 Trusted Platform Module Library 27775 27776 Part 3: Commands 27777 27778 27.3.2 Command and Response 27779 Table 167 TPM2_DictionaryAttackParameters Command 27780 Type 27781 27782 Name 27783 27784 Description 27785 27786 TPMI_ST_COMMAND_TAG 27787 27788 tag 27789 27790 UINT32 27791 27792 commandSize 27793 27794 TPM_CC 27795 27796 commandCode 27797 27798 TPM_CC_DictionaryAttackParameters {NV} 27799 27800 TPMI_RH_LOCKOUT 27801 27802 @lockHandle 27803 27804 TPM_RH_LOCKOUT 27805 Auth Index: 1 27806 Auth Role: USER 27807 27808 UINT32 27809 27810 newMaxTries 27811 27812 count of authorization failures before the lockout is 27813 imposed 27814 27815 UINT32 27816 27817 newRecoveryTime 27818 27819 time in seconds before the authorization failure count 27820 is automatically decremented 27821 A value of zero indicates that DA protection is 27822 disabled. 27823 27824 UINT32 27825 27826 lockoutRecovery 27827 27828 time in seconds after a lockoutAuth failure before use 27829 of lockoutAuth is allowed 27830 A value of zero indicates that a reboot is required. 27831 27832 Table 168 TPM2_DictionaryAttackParameters Response 27833 Type 27834 27835 Name 27836 27837 Description 27838 27839 TPM_ST 27840 27841 tag 27842 27843 see clause 8 27844 27845 UINT32 27846 27847 responseSize 27848 27849 TPM_RC 27850 27851 responseCode 27852 27853 Family 2.0 27854 Level 00 Revision 00.99 27855 27856 Published 27857 Copyright TCG 2006-2013 27858 27859 Page 335 27860 October 31, 2013 27861 27862 Part 3: Commands 27864 27865 Trusted Platform Module Library 27866 27867 27.3.3 Detailed Actions 27868 1 27869 2 27870 3 27871 4 27872 5 27873 6 27874 7 27875 8 27876 9 27877 10 27878 11 27879 12 27880 13 27881 14 27882 15 27883 16 27884 17 27885 18 27886 19 27887 20 27888 21 27889 22 27890 23 27891 24 27892 25 27893 26 27894 27 27895 28 27896 29 27897 30 27898 31 27899 32 27900 33 27901 27902 #include "InternalRoutines.h" 27903 #include "DictionaryAttackParameters_fp.h" 27904 27905 TPM_RC 27906 TPM2_DictionaryAttackParameters( 27907 DictionaryAttackParameters_In 27908 27909 *in 27910 27911 // IN: input parameter list 27912 27913 ) 27914 { 27915 TPM_RC 27916 27917 result; 27918 27919 // The command needs NV update. Check if NV is available. 27920 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 27921 // this point 27922 result = NvIsAvailable(); 27923 if(result != TPM_RC_SUCCESS) return result; 27924 // Internal Data Update 27925 // Set dictionary attack parameters 27926 gp.maxTries = in->newMaxTries; 27927 gp.recoveryTime = in->newRecoveryTime; 27928 gp.lockoutRecovery = in->lockoutRecovery; 27929 // Set failed tries to 0 27930 gp.failedTries = 0; 27931 // Record the changes to NV 27932 NvWriteReserved(NV_FAILED_TRIES, &gp.failedTries); 27933 NvWriteReserved(NV_MAX_TRIES, &gp.maxTries); 27934 NvWriteReserved(NV_RECOVERY_TIME, &gp.recoveryTime); 27935 NvWriteReserved(NV_LOCKOUT_RECOVERY, &gp.lockoutRecovery); 27936 return TPM_RC_SUCCESS; 27937 } 27938 27939 Page 336 27940 October 31, 2013 27941 27942 Published 27943 Copyright TCG 2006-2013 27944 27945 Family 2.0 27946 Level 00 Revision 00.99 27947 27948 Trusted Platform Module Library 27950 27951 28 27952 27953 Part 3: Commands 27954 27955 Miscellaneous Management Functions 27956 27957 28.1 27958 27959 Introduction 27960 27961 This clause contains commands that do not logically group with any other commands. 27962 28.2 27963 27964 TPM2_PP_Commands 27965 27966 28.2.1 General Description 27967 This command is used to determine which commands require assertion of Physical Presence (PP) in 27968 addition to platformAuth/platformPolicy. 27969 This command requires that auth is TPM_RH_PLATFORM and that Physical Presence be asserted. 27970 After this command executes successfully, the commands listed in setList will be added to the list of 27971 commands that require that Physical Presence be asserted when the handle associated with the 27972 authorization is TPM_RH_PLATFORM. The commands in clearList will no longer require assertion of 27973 Physical Presence in order to authorize a command. 27974 If a command is not in either list, its state is not changed. If a command is in both lists, then it will no 27975 longer require Physical Presence (for example, setList is processed first). 27976 Only commands with 27977 handle types of 27978 TPMI_RH_PLATFORM, TPMI_RH_PROVISION, 27979 TPMI_RH_CLEAR, or TPMI_RH_HIERARCHY can be gated with Physical Presence. If any other 27980 command is in either list, it is discarded. 27981 When a command requires that Physical Presence be provided, then Physical Presence shall be 27982 asserted for either an HMAC or a Policy authorization. 27983 NOTE 27984 27985 Physical Presence may be made a requirement of any policy. 27986 27987 TPM2_PP_Commands() always requires assertion of Physical Presence. 27988 27989 Family 2.0 27990 Level 00 Revision 00.99 27991 27992 Published 27993 Copyright TCG 2006-2013 27994 27995 Page 337 27996 October 31, 2013 27997 27998 Part 3: Commands 28000 28001 Trusted Platform Module Library 28002 28003 28.2.2 Command and Response 28004 Table 169 TPM2_PP_Commands Command 28005 Type 28006 28007 Name 28008 28009 Description 28010 28011 TPMI_ST_COMMAND_TAG 28012 28013 tag 28014 28015 UINT32 28016 28017 commandSize 28018 28019 TPM_CC 28020 28021 commandCode 28022 28023 TPM_CC_PP_Commands {NV} 28024 28025 TPMI_RH_PLATFORM 28026 28027 @auth 28028 28029 TPM_RH_PLATFORM+PP 28030 Auth Index: 1 28031 Auth Role: USER + Physical Presence 28032 28033 TPML_CC 28034 28035 setList 28036 28037 list of commands to be added to those that will require 28038 that Physical Presence be asserted 28039 28040 TPML_CC 28041 28042 clearList 28043 28044 list of commands that will no longer require that 28045 Physical Presence be asserted 28046 28047 Table 170 TPM2_PP_Commands Response 28048 Type 28049 28050 Name 28051 28052 Description 28053 28054 TPM_ST 28055 28056 tag 28057 28058 see clause 8 28059 28060 UINT32 28061 28062 responseSize 28063 28064 TPM_RC 28065 28066 responseCode 28067 28068 Page 338 28069 October 31, 2013 28070 28071 Published 28072 Copyright TCG 2006-2013 28073 28074 Family 2.0 28075 Level 00 Revision 00.99 28076 28077 Trusted Platform Module Library 28079 28080 Part 3: Commands 28081 28082 28.2.3 Detailed Actions 28083 1 28084 2 28085 3 28086 4 28087 5 28088 6 28089 7 28090 8 28091 9 28092 10 28093 11 28094 12 28095 13 28096 14 28097 15 28098 16 28099 17 28100 18 28101 19 28102 20 28103 21 28104 22 28105 23 28106 24 28107 25 28108 26 28109 27 28110 28 28111 29 28112 30 28113 31 28114 32 28115 33 28116 34 28117 35 28118 36 28119 37 28120 38 28121 39 28122 40 28123 41 28124 28125 #include "InternalRoutines.h" 28126 #include "PP_Commands_fp.h" 28127 28128 TPM_RC 28129 TPM2_PP_Commands( 28130 PP_Commands_In 28131 28132 *in 28133 28134 // IN: input parameter list 28135 28136 ) 28137 { 28138 UINT32 28139 TPM_RC 28140 28141 i; 28142 result; 28143 28144 // The command needs NV update. Check if NV is available. 28145 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 28146 // this point 28147 result = NvIsAvailable(); 28148 if(result != TPM_RC_SUCCESS) return result; 28149 // Internal Data Update 28150 // Process set list 28151 for(i = 0; i < in->setList.count; i++) 28152 // If command is implemented, set it as PP required. If the input 28153 // command is not a PP command, it will be ignored at 28154 // PhysicalPresenceCommandSet(). 28155 if(CommandIsImplemented(in->setList.commandCodes[i])) 28156 PhysicalPresenceCommandSet(in->setList.commandCodes[i]); 28157 // Process clear list 28158 for(i = 0; i < in->clearList.count; i++) 28159 // If command is implemented, clear it as PP required. If the input 28160 // command is not a PP command, it will be ignored at 28161 // PhysicalPresenceCommandClear(). If the input command is 28162 // TPM2_PP_Commands, it will be ignored as well 28163 if(CommandIsImplemented(in->clearList.commandCodes[i])) 28164 PhysicalPresenceCommandClear(in->clearList.commandCodes[i]); 28165 // Save the change of PP list 28166 NvWriteReserved(NV_PP_LIST, &gp.ppList); 28167 return TPM_RC_SUCCESS; 28168 } 28169 28170 Family 2.0 28171 Level 00 Revision 00.99 28172 28173 Published 28174 Copyright TCG 2006-2013 28175 28176 Page 339 28177 October 31, 2013 28178 28179 Part 3: Commands 28181 28182 28.3 28183 28184 Trusted Platform Module Library 28185 28186 TPM2_SetAlgorithmSet 28187 28188 28.3.1 General Description 28189 This command allows the platform to change the set of algorithms that are used by the TPM. The 28190 algorithmSet setting is a vendor-dependent value. 28191 If the changing of the algorithm set results in a change of the algorithms of PCR banks, then the TPM will 28192 need to be reset (_TPM_Init and TPM2_Startup(TPM_SU_CLEAR)) before the new PCR settings take 28193 effect. After this command executes successfully, if startupType in the next TPM2_Startup() is not 28194 TPM_SU_CLEAR, the TPM shall return TPM_RC_VALUE and enter Failure mode. 28195 This command does not change the algorithms available to the platform. 28196 NOTE 28197 28198 The reference implementation does not have support for this command. In particular, it does not 28199 support use of this command to selectively disable algorithms. Proper support wo uld require 28200 modification of the unmarshaling code so that each time an algorithm is unmarshaled, it would be 28201 verified as being enabled. 28202 28203 Page 340 28204 October 31, 2013 28205 28206 Published 28207 Copyright TCG 2006-2013 28208 28209 Family 2.0 28210 Level 00 Revision 00.99 28211 28212 Trusted Platform Module Library 28214 28215 Part 3: Commands 28216 28217 28.3.2 Command and Response 28218 Table 171 TPM2_SetAlgorithmSet Command 28219 Type 28220 28221 Name 28222 28223 Description 28224 28225 TPMI_ST_COMMAND_TAG 28226 28227 tag 28228 28229 UINT32 28230 28231 commandSize 28232 28233 TPM_CC 28234 28235 commandCode 28236 28237 TPM_CC_SetAlgorithmSet {NV} 28238 28239 TPMI_RH_PLATFORM 28240 28241 @authHandle 28242 28243 TPM_RH_PLATFORM 28244 Auth Index: 1 28245 Auth Role: USER 28246 28247 UINT32 28248 28249 algorithmSet 28250 28251 a TPM vendor-dependent value indicating the 28252 algorithm set selection 28253 28254 Table 172 TPM2_SetAlgorithmSet Response 28255 Type 28256 28257 Name 28258 28259 Description 28260 28261 TPM_ST 28262 28263 tag 28264 28265 see clause 8 28266 28267 UINT32 28268 28269 responseSize 28270 28271 TPM_RC 28272 28273 responseCode 28274 28275 Family 2.0 28276 Level 00 Revision 00.99 28277 28278 Published 28279 Copyright TCG 2006-2013 28280 28281 Page 341 28282 October 31, 2013 28283 28284 Part 3: Commands 28286 28287 Trusted Platform Module Library 28288 28289 28.3.3 Detailed Actions 28290 1 28291 2 28292 3 28293 4 28294 5 28295 6 28296 7 28297 8 28298 9 28299 10 28300 11 28301 12 28302 13 28303 14 28304 15 28305 16 28306 17 28307 18 28308 19 28309 20 28310 21 28311 22 28312 23 28313 28314 #include "InternalRoutines.h" 28315 #include "SetAlgorithmSet_fp.h" 28316 28317 TPM_RC 28318 TPM2_SetAlgorithmSet( 28319 SetAlgorithmSet_In 28320 28321 *in 28322 28323 // IN: input parameter list 28324 28325 ) 28326 { 28327 TPM_RC 28328 28329 result; 28330 28331 // The command needs NV update. Check if NV is available. 28332 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 28333 // this point 28334 result = NvIsAvailable(); 28335 if(result != TPM_RC_SUCCESS) return result; 28336 // Internal Data Update 28337 gp.algorithmSet = in->algorithmSet; 28338 // Write the algorithm set changes to NV 28339 NvWriteReserved(NV_ALGORITHM_SET, &gp.algorithmSet); 28340 return TPM_RC_SUCCESS; 28341 } 28342 28343 Page 342 28344 October 31, 2013 28345 28346 Published 28347 Copyright TCG 2006-2013 28348 28349 Family 2.0 28350 Level 00 Revision 00.99 28351 28352 Trusted Platform Module Library 28354 28355 Part 3: Commands 28356 28357 Field Upgrade 28358 28359 29 28360 29.1 28361 28362 Introduction 28363 28364 This clause contains the commands for managing field upgrade of the firmware in the TPM. The field 28365 upgrade scheme may be used for replacement or augmentation of the firmware installed in the TPM. 28366 EXAMPLE 1 28367 28368 If an algorithm is found to be flawed, a patch of that algorithm might be installed using the firmware 28369 upgrade process. The patch might be a replacement of a portion of the code or a complete 28370 replacement of the firmware. 28371 28372 EXAMPLE 2 28373 28374 If an additional set of ECC parameters is needed, the firmware process may be used to add the 28375 parameters to the TPM data set. 28376 28377 The 28378 field 28379 upgrade 28380 process 28381 uses 28382 two 28383 commands 28384 (TPM2_FieldUpgradeStart() 28385 and 28386 TPM2_FieldUpgradeData()). TPM2_FieldUpgradeStart() validates that a signature on the provided digest 28387 is from the TPM manufacturer and that proper authorization is provided using platformPolicy. 28388 NOTE 1 28389 28390 The platformPolicy for field upgraded is defined by the PM and may include requirements that the 28391 upgrade be signed by the PM or the TPM owner and include any other constraints that are desired 28392 by the PM. 28393 28394 If the proper authorization is given, the TPM will retain the signed digest and enter the Field Upgrade 28395 mode (FUM). While in FUM, the TPM will accept TPM2_FieldUpgradeData() commands. It may accept 28396 other commands if it is able to complete them using the previously installed firmware. Otherwise, it will 28397 return TPM_RC_UPGRADE. 28398 Each block of the field upgrade shall contain the digest of the next block of the field upgrade data. That 28399 digest shall be included in the digest of the previous block. The digest of the first block is signed by the 28400 TPM manufacturer. That signature and first block digest are the parameters for 28401 TPM2_FieldUpgradeStart(). The digest is saved in the TPM as the required digest for the next field 28402 upgrade data block and as the identifier of the field upgrade sequence. 28403 For each field upgrade data block that is sent to the TPM by TPM2_FieldUpgradeData(), the TPM shall 28404 validate that the digest matches the required digest and if not, shall return TPM_RC_VALUE. The TPM 28405 shall extract the digest of the next expected block and return that value to the caller, along with the digest 28406 of the first data block of the update sequence. 28407 The system may attempt to abandon the firmware upgrade by using a zero-length buffer in 28408 TPM2_FieldUpdateData(). If the TPM is able to resume operation using the firmware present when the 28409 upgrade started, then the TPM will indicate that it has abandon the update by setting the digest of the 28410 next block to the Empty Buffer. If the TPM cannot abandon the update, it will return the expected next 28411 digest. 28412 The system may also attempt to abandon the update because of a power interruption. If the TPM is able 28413 to resume normal operations, then it will respond normally to TPM2_Startup(). If the TPM is not able to 28414 resume normal operations, then it will respond to any command but TPM2_FieldUpgradeData() with 28415 TPM_RC_FIELDUPGRADE. 28416 After a _TPM_Init, system software may not be able to resume the field upgrade that was in process 28417 when the power interruption occurred. In such case, the TPM firmware may be reset to one of two other 28418 values: 28419 28420 28421 the original firmware that was installed at the factory (initial firmware); or 28422 28423 28424 28425 the firmware that was in the TPM when the field upgrade process started (previous firmware). 28426 28427 The TPM retains the digest of the first block for these firmware images and checks to see if the first block 28428 after _TPM_Init matches either of those digests. If so, the firmware update process restarts and the 28429 original firmware may be loaded. 28430 Family 2.0 28431 Level 00 Revision 00.99 28432 28433 Published 28434 Copyright TCG 2006-2013 28435 28436 Page 343 28437 October 31, 2013 28438 28439 Part 3: Commands 28441 NOTE 2 28442 28443 Trusted Platform Module Library 28444 28445 The TPM is required to accept the previous firmware as either a vendor -provided update or as 28446 recovered from the TPM using TPM2_FirmwareRead(). 28447 28448 When the last block of the firmware upgrade is loaded into the TPM (indicated to the TPM by data in the 28449 data block in a TPM vendor-specific manner), the TPM will complete the upgrade process. If the TPM is 28450 able to resume normal operations without a reboot, it will set the hash algorithm of the next block to 28451 TPM_ALG_NULL and return TPM_RC_SUCCESS. If a reboot is required, the TPM shall return 28452 TPM_RC_REBOOT in response to the last TPM2_FieldUpgradeData() and all subsequent TPM 28453 commands until a _TPM_Init is received. 28454 NOTE 3 28455 28456 Because no additional data is allowed when the res ponse code is not TPM_RC_SUCCESS, the TPM 28457 returns TPM_RC_SUCCESS for all calls to TPM2_FieldUpgradeData() except the last. In this 28458 manner, the TPM is able to indicate the digest of the next block. If a _TPM_Init occurs while the 28459 TPM is in FUM, the next block may be the digest for the first block of the original firmware. If it is 28460 not, then the TPM will not accept the original firmware until the next _TPM_Init when the TPM is in 28461 FUM. 28462 28463 During the field upgrade process, the TPM shall preserve: 28464 28465 28466 Primary Seeds; 28467 28468 28469 28470 Hierarchy authValue, authPolicy, and proof values; 28471 28472 28473 28474 Lockout authValue and authorization failure count values; 28475 28476 28477 28478 PCR authValue and authPolicy values; 28479 28480 28481 28482 NV Index allocations and contents; 28483 28484 28485 28486 Persistent object allocations and contents; and 28487 28488 28489 28490 Clock. 28491 28492 Page 344 28493 October 31, 2013 28494 28495 Published 28496 Copyright TCG 2006-2013 28497 28498 Family 2.0 28499 Level 00 Revision 00.99 28500 28501 Trusted Platform Module Library 28503 28504 29.2 28505 28506 Part 3: Commands 28507 28508 TPM2_FieldUpgradeStart 28509 28510 29.2.1 General Description 28511 This command uses platformPolicy and a TPM Vendor Authorization Key to authorize a Field Upgrade 28512 Manifest. 28513 If the signature checks 28514 TPM2_FieldUpgradeData(). 28515 28516 succeed, 28517 28518 the 28519 28520 authorization 28521 28522 is 28523 28524 valid 28525 28526 and 28527 28528 the 28529 28530 TPM 28531 28532 will 28533 28534 accept 28535 28536 This signature is checked against the loaded key referenced by keyHandle. This key will have a Name 28537 that is the same as a value that is part of the TPM firmware data. If the signature is not valid, the TPM 28538 shall return TPM_RC_SIGNATURE. 28539 NOTE 28540 28541 A loaded key is used rather than a hard-coded key to reduce the amount of memory needed for this 28542 key data in case more than one vendor key is needed. 28543 28544 Family 2.0 28545 Level 00 Revision 00.99 28546 28547 Published 28548 Copyright TCG 2006-2013 28549 28550 Page 345 28551 October 31, 2013 28552 28553 Part 3: Commands 28555 28556 Trusted Platform Module Library 28557 28558 29.2.2 Command and Response 28559 Table 173 TPM2_FieldUpgradeStart Command 28560 Type 28561 28562 Name 28563 28564 Description 28565 28566 TPMI_ST_COMMAND_TAG 28567 28568 tag 28569 28570 UINT32 28571 28572 commandSize 28573 28574 TPM_CC 28575 28576 commandCode 28577 28578 TPM_CC_FieldUpgradeStart 28579 28580 TPMI_RH_PLATFORM 28581 28582 @authorization 28583 28584 TPM_RH_PLATFORM+{PP} 28585 Auth Index:1 28586 Auth Role: ADMIN 28587 28588 TPMI_DH_OBJECT 28589 28590 keyHandle 28591 28592 handle of a public area that contains the TPM Vendor 28593 Authorization Key that will be used to validate 28594 manifestSignature 28595 Auth Index: None 28596 28597 TPM2B_DIGEST 28598 28599 fuDigest 28600 28601 digest of the first block in the field upgrade sequence 28602 28603 TPMT_SIGNATURE 28604 28605 manifestSignature 28606 28607 signature over fuDigest using the key associated with 28608 keyHandle (not optional) 28609 28610 Table 174 TPM2_FieldUpgradeStart Response 28611 Type 28612 28613 Name 28614 28615 Description 28616 28617 TPM_ST 28618 28619 tag 28620 28621 see clause 8 28622 28623 UINT32 28624 28625 responseSize 28626 28627 TPM_RC 28628 28629 responseCode 28630 28631 Page 346 28632 October 31, 2013 28633 28634 Published 28635 Copyright TCG 2006-2013 28636 28637 Family 2.0 28638 Level 00 Revision 00.99 28639 28640 Trusted Platform Module Library 28642 28643 Part 3: Commands 28644 28645 29.2.3 Detailed Actions 28646 1 28647 2 28648 3 28649 4 28650 5 28651 6 28652 7 28653 8 28654 9 28655 10 28656 11 28657 12 28658 13 28659 28660 #include "InternalRoutines.h" 28661 #include "FieldUpgradeStart_fp.h" 28662 #if CC_FieldUpgradeStart == YES 28663 28664 TPM_RC 28665 TPM2_FieldUpgradeStart( 28666 FieldUpgradeStart_In 28667 28668 *in 28669 28670 // IN: input parameter list 28671 28672 ) 28673 { 28674 // Not implemented 28675 UNUSED_PARAMETER(in); 28676 return TPM_RC_SUCCESS; 28677 } 28678 #endif 28679 28680 Family 2.0 28681 Level 00 Revision 00.99 28682 28683 Published 28684 Copyright TCG 2006-2013 28685 28686 Page 347 28687 October 31, 2013 28688 28689 Part 3: Commands 28691 28692 29.3 28693 28694 Trusted Platform Module Library 28695 28696 TPM2_FieldUpgradeData 28697 28698 29.3.1 General Description 28699 This command will take the actual field upgrade image to be installed on the TPM. The exact format of 28700 fuData is vendor-specific. This command is only possible following a successful 28701 TPM2_FieldUpgradeStart(). 28702 If 28703 the 28704 TPM 28705 has 28706 not 28707 received 28708 a 28709 properly 28710 authorized 28711 TPM2_FieldUpgradeStart(), then the TPM shall return TPM_RC_FIELDUPGRADE. 28712 The TPM will validate that the digest of fuData matches an expected value. If so, the TPM may buffer or 28713 immediately apply the update. If the digest of fuData does not match an expected value, the TPM shall 28714 return TPM_RC_VALUE. 28715 28716 Page 348 28717 October 31, 2013 28718 28719 Published 28720 Copyright TCG 2006-2013 28721 28722 Family 2.0 28723 Level 00 Revision 00.99 28724 28725 Trusted Platform Module Library 28727 28728 Part 3: Commands 28729 28730 29.3.2 Command and Response 28731 Table 175 TPM2_FieldUpgradeData Command 28732 Type 28733 28734 Name 28735 28736 Description 28737 28738 TPMI_ST_COMMAND_TAG 28739 28740 tag 28741 28742 UINT32 28743 28744 commandSize 28745 28746 TPM_CC 28747 28748 commandCode 28749 28750 TPM_CC_FieldUpgradeData {NV} 28751 28752 TPM2B_MAX_BUFFER 28753 28754 fuData 28755 28756 field upgrade image data 28757 28758 Table 176 TPM2_FieldUpgradeData Response 28759 Type 28760 28761 Name 28762 28763 Description 28764 28765 TPM_ST 28766 28767 tag 28768 28769 see clause 8 28770 28771 UINT32 28772 28773 responseSize 28774 28775 TPM_RC 28776 28777 responseCode 28778 28779 TPMT_HA+ 28780 28781 nextDigest 28782 28783 tagged digest of the next block 28784 TPM_ALG_NULL if field update is complete 28785 28786 TPMT_HA 28787 28788 firstDigest 28789 28790 tagged digest of the first block of the sequence 28791 28792 Family 2.0 28793 Level 00 Revision 00.99 28794 28795 Published 28796 Copyright TCG 2006-2013 28797 28798 Page 349 28799 October 31, 2013 28800 28801 Part 3: Commands 28803 28804 Trusted Platform Module Library 28805 28806 29.3.3 Detailed Actions 28807 1 28808 2 28809 3 28810 4 28811 5 28812 6 28813 7 28814 8 28815 9 28816 10 28817 11 28818 12 28819 13 28820 14 28821 15 28822 28823 #include "InternalRoutines.h" 28824 #include "FieldUpgradeData_fp.h" 28825 #if CC_FieldUpgradeData == YES 28826 28827 TPM_RC 28828 TPM2_FieldUpgradeData( 28829 FieldUpgradeData_In 28830 FieldUpgradeData_Out 28831 28832 *in, 28833 *out 28834 28835 // IN: input parameter list 28836 // OUT: output parameter list 28837 28838 ) 28839 { 28840 // Not implemented 28841 UNUSED_PARAMETER(in); 28842 UNUSED_PARAMETER(out); 28843 return TPM_RC_SUCCESS; 28844 } 28845 #endif 28846 28847 Page 350 28848 October 31, 2013 28849 28850 Published 28851 Copyright TCG 2006-2013 28852 28853 Family 2.0 28854 Level 00 Revision 00.99 28855 28856 Trusted Platform Module Library 28858 28859 29.4 28860 28861 Part 3: Commands 28862 28863 TPM2_FirmwareRead 28864 28865 29.4.1 General Description 28866 This command is used to read a copy of the current firmware installed in the TPM. 28867 The presumption is that the data will be returned in reverse order so that the last block in the sequence 28868 would be the first block given to the TPM in case of a failure recovery. If the TPM2_FirmwareRead 28869 sequence completes successfully, then the data provided from the TPM will be sufficient to allow the TPM 28870 to recover from an abandoned upgrade of this firmware. 28871 To start the sequence of retrieving the data, the caller sets sequenceNumber to zero. When the TPM has 28872 returned all the firmware data, the TPM will return the Empty Buffer as fuData. 28873 The contents of fuData are opaque to the caller. 28874 NOTE 1 28875 28876 The caller should retain the ordering of the update blocks so that the blocks sent to the TPM have 28877 the same size and inverse order as the blocks returned by a sequence of calls to this command. 28878 28879 NOTE 2 28880 28881 Support for this command is optional even if the TPM implements TPM2_FieldUpgradeStart() and 28882 TPM2_FieldUpgradeData(). 28883 28884 Family 2.0 28885 Level 00 Revision 00.99 28886 28887 Published 28888 Copyright TCG 2006-2013 28889 28890 Page 351 28891 October 31, 2013 28892 28893 Part 3: Commands 28895 28896 Trusted Platform Module Library 28897 28898 29.4.2 Command and Response 28899 Table 177 TPM2_FirmwareRead Command 28900 Type 28901 28902 Name 28903 28904 Description 28905 28906 TPMI_ST_COMMAND_TAG 28907 28908 tag 28909 28910 UINT32 28911 28912 commandSize 28913 28914 TPM_CC 28915 28916 commandCode 28917 28918 TPM_CC_FirmwareRead 28919 28920 UINT32 28921 28922 sequenceNumber 28923 28924 the number of previous calls to this command in this 28925 sequence 28926 set to 0 on the first call 28927 28928 Table 178 TPM2_FirmwareRead Response 28929 Type 28930 28931 Name 28932 28933 Description 28934 28935 TPM_ST 28936 28937 tag 28938 28939 see clause 8 28940 28941 UINT32 28942 28943 responseSize 28944 28945 TPM_RC 28946 28947 responseCode 28948 28949 TPM2B_MAX_BUFFER 28950 28951 fuData 28952 28953 Page 352 28954 October 31, 2013 28955 28956 field upgrade image data 28957 28958 Published 28959 Copyright TCG 2006-2013 28960 28961 Family 2.0 28962 Level 00 Revision 00.99 28963 28964 Trusted Platform Module Library 28966 28967 Part 3: Commands 28968 28969 29.4.3 Detailed Actions 28970 1 28971 2 28972 3 28973 4 28974 5 28975 6 28976 7 28977 8 28978 9 28979 10 28980 11 28981 12 28982 13 28983 28984 #include "InternalRoutines.h" 28985 #include "FirmwareRead_fp.h" 28986 28987 TPM_RC 28988 TPM2_FirmwareRead( 28989 FirmwareRead_In 28990 FirmwareRead_Out 28991 28992 *in, 28993 *out 28994 28995 // IN: input parameter list 28996 // OUT: output parameter list 28997 28998 ) 28999 { 29000 // Not implemented 29001 UNUSED_PARAMETER(in); 29002 UNUSED_PARAMETER(out); 29003 return TPM_RC_SUCCESS; 29004 } 29005 29006 Family 2.0 29007 Level 00 Revision 00.99 29008 29009 Published 29010 Copyright TCG 2006-2013 29011 29012 Page 353 29013 October 31, 2013 29014 29015 Part 3: Commands 29017 29018 30 29019 29020 Trusted Platform Module Library 29021 29022 Context Management 29023 29024 30.1 29025 29026 Introduction 29027 29028 Three of the commands in this clause (TPM2_ContextSave(), TPM2_ContextLoad(), and 29029 TPM2_FlushContext()) implement the resource management described in the "Context Management" 29030 clause in Part 1. 29031 The fourth command in this clause (TPM2_EvictControl()) is used to control the persistence of a loadable 29032 objects in TPM memory. Background for this command may be found in the "Owner and Platform Evict 29033 Objects" clause in Part 1. 29034 30.2 29035 29036 TPM2_ContextSave 29037 29038 30.2.1 General Description 29039 This command saves a session context, object context, or sequence object context outside the TPM. 29040 No authorization sessions of any type are allowed with this command and tag is required to be 29041 TPM_ST_NO_SESSIONS. 29042 NOTE 29043 29044 This preclusion avoids complex issues of dealing with the same session in handle and in the session 29045 area. While it might be possible to provide specificity, it would add unnecessary complexity to the 29046 TPM and, because this capability would provide no application benefit, use of authorization ses sions 29047 for audit or encryption is prohibited. 29048 29049 The TPM shall encrypt and integrity protect the context as described in the "Context Protection" clause in 29050 Part 1. 29051 See the Context Data clause in Part 2 for a description of the context structure in the response. 29052 29053 Page 354 29054 October 31, 2013 29055 29056 Published 29057 Copyright TCG 2006-2013 29058 29059 Family 2.0 29060 Level 00 Revision 00.99 29061 29062 Trusted Platform Module Library 29064 29065 Part 3: Commands 29066 29067 30.2.2 Command and Response 29068 Table 179 TPM2_ContextSave Command 29069 Type 29070 29071 Name 29072 29073 Description 29074 29075 TPMI_ST_COMMAND_TAG 29076 29077 tag 29078 29079 TPM_ST_NO_SESSIONS 29080 29081 UINT32 29082 29083 commandSize 29084 29085 TPM_CC 29086 29087 commandCode 29088 29089 TPM_CC_ContextSave 29090 29091 TPMI_DH_CONTEXT 29092 29093 saveHandle 29094 29095 handle of the resource to save 29096 Auth Index: None 29097 29098 Table 180 TPM2_ContextSave Response 29099 Type 29100 29101 Name 29102 29103 Description 29104 29105 TPM_ST 29106 29107 tag 29108 29109 see clause 8 29110 29111 UINT32 29112 29113 responseSize 29114 29115 TPM_RC 29116 29117 responseCode 29118 29119 TPMS_CONTEXT 29120 29121 context 29122 29123 Family 2.0 29124 Level 00 Revision 00.99 29125 29126 Published 29127 Copyright TCG 2006-2013 29128 29129 Page 355 29130 October 31, 2013 29131 29132 Part 3: Commands 29134 29135 Trusted Platform Module Library 29136 29137 30.2.3 Detailed Actions 29138 1 29139 2 29140 3 29141 29142 #include "InternalRoutines.h" 29143 #include "ContextSave_fp.h" 29144 #include "Context_spt_fp.h" 29145 Error Returns 29146 TPM_RC_CONTEXT_GAP 29147 29148 a contextID could not be assigned for a session context save 29149 29150 TPM_RC_TOO_MANY_CONTEXTS 29151 4 29152 5 29153 6 29154 7 29155 8 29156 9 29157 10 29158 11 29159 12 29160 13 29161 14 29162 15 29163 16 29164 17 29165 18 29166 19 29167 20 29168 21 29169 22 29170 23 29171 24 29172 25 29173 26 29174 27 29175 28 29176 29 29177 30 29178 31 29179 32 29180 33 29181 34 29182 35 29183 36 29184 37 29185 38 29186 39 29187 40 29188 41 29189 42 29190 43 29191 44 29192 45 29193 46 29194 47 29195 48 29196 49 29197 50 29198 51 29199 52 29200 53 29201 29202 Meaning 29203 29204 no more contexts can be saved as the counter has maxed out 29205 29206 TPM_RC 29207 TPM2_ContextSave( 29208 ContextSave_In 29209 ContextSave_Out 29210 29211 *in, 29212 *out 29213 29214 // IN: input parameter list 29215 // OUT: output parameter list 29216 29217 ) 29218 { 29219 TPM_RC 29220 UINT16 29221 // blob. 29222 UINT64 29223 TPM2B_SYM_KEY 29224 TPM2B_IV 29225 29226 result; 29227 fingerprintSize; 29228 29229 TPM2B_DIGEST 29230 UINT16 29231 BYTE 29232 29233 integrity; 29234 integritySize; 29235 *buffer; 29236 29237 contextID = 0; 29238 symKey; 29239 iv; 29240 29241 // The size of fingerprint in context 29242 // session context ID 29243 29244 // This command may cause the orderlyState to be cleared due to 29245 // the update of state reset data. If this is the case, check if NV is 29246 // available first 29247 if(gp.orderlyState != SHUTDOWN_NONE) 29248 { 29249 // The command needs NV update. Check if NV is available. 29250 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 29251 // this point 29252 result = NvIsAvailable(); 29253 if(result != TPM_RC_SUCCESS) return result; 29254 } 29255 // Internal Data Update 29256 // Initialize output handle. At the end of command action, the output 29257 // handle of an object will be replaced, while the output handle 29258 // for a session will be the same as input 29259 out->context.savedHandle = in->saveHandle; 29260 // Get the size of fingerprint in context blob. The sequence value in 29261 // TPMS_CONTEXT structure is used as the fingerprint 29262 fingerprintSize = sizeof(out->context.sequence); 29263 // Compute the integrity size at the beginning of context blob 29264 integritySize = sizeof(integrity.t.size) 29265 + CryptGetHashDigestSize(CONTEXT_INTEGRITY_HASH_ALG); 29266 // Perform object or session specific context save 29267 switch(HandleGetType(in->saveHandle)) 29268 { 29269 case TPM_HT_TRANSIENT: 29270 { 29271 29272 Page 356 29273 October 31, 2013 29274 29275 Published 29276 Copyright TCG 2006-2013 29277 29278 Family 2.0 29279 Level 00 Revision 00.99 29280 29281 Trusted Platform Module Library 29283 54 29284 55 29285 56 29286 57 29287 58 29288 59 29289 60 29290 61 29291 62 29292 63 29293 64 29294 65 29295 66 29296 67 29297 68 29298 69 29299 70 29300 71 29301 72 29302 73 29303 74 29304 75 29305 76 29306 77 29307 78 29308 79 29309 80 29310 81 29311 82 29312 83 29313 84 29314 85 29315 86 29316 87 29317 88 29318 89 29319 90 29320 91 29321 92 29322 93 29323 94 29324 95 29325 96 29326 97 29327 98 29328 99 29329 100 29330 101 29331 102 29332 103 29333 104 29334 105 29335 106 29336 107 29337 108 29338 109 29339 110 29340 111 29341 112 29342 113 29343 114 29344 115 29345 116 29346 117 29347 29348 OBJECT 29349 OBJECT 29350 29351 Part 3: Commands 29352 29353 *object = ObjectGet(in->saveHandle); 29354 *outObject = 29355 (OBJECT *)(out->context.contextBlob.t.buffer 29356 + integritySize + fingerprintSize); 29357 29358 // Set size of the context data. The contents of context blob is vendor 29359 // defined. In this implementation, the size is size of integrity 29360 // plus fingerprint plus the whole internal OBJECT structure 29361 out->context.contextBlob.t.size = integritySize + 29362 fingerprintSize + sizeof(*object); 29363 // Copy the whole internal OBJECT structure to context blob, leave 29364 // the size for fingerprint 29365 *outObject = *object; 29366 // Increment object context ID 29367 gr.objectContextID++; 29368 // If object context ID overflows, TPM should be put in failure mode 29369 if(gr.objectContextID == 0) 29370 FAIL(FATAL_ERROR_INTERNAL); 29371 // Fill in other return values for an object. 29372 out->context.sequence = gr.objectContextID; 29373 // For regular object, savedHandle is 0x80000000. For sequence object, 29374 // savedHandle is 0x80000001. For object with stClear, savedHandle 29375 // is 0x80000002 29376 if(ObjectIsSequence(object)) 29377 { 29378 out->context.savedHandle = 0x80000001; 29379 SequenceDataImportExport(object, outObject, EXPORT_STATE); 29380 } 29381 else if(object->attributes.stClear == SET) 29382 { 29383 out->context.savedHandle = 0x80000002; 29384 } 29385 else 29386 { 29387 out->context.savedHandle = 0x80000000; 29388 } 29389 // Get object hierarchy 29390 out->context.hierarchy = ObjectDataGetHierarchy(object); 29391 break; 29392 } 29393 case TPM_HT_HMAC_SESSION: 29394 case TPM_HT_POLICY_SESSION: 29395 { 29396 SESSION 29397 *session = SessionGet(in->saveHandle); 29398 // Set size of the context data. The contents of context blob is vendor 29399 // defined. In this implementation, the size of context blob is the 29400 // size of a internal session structure plus the size of 29401 // fingerprint plus the size of integrity 29402 out->context.contextBlob.t.size = integritySize + 29403 fingerprintSize + sizeof(*session); 29404 // Copy the whole internal SESSION structure to context blob. 29405 // Save space for fingerprint at the beginning of the buffer 29406 // This is done before anything else so that the actual context 29407 // can be reclaimed after this call 29408 MemoryCopy(out->context.contextBlob.t.buffer 29409 + integritySize + fingerprintSize, 29410 session, sizeof(*session), 29411 29412 Family 2.0 29413 Level 00 Revision 00.99 29414 29415 Published 29416 Copyright TCG 2006-2013 29417 29418 Page 357 29419 October 31, 2013 29420 29421 Part 3: Commands 29423 118 29424 119 29425 120 29426 121 29427 122 29428 123 29429 124 29430 125 29431 126 29432 127 29433 128 29434 129 29435 130 29436 131 29437 132 29438 133 29439 134 29440 135 29441 136 29442 137 29443 138 29444 139 29445 140 29446 141 29447 142 29448 143 29449 144 29450 145 29451 146 29452 147 29453 148 29454 149 29455 150 29456 151 29457 152 29458 153 29459 154 29460 155 29461 156 29462 157 29463 158 29464 159 29465 160 29466 161 29467 162 29468 163 29469 164 29470 165 29471 166 29472 167 29473 168 29474 169 29475 170 29476 171 29477 172 29478 173 29479 174 29480 29481 Trusted Platform Module Library 29482 sizeof(out->context.contextBlob.t.buffer) 29483 - integritySize - fingerprintSize); 29484 29485 // Fill in the other return parameters for a session 29486 // Get a context ID and set the session tracking values appropriately 29487 // TPM_RC_CONTEXT_GAP is a possible error. 29488 // SessionContextSave() will flush the in-memory context 29489 // so no additional errors may occur after this call. 29490 result = SessionContextSave(out->context.savedHandle, &contextID); 29491 if(result != TPM_RC_SUCCESS) return result; 29492 // sequence number is the current session contextID 29493 out->context.sequence = contextID; 29494 // use TPM_RH_NULL as hierarchy for session context 29495 out->context.hierarchy = TPM_RH_NULL; 29496 break; 29497 } 29498 default: 29499 // SaveContext may only take an object handle or a session handle. 29500 // All the other handle type should be filtered out at unmarshal 29501 pAssert(FALSE); 29502 break; 29503 } 29504 // Save fingerprint at the beginning of encrypted area of context blob. 29505 // Reserve the integrity space 29506 MemoryCopy(out->context.contextBlob.t.buffer + integritySize, 29507 &out->context.sequence, sizeof(out->context.sequence), 29508 sizeof(out->context.contextBlob.t.buffer) - integritySize); 29509 // Compute context encryption key 29510 ComputeContextProtectionKey(&out->context, &symKey, &iv); 29511 // Encrypt context blob 29512 CryptSymmetricEncrypt(out->context.contextBlob.t.buffer + integritySize, 29513 CONTEXT_ENCRYPT_ALG, CONTEXT_ENCRYPT_KEY_BITS, 29514 TPM_ALG_CFB, symKey.t.buffer, &iv, 29515 out->context.contextBlob.t.size - integritySize, 29516 out->context.contextBlob.t.buffer + integritySize); 29517 // Compute integrity hash for the object 29518 // In this implementation, the same routine is used for both sessions 29519 // and objects. 29520 ComputeContextIntegrity(&out->context, &integrity); 29521 // add integrity at the beginning of context blob 29522 buffer = out->context.contextBlob.t.buffer; 29523 TPM2B_DIGEST_Marshal(&integrity, &buffer, NULL); 29524 // orderly state should be cleared because of the update of state reset and 29525 // state clear data 29526 g_clearOrderly = TRUE; 29527 return TPM_RC_SUCCESS; 29528 } 29529 29530 Page 358 29531 October 31, 2013 29532 29533 Published 29534 Copyright TCG 2006-2013 29535 29536 Family 2.0 29537 Level 00 Revision 00.99 29538 29539 Trusted Platform Module Library 29541 29542 30.3 29543 29544 Part 3: Commands 29545 29546 TPM2_ContextLoad 29547 29548 30.3.1 General Description 29549 This command is used to reload a context that has been saved by TPM2_ContextSave(). 29550 No authorization sessions of any type are allowed with this command and tag is required to be 29551 TPM_ST_NO_SESSIONS (see note in 30.2.1). 29552 The TPM will return TPM_RC_HIERARCHY if the context is associated with a hierarchy that is disabled. 29553 NOTE 29554 29555 Contexts for authorization sessions and for sequence object s belong to the NULL hierarchy which is 29556 never disabled. 29557 29558 See the Context Data clause in Part 2 for a description of the values in the context parameter. 29559 If the integrity HMAC of the saved context is not valid, the TPM shall return TPM_RC_INTEGRITY. 29560 The TPM shall perform a check on the decrypted context as described in the "Context Confidentiality 29561 Protections" clause of Part 1 and enter failure mode if the check fails. 29562 29563 Family 2.0 29564 Level 00 Revision 00.99 29565 29566 Published 29567 Copyright TCG 2006-2013 29568 29569 Page 359 29570 October 31, 2013 29571 29572 Part 3: Commands 29574 29575 Trusted Platform Module Library 29576 29577 30.3.2 Command and Response 29578 Table 181 TPM2_ContextLoad Command 29579 Type 29580 29581 Name 29582 29583 Description 29584 29585 TPMI_ST_COMMAND_TAG 29586 29587 tag 29588 29589 TPM_ST_NO_SESSIONS 29590 29591 UINT32 29592 29593 commandSize 29594 29595 TPM_CC 29596 29597 commandCode 29598 29599 TPM_CC_ContextLoad 29600 29601 TPMS_CONTEXT 29602 29603 context 29604 29605 the context blob 29606 29607 Table 182 TPM2_ContextLoad Response 29608 Type 29609 29610 Name 29611 29612 Description 29613 29614 TPM_ST 29615 29616 tag 29617 29618 see clause 8 29619 29620 UINT32 29621 29622 responseSize 29623 29624 TPM_RC 29625 29626 responseCode 29627 29628 TPMI_DH_CONTEXT 29629 29630 loadedHandle 29631 29632 Page 360 29633 October 31, 2013 29634 29635 the handle assigned to the resource after it has been 29636 successfully loaded 29637 29638 Published 29639 Copyright TCG 2006-2013 29640 29641 Family 2.0 29642 Level 00 Revision 00.99 29643 29644 Trusted Platform Module Library 29646 29647 Part 3: Commands 29648 29649 30.3.3 Detailed Actions 29650 1 29651 2 29652 3 29653 29654 #include "InternalRoutines.h" 29655 #include "ContextLoad_fp.h" 29656 #include "Context_spt_fp.h" 29657 Error Returns 29658 TPM_RC_CONTEXT_GAP 29659 29660 there is only one available slot and this is not the oldest saved 29661 session context 29662 29663 TPM_RC_HANDLE 29664 29665 'context. savedHandle' does not reference a saved session 29666 29667 TPM_RC_HIERARCHY 29668 29669 'context.hierarchy' is disabled 29670 29671 TPM_RC_INTEGRITY 29672 29673 context integrity check fail 29674 29675 TPM_RC_OBJECT_MEMORY 29676 29677 no free slot for an object 29678 29679 TPM_RC_SESSION_MEMORY 29680 29681 no free session slots 29682 29683 TPM_RC_SIZE 29684 4 29685 5 29686 6 29687 7 29688 8 29689 9 29690 10 29691 11 29692 12 29693 13 29694 14 29695 15 29696 16 29697 17 29698 18 29699 19 29700 20 29701 21 29702 22 29703 23 29704 24 29705 25 29706 26 29707 27 29708 28 29709 29 29710 30 29711 31 29712 32 29713 33 29714 34 29715 35 29716 36 29717 37 29718 38 29719 39 29720 40 29721 41 29722 42 29723 43 29724 29725 Meaning 29726 29727 incorrect context blob size 29728 29729 TPM_RC 29730 TPM2_ContextLoad( 29731 ContextLoad_In 29732 ContextLoad_Out 29733 29734 *in, 29735 *out 29736 29737 // IN: input parameter list 29738 // OUT: output parameter list 29739 29740 ) 29741 { 29742 // Local Variables 29743 TPM_RC 29744 result = TPM_RC_SUCCESS; 29745 TPM2B_DIGEST 29746 TPM2B_DIGEST 29747 UINT16 29748 UINT64 29749 BYTE 29750 INT32 29751 29752 ingerityToCompare; 29753 integrity; 29754 integritySize; 29755 fingerprint; 29756 *buffer; 29757 size; 29758 29759 TPM_HT 29760 TPM2B_SYM_KEY 29761 TPM2B_IV 29762 29763 handleType; 29764 symKey; 29765 iv; 29766 29767 // Input Validation 29768 // Check context blob size 29769 handleType = HandleGetType(in->context.savedHandle); 29770 // Check integrity 29771 // In this implementation, the same routine is used for both sessions 29772 // and objects. 29773 integritySize = sizeof(integrity.t.size) 29774 + CryptGetHashDigestSize(CONTEXT_INTEGRITY_HASH_ALG); 29775 // Get integrity from context blob 29776 buffer = in->context.contextBlob.t.buffer; 29777 size = (INT32) in->context.contextBlob.t.size; 29778 result = TPM2B_DIGEST_Unmarshal(&integrity, &buffer, &size); 29779 if(result != TPM_RC_SUCCESS) 29780 return result; 29781 // Compute context integrity 29782 ComputeContextIntegrity(&in->context, &ingerityToCompare); 29783 29784 Family 2.0 29785 Level 00 Revision 00.99 29786 29787 Published 29788 Copyright TCG 2006-2013 29789 29790 Page 361 29791 October 31, 2013 29792 29793 Part 3: Commands 29795 44 29796 45 29797 46 29798 47 29799 48 29800 49 29801 50 29802 51 29803 52 29804 53 29805 54 29806 55 29807 56 29808 57 29809 58 29810 59 29811 60 29812 61 29813 62 29814 63 29815 64 29816 65 29817 66 29818 67 29819 68 29820 69 29821 70 29822 71 29823 72 29824 73 29825 74 29826 75 29827 76 29828 77 29829 78 29830 79 29831 80 29832 81 29833 82 29834 83 29835 84 29836 85 29837 86 29838 87 29839 88 29840 89 29841 90 29842 91 29843 92 29844 93 29845 94 29846 95 29847 96 29848 97 29849 98 29850 99 29851 100 29852 101 29853 102 29854 103 29855 104 29856 105 29857 106 29858 107 29859 29860 Trusted Platform Module Library 29861 29862 // Compare integrity 29863 if(!Memory2BEqual(&integrity.b, &ingerityToCompare.b)) 29864 return TPM_RC_INTEGRITY + RC_ContextLoad_context; 29865 // Compute context encryption key 29866 ComputeContextProtectionKey(&in->context, &symKey, &iv); 29867 // Decrypt context data in place 29868 CryptSymmetricDecrypt(in->context.contextBlob.t.buffer + integritySize, 29869 CONTEXT_ENCRYPT_ALG, CONTEXT_ENCRYPT_KEY_BITS, 29870 TPM_ALG_CFB, symKey.t.buffer, &iv, 29871 in->context.contextBlob.t.size - integritySize, 29872 in->context.contextBlob.t.buffer + integritySize); 29873 // Read the fingerprint value, skip the leading integrity size 29874 MemoryCopy(&fingerprint, in->context.contextBlob.t.buffer + integritySize, 29875 sizeof(fingerprint), sizeof(fingerprint)); 29876 // Check fingerprint. If the check fails, TPM should be put to failure mode 29877 if(fingerprint != in->context.sequence) 29878 FAIL(FATAL_ERROR_INTERNAL); 29879 // Perform object or session specific input check 29880 switch(handleType) 29881 { 29882 case TPM_HT_TRANSIENT: 29883 { 29884 // Get a pointer to the object in the context blob 29885 OBJECT 29886 *outObject = (OBJECT *)(in->context.contextBlob.t.buffer 29887 + integritySize + sizeof(fingerprint)); 29888 // Discard any changes to the handle that the TRM might have made 29889 in->context.savedHandle = TRANSIENT_FIRST; 29890 // If hierarchy is disabled, no object context can be loaded in this 29891 // hierarchy 29892 if(!HierarchyIsEnabled(in->context.hierarchy)) 29893 return TPM_RC_HIERARCHY + RC_ContextLoad_context; 29894 // Restore object. A TPM_RC_OBJECT_MEMORY error may be returned at 29895 // this point 29896 result = ObjectContextLoad(outObject, &out->loadedHandle); 29897 if(result != TPM_RC_SUCCESS) 29898 return result; 29899 // If this is a sequence object, the crypto library may need to 29900 // reformat the data into an internal format 29901 if(ObjectIsSequence(outObject)) 29902 SequenceDataImportExport(ObjectGet(out->loadedHandle), 29903 outObject, IMPORT_STATE); 29904 break; 29905 } 29906 case TPM_HT_POLICY_SESSION: 29907 case TPM_HT_HMAC_SESSION: 29908 { 29909 SESSION 29910 29911 *session = (SESSION *)(in->context.contextBlob.t.buffer 29912 + integritySize + sizeof(fingerprint)); 29913 29914 // This command may cause the orderlyState to be cleared due to 29915 // the update of state reset data. If this is the case, check if NV is 29916 // available first 29917 29918 Page 362 29919 October 31, 2013 29920 29921 Published 29922 Copyright TCG 2006-2013 29923 29924 Family 2.0 29925 Level 00 Revision 00.99 29926 29927 Trusted Platform Module Library 29929 108 29930 109 29931 110 29932 111 29933 112 29934 113 29935 114 29936 115 29937 116 29938 117 29939 118 29940 119 29941 120 29942 121 29943 122 29944 123 29945 124 29946 125 29947 126 29948 127 29949 128 29950 129 29951 130 29952 131 29953 132 29954 133 29955 134 29956 135 29957 136 29958 137 29959 138 29960 139 29961 140 29962 141 29963 142 29964 143 29965 144 29966 29967 Part 3: Commands 29968 29969 if(gp.orderlyState != SHUTDOWN_NONE) 29970 { 29971 // The command needs NV update. Check if NV is available. 29972 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned 29973 // at this point 29974 result = NvIsAvailable(); 29975 if(result != TPM_RC_SUCCESS) 29976 return result; 29977 } 29978 // Check if input handle points to a valid saved session 29979 if(!SessionIsSaved(in->context.savedHandle)) 29980 return TPM_RC_HANDLE + RC_ContextLoad_context; 29981 // Restore session. A TPM_RC_SESSION_MEMORY, TPM_RC_CONTEXT_GAP error 29982 // may be returned at this point 29983 result = SessionContextLoad(session, &in->context.savedHandle); 29984 if(result != TPM_RC_SUCCESS) 29985 return result; 29986 out->loadedHandle = in->context.savedHandle; 29987 // orderly state should be cleared because of the update of state 29988 // reset and state clear data 29989 g_clearOrderly = TRUE; 29990 break; 29991 } 29992 default: 29993 // Context blob may only have an object handle or a session handle. 29994 // All the other handle type should be filtered out at unmarshal 29995 pAssert(FALSE); 29996 break; 29997 } 29998 return TPM_RC_SUCCESS; 29999 } 30000 30001 Family 2.0 30002 Level 00 Revision 00.99 30003 30004 Published 30005 Copyright TCG 2006-2013 30006 30007 Page 363 30008 October 31, 2013 30009 30010 Part 3: Commands 30012 30013 30.4 30014 30015 Trusted Platform Module Library 30016 30017 TPM2_FlushContext 30018 30019 30.4.1 General Description 30020 This command causes all context associated with a loaded object or session to be removed from TPM 30021 memory. 30022 This command may not be used to remove a persistent object from the TPM. 30023 A session does not have to be loaded in TPM memory to have its context flushed. The saved session 30024 context associated with the indicated handle is invalidated. 30025 No sessions of any type are allowed with 30026 TPM_ST_NO_SESSIONS (see note in 30.2.1). 30027 30028 this 30029 30030 command 30031 30032 and 30033 30034 tag 30035 30036 is 30037 30038 required 30039 30040 to 30041 30042 be 30043 30044 If the handle is for a transient object and the handle is not associated with a loaded object, then the TPM 30045 shall return TPM_RC_HANDLE. 30046 If the handle is for an authorization session and the handle does not reference a loaded or active session, 30047 then the TPM shall return TPM_RC_HANDLE. 30048 NOTE 30049 30050 flushHandle is a parameter and not a handle. If it were in the handle area, the TPM would validate 30051 that the context for the referenced entity is in the TPM. When a TPM2_FlushContext references a 30052 saved session context, it is not necessary for the context to be in the TPM . 30053 30054 Page 364 30055 October 31, 2013 30056 30057 Published 30058 Copyright TCG 2006-2013 30059 30060 Family 2.0 30061 Level 00 Revision 00.99 30062 30063 Trusted Platform Module Library 30065 30066 Part 3: Commands 30067 30068 30.4.2 Command and Response 30069 Table 183 TPM2_FlushContext Command 30070 Type 30071 30072 Name 30073 30074 Description 30075 30076 TPMI_ST_COMMAND_TAG 30077 30078 tag 30079 30080 TPM_ST_NO_SESSIONS 30081 30082 UINT32 30083 30084 commandSize 30085 30086 TPM_CC 30087 30088 commandCode 30089 30090 TPMI_DH_CONTEXT 30091 30092 flushHandle 30093 30094 TPM_CC_FlushContext 30095 the handle of the item to flush 30096 NOTE 30097 30098 This is a use of a handle as a parameter. 30099 30100 Table 184 TPM2_FlushContext Response 30101 Type 30102 30103 Name 30104 30105 Description 30106 30107 TPM_ST 30108 30109 tag 30110 30111 see clause 8 30112 30113 UINT32 30114 30115 responseSize 30116 30117 TPM_RC 30118 30119 responseCode 30120 30121 Family 2.0 30122 Level 00 Revision 00.99 30123 30124 Published 30125 Copyright TCG 2006-2013 30126 30127 Page 365 30128 October 31, 2013 30129 30130 Part 3: Commands 30132 30133 Trusted Platform Module Library 30134 30135 30.4.3 Detailed Actions 30136 1 30137 2 30138 30139 #include "InternalRoutines.h" 30140 #include "FlushContext_fp.h" 30141 Error Returns 30142 TPM_RC_HANDLE 30143 30144 3 30145 4 30146 5 30147 6 30148 7 30149 8 30150 9 30151 10 30152 11 30153 12 30154 13 30155 14 30156 15 30157 16 30158 17 30159 18 30160 19 30161 20 30162 21 30163 22 30164 23 30165 24 30166 25 30167 26 30168 27 30169 28 30170 29 30171 30 30172 31 30173 32 30174 33 30175 34 30176 35 30177 36 30178 37 30179 38 30180 39 30181 40 30182 41 30183 42 30184 30185 Meaning 30186 flushHandle does not reference a loaded object or session 30187 30188 TPM_RC 30189 TPM2_FlushContext( 30190 FlushContext_In 30191 ) 30192 { 30193 // Internal Data Update 30194 30195 *in 30196 30197 // IN: input parameter list 30198 30199 // Call object or session specific routine to flush 30200 switch(HandleGetType(in->flushHandle)) 30201 { 30202 case TPM_HT_TRANSIENT: 30203 if(!ObjectIsPresent(in->flushHandle)) 30204 return TPM_RC_HANDLE; 30205 // Flush object 30206 ObjectFlush(in->flushHandle); 30207 break; 30208 case TPM_HT_HMAC_SESSION: 30209 case TPM_HT_POLICY_SESSION: 30210 if( 30211 !SessionIsLoaded(in->flushHandle) 30212 && !SessionIsSaved(in->flushHandle) 30213 ) 30214 return TPM_RC_HANDLE; 30215 // If the session to be flushed is the exclusive audit session, then 30216 // indicate that there is no exclusive audit session any longer. 30217 if(in->flushHandle == g_exclusiveAuditSession) 30218 g_exclusiveAuditSession = TPM_RH_UNASSIGNED; 30219 // Flush session 30220 SessionFlush(in->flushHandle); 30221 break; 30222 default: 30223 // This command only take object or session handle. 30224 // should be filtered out at handle unmarshal 30225 pAssert(FALSE); 30226 break; 30227 } 30228 30229 Other handles 30230 30231 return TPM_RC_SUCCESS; 30232 } 30233 30234 Page 366 30235 October 31, 2013 30236 30237 Published 30238 Copyright TCG 2006-2013 30239 30240 Family 2.0 30241 Level 00 Revision 00.99 30242 30243 Trusted Platform Module Library 30245 30246 30.5 30247 30248 Part 3: Commands 30249 30250 TPM2_EvictControl 30251 30252 30.5.1 General Description 30253 This command allows a transient object to be made persistent or a persistent object to be evicted. 30254 NOTE 1 30255 30256 A transient object is one that may be removed from TPM memory using either TPM2_FlushContext 30257 or TPM2_Startup(). A persistent object is not removed from TPM memory by TPM2_FlushContext() 30258 or TPM2_Startup(). 30259 30260 If objectHandle is a transient object, then the call is to make the object persistent and assign 30261 persistentHandle to the persistent version of the object. If objectHandle is a persistent object, then the call 30262 is to evict the persistent object. 30263 Before execution of TPM2_EvictControl code below, the TPM verifies that objectHandle references an 30264 object that is resident on the TPM and that persistentHandle is a valid handle for a persistent object. 30265 NOTE 2 30266 30267 This requirement simplifies the unmarshaling code so that it only need check that persistentHandle 30268 is always a persistent object. 30269 30270 If objectHandle references a transient object: 30271 a) The TPM shall return TPM_RC_ATTRIBUTES if 30272 1) it is in the hierarchy of TPM_RH_NULL, 30273 2) only the public portion of the object is loaded, or 30274 3) the stClear is SET in the object or in an ancestor key. 30275 b) The TPM shall return TPM_RC_HIERARCHY if the object is not in the proper hierarchy as 30276 determined by auth. 30277 1) If auth is TPM_RH_PLATFORM, the proper hierarchy is the Platform hierarchy. 30278 2) If auth is TPM_RH_OWNER, the proper hierarchy is either the Storage or the Endorsement 30279 hierarchy. 30280 c) The TPM shall return TPM_RC_RANGE if persistentHandle is not in the proper range as determined 30281 by auth. 30282 1) If auth is TPM_RH_OWNER, then persistentHandle shall be in the inclusive range of 30283 81 00 00 0016 to 81 7F FF FF16. 30284 2) If auth is TPM_RH_PLATFORM, then persistentHandle shall be in the inclusive range of 30285 81 80 00 0016 to 81 FF FF FF16. 30286 d) The TPM shall return TPM_RC_NV_DEFINED if a persistent object exists with the same handle as 30287 persistentHandle. 30288 e) The TPM shall return TPM_RC_NV_SPACE if insufficient space is available to make the object 30289 persistent. 30290 f) 30291 30292 The TPM shall return TPM_RC_NV_SPACE if execution of this command will prevent the TPM from 30293 being able to hold two transient objects of any kind. 30294 NOTE 3 30295 30296 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 30297 between memory of different types and it is necessary that the TPM ensure that it is always 30298 possible for the management software to move objects to/from TPM memory in order to ensure 30299 that the objects required for command execution can be context restored. 30300 30301 Family 2.0 30302 Level 00 Revision 00.99 30303 30304 Published 30305 Copyright TCG 2006-2013 30306 30307 Page 367 30308 October 31, 2013 30309 30310 Part 3: Commands 30312 30313 Trusted Platform Module Library 30314 30315 g) If the TPM returns TPM_RC_SUCCESS, the object referenced by objectHandle will not be flushed 30316 and both objectHandle and persistentHandle may be used to access the object. 30317 If objectHandle references a persistent object: 30318 h) The TPM shall return TPM_RC_RANGE if objectHandle is not in the proper range as determined by 30319 auth. If auth is TPM_RC_OWNER, objectHandle shall be in the inclusive range of 81 00 00 0016 to 30320 81 7F FF FF16. If auth is TPM_RC_PLATFORM, objectHandle may be any valid persistent object 30321 handle. 30322 i) 30323 30324 If the TPM returns TPM_RC_SUCCESS, objectHandle will be removed from persistent memory and 30325 no longer be accessible. 30326 30327 NOTE 4 30328 30329 The persistent object is not converted to a transient object, as this would prevent the immediate 30330 revocation of an object by removing it from persistent memory. 30331 30332 Page 368 30333 October 31, 2013 30334 30335 Published 30336 Copyright TCG 2006-2013 30337 30338 Family 2.0 30339 Level 00 Revision 00.99 30340 30341 Trusted Platform Module Library 30343 30344 Part 3: Commands 30345 30346 30.5.2 Command and Response 30347 Table 185 TPM2_EvictControl Command 30348 Type 30349 30350 Name 30351 30352 TPMI_ST_COMMAND_TAG 30353 30354 tag 30355 30356 UINT32 30357 30358 commandSize 30359 30360 TPM_CC 30361 30362 commandCode 30363 30364 TPM_CC_EvictControl {NV} 30365 30366 TPMI_RH_PROVISION 30367 30368 @auth 30369 30370 TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} 30371 Auth Handle: 1 30372 Auth Role: USER 30373 30374 TPMI_DH_OBJECT 30375 30376 objectHandle 30377 30378 the handle of a loaded object 30379 Auth Index: None 30380 30381 TPMI_DH_PERSISTENT 30382 30383 persistentHandle 30384 30385 if objectHandle is a transient object handle, then this is 30386 the persistent handle for the object 30387 if objectHandle is a persistent object handle, then this 30388 shall be the same value as persistentHandle 30389 30390 Description 30391 30392 Table 186 TPM2_EvictControl Response 30393 Type 30394 30395 Name 30396 30397 Description 30398 30399 TPM_ST 30400 30401 tag 30402 30403 see clause 8 30404 30405 UINT32 30406 30407 responseSize 30408 30409 TPM_RC 30410 30411 responseCode 30412 30413 Family 2.0 30414 Level 00 Revision 00.99 30415 30416 Published 30417 Copyright TCG 2006-2013 30418 30419 Page 369 30420 October 31, 2013 30421 30422 Part 3: Commands 30424 30425 Trusted Platform Module Library 30426 30427 30.5.3 Detailed Actions 30428 1 30429 2 30430 30431 #include "InternalRoutines.h" 30432 #include "EvictControl_fp.h" 30433 Error Returns 30434 TPM_RC_ATTRIBUTES 30435 30436 an object with temporary, stClear or publicOnly attribute SET cannot 30437 be made persistent 30438 30439 TPM_RC_HIERARCHY 30440 30441 auth cannot authorize the operation in the hierarchy of evictObject 30442 30443 TPM_RC_HANDLE 30444 30445 evictHandle of the persistent object to be evicted is not the same as 30446 the persistentHandle argument 30447 30448 TPM_RC_NV_HANDLE 30449 30450 persistentHandle is unavailable 30451 30452 TPM_RC_NV_SPACE 30453 30454 no space in NV to make evictHandle persistent 30455 30456 TPM_RC_RANGE 30457 30458 3 30459 4 30460 5 30461 6 30462 7 30463 8 30464 9 30465 10 30466 11 30467 12 30468 13 30469 14 30470 15 30471 16 30472 17 30473 18 30474 19 30475 20 30476 21 30477 22 30478 23 30479 24 30480 25 30481 26 30482 27 30483 28 30484 29 30485 30 30486 31 30487 32 30488 33 30489 34 30490 35 30491 36 30492 37 30493 38 30494 39 30495 40 30496 41 30497 42 30498 43 30499 30500 Meaning 30501 30502 persistentHandle is not in the range corresponding to the hierarchy of 30503 evictObject 30504 30505 TPM_RC 30506 TPM2_EvictControl( 30507 EvictControl_In 30508 30509 *in 30510 30511 // IN: input parameter list 30512 30513 ) 30514 { 30515 TPM_RC 30516 OBJECT 30517 30518 result; 30519 *evictObject; 30520 30521 // The command needs NV update. Check if NV is available. 30522 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 30523 // this point 30524 result = NvIsAvailable(); 30525 if(result != TPM_RC_SUCCESS) return result; 30526 // Input Validation 30527 // Get internal object pointer 30528 evictObject = ObjectGet(in->objectHandle); 30529 // Temporary, stClear or public only objects can not be made persistent 30530 if( 30531 evictObject->attributes.temporary == SET 30532 || evictObject->attributes.stClear == SET 30533 || evictObject->attributes.publicOnly == SET 30534 ) 30535 return TPM_RC_ATTRIBUTES + RC_EvictControl_objectHandle; 30536 // If objectHandle refers to a persistent object, it should be the same as 30537 // input persistentHandle 30538 if( 30539 evictObject->attributes.evict == SET 30540 && evictObject->evictHandle != in->persistentHandle 30541 ) 30542 return TPM_RC_HANDLE + RC_EvictControl_objectHandle; 30543 // Additional auth validation 30544 if(in->auth == TPM_RH_PLATFORM) 30545 { 30546 // To make persistent 30547 if(evictObject->attributes.evict == CLEAR) 30548 { 30549 // Platform auth can not set evict object in storage or endorsement 30550 // hierarchy 30551 30552 Page 370 30553 October 31, 2013 30554 30555 Published 30556 Copyright TCG 2006-2013 30557 30558 Family 2.0 30559 Level 00 Revision 00.99 30560 30561 Trusted Platform Module Library 30563 44 30564 45 30565 46 30566 47 30567 48 30568 49 30569 50 30570 51 30571 52 30572 53 30573 54 30574 55 30575 56 30576 57 30577 58 30578 59 30579 60 30580 61 30581 62 30582 63 30583 64 30584 65 30585 66 30586 67 30587 68 30588 69 30589 70 30590 71 30591 72 30592 73 30593 74 30594 75 30595 76 30596 77 30597 78 30598 79 30599 80 30600 81 30601 82 30602 83 30603 84 30604 85 30605 86 30606 87 30607 88 30608 89 30609 90 30610 91 30611 30612 Part 3: Commands 30613 30614 if(evictObject->attributes.ppsHierarchy == CLEAR) 30615 return TPM_RC_HIERARCHY + RC_EvictControl_objectHandle; 30616 // Platform cannot use a handle outside of platform persistent range. 30617 if(!NvIsPlatformPersistentHandle(in->persistentHandle)) 30618 return TPM_RC_RANGE + RC_EvictControl_persistentHandle; 30619 } 30620 // Platform auth can delete any persistent object 30621 } 30622 else if(in->auth == TPM_RH_OWNER) 30623 { 30624 // Owner auth can not set or clear evict object in platform hierarchy 30625 if(evictObject->attributes.ppsHierarchy == SET) 30626 return TPM_RC_HIERARCHY + RC_EvictControl_objectHandle; 30627 // Owner cannot use a handle outside of owner persistent range. 30628 if( 30629 evictObject->attributes.evict == CLEAR 30630 && !NvIsOwnerPersistentHandle(in->persistentHandle) 30631 ) 30632 return TPM_RC_RANGE + RC_EvictControl_persistentHandle; 30633 } 30634 else 30635 { 30636 // Other auth is not allowed in this command and should be filtered out 30637 // at unmarshal process 30638 pAssert(FALSE); 30639 } 30640 // Internal Data Update 30641 // Change evict state 30642 if(evictObject->attributes.evict == CLEAR) 30643 { 30644 // Make object persistent 30645 // A TPM_RC_NV_HANDLE or TPM_RC_NV_SPACE error may be returned at this 30646 // point 30647 result = NvAddEvictObject(in->persistentHandle, evictObject); 30648 if(result != TPM_RC_SUCCESS) return result; 30649 } 30650 else 30651 { 30652 // Delete the persistent object in NV 30653 NvDeleteEntity(evictObject->evictHandle); 30654 } 30655 return TPM_RC_SUCCESS; 30656 } 30657 30658 Family 2.0 30659 Level 00 Revision 00.99 30660 30661 Published 30662 Copyright TCG 2006-2013 30663 30664 Page 371 30665 October 31, 2013 30666 30667 Part 3: Commands 30669 30670 31 30671 30672 Trusted Platform Module Library 30673 30674 Clocks and Timers 30675 30676 31.1 30677 30678 TPM2_ReadClock 30679 30680 31.1.1 General Description 30681 This command reads the current TPMS_TIME_INFO structure that contains the current setting of Time, 30682 Clock, resetCount, and restartCount. 30683 No authorization sessions of any type are allowed with this command and tag is required to be 30684 TPM_ST_NO_SESSIONS. 30685 NOTE 30686 30687 This command is intended to allow the TCB to have access to values that have the potential to be 30688 privacy sensitive. The values may be read without authorization because the TCB will not disclose 30689 these values. Since they are not signed and cannot be accessed in a command that uses an 30690 authorization session, it is not possible for any entity, other than the TCB, to be assured that the 30691 values are accurate. 30692 30693 Page 372 30694 October 31, 2013 30695 30696 Published 30697 Copyright TCG 2006-2013 30698 30699 Family 2.0 30700 Level 00 Revision 00.99 30701 30702 Trusted Platform Module Library 30704 30705 Part 3: Commands 30706 30707 31.1.2 Command and Response 30708 Table 187 TPM2_ReadClock Command 30709 Type 30710 30711 Name 30712 30713 Description 30714 30715 TPMI_ST_COMMAND_TAG 30716 30717 tag 30718 30719 TPM_ST_NO_SESSIONS 30720 30721 UINT32 30722 30723 commandSize 30724 30725 TPM_CC 30726 30727 commandCode 30728 30729 TPM_CC_ReadClock 30730 30731 Table 188 TPM2_ReadClock Response 30732 Type 30733 30734 Name 30735 30736 Description 30737 30738 TPM_ST 30739 30740 tag 30741 30742 see clause 8 30743 30744 UINT32 30745 30746 responseSize 30747 30748 TPM_RC 30749 30750 returnCode 30751 30752 TPMS_TIME_INFO 30753 30754 currentTime 30755 30756 Family 2.0 30757 Level 00 Revision 00.99 30758 30759 Published 30760 Copyright TCG 2006-2013 30761 30762 Page 373 30763 October 31, 2013 30764 30765 Part 3: Commands 30767 30768 Trusted Platform Module Library 30769 30770 31.1.3 Detailed Actions 30771 1 30772 2 30773 3 30774 4 30775 5 30776 6 30777 7 30778 8 30779 9 30780 10 30781 11 30782 12 30783 13 30784 14 30785 30786 #include "InternalRoutines.h" 30787 #include "ReadClock_fp.h" 30788 30789 TPM_RC 30790 TPM2_ReadClock( 30791 ReadClock_Out *out 30792 ) 30793 { 30794 // Command Output 30795 30796 // OUT: output parameter list 30797 30798 out->currentTime.time = g_time; 30799 TimeFillInfo(&out->currentTime.clockInfo); 30800 return TPM_RC_SUCCESS; 30801 } 30802 30803 Page 374 30804 October 31, 2013 30805 30806 Published 30807 Copyright TCG 2006-2013 30808 30809 Family 2.0 30810 Level 00 Revision 00.99 30811 30812 Trusted Platform Module Library 30814 30815 31.2 30816 30817 Part 3: Commands 30818 30819 TPM2_ClockSet 30820 30821 31.2.1 General Description 30822 This command is used to advance the value of the TPMs Clock. The command will fail if newTime is less 30823 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 30824 these checks succeed, Clock is set to newTime. If either of these checks fails, the TPM shall return 30825 TPM_RC_VALUE and make no change to Clock. 30826 NOTE 30827 30828 This maximum setting would prevent Clock from rolling over to zero for approximately 8,000 years if 30829 the Clock update rate was set so that TPM time was passing 33 percent faster than real time. This 30830 would still be more than 6,000 years before Clock would roll over to zero. Because Clock will not roll 30831 over in the lifetime of the TPM, there is no need for external software to deal with the possibility that 30832 Clock may wrap around. 30833 30834 If the value of Clock after the update makes the volatile and non-volatile versions of 30835 TPMS_CLOCK_INFO.clock differ by more than the reported update interval, then the TPM shall update 30836 the non-volatile version of TPMS_CLOCK_INFO.clock before returning. 30837 This command requires platformAuth or ownerAuth. 30838 30839 Family 2.0 30840 Level 00 Revision 00.99 30841 30842 Published 30843 Copyright TCG 2006-2013 30844 30845 Page 375 30846 October 31, 2013 30847 30848 Part 3: Commands 30850 30851 Trusted Platform Module Library 30852 30853 31.2.2 Command and Response 30854 Table 189 TPM2_ClockSet Command 30855 Type 30856 30857 Name 30858 30859 Description 30860 30861 TPMI_ST_COMMAND_TAG 30862 30863 tag 30864 30865 UINT32 30866 30867 commandSize 30868 30869 TPM_CC 30870 30871 commandCode 30872 30873 TPM_CC_ClockSet {NV} 30874 30875 TPMI_RH_PROVISION 30876 30877 @auth 30878 30879 TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} 30880 Auth Handle: 1 30881 Auth Role: USER 30882 30883 UINT64 30884 30885 newTime 30886 30887 new Clock setting in milliseconds 30888 30889 Table 190 TPM2_ClockSet Response 30890 Type 30891 30892 Name 30893 30894 Description 30895 30896 TPM_ST 30897 30898 tag 30899 30900 see clause 8 30901 30902 UINT32 30903 30904 responseSize 30905 30906 TPM_RC 30907 30908 returnCode 30909 30910 Page 376 30911 October 31, 2013 30912 30913 Published 30914 Copyright TCG 2006-2013 30915 30916 Family 2.0 30917 Level 00 Revision 00.99 30918 30919 Trusted Platform Module Library 30921 30922 Part 3: Commands 30923 30924 31.2.3 Detailed Actions 30925 1 30926 2 30927 30928 #include "InternalRoutines.h" 30929 #include "ClockSet_fp.h" 30930 30931 Read the current TPMS_TIMER_INFO structure settings 30932 Error Returns 30933 TPM_RC_VALUE 30934 3 30935 4 30936 5 30937 6 30938 7 30939 8 30940 9 30941 10 30942 11 30943 12 30944 13 30945 14 30946 15 30947 16 30948 17 30949 18 30950 19 30951 20 30952 21 30953 22 30954 23 30955 24 30956 25 30957 26 30958 27 30959 28 30960 29 30961 30 30962 31 30963 32 30964 33 30965 34 30966 35 30967 30968 Meaning 30969 invalid new clock 30970 30971 TPM_RC 30972 TPM2_ClockSet( 30973 ClockSet_In *in 30974 ) 30975 { 30976 #define CLOCK_UPDATE_MASK 30977 UINT64 30978 clockNow; 30979 30980 // IN: input parameter list 30981 ((1ULL << NV_CLOCK_UPDATE_INTERVAL)- 1) 30982 30983 // Input Validation 30984 // new time can not be bigger than 0xFFFF000000000000 or smaller than 30985 // current clock 30986 if(in->newTime > 0xFFFF000000000000ULL 30987 || in->newTime < go.clock) 30988 return TPM_RC_VALUE + RC_ClockSet_newTime; 30989 // Internal Data Update 30990 // Internal Data Update 30991 clockNow = go.clock; 30992 // grab the old value 30993 go.clock = in->newTime; 30994 // set the new value 30995 // Check to see if the update has caused a need for an nvClock update 30996 if((in->newTime & CLOCK_UPDATE_MASK) > (clockNow & CLOCK_UPDATE_MASK)) 30997 { 30998 CryptDrbgGetPutState(GET_STATE); 30999 NvWriteReserved(NV_ORDERLY_DATA, &go); 31000 // Now the time state is safe 31001 go.clockSafe = YES; 31002 } 31003 return TPM_RC_SUCCESS; 31004 } 31005 31006 Family 2.0 31007 Level 00 Revision 00.99 31008 31009 Published 31010 Copyright TCG 2006-2013 31011 31012 Page 377 31013 October 31, 2013 31014 31015 Part 3: Commands 31017 31018 31.3 31019 31020 Trusted Platform Module Library 31021 31022 TPM2_ClockRateAdjust 31023 31024 31.3.1 General Description 31025 This command adjusts the rate of advance of Clock and Time to provide a better approximation to real 31026 time. 31027 The rateAdjust value is relative to the current rate and not the nominal rate of advance. 31028 EXAMPLE 1 31029 31030 If this command had been called three times with rateAdjust = TPM_CLOCK_COARSE_SLOWER 31031 and once with rateAdjust = TPM_CLOCK_COARSE_FASTER, the net effect will be as if the 31032 command had been called twice with rateAdjust = TPM_CLOCK_COARSE_SLOWER. 31033 31034 The range of adjustment shall be sufficient to allow Clock and Time to advance at real time but no more. 31035 If the requested adjustment would make the rate advance faster or slower than the nominal accuracy of 31036 the input frequency, the TPM shall return TPM_RC_VALUE. 31037 EXAMPLE 2 31038 31039 If the frequency tolerance of the TPM's input clock is +/-10 percent, then the TPM will return 31040 TPM_RC_VALUE if the adjustment would make Clock run more than 10 percent faster or slower than 31041 nominal. That is, if the input oscillator were nominally 100 megahertz (MHz), then 1 millisecond (ms) 31042 would normally take 100,000 counts. The update Clock should be adjustable so that 1 ms is between 31043 90,000 and 110,000 counts. 31044 31045 The interpretation of fine and coarse adjustments is implementation-specific. 31046 The nominal rate of advance for Clock and Time shall be accurate to within 15 percent. That is, with no 31047 adjustment applied, Clock and Time shall be advanced at a rate within 15 percent of actual time. 31048 NOTE 31049 31050 If the adjustments are incorrect, it will be possible to m ake the difference between advance of 31051 Clock/Time and real time to be as much as 1.15 2 or ~1.33. 31052 31053 Changes to the current Clock update rate adjustment need not be persisted across TPM power cycles. 31054 31055 Page 378 31056 October 31, 2013 31057 31058 Published 31059 Copyright TCG 2006-2013 31060 31061 Family 2.0 31062 Level 00 Revision 00.99 31063 31064 Trusted Platform Module Library 31066 31067 Part 3: Commands 31068 31069 31.3.2 Command and Response 31070 Table 191 TPM2_ClockRateAdjust Command 31071 Type 31072 31073 Name 31074 31075 Description 31076 31077 TPMI_ST_COMMAND_TAG 31078 31079 tag 31080 31081 UINT32 31082 31083 commandSize 31084 31085 TPM_CC 31086 31087 commandCode 31088 31089 TPM_CC_ClockRateAdjust 31090 31091 TPMI_RH_PROVISION 31092 31093 @auth 31094 31095 TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} 31096 Auth Handle: 1 31097 Auth Role: USER 31098 31099 TPM_CLOCK_ADJUST 31100 31101 rateAdjust 31102 31103 Adjustment to current Clock update rate 31104 31105 Table 192 TPM2_ClockRateAdjust Response 31106 Type 31107 31108 Name 31109 31110 Description 31111 31112 TPM_ST 31113 31114 tag 31115 31116 see clause 8 31117 31118 UINT32 31119 31120 responseSize 31121 31122 TPM_RC 31123 31124 returnCode 31125 31126 Family 2.0 31127 Level 00 Revision 00.99 31128 31129 Published 31130 Copyright TCG 2006-2013 31131 31132 Page 379 31133 October 31, 2013 31134 31135 Part 3: Commands 31137 31138 Trusted Platform Module Library 31139 31140 31.3.3 Detailed Actions 31141 1 31142 2 31143 3 31144 4 31145 5 31146 6 31147 7 31148 8 31149 9 31150 10 31151 11 31152 12 31153 31154 #include "InternalRoutines.h" 31155 #include "ClockRateAdjust_fp.h" 31156 31157 TPM_RC 31158 TPM2_ClockRateAdjust( 31159 ClockRateAdjust_In 31160 *in 31161 ) 31162 { 31163 // Internal Data Update 31164 TimeSetAdjustRate(in->rateAdjust); 31165 31166 // IN: input parameter list 31167 31168 return TPM_RC_SUCCESS; 31169 } 31170 31171 Page 380 31172 October 31, 2013 31173 31174 Published 31175 Copyright TCG 2006-2013 31176 31177 Family 2.0 31178 Level 00 Revision 00.99 31179 31180 Trusted Platform Module Library 31182 31183 32 31184 31185 Part 3: Commands 31186 31187 Capability Commands 31188 31189 32.1 31190 31191 Introduction 31192 31193 The TPM has numerous values that indicate the state, capabilities, and properties of the TPM. These 31194 values are needed for proper management of the TPM. The TPM2_GetCapability() command is used to 31195 access these values. 31196 TPM2_GetCapability() allows reporting of multiple values in a single call. The values are grouped 31197 according to type. 31198 NOTE 31199 31200 32.2 31201 31202 TPM2_TestParms()is used to determine if a TPM supports a particular combination of algorithm 31203 parameters 31204 31205 TPM2_GetCapability 31206 31207 32.2.1 General Description 31208 This command returns various information regarding the TPM and its current state. 31209 The capability parameter determines the category of data returned. The property parameter selects the 31210 first value of the selected category to be returned. If there is no property that corresponds to the value of 31211 property, the next higher value is returned, if it exists. 31212 EXAMPLE 1 31213 31214 The list of handles of transient objects currently loaded in the TPM may be read one at a time. On 31215 the first read, set the property to TRANSIENT_FIRST and propertyCount to one. If a transient object 31216 is present, the lowest numbered handle is returned and moreData will be YES if transient objects 31217 with higher handles are loaded. On the subsequent call, use returned handle value plus 1 in order to 31218 access the next higher handle. 31219 31220 The propertyCount parameter indicates the number of capabilities in the indicated group that are 31221 requested. The TPM will return the number of requested values (propertyCount) or until the last property 31222 of the requested type has been returned. 31223 NOTE 1 31224 31225 The type of the capability is determined by a combination of capability and property. 31226 31227 When all of the properties of the requested type have been returned, the moreData parameter in the 31228 response will be set to NO. Otherwise, it will be set to YES. 31229 NOTE 2 31230 31231 The moreData parameter will be YES if there are more properties e ven if the requested number of 31232 capabilities has been returned. 31233 31234 The TPM is not required to return more than one value at a time. It is not required to provide the same 31235 number of values in response to subsequent requests. 31236 EXAMPLE 2 31237 31238 A TPM may return 4 properties in response to a TPM2_GetCapability(capability = 31239 TPM_CAP_TPM_PROPERTY, property = TPM_PT_MANUFACTURER, propertyCount = 8 ) and for a 31240 latter request with the same parameters, the TPM may return as few as one and as many as 8 31241 values. 31242 31243 When the TPM is in Failure mode, a TPM is required to allow use of this command for access of the 31244 following capabilities: 31245 31246 Family 2.0 31247 Level 00 Revision 00.99 31248 31249 Published 31250 Copyright TCG 2006-2013 31251 31252 Page 381 31253 October 31, 2013 31254 31255 Part 3: Commands 31257 31258 Trusted Platform Module Library 31259 31260 31261 31262 TPM_PT_MANUFACTURER 31263 31264 31265 31266 TPM_PT_VENDOR_STRING_1 31267 31268 31269 31270 TPM_PT_VENDOR_STRING_2 31271 31272 (3) 31273 31274 31275 31276 TPM_PT_VENDOR_STRING_3 31277 31278 (3) 31279 31280 31281 31282 TPM_PT_VENDOR_STRING_4 31283 31284 (3) 31285 31286 31287 31288 TPM_PT_VENDOR_TPM_TYPE 31289 31290 31291 31292 TPM_PT_FIRMWARE_VERSION_1 31293 31294 31295 31296 TPM_PT_FIRMWARE_VERSION_2 31297 31298 NOTE 3 31299 31300 If the vendor string does not require one of these values, the property type does not need to exist. 31301 31302 A vendor may optionally allow the TPM to return other values. 31303 If in Failure mode and a capability is requested that is not available in Failure mode, the TPM shall return 31304 no value. 31305 EXAMPLE 3 31306 31307 Assume the TPM is in Failure mode and the TPM only supports reporting of the minimum required 31308 set of properties (the limited set to TPML_TAGGED_PCR_PROPERTY values). If a 31309 TPM2_GetCapability is received requesting a capability that has a property type value greater than 31310 TPM_PT_FIRMWARE_VERSION_2, the TPM will return a zero length list with the moreData 31311 parameter set to NO. If the property type is less than TPM_PT_M ANUFACTURER, the TPM will 31312 return TPM_PT_MANUFACTURER. 31313 31314 In Failure mode, tag is required to be TPM_ST_NO_SESSIONS or the TPM shall return 31315 TPM_RC_FAILURE. 31316 The capability categories and the types of the return values are: 31317 capability 31318 31319 Return Type 31320 31321 property 31322 (1) 31323 31324 TPM_CAP_ALGS 31325 31326 TPM_ALG_ID 31327 31328 TPML_ALG_PROPERTY 31329 31330 TPM_CAP_HANDLES 31331 31332 TPM_HANDLE 31333 31334 TPML_HANDLE 31335 31336 TPM_CAP_COMMANDS 31337 31338 TPM_CC 31339 31340 TPML_CCA 31341 31342 TPM_CAP_PP_COMMANDS 31343 31344 TPM_CC 31345 31346 TPML_CC 31347 31348 TPM_CAP_AUDIT_COMMANDS 31349 31350 TPM_CC 31351 31352 TPML_CC 31353 31354 TPM_CAP_PCRS 31355 31356 Reserved 31357 31358 TPML_PCR_SELECTION 31359 31360 TPM_CAP_TPM_PROPERTIES 31361 31362 TPM_PT 31363 31364 TPML_TAGGED_TPM_PROPERTY 31365 31366 TPM_CAP_PCR_PROPERTIES 31367 31368 TPM_PT_PCR 31369 31370 TPML_TAGGED_PCR_PROPERTY 31371 (1) 31372 31373 TPM_CAP_ECC_CURVE 31374 31375 TPM_ECC_CURVE 31376 31377 TPM_CAP_VENDOR_PROPERTY 31378 31379 manufacturer specific 31380 31381 TPML_ECC_CURVE 31382 manufacturer-specific values 31383 31384 NOTES: 31385 (1) The TPM_ALG_ID or TPM_ECC_CURVE is cast to a UINT32 31386 31387 Page 382 31388 October 31, 2013 31389 31390 Published 31391 Copyright TCG 2006-2013 31392 31393 Family 2.0 31394 Level 00 Revision 00.99 31395 31396 Trusted Platform Module Library 31398 31399 Part 3: Commands 31400 31401 31402 31403 TPM_CAP_ALGS Returns a list of TPMS_ALG_PROPERTIES. Each entry is an algorithm ID and a 31404 set of properties of the algorithm. 31405 31406 31407 31408 TPM_CAP_HANDLES Returns a list of all of the handles within the handle range of the property 31409 parameter. The range of the returned handles is determined by the handle type (the most-significant 31410 octet (MSO) of the property). Any of the defined handle types is allowed 31411 EXAMPLE 4 31412 31413 EXAMPLE 5 31414 31415 31416 31417 If the MSO of property is TPM_HT_NV_INDEX, then the TPM will return a list of NV Index 31418 values. 31419 If the MSO of property is TPM_HT_PCR, then the TPM will return a list of PCR. 31420 31421 For this capability, use of TPM_HT_LOADED_SESSION and TPM_HT_SAVED_SESSION is 31422 allowed. Requesting handles with a handle type of TPM_HT_LOADED_SESSION will return handles 31423 for loaded sessions. The returned handle values will have a handle type of either 31424 TPM_HT_HMAC_SESSION or TPM_HT_POLICY_SESSION. If saved sessions are requested, all 31425 returned values will have the TPM_HT_HMAC_SESSION handle type because the TPM does not 31426 track the session type of saved sessions. 31427 NOTE 2 31428 31429 31430 31431 TPM_HT_LOADED_SESSION and TPM_HT_HMAC_SESSION have the same value, as do 31432 TPM_HT_SAVED_SESSION and TPM_HT_POLICY_SESSION. It is not possible to request that 31433 the TPM return a list of loaded HMAC sessions without including the policy sessions. 31434 31435 TPM_CAP_COMMANDS Returns a list of the command attributes for all of the commands 31436 implemented in the TPM, starting with the TPM_CC indicated by the property parameter. If vendor 31437 specific commands are implemented, the vendor-specific command attribute with the lowest 31438 commandIndex, is returned after the non-vendor-specific (base) command. 31439 NOTE 4 31440 31441 The type of the property parameter is a TPM_CC while the type of the returned list is 31442 TPML_CCA. 31443 31444 31445 31446 TPM_CAP_PP_COMMANDS Returns a list of all of the commands currently requiring Physical 31447 Presence for confirmation of platform authorization. The list will start with the TPM_CC indicated by 31448 property. 31449 31450 31451 31452 TPM_CAP_AUDIT_COMMANDS Returns a list of all of the commands currently set for command 31453 audit. 31454 31455 31456 31457 TPM_CAP_PCRS Returns the current allocation of PCR in a TPML_PCR_SELECTION. The 31458 property parameter shall be zero. The TPM will always respond to this command with the full PCR 31459 allocation and moreData will be NO. 31460 31461 31462 31463 TPM_CAP_TPM_PROPERTIES Returns a list of tagged properties. The tag is a TPM_PT and the 31464 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 31465 will only return values in the same group as the property parameter in the command. 31466 31467 31468 31469 TPM_CAP_PCR_PROPERTIES Returns a list of tagged PCR properties. The tag is a 31470 TPM_PT_PCR and the property is a TPMS_PCR_SELECT. 31471 31472 The input command property is a TPM_PT_PCR (see Part 2 for PCR properties to be requested) that 31473 specifies the first property to be returned. If propertyCount is greater than 1, the list of properties begins 31474 with that property and proceeds in TPM_PT_PCR sequence. 31475 NOTE 5 31476 31477 If the propertyCount selects an unimplemented property, the next higher implemented property 31478 is returned. 31479 31480 Each item in the list is a TPMS_PCR_SELECT structure that contains a bitmap of all PCR. 31481 NOTE 6 31482 31483 A PCR index in all banks (all hash algorithms) has the same properties, so the hash algorithm is 31484 not specified here. 31485 31486 Family 2.0 31487 Level 00 Revision 00.99 31488 31489 Published 31490 Copyright TCG 2006-2013 31491 31492 Page 383 31493 October 31, 2013 31494 31495 Part 3: Commands 31497 31498 31499 Trusted Platform Module Library 31500 31501 TPM_CAP_TPM_ECC_CURVES Returns a list of ECC curve identifiers currently available for use 31502 in the TPM. 31503 31504 The moreData parameter will have a value of YES if there are more values of the requested type that 31505 were not returned. 31506 If no next capability exists, the TPM will return a zero-length list and moreData will have a value of NO. 31507 31508 Page 384 31509 October 31, 2013 31510 31511 Published 31512 Copyright TCG 2006-2013 31513 31514 Family 2.0 31515 Level 00 Revision 00.99 31516 31517 Trusted Platform Module Library 31519 31520 Part 3: Commands 31521 31522 32.2.2 Command and Response 31523 Table 193 TPM2_GetCapability Command 31524 Type 31525 31526 Name 31527 31528 Description 31529 31530 TPMI_ST_COMMAND_TAG 31531 31532 tag 31533 31534 UINT32 31535 31536 commandSize 31537 31538 TPM_CC 31539 31540 commandCode 31541 31542 TPM_CC_GetCapability 31543 31544 TPM_CAP 31545 31546 capability 31547 31548 group selection; determines the format of the response 31549 31550 UINT32 31551 31552 property 31553 31554 further definition of information 31555 31556 UINT32 31557 31558 propertyCount 31559 31560 number of properties of the indicated type to return 31561 31562 Table 194 TPM2_GetCapability Response 31563 Type 31564 31565 Name 31566 31567 Description 31568 31569 TPM_ST 31570 31571 tag 31572 31573 see clause 8 31574 31575 UINT32 31576 31577 responseSize 31578 31579 TPM_RC 31580 31581 responseCode 31582 31583 TPMI_YES_NO 31584 31585 moreData 31586 31587 flag to indicate if there are more values of this type 31588 31589 TPMS_CAPABILITY_DATA 31590 31591 capabilityData 31592 31593 the capability data 31594 31595 Family 2.0 31596 Level 00 Revision 00.99 31597 31598 Published 31599 Copyright TCG 2006-2013 31600 31601 Page 385 31602 October 31, 2013 31603 31604 Part 3: Commands 31606 31607 Trusted Platform Module Library 31608 31609 32.2.3 Detailed Actions 31610 1 31611 2 31612 31613 #include "InternalRoutines.h" 31614 #include "GetCapability_fp.h" 31615 Error Returns 31616 TPM_RC_HANDLE 31617 31618 value of property is in an unsupported handle range for the 31619 TPM_CAP_HANDLES capability value 31620 31621 TPM_RC_VALUE 31622 31623 3 31624 4 31625 5 31626 6 31627 7 31628 8 31629 9 31630 10 31631 11 31632 12 31633 13 31634 14 31635 15 31636 16 31637 17 31638 18 31639 19 31640 20 31641 21 31642 22 31643 23 31644 24 31645 25 31646 26 31647 27 31648 28 31649 29 31650 30 31651 31 31652 32 31653 33 31654 34 31655 35 31656 36 31657 37 31658 38 31659 39 31660 40 31661 41 31662 42 31663 43 31664 44 31665 45 31666 46 31667 47 31668 48 31669 49 31670 50 31671 51 31672 31673 Meaning 31674 31675 invalid capability; or property is not 0 for the TPM_CAP_PCRS 31676 capability value 31677 31678 TPM_RC 31679 TPM2_GetCapability( 31680 GetCapability_In 31681 GetCapability_Out 31682 31683 *in, 31684 *out 31685 31686 // IN: input parameter list 31687 // OUT: output parameter list 31688 31689 ) 31690 { 31691 // Command Output 31692 // Set output capability type the same as input type 31693 out->capabilityData.capability = in->capability; 31694 switch(in->capability) 31695 { 31696 case TPM_CAP_ALGS: 31697 out->moreData = AlgorithmCapGetImplemented((TPM_ALG_ID) in->property, 31698 in->propertyCount, &out->capabilityData.data.algorithms); 31699 break; 31700 case TPM_CAP_HANDLES: 31701 switch(HandleGetType((TPM_HANDLE) in->property)) 31702 { 31703 case TPM_HT_TRANSIENT: 31704 // Get list of handles of loaded transient objects 31705 out->moreData = ObjectCapGetLoaded((TPM_HANDLE) in->property, 31706 in->propertyCount, 31707 &out->capabilityData.data.handles); 31708 break; 31709 case TPM_HT_PERSISTENT: 31710 // Get list of handles of persistent objects 31711 out->moreData = NvCapGetPersistent((TPM_HANDLE) in->property, 31712 in->propertyCount, 31713 &out->capabilityData.data.handles); 31714 break; 31715 case TPM_HT_NV_INDEX: 31716 // Get list of defined NV index 31717 out->moreData = NvCapGetIndex((TPM_HANDLE) in->property, 31718 in->propertyCount, 31719 &out->capabilityData.data.handles); 31720 break; 31721 case TPM_HT_LOADED_SESSION: 31722 // Get list of handles of loaded sessions 31723 out->moreData = SessionCapGetLoaded((TPM_HANDLE) in->property, 31724 in->propertyCount, 31725 &out->capabilityData.data.handles); 31726 break; 31727 case TPM_HT_ACTIVE_SESSION: 31728 // Get list of handles of 31729 out->moreData = SessionCapGetSaved((TPM_HANDLE) in->property, 31730 in->propertyCount, 31731 &out->capabilityData.data.handles); 31732 31733 Page 386 31734 October 31, 2013 31735 31736 Published 31737 Copyright TCG 2006-2013 31738 31739 Family 2.0 31740 Level 00 Revision 00.99 31741 31742 Trusted Platform Module Library 31744 52 31745 53 31746 54 31747 55 31748 56 31749 57 31750 58 31751 59 31752 60 31753 61 31754 62 31755 63 31756 64 31757 65 31758 66 31759 67 31760 68 31761 69 31762 70 31763 71 31764 72 31765 73 31766 74 31767 75 31768 76 31769 77 31770 78 31771 79 31772 80 31773 81 31774 82 31775 83 31776 84 31777 85 31778 86 31779 87 31780 88 31781 89 31782 90 31783 91 31784 92 31785 93 31786 94 31787 95 31788 96 31789 97 31790 98 31791 99 31792 100 31793 101 31794 102 31795 103 31796 104 31797 105 31798 106 31799 107 31800 108 31801 109 31802 110 31803 111 31804 112 31805 113 31806 114 31807 115 31808 31809 Part 3: Commands 31810 31811 break; 31812 case TPM_HT_PCR: 31813 // Get list of handles of PCR 31814 out->moreData = PCRCapGetHandles((TPM_HANDLE) in->property, 31815 in->propertyCount, 31816 &out->capabilityData.data.handles); 31817 break; 31818 case TPM_HT_PERMANENT: 31819 // Get list of permanent handles 31820 out->moreData = PermanentCapGetHandles( 31821 (TPM_HANDLE) in->property, 31822 in->propertyCount, 31823 &out->capabilityData.data.handles); 31824 break; 31825 default: 31826 // Unsupported input handle type 31827 return TPM_RC_HANDLE + RC_GetCapability_property; 31828 break; 31829 } 31830 break; 31831 case TPM_CAP_COMMANDS: 31832 out->moreData = CommandCapGetCCList((TPM_CC) in->property, 31833 in->propertyCount, 31834 &out->capabilityData.data.command); 31835 break; 31836 case TPM_CAP_PP_COMMANDS: 31837 out->moreData = PhysicalPresenceCapGetCCList((TPM_CC) in->property, 31838 in->propertyCount, &out->capabilityData.data.ppCommands); 31839 break; 31840 case TPM_CAP_AUDIT_COMMANDS: 31841 out->moreData = CommandAuditCapGetCCList((TPM_CC) in->property, 31842 in->propertyCount, 31843 &out->capabilityData.data.auditCommands); 31844 break; 31845 case TPM_CAP_PCRS: 31846 // Input property must be 0 31847 if(in->property != 0) 31848 return TPM_RC_VALUE + RC_GetCapability_property; 31849 out->moreData = PCRCapGetAllocation(in->propertyCount, 31850 &out->capabilityData.data.assignedPCR); 31851 break; 31852 case TPM_CAP_PCR_PROPERTIES: 31853 out->moreData = PCRCapGetProperties((TPM_PT_PCR) in->property, 31854 in->propertyCount, 31855 &out->capabilityData.data.pcrProperties); 31856 break; 31857 case TPM_CAP_TPM_PROPERTIES: 31858 out->moreData = TPMCapGetProperties((TPM_PT) in->property, 31859 in->propertyCount, 31860 &out->capabilityData.data.tpmProperties); 31861 break; 31862 #ifdef TPM_ALG_ECC 31863 case TPM_CAP_ECC_CURVES: 31864 out->moreData = CryptCapGetECCCurve((TPM_ECC_CURVE 31865 ) in->property, 31866 in->propertyCount, 31867 &out->capabilityData.data.eccCurves); 31868 break; 31869 #endif // TPM_ALG_ECC 31870 case TPM_CAP_VENDOR_PROPERTY: 31871 // vendor property is not implemented 31872 default: 31873 // Unexpected TPM_CAP value 31874 return TPM_RC_VALUE; 31875 break; 31876 31877 Family 2.0 31878 Level 00 Revision 00.99 31879 31880 Published 31881 Copyright TCG 2006-2013 31882 31883 Page 387 31884 October 31, 2013 31885 31886 Part 3: Commands 31888 116 31889 117 31890 118 31891 119 31892 31893 Trusted Platform Module Library 31894 31895 } 31896 return TPM_RC_SUCCESS; 31897 } 31898 31899 Page 388 31900 October 31, 2013 31901 31902 Published 31903 Copyright TCG 2006-2013 31904 31905 Family 2.0 31906 Level 00 Revision 00.99 31907 31908 Trusted Platform Module Library 31910 31911 32.3 31912 31913 Part 3: Commands 31914 31915 TPM2_TestParms 31916 31917 32.3.1 General Description 31918 This command is used to check to see if specific combinations of algorithm parameters are supported. 31919 The TPM will unmarshal the provided TPMT_PUBLIC_PARMS. If the parameters unmarshal correctly, 31920 then the TPM will return TPM_RC_SUCCESS, indicating that the parameters are valid for the TPM. The 31921 TPM will return the appropriate unmarshaling error if a parameter is not valid. 31922 31923 Family 2.0 31924 Level 00 Revision 00.99 31925 31926 Published 31927 Copyright TCG 2006-2013 31928 31929 Page 389 31930 October 31, 2013 31931 31932 Part 3: Commands 31934 31935 Trusted Platform Module Library 31936 31937 32.3.2 Command and Response 31938 Table 195 TPM2_TestParms Command 31939 Type 31940 31941 Name 31942 31943 Description 31944 31945 TPMI_ST_COMMAND_TAG 31946 31947 tag 31948 31949 UINT32 31950 31951 commandSize 31952 31953 TPM_CC 31954 31955 commandCode 31956 31957 TPM_CC_TestParms 31958 31959 TPMT_PUBLIC_PARMS 31960 31961 parameters 31962 31963 algorithm parameters to be validated 31964 31965 Table 196 TPM2_TestParms Response 31966 Type 31967 31968 Name 31969 31970 Description 31971 31972 TPM_ST 31973 31974 tag 31975 31976 see clause 8 31977 31978 UINT32 31979 31980 responseSize 31981 31982 TPM_RC 31983 31984 responseCode 31985 31986 Page 390 31987 October 31, 2013 31988 31989 Published 31990 Copyright TCG 2006-2013 31991 31992 Family 2.0 31993 Level 00 Revision 00.99 31994 31995 Trusted Platform Module Library 31997 31998 Part 3: Commands 31999 32000 32.3.3 Detailed Actions 32001 1 32002 2 32003 3 32004 4 32005 5 32006 6 32007 7 32008 8 32009 9 32010 10 32011 11 32012 12 32013 13 32014 14 32015 32016 #include "InternalRoutines.h" 32017 #include "TestParms_fp.h" 32018 32019 TPM_RC 32020 TPM2_TestParms( 32021 TestParms_In 32022 32023 *in 32024 32025 // IN: input parameter list 32026 32027 ) 32028 { 32029 // Input parameter is not reference in command action 32030 in = NULL; 32031 // The parameters are tested at unmarshal process. 32032 // action 32033 return TPM_RC_SUCCESS; 32034 32035 We do nothing in command 32036 32037 } 32038 32039 Family 2.0 32040 Level 00 Revision 00.99 32041 32042 Published 32043 Copyright TCG 2006-2013 32044 32045 Page 391 32046 October 31, 2013 32047 32048 Part 3: Commands 32050 32051 33 32052 32053 Trusted Platform Module Library 32054 32055 Non-volatile Storage 32056 32057 33.1 32058 32059 Introduction 32060 32061 The NV commands are used to create, update, read, and delete allocations of space in NV memory. 32062 Before an Index may be used, it must be defined (TPM2_NV_DefineSpace()). 32063 An Index may be modified if the proper write authorization is provided or read if the proper read 32064 authorization is provided. Different controls are available for reading and writing. 32065 An Index may have an Index-specific authValue and authPolicy. The authValue may be used to authorize 32066 reading if TPMA_NV_AUTHREAD is SET and writing if TPMA_NV_AUTHREAD is SET. The authPolicy 32067 may be used to authorize reading if TPMA_NV_POLICYREAD is SET and writing if 32068 TPMA_NV_POLICYWRITE is SET. 32069 TPMA_NV_PPREAD and TPMA_NV_PPWRITE indicate if reading or writing of the NV Index may be 32070 authorized by platformAuth or platformPolicy. 32071 TPMA_NV_OWNERREAD and TPMA_NV_OWNERWRITE indicate if reading or writing of the NV Index 32072 may be authorized by ownerAuth or ownerPolicy. 32073 If an operation on an NV index requires authorization, and the authHandle parameter is the handle of an 32074 NV Index, then the nvIndex parameter must have the same value or the TPM will return 32075 TPM_RC_NV_AUTHORIZATION. 32076 NOTE 1 32077 32078 This check ensures that the authorization that was provided is associated with the NV Index being 32079 authorized. 32080 32081 For creating an Index, ownerAuth may not be used if shEnable is CLEAR and platformAuth may not be 32082 used if phEnableNV is CLEAR. 32083 If an Index was defined using platformAuth, then that Index is not accessible when phEnableNV is 32084 CLEAR. If an Index was defined using ownerAuth, then that Index is not accessible when shEnable is 32085 CLEAR. 32086 For read access control, any combination of TPMA_NV_PPREAD, TPMA_NV_OWNERREAD, 32087 TPMA_NV_AUTHREAD, or TPMA_NV_POLICYREAD is allowed as long as at least one is SET. 32088 For write access control, any combination of TPMA_NV_PPWRITE, TPMA_NV_OWNERWRITE, 32089 TPMA_NV_AUTHWRITE, or TPMA_NV_POLICYWRITE is allowed as long as at least one is SET. 32090 If an Index has been defined and not written, then any operation on the NV Index that requires read 32091 authorization will fail (TPM_RC_NV_INITIALIZED). This check may be made before or after other 32092 authorization checks but shall be performed before checking the NV Index authValue. An authorization 32093 failure due to the NV Index not having been written shall not be logged by the dictionary attack logic. 32094 If TPMA_NV_CLEAR_STCLEAR is SET, then the TPMA_NV_WRITTEN will be CLEAR on each 32095 TPM2_Startup(TPM_SU_CLEAR). 32096 TPMA_NV_CLEAR_STCLEAR 32097 shall 32098 not 32099 be 32100 SET 32101 if 32102 TPMA_NV_COUNTER is SET. 32103 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 32104 structure of the NV data. 32105 Only one NV Index may be directly referenced in a command. 32106 NOTE 2 32107 32108 This means that, if authHandle references an NV Index, then nvIndex will have the same value. 32109 However, this does not limit the number of changes that may occur as side effects. For example, any 32110 number of NV Indexes might be relocated as a result of deleting or adding a NV Ind ex. 32111 32112 Page 392 32113 October 31, 2013 32114 32115 Published 32116 Copyright TCG 2006-2013 32117 32118 Family 2.0 32119 Level 00 Revision 00.99 32120 32121 Trusted Platform Module Library 32123 32124 33.2 32125 32126 Part 3: Commands 32127 32128 NV Counters 32129 32130 When an Index has the TPMA_NV_COUNTER attribute set, it behaves as a monotonic counter and may 32131 only be updated using TPM2_NV_Increment(). 32132 When an NV counter is created, the TPM shall initialize the 8-octet counter value with a number that is 32133 greater than any count value for any NV counter on the TPM since the time of TPM manufacture. 32134 An NV counter may be defined with the TPMA_NV_ORDERLY attribute to indicate that the NV Index is 32135 expected to be modified at a high frequency and that the data is only required to persist when the TPM 32136 goes through an orderly shutdown process. The TPM may update the counter value in RAM and 32137 occasionally update the non-volatile version of the counter. An orderly shutdown is one occasion to 32138 update the non-volatile count. If the difference between the volatile and non-volatile version of the counter 32139 becomes as large as MAX_ORDERLY_COUNT, this shall be another occasion for updating the nonvolatile count. 32140 Before an NV counter can be used, the TPM shall validate that the count is not less than a previously 32141 reported value. If the TPMA_NV_ORDERLY attribute is not SET, or if the TPM experienced an orderly 32142 shutdown, then the count is assumed to be correct. If the TPMA_NV_ORDERLY attribute is SET, and the 32143 TPM shutdown was not orderly, then the TPM shall OR MAX_ORDERLY_COUNT to the contents of the 32144 non-volatile counter and set that as the current count. 32145 NOTE 1 32146 32147 Because the TPM would have updated the NV Index if the difference between the count values was 32148 equal to MAX_ORDERLY_COUNT + 1, the highest value that could have been in the NV Index is 32149 MAX_ORDERLY_COUNT so it is safe to restore that value. 32150 32151 NOTE 2 32152 32153 The TPM may implement the RAM portion of the counter such that the effective value of the NV 32154 counter is the sum of both the volatile and non-volatile parts. If so, then the TPM may initialize the 32155 RAM version of the counter to MAX_ORDERLY_COUNT and no update of NV is necessary. 32156 32157 NOTE 3 32158 32159 When a new NV counter is created, the TPM may search all the counters to determine which has the 32160 highest value. In this search, the TPM would use the sum of the non -volatile and RAM portions of 32161 the counter. The RAM portion of the counter shall be properly initialized to reflect shutdown p rocess 32162 (orderly or not) of the TPM. 32163 32164 Family 2.0 32165 Level 00 Revision 00.99 32166 32167 Published 32168 Copyright TCG 2006-2013 32169 32170 Page 393 32171 October 31, 2013 32172 32173 Part 3: Commands 32175 32176 33.3 32177 32178 Trusted Platform Module Library 32179 32180 TPM2_NV_DefineSpace 32181 32182 33.3.1 General Description 32183 This command defines the attributes of an NV Index and causes the TPM to reserve space to hold the 32184 data associated with the NV Index. If a definition already exists at the NV Index, the TPM will return 32185 TPM_RC_NV_DEFINED. 32186 The TPM will return TPM_RC_ATTRIBUTES if more 32187 TPMA_NV_BITS, or TPMA_NV_EXTEND is SET in publicInfo. 32188 NOTE 32189 32190 than 32191 32192 one 32193 32194 of 32195 32196 TPMA_NV_COUNTER, 32197 32198 It is not required that any of these three attributes be set. 32199 32200 The TPM shall return TPM_RC_ATTRIBUTES if TPMA_NV_WRITTEN, TPM_NV_READLOCKED, or 32201 TPMA_NV_WRITELOCKED is SET. 32202 If TPMA_NV_COUNTER or TPMA_NV_BITS is SET, then publicInfodataSize shall be set to eight (8) or 32203 the TPM shall return TPM_RC_SIZE. 32204 If TPMA_NV_EXTEND is SET, then publicInfodataSize shall match the digest size of the 32205 publicInfo.nameAlg or the TPM shall return TPM_RC_SIZE. 32206 If the NV Index is an ordinary Index and publicInfodataSize is larger than supported by the TPM 32207 implementation then the TPM shall return TPM_RC_SIZE. 32208 NOTE 32209 32210 The limit for the data size may vary according to the type of the index. For example, if the index is 32211 has TPMA_NV_ORDERLY SET, then the maximum size of an ordin ary NV Index may be less than 32212 the size of an ordinary NV Index that has TPMA_NV_ORDERLY CLEAR. 32213 32214 At least one of TPMA_NV_PPREAD, TPMA_NV_OWNERREAD, TPMA_NV_AUTHREAD, 32215 TPMA_NV_POLICYREAD shall be SET or the TPM shall return TPM_RC_ATTRIBUTES. 32216 32217 or 32218 32219 At least one of TPMA_NV_PPWRITE, TPMA_NV_OWNERWRITE, TPMA_NV_AUTHWRITE, or 32220 TPMA_NV_POLICYWRITE shall be SET or the TPM shall return TPM_RC_ATTRIBUTES. 32221 If TPMA_NV_CLEAR_STCLEAR is SET, then TPMA_NV_COUNTER shall be CLEAR or the TPM shall 32222 return TPM_RC_ATTRIBUTES. 32223 If platformAuth/platformPolicy is used for authorization, then TPMA_NV_PLATFORMCREATE shall be 32224 SET in publicInfo. If ownerAuth/ownerPolicy is used for authorization, TPMA_NV_PLATFORMCREATE 32225 shall be CLEAR in publicInfo. If TPMA_NV_PLATFORMCREATE is not set correctly for the authorization, 32226 the TPM shall return TPM_RC_ATTRIBUTES. 32227 If TPMA_NV_POLICY_DELETE is SET, then the authorization shall be with platformAuth or the TPM 32228 shall return TPM_RC_ATTRIBUTES. 32229 If the implementation does not support TPM2_NV_Increment(), 32230 TPM_RC_ATTRIBUTES if TPMA_NV_COUNTER is SET. 32231 32232 the 32233 32234 TPM 32235 32236 shall 32237 32238 return 32239 32240 If the implementation does not support TPM2_NV_SetBits(), 32241 TPM_RC_ATTRIBUTES if TPMA_NV_BITS is SET. 32242 32243 the 32244 32245 TPM 32246 32247 shall 32248 32249 return 32250 32251 If the implementation does not support TPM2_NV_Extend(), 32252 TPM_RC_ATTRIBUTES if TPMA_NV_EXTEND is SET. 32253 32254 the 32255 32256 TPM 32257 32258 shall 32259 32260 return 32261 32262 If the implementation does not support TPM2_NV_UndefineSpaceSpecial(), the TPM shall return 32263 TPM_RC_ATTRIBUTES if TPMA_NV_POLICY_DELETE is SET. 32264 After the successful completion of this command, the NV Index exists but TPMA_NV_WRITTEN will be 32265 CLEAR. Any access of the NV data will return TPM_RC_NV_UINITIALIZED. 32266 32267 Page 394 32268 October 31, 2013 32269 32270 Published 32271 Copyright TCG 2006-2013 32272 32273 Family 2.0 32274 Level 00 Revision 00.99 32275 32276 Trusted Platform Module Library 32278 32279 Part 3: Commands 32280 32281 In some implementations, an NV Index with the TPMA_NV_COUNTER attribute may require special TPM 32282 resources that provide higher endurance than regular NV. For those implementations, if this command 32283 fails because of lack of resources, the TPM will return TPM_RC_NV_SPACE. 32284 The value of auth is saved in the created structure. The size of auth is limited to be no larger than the size 32285 of the digest produced by the NV Index's nameAlg (TPM_RC_SIZE). 32286 32287 Family 2.0 32288 Level 00 Revision 00.99 32289 32290 Published 32291 Copyright TCG 2006-2013 32292 32293 Page 395 32294 October 31, 2013 32295 32296 Part 3: Commands 32298 32299 Trusted Platform Module Library 32300 32301 33.3.2 Command and Response 32302 Table 197 TPM2_NV_DefineSpace Command 32303 Type 32304 32305 Name 32306 32307 Description 32308 32309 TPMI_ST_COMMAND_TAG 32310 32311 tag 32312 32313 UINT32 32314 32315 commandSize 32316 32317 TPM_CC 32318 32319 commandCode 32320 32321 TPM_CC_NV_DefineSpace {NV} 32322 32323 TPMI_RH_PROVISION 32324 32325 @authHandle 32326 32327 TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} 32328 Auth Index: 1 32329 Auth Role: USER 32330 32331 TPM2B_AUTH 32332 32333 auth 32334 32335 the authorization value 32336 32337 TPM2B_NV_PUBLIC 32338 32339 publicInfo 32340 32341 the public parameters of the NV area 32342 32343 Table 198 TPM2_NV_DefineSpace Response 32344 Type 32345 32346 Name 32347 32348 Description 32349 32350 TPM_ST 32351 32352 tag 32353 32354 see clause 8 32355 32356 UINT32 32357 32358 responseSize 32359 32360 TPM_RC 32361 32362 responseCode 32363 32364 Page 396 32365 October 31, 2013 32366 32367 Published 32368 Copyright TCG 2006-2013 32369 32370 Family 2.0 32371 Level 00 Revision 00.99 32372 32373 Trusted Platform Module Library 32375 32376 Part 3: Commands 32377 32378 33.3.3 Detailed Actions 32379 1 32380 2 32381 32382 #include "InternalRoutines.h" 32383 #include "NV_DefineSpace_fp.h" 32384 Error Returns 32385 TPM_RC_NV_ATTRIBUTES 32386 32387 attributes of the index are not consistent 32388 32389 TPM_RC_NV_DEFINED 32390 32391 index already exists 32392 32393 TPM_RC_HIERARCHY 32394 32395 for authorizations using TPM_RH_PLATFORM phEnable_NV is 32396 clear. 32397 32398 TPM_RC_NV_SPACE 32399 32400 Insufficient space for the index 32401 32402 TPM_RC_SIZE 32403 32404 3 32405 4 32406 5 32407 6 32408 7 32409 8 32410 9 32411 10 32412 11 32413 12 32414 13 32415 14 32416 15 32417 16 32418 17 32419 18 32420 19 32421 20 32422 21 32423 22 32424 23 32425 24 32426 25 32427 26 32428 27 32429 28 32430 29 32431 30 32432 31 32433 32 32434 33 32435 34 32436 35 32437 36 32438 37 32439 38 32440 39 32441 40 32442 41 32443 42 32444 43 32445 44 32446 32447 Meaning 32448 32449 'auth->size' or 'publicInfo->authPolicy. size' is larger than the digest 32450 size of 'publicInfo->nameAlg', or 'publicInfo->dataSize' is not 32451 consistent with 'publicInfo->attributes'. 32452 32453 TPM_RC 32454 TPM2_NV_DefineSpace( 32455 NV_DefineSpace_In 32456 32457 *in 32458 32459 // IN: input parameter list 32460 32461 ) 32462 { 32463 TPM_RC 32464 TPMA_NV 32465 UINT16 32466 32467 result; 32468 attributes; 32469 nameSize; 32470 32471 nameSize = CryptGetHashDigestSize(in->publicInfo.t.nvPublic.nameAlg); 32472 // Check if NV is available. NvIsAvailable may return TPM_RC_NV_UNAVAILABLE 32473 // TPM_RC_NV_RATE or TPM_RC_SUCCESS. 32474 result = NvIsAvailable(); 32475 if(result != TPM_RC_SUCCESS) 32476 return result; 32477 // Input Validation 32478 // If an index is being created by the owner and shEnable is 32479 // clear, then we would not reach this point because ownerAuth 32480 // can't be given when shEnable is CLEAR. However, if phEnable 32481 // is SET but phEnableNV is CLEAR, we have to check here 32482 if(in->authHandle == TPM_RH_PLATFORM && gc.phEnableNV == CLEAR) 32483 return TPM_RC_HIERARCHY + RC_NV_DefineSpace_authHandle; 32484 attributes = in->publicInfo.t.nvPublic.attributes; 32485 //TPMS_NV_PUBLIC validation. 32486 // Counters and bit fields must have a size of 8 32487 if ( 32488 (attributes.TPMA_NV_COUNTER == SET || attributes.TPMA_NV_BITS == SET) 32489 && (in->publicInfo.t.nvPublic.dataSize != 8)) 32490 return TPM_RC_SIZE + RC_NV_DefineSpace_publicInfo; 32491 // check that the authPolicy consistent with hash algorithm 32492 if( 32493 in->publicInfo.t.nvPublic.authPolicy.t.size != 0 32494 && in->publicInfo.t.nvPublic.authPolicy.t.size != nameSize) 32495 return TPM_RC_SIZE + RC_NV_DefineSpace_publicInfo; 32496 // make sure that the authValue is not too large 32497 MemoryRemoveTrailingZeros(&in->auth); 32498 if(in->auth.t.size > nameSize) 32499 return TPM_RC_SIZE + RC_NV_DefineSpace_auth; 32500 32501 Family 2.0 32502 Level 00 Revision 00.99 32503 32504 Published 32505 Copyright TCG 2006-2013 32506 32507 Page 397 32508 October 31, 2013 32509 32510 Part 3: Commands 32512 45 32513 46 32514 47 32515 48 32516 49 32517 50 32518 51 32519 52 32520 53 32521 54 32522 55 32523 56 32524 57 32525 58 32526 59 32527 60 32528 61 32529 62 32530 63 32531 64 32532 65 32533 66 32534 67 32535 68 32536 69 32537 70 32538 71 32539 72 32540 73 32541 74 32542 75 32543 76 32544 77 32545 78 32546 79 32547 80 32548 81 32549 82 32550 83 32551 84 32552 85 32553 86 32554 87 32555 88 32556 89 32557 90 32558 91 32559 92 32560 93 32561 94 32562 95 32563 96 32564 97 32565 98 32566 99 32567 100 32568 101 32569 102 32570 103 32571 104 32572 105 32573 106 32574 107 32575 108 32576 32577 Trusted Platform Module Library 32578 32579 //TPMA_NV validation. 32580 // Locks may not be SET and written cannot be SET 32581 if( 32582 attributes.TPMA_NV_WRITTEN == SET 32583 || attributes.TPMA_NV_WRITELOCKED == SET 32584 || attributes.TPMA_NV_READLOCKED == SET) 32585 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32586 // There must be a way to read the index 32587 if( 32588 attributes.TPMA_NV_OWNERREAD == CLEAR 32589 && attributes.TPMA_NV_PPREAD == CLEAR 32590 && attributes.TPMA_NV_AUTHREAD == CLEAR 32591 && attributes.TPMA_NV_POLICYREAD == CLEAR) 32592 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32593 // There must be a way to write the index 32594 if( 32595 attributes.TPMA_NV_OWNERWRITE == CLEAR 32596 && attributes.TPMA_NV_PPWRITE == CLEAR 32597 && attributes.TPMA_NV_AUTHWRITE == CLEAR 32598 && attributes.TPMA_NV_POLICYWRITE == CLEAR) 32599 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32600 // Make sure that no attribute is used that is not supported by the proper 32601 // command 32602 #if CC_NV_Increment == NO 32603 if( attributes.TPMA_NV_COUNTER == SET) 32604 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32605 #endif 32606 #if CC_NV_SetBits == NO 32607 if( attributes.TPMA_NV_BITS == SET) 32608 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32609 #endif 32610 #if CC_NV_Extend == NO 32611 if( attributes.TPMA_NV_EXTEND == SET) 32612 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32613 #endif 32614 #if CC_NV_UndefineSpaceSpecial == NO 32615 if( attributes.TPMA_NV_POLICY_DELETE == SET) 32616 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32617 #endif 32618 // Can be COUNTER or BITS or EXTEND but not more than one 32619 if( attributes.TPMA_NV_COUNTER == SET 32620 && attributes.TPMA_NV_BITS == SET) 32621 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32622 if( 32623 attributes.TPMA_NV_COUNTER == SET 32624 && attributes.TPMA_NV_EXTEND == SET) 32625 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32626 if( 32627 attributes.TPMA_NV_BITS == SET 32628 && attributes.TPMA_NV_EXTEND == SET) 32629 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32630 // An index with TPMA_NV_CLEAR_STCLEAR can't be a counter 32631 if( 32632 attributes.TPMA_NV_CLEAR_STCLEAR == SET 32633 && attributes.TPMA_NV_COUNTER == SET) 32634 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32635 // The index is allowed to have one of GLOBALLOCK or WRITEDEFINE SET 32636 if( 32637 attributes.TPMA_NV_GLOBALLOCK == SET 32638 && attributes.TPMA_NV_WRITEDEFINE == SET) 32639 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32640 // Make sure that the creator of the index can delete the index 32641 32642 Page 398 32643 October 31, 2013 32644 32645 Published 32646 Copyright TCG 2006-2013 32647 32648 Family 2.0 32649 Level 00 Revision 00.99 32650 32651 Trusted Platform Module Library 32653 109 32654 110 32655 111 32656 112 32657 113 32658 114 32659 115 32660 116 32661 117 32662 118 32663 119 32664 120 32665 121 32666 122 32667 123 32668 124 32669 125 32670 126 32671 127 32672 128 32673 129 32674 130 32675 131 32676 132 32677 133 32678 134 32679 135 32680 136 32681 137 32682 138 32683 139 32684 140 32685 141 32686 142 32687 143 32688 144 32689 32690 if( 32691 32692 Part 3: Commands 32693 32694 ( 32695 32696 in->publicInfo.t.nvPublic.attributes.TPMA_NV_PLATFORMCREATE == SET 32697 && in->authHandle == TPM_RH_OWNER 32698 ) 32699 || ( 32700 in->publicInfo.t.nvPublic.attributes.TPMA_NV_PLATFORMCREATE == CLEAR 32701 && in->authHandle == TPM_RH_PLATFORM 32702 ) 32703 ) 32704 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_authHandle; 32705 32706 // If TPMA_NV_POLICY_DELETE is SET, then the index must be defined by 32707 // the platform 32708 if( 32709 in->publicInfo.t.nvPublic.attributes.TPMA_NV_POLICY_DELETE == SET 32710 && TPM_RH_PLATFORM != in->authHandle 32711 ) 32712 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32713 // If the NV index is used as a PCR, the data size must match the digest 32714 // size 32715 if( 32716 in->publicInfo.t.nvPublic.attributes.TPMA_NV_EXTEND == SET 32717 && in->publicInfo.t.nvPublic.dataSize != nameSize 32718 ) 32719 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; 32720 // See if the index is already defined. 32721 if(NvIsUndefinedIndex(in->publicInfo.t.nvPublic.nvIndex)) 32722 return TPM_RC_NV_DEFINED; 32723 // Internal Data Update 32724 // define the space. A TPM_RC_NV_SPACE error may be returned at this point 32725 result = NvDefineIndex(&in->publicInfo.t.nvPublic, &in->auth); 32726 if(result != TPM_RC_SUCCESS) 32727 return result; 32728 return TPM_RC_SUCCESS; 32729 } 32730 32731 Family 2.0 32732 Level 00 Revision 00.99 32733 32734 Published 32735 Copyright TCG 2006-2013 32736 32737 Page 399 32738 October 31, 2013 32739 32740 Part 3: Commands 32742 32743 33.4 32744 32745 Trusted Platform Module Library 32746 32747 TPM2_NV_UndefineSpace 32748 32749 33.4.1 General Description 32750 This command removes an Index from the TPM. 32751 If nvIndex is not defined, the TPM shall return TPM_RC_HANDLE. 32752 If nvIndex references an Index that has its TPMA_NV_PLATFORMCREATE attribute SET, the TPM shall 32753 return TPM_RC_NV_AUTHORITY unless platformAuth is provided. 32754 NOTE 32755 32756 An Index with TPMA_NV_PLATFORMCREATE CLEAR may be deleted with platformAuth as long as 32757 shEnable is SET. If shEnable is CLEAR, indexes created using ownerAuth are not accessible even 32758 for deletion by the platform. 32759 32760 Page 400 32761 October 31, 2013 32762 32763 Published 32764 Copyright TCG 2006-2013 32765 32766 Family 2.0 32767 Level 00 Revision 00.99 32768 32769 Trusted Platform Module Library 32771 32772 Part 3: Commands 32773 32774 33.4.2 Command and Response 32775 Table 199 TPM2_NV_UndefineSpace Command 32776 Type 32777 32778 Name 32779 32780 Description 32781 32782 TPMI_ST_COMMAND_TAG 32783 32784 tag 32785 32786 UINT32 32787 32788 commandSize 32789 32790 TPM_CC 32791 32792 commandCode 32793 32794 TPM_CC_NV_UndefineSpace {NV} 32795 32796 TPMI_RH_PROVISION 32797 32798 @authHandle 32799 32800 TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} 32801 Auth Index: 1 32802 Auth Role: USER 32803 32804 TPMI_RH_NV_INDEX 32805 32806 nvIndex 32807 32808 the NV Index to remove from NV space 32809 Auth Index: None 32810 32811 Table 200 TPM2_NV_UndefineSpace Response 32812 Type 32813 32814 Name 32815 32816 Description 32817 32818 TPM_ST 32819 32820 tag 32821 32822 see clause 8 32823 32824 UINT32 32825 32826 responseSize 32827 32828 TPM_RC 32829 32830 responseCode 32831 32832 Family 2.0 32833 Level 00 Revision 00.99 32834 32835 Published 32836 Copyright TCG 2006-2013 32837 32838 Page 401 32839 October 31, 2013 32840 32841 Part 3: Commands 32843 32844 Trusted Platform Module Library 32845 32846 33.4.3 Detailed Actions 32847 1 32848 2 32849 32850 #include "InternalRoutines.h" 32851 #include "NV_UndefineSpace_fp.h" 32852 Error Returns 32853 TPM_RC_ATTRIBUTES 32854 32855 TPMA_NV_POLICY_DELETE is SET in the Index referenced by 32856 nvIndex so this command may not be used to delete this Index (see 32857 TPM2_NV_UndefineSpaceSpecial()) 32858 32859 TPM_RC_NV_AUTHORIZATION 32860 3 32861 4 32862 5 32863 6 32864 7 32865 8 32866 9 32867 10 32868 11 32869 12 32870 13 32871 14 32872 15 32873 16 32874 17 32875 18 32876 19 32877 20 32878 21 32879 22 32880 23 32881 24 32882 25 32883 26 32884 27 32885 28 32886 29 32887 30 32888 31 32889 32 32890 33 32891 34 32892 35 32893 36 32894 37 32895 38 32896 32897 Meaning 32898 32899 attempt to use ownerAuth to delete an index created by the platform 32900 32901 TPM_RC 32902 TPM2_NV_UndefineSpace( 32903 NV_UndefineSpace_In *in 32904 32905 // IN: input parameter list 32906 32907 ) 32908 { 32909 TPM_RC 32910 NV_INDEX 32911 32912 result; 32913 nvIndex; 32914 32915 // The command needs NV update. Check if NV is available. 32916 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 32917 // this point 32918 result = NvIsAvailable(); 32919 if(result != TPM_RC_SUCCESS) return result; 32920 // Input Validation 32921 // Get NV index info 32922 NvGetIndexInfo(in->nvIndex, &nvIndex); 32923 // This command can't be used to delete an index with TPMA_NV_POLICY_DELETE SET 32924 if(SET == nvIndex.publicArea.attributes.TPMA_NV_POLICY_DELETE) 32925 return TPM_RC_ATTRIBUTES + RC_NV_UndefineSpace_nvIndex; 32926 // The owner may only delete an index that was defined with ownerAuth. The 32927 // platform may delete an index that was created with either auth. 32928 if( 32929 in->authHandle == TPM_RH_OWNER 32930 && nvIndex.publicArea.attributes.TPMA_NV_PLATFORMCREATE == SET) 32931 return TPM_RC_NV_AUTHORIZATION; 32932 // Internal Data Update 32933 // Call implementation dependent internal routine to delete NV index 32934 NvDeleteEntity(in->nvIndex); 32935 return TPM_RC_SUCCESS; 32936 } 32937 32938 Page 402 32939 October 31, 2013 32940 32941 Published 32942 Copyright TCG 2006-2013 32943 32944 Family 2.0 32945 Level 00 Revision 00.99 32946 32947 Trusted Platform Module Library 32949 32950 33.5 32951 32952 Part 3: Commands 32953 32954 TPM2_NV_UndefineSpaceSpecial 32955 32956 33.5.1 General Description 32957 This command allows removal of a platform-created NV Index that has TPMA_NV_POLICY_DELETE 32958 SET. 32959 This command requires that the policy of the NV Index be satisfied before the NV Index may be deleted. 32960 Because administrative role is required, the policy must contain a command that sets the policy command 32961 code to TPM_CC_NV_UndefineSpaceSpecial. This indicates that the policy that is being used is a policy 32962 that is for this command, and not a policy that would approve another use. That is, authority to use an 32963 object does not grant authority to undefined the object. 32964 If nvIndex is not defined, the TPM shall return TPM_RC_HANDLE. 32965 If 32966 nvIndex 32967 references 32968 an 32969 Index 32970 that 32971 has 32972 its 32973 TPMA_NV_PLATFORMCREATE 32974 TPMA_NV_POLICY_DELETE attribute CLEAR, the TPM shall return TPM_RC_NV_ATTRIBUTES. 32975 NOTE 32976 32977 or 32978 32979 An 32980 Index 32981 with 32982 TPMA_NV_PLATFORMCREATE 32983 CLEAR 32984 may 32985 be 32986 deleted 32987 with 32988 TPM2_UndefineSpace()as long as shEnable is SET. If shEnable is CLEAR, indexes created using 32989 ownerAuth are not accessible even for deletion by the platform . 32990 32991 Family 2.0 32992 Level 00 Revision 00.99 32993 32994 Published 32995 Copyright TCG 2006-2013 32996 32997 Page 403 32998 October 31, 2013 32999 33000 Part 3: Commands 33002 33003 Trusted Platform Module Library 33004 33005 33.5.2 Command and Response 33006 Table 201 TPM2_NV_UndefineSpaceSpecial Command 33007 Type 33008 33009 Name 33010 33011 Description 33012 33013 TPMI_ST_COMMAND_TAG 33014 33015 tag 33016 33017 UINT32 33018 33019 commandSize 33020 33021 TPM_CC 33022 33023 commandCode 33024 33025 TPM_CC_NV_UndefineSpaceSpecial {NV} 33026 33027 TPMI_RH_NV_INDEX 33028 33029 @nvIndex 33030 33031 Index to be deleted 33032 Auth Index: 1 33033 Auth Role: ADMIN 33034 33035 TPMI_RH_PLATFORM 33036 33037 @platform 33038 33039 TPM_RH_PLATFORM + {PP} 33040 Auth Index: 2 33041 Auth Role: USER 33042 33043 Table 202 TPM2_NV_UndefineSpaceSpecial Response 33044 Type 33045 33046 Name 33047 33048 Description 33049 33050 TPM_ST 33051 33052 tag 33053 33054 see clause 8 33055 33056 UINT32 33057 33058 responseSize 33059 33060 TPM_RC 33061 33062 responseCode 33063 33064 Page 404 33065 October 31, 2013 33066 33067 Published 33068 Copyright TCG 2006-2013 33069 33070 Family 2.0 33071 Level 00 Revision 00.99 33072 33073 Trusted Platform Module Library 33075 33076 Part 3: Commands 33077 33078 33.5.3 Detailed Actions 33079 1 33080 2 33081 33082 #include "InternalRoutines.h" 33083 #include "NV_UndefineSpaceSpecial_fp.h" 33084 Error Returns 33085 TPM_RC_ATTRIBUTES 33086 33087 3 33088 4 33089 5 33090 6 33091 7 33092 8 33093 9 33094 10 33095 11 33096 12 33097 13 33098 14 33099 15 33100 16 33101 17 33102 18 33103 19 33104 20 33105 21 33106 22 33107 23 33108 24 33109 25 33110 26 33111 27 33112 28 33113 29 33114 30 33115 31 33116 32 33117 33 33118 33119 Meaning 33120 TPMA_NV_POLICY_DELETE is not SET in the Index referenced by 33121 nvIndex 33122 33123 TPM_RC 33124 TPM2_NV_UndefineSpaceSpecial( 33125 NV_UndefineSpaceSpecial_In *in 33126 33127 // IN: input parameter list 33128 33129 ) 33130 { 33131 TPM_RC 33132 NV_INDEX 33133 33134 result; 33135 nvIndex; 33136 33137 // The command needs NV update. Check if NV is available. 33138 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 33139 // this point 33140 result = NvIsAvailable(); 33141 if(result != TPM_RC_SUCCESS) 33142 return result; 33143 // Input Validation 33144 // Get NV index info 33145 NvGetIndexInfo(in->nvIndex, &nvIndex); 33146 // This operation only applies when the TPMA_NV_POLICY_DELETE attribute is SET 33147 if(CLEAR == nvIndex.publicArea.attributes.TPMA_NV_POLICY_DELETE) 33148 return TPM_RC_ATTRIBUTES + RC_NV_UndefineSpaceSpecial_nvIndex; 33149 // Internal Data Update 33150 // Call implementation dependent internal routine to delete NV index 33151 NvDeleteEntity(in->nvIndex); 33152 return TPM_RC_SUCCESS; 33153 } 33154 33155 Family 2.0 33156 Level 00 Revision 00.99 33157 33158 Published 33159 Copyright TCG 2006-2013 33160 33161 Page 405 33162 October 31, 2013 33163 33164 Part 3: Commands 33166 33167 33.6 33168 33169 Trusted Platform Module Library 33170 33171 TPM2_NV_ReadPublic 33172 33173 33.6.1 General Description 33174 This command is used to read the public area and Name of an NV Index. The public area of an Index is 33175 not privacy-sensitive and no authorization is required to read this data. 33176 33177 Page 406 33178 October 31, 2013 33179 33180 Published 33181 Copyright TCG 2006-2013 33182 33183 Family 2.0 33184 Level 00 Revision 00.99 33185 33186 Trusted Platform Module Library 33188 33189 Part 3: Commands 33190 33191 33.6.2 Command and Response 33192 Table 203 TPM2_NV_ReadPublic Command 33193 Type 33194 33195 Name 33196 33197 Description 33198 33199 TPMI_ST_COMMAND_TAG 33200 33201 tag 33202 33203 UINT32 33204 33205 commandSize 33206 33207 TPM_CC 33208 33209 commandCode 33210 33211 TPM_CC_NV_ReadPublic 33212 33213 TPMI_RH_NV_INDEX 33214 33215 nvIndex 33216 33217 the NV Index 33218 Auth Index: None 33219 33220 Table 204 TPM2_NV_ReadPublic Response 33221 Type 33222 33223 Name 33224 33225 Description 33226 33227 TPM_ST 33228 33229 tag 33230 33231 see clause 8 33232 33233 UINT32 33234 33235 responseSize 33236 33237 TPM_RC 33238 33239 responseCode 33240 33241 TPM2B_NV_PUBLIC 33242 33243 nvPublic 33244 33245 the public area of the NV Index 33246 33247 TPM2B_NAME 33248 33249 nvName 33250 33251 the Name of the nvIndex 33252 33253 Family 2.0 33254 Level 00 Revision 00.99 33255 33256 Published 33257 Copyright TCG 2006-2013 33258 33259 Page 407 33260 October 31, 2013 33261 33262 Part 3: Commands 33264 33265 Trusted Platform Module Library 33266 33267 33.6.3 Detailed Actions 33268 1 33269 2 33270 3 33271 4 33272 5 33273 6 33274 7 33275 8 33276 9 33277 10 33278 11 33279 12 33280 13 33281 14 33282 15 33283 16 33284 17 33285 18 33286 19 33287 20 33288 21 33289 22 33290 23 33291 33292 #include "InternalRoutines.h" 33293 #include "NV_ReadPublic_fp.h" 33294 33295 TPM_RC 33296 TPM2_NV_ReadPublic( 33297 NV_ReadPublic_In 33298 NV_ReadPublic_Out 33299 33300 *in, 33301 *out 33302 33303 // IN: input parameter list 33304 // OUT: output parameter list 33305 33306 ) 33307 { 33308 NV_INDEX 33309 33310 nvIndex; 33311 33312 // Command Output 33313 // Get NV index info 33314 NvGetIndexInfo(in->nvIndex, &nvIndex); 33315 // Copy data to output 33316 out->nvPublic.t.nvPublic = nvIndex.publicArea; 33317 // Compute NV name 33318 out->nvName.t.size = NvGetName(in->nvIndex, &out->nvName.t.name); 33319 return TPM_RC_SUCCESS; 33320 } 33321 33322 Page 408 33323 October 31, 2013 33324 33325 Published 33326 Copyright TCG 2006-2013 33327 33328 Family 2.0 33329 Level 00 Revision 00.99 33330 33331 Trusted Platform Module Library 33333 33334 33.7 33335 33336 Part 3: Commands 33337 33338 TPM2_NV_Write 33339 33340 33.7.1 General Description 33341 This command writes a value to an area in NV memory that was previously defined by 33342 TPM2_NV_DefineSpace(). 33343 Proper authorizations are required for this command as determined by TPMA_NV_PPWRITE; 33344 TPMA_NV_OWNERWRITE; TPMA_NV_AUTHWRITE; and, if TPMA_NV_POLICY_WRITE is SET, the 33345 authPolicy of the NV Index. 33346 If the TPMA_NV_WRITELOCKED attribute of the NV Index is SET, then the TPM shall return 33347 TPM_RC_NV_LOCKED. 33348 NOTE 1 33349 33350 If authorization sessions are present, they are checked before checks to see if writes to the NV 33351 Index are locked. 33352 33353 If TPMA_NV_COUNTER, TPMA_NV_BITS or TPMA_NV_EXTEND of the NV Index is SET, then the 33354 TPM shall return TPM_RC_NV_ATTRIBUTE. 33355 If the size of the data parameter plus the offset parameter adds to a value that is greater than the size of 33356 the NV Index data, the TPM shall return TPM_RC_NV_RANGE and not write any data to the NV Index. 33357 If the TPMA_NV_WRITEALL attribute of the NV Index is SET, then the TPM shall return 33358 TPM_RC_NV_RANGE if the size of the data parameter of the command is not the same as the data field 33359 of the NV Index. 33360 If all checks succeed, the TPM will merge the data.size octets of data.buffer value into the nvIndexdata 33361 starting at nvIndexdata[offset]. If the NV memory is implemented with a technology that has endurance 33362 limitations, the TPM shall check that the merged data is different from the current contents of the NV 33363 Index and only perform a write to NV memory if they differ. 33364 After successful completion of this command, TPMA_NV_WRITTEN for the NV Index will be SET. 33365 NOTE 2 33366 33367 Once SET, TPMA_NV_WRITTEN remains SET until the NV Index is undefined or the NV Index is 33368 cleared. 33369 33370 Family 2.0 33371 Level 00 Revision 00.99 33372 33373 Published 33374 Copyright TCG 2006-2013 33375 33376 Page 409 33377 October 31, 2013 33378 33379 Part 3: Commands 33381 33382 Trusted Platform Module Library 33383 33384 33.7.2 Command and Response 33385 Table 205 TPM2_NV_Write Command 33386 Type 33387 33388 Name 33389 33390 Description 33391 33392 TPMI_ST_COMMAND_TAG 33393 33394 tag 33395 33396 UINT32 33397 33398 commandSize 33399 33400 TPM_CC 33401 33402 commandCode 33403 33404 TPM_CC_NV_Write {NV} 33405 33406 TPMI_RH_NV_AUTH 33407 33408 @authHandle 33409 33410 handle indicating the source of the authorization value 33411 Auth Index: 1 33412 Auth Role: USER 33413 33414 TPMI_RH_NV_INDEX 33415 33416 nvIndex 33417 33418 the NV Index of the area to write 33419 Auth Index: None 33420 33421 TPM2B_MAX_NV_BUFFER 33422 33423 data 33424 33425 the data to write 33426 33427 UINT16 33428 33429 offset 33430 33431 the offset into the NV Area 33432 33433 Table 206 TPM2_NV_Write Response 33434 Type 33435 33436 Name 33437 33438 Description 33439 33440 TPM_ST 33441 33442 tag 33443 33444 see clause 8 33445 33446 UINT32 33447 33448 responseSize 33449 33450 TPM_RC 33451 33452 responseCode 33453 33454 Page 410 33455 October 31, 2013 33456 33457 Published 33458 Copyright TCG 2006-2013 33459 33460 Family 2.0 33461 Level 00 Revision 00.99 33462 33463 Trusted Platform Module Library 33465 33466 Part 3: Commands 33467 33468 33.7.3 Detailed Actions 33469 1 33470 2 33471 3 33472 33473 #include "InternalRoutines.h" 33474 #include "NV_Write_fp.h" 33475 #include "NV_spt_fp.h" 33476 Error Returns 33477 TPM_RC_ATTRIBUTES 33478 33479 Index referenced by nvIndex has either TPMA_NV_BITS, 33480 TPMA_NV_COUNTER, or TPMA_NV_EVENT attribute SET 33481 33482 TPM_RC_NV_AUTHORIZATION 33483 33484 the authorization was valid but the authorizing entity (authHandle) is 33485 not allowed to write to the Index referenced by nvIndex 33486 33487 TPM_RC_NV_LOCKED 33488 33489 Index referenced by nvIndex is write locked 33490 33491 TPM_RC_NV_RANGE 33492 33493 4 33494 5 33495 6 33496 7 33497 8 33498 9 33499 10 33500 11 33501 12 33502 13 33503 14 33504 15 33505 16 33506 17 33507 18 33508 19 33509 20 33510 21 33511 22 33512 23 33513 24 33514 25 33515 26 33516 27 33517 28 33518 29 33519 30 33520 31 33521 32 33522 33 33523 34 33524 35 33525 36 33526 37 33527 38 33528 39 33529 40 33530 41 33531 42 33532 43 33533 44 33534 45 33535 33536 Meaning 33537 33538 if TPMA_NV_WRITEALL is SET then the write is not the size of the 33539 Index referenced by nvIndex; otherwise, the write extends beyond the 33540 limits of the Index 33541 33542 TPM_RC 33543 TPM2_NV_Write( 33544 NV_Write_In 33545 33546 *in 33547 33548 // IN: input parameter list 33549 33550 ) 33551 { 33552 NV_INDEX 33553 TPM_RC 33554 33555 nvIndex; 33556 result; 33557 33558 // Input Validation 33559 // Get NV index info 33560 NvGetIndexInfo(in->nvIndex, &nvIndex); 33561 // common access checks. NvWrtieAccessChecks() may return 33562 // TPM_RC_NV_AUTHORIZATION or TPM_RC_NV_LOCKED 33563 result = NvWriteAccessChecks(in->authHandle, in->nvIndex); 33564 if(result != TPM_RC_SUCCESS) 33565 return result; 33566 // Bits index, extend index or counter index may not be updated by 33567 // TPM2_NV_Write 33568 if( 33569 nvIndex.publicArea.attributes.TPMA_NV_COUNTER == SET 33570 || nvIndex.publicArea.attributes.TPMA_NV_BITS == SET 33571 || nvIndex.publicArea.attributes.TPMA_NV_EXTEND == SET) 33572 return TPM_RC_ATTRIBUTES; 33573 // Too much data 33574 if((in->data.t.size + in->offset) > nvIndex.publicArea.dataSize) 33575 return TPM_RC_NV_RANGE; 33576 // If this index requires a full sized write, make sure that input range is 33577 // full sized 33578 if( 33579 nvIndex.publicArea.attributes.TPMA_NV_WRITEALL == SET 33580 && in->data.t.size < nvIndex.publicArea.dataSize) 33581 return TPM_RC_NV_RANGE; 33582 // Internal Data Update 33583 // Perform the write. This called routine will SET the TPMA_NV_WRITTEN 33584 // attribute if it has not already been SET. If NV isn't available, an error 33585 // will be returned. 33586 return NvWriteIndexData(in->nvIndex, &nvIndex, in->offset, 33587 33588 Family 2.0 33589 Level 00 Revision 00.99 33590 33591 Published 33592 Copyright TCG 2006-2013 33593 33594 Page 411 33595 October 31, 2013 33596 33597 Part 3: Commands 33599 46 33600 47 33601 48 33602 33603 Trusted Platform Module Library 33604 in->data.t.size, in->data.t.buffer); 33605 33606 } 33607 33608 Page 412 33609 October 31, 2013 33610 33611 Published 33612 Copyright TCG 2006-2013 33613 33614 Family 2.0 33615 Level 00 Revision 00.99 33616 33617 Trusted Platform Module Library 33619 33620 33.8 33621 33622 Part 3: Commands 33623 33624 TPM2_NV_Increment 33625 33626 33.8.1 General Description 33627 This command is used to increment the value in an NV Index that has TPMA_NV_COUNTER SET. The 33628 data value of the NV Index is incremented by one. 33629 NOTE 1 33630 33631 The NV Index counter is an unsigned value. 33632 33633 If TPMA_NV_COUNTER 33634 TPM_RC_ATTRIBUTES. 33635 33636 is 33637 33638 not 33639 33640 SET 33641 33642 in 33643 33644 the 33645 33646 indicated 33647 33648 NV 33649 33650 Index, 33651 33652 the 33653 33654 TPM 33655 33656 shall 33657 33658 return 33659 33660 If TPMA_NV_WRITELOCKED is SET, the TPM shall return TPM_RC_NV_LOCKED. 33661 If TPMA_NV_WRITTEN is CLEAR, it will be SET. 33662 If TPMA_NV_ORDERLY is SET, and the difference between the volatile and non-volatile versions of this 33663 field is greater than MAX_ORDERLY_COUNT, then the non-volatile version of the counter is updated. 33664 NOTE 2 33665 33666 If a TPM implements TPMA_NV_ORDERLY and an Index is defined with TPMA_NV_ORDERLY and 33667 TPM_NV_COUNTER both SET, then in the Event of a non-orderly shutdown, the non-volatile value 33668 for the counter Index will be advanced by MAX_ORDERLY_COUNT at the next TPM2_Startup(). 33669 33670 NOTE 3 33671 33672 An allowed implementation would keep a counter value in NV and a resettable counter in RAM. The 33673 reported value of the NV Index would be the sum of the two values. When the RAM count increments 33674 past the maximum allowed value (MAX_ORDERLY_COUNT), the non-volatile version of the count is 33675 updated with the sum of the values and the RAM count is reset to zero. 33676 33677 Family 2.0 33678 Level 00 Revision 00.99 33679 33680 Published 33681 Copyright TCG 2006-2013 33682 33683 Page 413 33684 October 31, 2013 33685 33686 Part 3: Commands 33688 33689 Trusted Platform Module Library 33690 33691 33.8.2 Command and Response 33692 Table 207 TPM2_NV_Increment Command 33693 Type 33694 33695 Name 33696 33697 Description 33698 33699 TPMI_ST_COMMAND_TAG 33700 33701 tag 33702 33703 UINT32 33704 33705 commandSize 33706 33707 TPM_CC 33708 33709 commandCode 33710 33711 TPM_CC_NV_Increment {NV} 33712 33713 TPMI_RH_NV_AUTH 33714 33715 @authHandle 33716 33717 handle indicating the source of the authorization value 33718 Auth Index: 1 33719 Auth Role: USER 33720 33721 TPMI_RH_NV_INDEX 33722 33723 nvIndex 33724 33725 the NV Index to increment 33726 Auth Index: None 33727 33728 Table 208 TPM2_NV_Increment Response 33729 Type 33730 33731 Name 33732 33733 Description 33734 33735 TPM_ST 33736 33737 tag 33738 33739 see clause 8 33740 33741 UINT32 33742 33743 responseSize 33744 33745 TPM_RC 33746 33747 responseCode 33748 33749 Page 414 33750 October 31, 2013 33751 33752 Published 33753 Copyright TCG 2006-2013 33754 33755 Family 2.0 33756 Level 00 Revision 00.99 33757 33758 Trusted Platform Module Library 33760 33761 Part 3: Commands 33762 33763 33.8.3 Detailed Actions 33764 1 33765 2 33766 3 33767 33768 #include "InternalRoutines.h" 33769 #include "NV_Increment_fp.h" 33770 #include "NV_spt_fp.h" 33771 Error Returns 33772 TPM_RC_ATTRIBUTES 33773 33774 NV index is not a counter 33775 33776 TPM_RC_NV_AUTHORIZATION 33777 33778 authorization failure 33779 33780 TPM_RC_NV_LOCKED 33781 4 33782 5 33783 6 33784 7 33785 8 33786 9 33787 10 33788 11 33789 12 33790 13 33791 14 33792 15 33793 16 33794 17 33795 18 33796 19 33797 20 33798 21 33799 22 33800 23 33801 24 33802 25 33803 26 33804 27 33805 28 33806 29 33807 30 33808 31 33809 32 33810 33 33811 34 33812 35 33813 36 33814 37 33815 38 33816 39 33817 40 33818 41 33819 42 33820 43 33821 44 33822 45 33823 46 33824 47 33825 48 33826 49 33827 50 33828 51 33829 33830 Meaning 33831 33832 Index is write locked 33833 33834 TPM_RC 33835 TPM2_NV_Increment( 33836 NV_Increment_In 33837 33838 *in 33839 33840 // IN: input parameter list 33841 33842 ) 33843 { 33844 TPM_RC 33845 NV_INDEX 33846 UINT64 33847 33848 result; 33849 nvIndex; 33850 countValue; 33851 33852 // Input Validation 33853 // Common access checks, a TPM_RC_NV_AUTHORIZATION or TPM_RC_NV_LOCKED 33854 // error may be returned at this point 33855 result = NvWriteAccessChecks(in->authHandle, in->nvIndex); 33856 if(result != TPM_RC_SUCCESS) 33857 return result; 33858 // Get NV index info 33859 NvGetIndexInfo(in->nvIndex, &nvIndex); 33860 // Make sure that this is a counter 33861 if(nvIndex.publicArea.attributes.TPMA_NV_COUNTER != SET) 33862 return TPM_RC_ATTRIBUTES + RC_NV_Increment_nvIndex; 33863 // Internal Data Update 33864 // If counter index is not been written, initialize it 33865 if(nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == CLEAR) 33866 countValue = NvInitialCounter(); 33867 else 33868 // Read NV data in native format for TPM CPU. 33869 NvGetIntIndexData(in->nvIndex, &nvIndex, &countValue); 33870 // Do the increment 33871 countValue++; 33872 // If this is an orderly counter that just rolled over, need to be able to 33873 // write to NV to proceed. This check is done here, because NvWriteIndexData() 33874 // does not see if the update is for counter rollover. 33875 if( 33876 nvIndex.publicArea.attributes.TPMA_NV_ORDERLY == SET 33877 && (countValue & MAX_ORDERLY_COUNT) == 0) 33878 { 33879 result = NvIsAvailable(); 33880 if(result != TPM_RC_SUCCESS) 33881 return result; 33882 // Need to force an NV update 33883 33884 Family 2.0 33885 Level 00 Revision 00.99 33886 33887 Published 33888 Copyright TCG 2006-2013 33889 33890 Page 415 33891 October 31, 2013 33892 33893 Part 3: Commands 33895 52 33896 53 33897 54 33898 55 33899 56 33900 57 33901 58 33902 59 33903 60 33904 33905 Trusted Platform Module Library 33906 33907 g_updateNV = TRUE; 33908 } 33909 // Write NV data back. A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may 33910 // be returned at this point. If necessary, this function will set the 33911 // TPMA_NV_WRITTEN attribute 33912 return NvWriteIndexData(in->nvIndex, &nvIndex, 0, 8, &countValue); 33913 } 33914 33915 Page 416 33916 October 31, 2013 33917 33918 Published 33919 Copyright TCG 2006-2013 33920 33921 Family 2.0 33922 Level 00 Revision 00.99 33923 33924 Trusted Platform Module Library 33926 33927 33.9 33928 33929 Part 3: Commands 33930 33931 TPM2_NV_Extend 33932 33933 33.9.1 General Description 33934 This command extends a value to an area in NV memory that was previously defined by 33935 TPM2_NV_DefineSpace. 33936 If TPMA_NV_EXTEND is not SET, then the TPM shall return TPM_RC_ATTRIBUTES. 33937 Proper write authorizations are required for this command as determined by TPMA_NV_PPWRITE, 33938 TPMA_NV_OWNERWRITE, TPMA_NV_AUTHWRITE, and the authPolicy of the NV Index. 33939 After successful completion of this command, TPMA_NV_WRITTEN for the NV Index will be SET. 33940 NOTE 1 33941 33942 Once SET, TPMA_NV_WRITTEN remains SET until the NV Index is undefined or the NV Index is 33943 cleared. 33944 33945 If the TPMA_NV_WRITELOCKED attribute of the NV Index is SET, then the TPM shall return 33946 TPM_RC_NV_LOCKED. 33947 NOTE 2 33948 33949 If authorization sessions are present, they are checked before checks to see if writes to the NV 33950 Index are locked. 33951 33952 The data.buffer parameter may be larger than the defined size of the NV Index. 33953 The Index will be updated by: 33954 33955 nvIndexdatanew HnameAkg(nvIndexdataold || data.buffer) 33956 33957 (39) 33958 33959 where 33960 33961 HnameAkg() 33962 33963 the hash algorithm indicated in nvIndexnameAlg 33964 33965 nvIndexdata 33966 33967 the value of the data field in the NV Index 33968 33969 data.buffer 33970 33971 the data buffer of the command parameter 33972 33973 NOTE 3 33974 33975 If TPMA_NV_WRITTEN is CLEAR, then nvIndexdata is a Zero Digest. 33976 33977 Family 2.0 33978 Level 00 Revision 00.99 33979 33980 Published 33981 Copyright TCG 2006-2013 33982 33983 Page 417 33984 October 31, 2013 33985 33986 Part 3: Commands 33988 33989 Trusted Platform Module Library 33990 33991 33.9.2 Command and Response 33992 Table 209 TPM2_NV_Extend Command 33993 Type 33994 33995 Name 33996 33997 Description 33998 33999 TPMI_ST_COMMAND_TAG 34000 34001 tag 34002 34003 UINT32 34004 34005 commandSize 34006 34007 TPM_CC 34008 34009 commandCode 34010 34011 TPM_CC_NV_Extend {NV} 34012 34013 TPMI_RH_NV_AUTH 34014 34015 @authHandle 34016 34017 handle indicating the source of the authorization value 34018 Auth Index: 1 34019 Auth Role: USER 34020 34021 TPMI_RH_NV_INDEX 34022 34023 nvIndex 34024 34025 the NV Index to extend 34026 Auth Index: None 34027 34028 TPM2B_MAX_NV_BUFFER 34029 34030 data 34031 34032 the data to extend 34033 34034 Table 210 TPM2_NV_Extend Response 34035 Type 34036 34037 Name 34038 34039 Description 34040 34041 TPM_ST 34042 34043 tag 34044 34045 see clause 8 34046 34047 UINT32 34048 34049 responseSize 34050 34051 TPM_RC 34052 34053 responseCode 34054 34055 Page 418 34056 October 31, 2013 34057 34058 Published 34059 Copyright TCG 2006-2013 34060 34061 Family 2.0 34062 Level 00 Revision 00.99 34063 34064 Trusted Platform Module Library 34066 34067 Part 3: Commands 34068 34069 33.9.3 Detailed Actions 34070 1 34071 2 34072 3 34073 34074 #include "InternalRoutines.h" 34075 #include "NV_Extend_fp.h" 34076 #include "NV_spt_fp.h" 34077 Error Returns 34078 TPM_RC_ATTRIBUTES 34079 34080 the TPMA_NV_EXTEND attribute is not SET in the Index referenced 34081 by nvIndex 34082 34083 TPM_RC_NV_AUTHORIZATION 34084 34085 the authorization was valid but the authorizing entity (authHandle) is 34086 not allowed to write to the Index referenced by nvIndex 34087 34088 TPM_RC_NV_LOCKED 34089 4 34090 5 34091 6 34092 7 34093 8 34094 9 34095 10 34096 11 34097 12 34098 13 34099 14 34100 15 34101 16 34102 17 34103 18 34104 19 34105 20 34106 21 34107 22 34108 23 34109 24 34110 25 34111 26 34112 27 34113 28 34114 29 34115 30 34116 31 34117 32 34118 33 34119 34 34120 35 34121 36 34122 37 34123 38 34124 39 34125 40 34126 41 34127 42 34128 43 34129 44 34130 45 34131 46 34132 47 34133 48 34134 49 34135 34136 Meaning 34137 34138 the Index referenced by nvIndex is locked for writing 34139 34140 TPM_RC 34141 TPM2_NV_Extend( 34142 NV_Extend_In 34143 34144 *in 34145 34146 // IN: input parameter list 34147 34148 ) 34149 { 34150 TPM_RC 34151 NV_INDEX 34152 34153 result; 34154 nvIndex; 34155 34156 TPM2B_DIGEST 34157 TPM2B_DIGEST 34158 HASH_STATE 34159 34160 oldDigest; 34161 newDigest; 34162 hashState; 34163 34164 // Input Validation 34165 // Common access checks, NvWriteAccessCheck() may return TPM_RC_NV_AUTHORIZATION 34166 // or TPM_RC_NV_LOCKED 34167 result = NvWriteAccessChecks(in->authHandle, in->nvIndex); 34168 if(result != TPM_RC_SUCCESS) 34169 return result; 34170 // Get NV index info 34171 NvGetIndexInfo(in->nvIndex, &nvIndex); 34172 // Make sure that this is an extend index 34173 if(nvIndex.publicArea.attributes.TPMA_NV_EXTEND != SET) 34174 return TPM_RC_ATTRIBUTES + RC_NV_Extend_nvIndex; 34175 // If the Index is not-orderly, or if this is the first write, NV will 34176 // need to be updated. 34177 if( 34178 nvIndex.publicArea.attributes.TPMA_NV_ORDERLY == CLEAR 34179 || nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == CLEAR) 34180 { 34181 // Check if NV is available. NvIsAvailable may return TPM_RC_NV_UNAVAILABLE 34182 // TPM_RC_NV_RATE or TPM_RC_SUCCESS. 34183 result = NvIsAvailable(); 34184 if(result != TPM_RC_SUCCESS) 34185 return result; 34186 } 34187 // Internal Data Update 34188 // Perform the write. 34189 oldDigest.t.size = CryptGetHashDigestSize(nvIndex.publicArea.nameAlg); 34190 if(nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == SET) 34191 { 34192 NvGetIndexData(in->nvIndex, &nvIndex, 0, 34193 34194 Family 2.0 34195 Level 00 Revision 00.99 34196 34197 Published 34198 Copyright TCG 2006-2013 34199 34200 Page 419 34201 October 31, 2013 34202 34203 Part 3: Commands 34205 50 34206 51 34207 52 34208 53 34209 54 34210 55 34211 56 34212 57 34213 58 34214 59 34215 60 34216 61 34217 62 34218 63 34219 64 34220 65 34221 66 34222 67 34223 68 34224 69 34225 70 34226 71 34227 72 34228 34229 Trusted Platform Module Library 34230 34231 oldDigest.t.size, oldDigest.t.buffer); 34232 } 34233 else 34234 { 34235 MemorySet(oldDigest.t.buffer, 0, oldDigest.t.size); 34236 } 34237 // Start hash 34238 newDigest.t.size = CryptStartHash(nvIndex.publicArea.nameAlg, &hashState); 34239 // Adding old digest 34240 CryptUpdateDigest2B(&hashState, &oldDigest.b); 34241 // Adding new data 34242 CryptUpdateDigest2B(&hashState, &in->data.b); 34243 // Complete hash 34244 CryptCompleteHash2B(&hashState, &newDigest.b); 34245 // Write extended hash back. 34246 // Note, this routine will SET the TPMA_NV_WRITTEN attribute if necessary 34247 return NvWriteIndexData(in->nvIndex, &nvIndex, 0, 34248 newDigest.t.size, newDigest.t.buffer); 34249 } 34250 34251 Page 420 34252 October 31, 2013 34253 34254 Published 34255 Copyright TCG 2006-2013 34256 34257 Family 2.0 34258 Level 00 Revision 00.99 34259 34260 Trusted Platform Module Library 34262 34263 Part 3: Commands 34264 34265 33.10 TPM2_NV_SetBits 34266 33.10.1 34267 34268 General Description 34269 34270 This command is used to SET bits in an NV Index that was created as a bit field. Any number of bits from 34271 0 to 64 may be SET. The contents of data are ORed with the current contents of the NV Index starting at 34272 offset. The checks on data and offset are the same as for TPM2_NV_Write. 34273 If TPMA_NV_WRITTEN is not SET, then, for the purposes of this command, the NV Index is considered 34274 to contain all zero bits and data is OR with that value. 34275 If TPMA_NV_BITS is not SET, then the TPM shall return TPM_RC_ATTRIBUTES. 34276 After successful completion of this command, TPMA_NV_WRITTEN for the NV Index will be SET. 34277 NOTE 34278 34279 TPMA_NV_WRITTEN will be SET even if no bits were SET. 34280 34281 Family 2.0 34282 Level 00 Revision 00.99 34283 34284 Published 34285 Copyright TCG 2006-2013 34286 34287 Page 421 34288 October 31, 2013 34289 34290 Part 3: Commands 34292 34293 33.10.2 34294 34295 Trusted Platform Module Library 34296 34297 Command and Response 34298 Table 211 TPM2_NV_SetBits Command 34299 34300 Type 34301 34302 Name 34303 34304 Description 34305 34306 TPMI_ST_COMMAND_TAG 34307 34308 tag 34309 34310 UINT32 34311 34312 commandSize 34313 34314 TPM_CC 34315 34316 commandCode 34317 34318 TPM_CC_NV_SetBits {NV} 34319 34320 TPMI_RH_NV_AUTH 34321 34322 @authHandle 34323 34324 handle indicating the source of the authorization value 34325 Auth Index: 1 34326 Auth Role: USER 34327 34328 TPMI_RH_NV_INDEX 34329 34330 nvIndex 34331 34332 NV Index of the area in which the bit is to be set 34333 Auth Index: None 34334 34335 UINT64 34336 34337 bits 34338 34339 the data to OR with the current contents 34340 34341 Table 212 TPM2_NV_SetBits Response 34342 Type 34343 34344 Name 34345 34346 Description 34347 34348 TPM_ST 34349 34350 tag 34351 34352 see clause 8 34353 34354 UINT32 34355 34356 responseSize 34357 34358 TPM_RC 34359 34360 responseCode 34361 34362 Page 422 34363 October 31, 2013 34364 34365 Published 34366 Copyright TCG 2006-2013 34367 34368 Family 2.0 34369 Level 00 Revision 00.99 34370 34371 Trusted Platform Module Library 34373 34374 33.10.3 34375 1 34376 2 34377 3 34378 34379 Part 3: Commands 34380 34381 Detailed Actions 34382 34383 #include "InternalRoutines.h" 34384 #include "NV_SetBits_fp.h" 34385 #include "NV_spt_fp.h" 34386 Error Returns 34387 TPM_RC_ATTRIBUTES 34388 34389 the TPMA_NV_BITS attribute is not SET in the Index referenced by 34390 nvIndex 34391 34392 TPM_RC_NV_AUTHORIZATION 34393 34394 the authorization was valid but the authorizing entity (authHandle) is 34395 not allowed to write to the Index referenced by nvIndex 34396 34397 TPM_RC_NV_LOCKED 34398 4 34399 5 34400 6 34401 7 34402 8 34403 9 34404 10 34405 11 34406 12 34407 13 34408 14 34409 15 34410 16 34411 17 34412 18 34413 19 34414 20 34415 21 34416 22 34417 23 34418 24 34419 25 34420 26 34421 27 34422 28 34423 29 34424 30 34425 31 34426 32 34427 33 34428 34 34429 35 34430 36 34431 37 34432 38 34433 39 34434 40 34435 41 34436 42 34437 43 34438 44 34439 45 34440 46 34441 47 34442 48 34443 49 34444 34445 Meaning 34446 34447 the Index referenced by nvIndex is locked for writing 34448 34449 TPM_RC 34450 TPM2_NV_SetBits( 34451 NV_SetBits_In 34452 34453 *in 34454 34455 // IN: input parameter list 34456 34457 ) 34458 { 34459 TPM_RC 34460 NV_INDEX 34461 UINT64 34462 34463 result; 34464 nvIndex; 34465 bitValue; 34466 34467 // Input Validation 34468 // Common access checks, NvWriteAccessCheck() may return TPM_RC_NV_AUTHORIZATION 34469 // or TPM_RC_NV_LOCKED 34470 // error may be returned at this point 34471 result = NvWriteAccessChecks(in->authHandle, in->nvIndex); 34472 if(result != TPM_RC_SUCCESS) 34473 return result; 34474 // Get NV index info 34475 NvGetIndexInfo(in->nvIndex, &nvIndex); 34476 // Make sure that this is a bit field 34477 if(nvIndex.publicArea.attributes.TPMA_NV_BITS != SET) 34478 return TPM_RC_ATTRIBUTES + RC_NV_SetBits_nvIndex; 34479 // If the Index is not-orderly, or if this is the first write, NV will 34480 // need to be updated. 34481 if( 34482 nvIndex.publicArea.attributes.TPMA_NV_ORDERLY == CLEAR 34483 || nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == CLEAR) 34484 { 34485 // Check if NV is available. NvIsAvailable may return TPM_RC_NV_UNAVAILABLE 34486 // TPM_RC_NV_RATE or TPM_RC_SUCCESS. 34487 result = NvIsAvailable(); 34488 if(result != TPM_RC_SUCCESS) 34489 return result; 34490 } 34491 // Internal Data Update 34492 // If index is not been written, initialize it 34493 if(nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == CLEAR) 34494 bitValue = 0; 34495 else 34496 // Read index data 34497 34498 Family 2.0 34499 Level 00 Revision 00.99 34500 34501 Published 34502 Copyright TCG 2006-2013 34503 34504 Page 423 34505 October 31, 2013 34506 34507 Part 3: Commands 34509 50 34510 51 34511 52 34512 53 34513 54 34514 55 34515 56 34516 57 34517 58 34518 59 34519 34520 Trusted Platform Module Library 34521 34522 NvGetIntIndexData(in->nvIndex, &nvIndex, &bitValue); 34523 // OR in the new bit setting 34524 bitValue |= in->bits; 34525 // Write index data back. If necessary, this function will SET 34526 // TPMA_NV_WRITTEN. 34527 return NvWriteIndexData(in->nvIndex, &nvIndex, 0, 8, &bitValue); 34528 } 34529 34530 Page 424 34531 October 31, 2013 34532 34533 Published 34534 Copyright TCG 2006-2013 34535 34536 Family 2.0 34537 Level 00 Revision 00.99 34538 34539 Trusted Platform Module Library 34541 34542 Part 3: Commands 34543 34544 33.11 TPM2_NV_WriteLock 34545 33.11.1 34546 34547 General Description 34548 34549 If the TPMA_NV_WRITEDEFINE or TPMA_NV_WRITE_STCLEAR attributes of an NV location are SET, 34550 then this command may be used to inhibit further writes of the NV Index. 34551 Proper write authorization is required for this command as determined by TPMA_NV_PPWRITE, 34552 TPMA_NV_OWNERWRITE, TPMA_NV_AUTHWRITE, and the authPolicy of the NV Index. 34553 It is not an error if TPMA_NV_WRITELOCKED for the NV Index is already SET. 34554 If neither TPMA_NV_WRITEDEFINE nor TPMA_NV_WRITE_STCLEAR of the NV Index is SET, then the 34555 TPM shall return TPM_RC_ATTRIBUTES. 34556 If the command is properly authorized and TPMA_NV_WRITE_STCLEAR or TPMA_NV_WRITEDEFINE 34557 is SET, then the TPM shall SET TPMA_NV_WRITELOCKED for the NV Index. 34558 TPMA_NV_WRITELOCKED will be clear on the next TPM2_Startup(TPM_SU_CLEAR) unless 34559 TPMA_NV_WRITEDEFINE is SET. 34560 34561 Family 2.0 34562 Level 00 Revision 00.99 34563 34564 Published 34565 Copyright TCG 2006-2013 34566 34567 Page 425 34568 October 31, 2013 34569 34570 Part 3: Commands 34572 34573 33.11.2 34574 34575 Trusted Platform Module Library 34576 34577 Command and Response 34578 Table 213 TPM2_NV_WriteLock Command 34579 34580 Type 34581 34582 Name 34583 34584 Description 34585 34586 TPMI_ST_COMMAND_TAG 34587 34588 tag 34589 34590 UINT32 34591 34592 commandSize 34593 34594 TPM_CC 34595 34596 commandCode 34597 34598 TPM_CC_NV_WriteLock {NV} 34599 34600 TPMI_RH_NV_AUTH 34601 34602 @authHandle 34603 34604 handle indicating the source of the authorization value 34605 Auth Index: 1 34606 Auth Role: USER 34607 34608 TPMI_RH_NV_INDEX 34609 34610 nvIndex 34611 34612 the NV Index of the area to lock 34613 Auth Index: None 34614 34615 Table 214 TPM2_NV_WriteLock Response 34616 Type 34617 34618 Name 34619 34620 Description 34621 34622 TPM_ST 34623 34624 tag 34625 34626 see clause 8 34627 34628 UINT32 34629 34630 responseSize 34631 34632 TPM_RC 34633 34634 responseCode 34635 34636 Page 426 34637 October 31, 2013 34638 34639 Published 34640 Copyright TCG 2006-2013 34641 34642 Family 2.0 34643 Level 00 Revision 00.99 34644 34645 Trusted Platform Module Library 34647 34648 33.11.3 34649 1 34650 2 34651 3 34652 34653 Part 3: Commands 34654 34655 Detailed Actions 34656 34657 #include "InternalRoutines.h" 34658 #include "NV_WriteLock_fp.h" 34659 #include "NV_spt_fp.h" 34660 Error Returns 34661 TPM_RC_ATTRIBUTES 34662 34663 neither TPMA_NV_WRITEDEFINE nor 34664 TPMA_NV_WRITE_STCLEAR is SET in Index referenced by 34665 nvIndex 34666 34667 TPM_RC_NV_AUTHORIZATION 34668 34669 4 34670 5 34671 6 34672 7 34673 8 34674 9 34675 10 34676 11 34677 12 34678 13 34679 14 34680 15 34681 16 34682 17 34683 18 34684 19 34685 20 34686 21 34687 22 34688 23 34689 24 34690 25 34691 26 34692 27 34693 28 34694 29 34695 30 34696 31 34697 32 34698 33 34699 34 34700 35 34701 36 34702 37 34703 38 34704 39 34705 40 34706 41 34707 42 34708 43 34709 44 34710 45 34711 46 34712 47 34713 48 34714 49 34715 50 34716 34717 Meaning 34718 34719 the authorization was valid but the authorizing entity (authHandle) is 34720 not allowed to write to the Index referenced by nvIndex 34721 34722 TPM_RC 34723 TPM2_NV_WriteLock( 34724 NV_WriteLock_In *in 34725 34726 // IN: input parameter list 34727 34728 ) 34729 { 34730 TPM_RC 34731 NV_INDEX 34732 34733 result; 34734 nvIndex; 34735 34736 // The command needs NV update. Check if NV is available. 34737 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 34738 // this point 34739 result = NvIsAvailable(); 34740 if(result != TPM_RC_SUCCESS) 34741 return result; 34742 // Input Validation: 34743 // Common write access checks, a TPM_RC_NV_AUTHORIZATION or TPM_RC_NV_LOCKED 34744 // error may be returned at this point 34745 result = NvWriteAccessChecks(in->authHandle, in->nvIndex); 34746 if(result != TPM_RC_SUCCESS) 34747 { 34748 if(result == TPM_RC_NV_AUTHORIZATION) 34749 return TPM_RC_NV_AUTHORIZATION; 34750 // If write access failed because the index is already locked, then it is 34751 // no error. 34752 return TPM_RC_SUCCESS; 34753 } 34754 // Get NV index info 34755 NvGetIndexInfo(in->nvIndex, &nvIndex); 34756 // if non of TPMA_NV_WRITEDEFINE or TPMA_NV_WRITE_STCLEAR is set, the index 34757 // can not be write-locked 34758 if( 34759 nvIndex.publicArea.attributes.TPMA_NV_WRITEDEFINE == CLEAR 34760 && nvIndex.publicArea.attributes.TPMA_NV_WRITE_STCLEAR == CLEAR) 34761 return TPM_RC_ATTRIBUTES + RC_NV_WriteLock_nvIndex; 34762 // Internal Data Update 34763 // Set the WRITELOCK attribute 34764 nvIndex.publicArea.attributes.TPMA_NV_WRITELOCKED = SET; 34765 // Write index info back 34766 NvWriteIndexInfo(in->nvIndex, &nvIndex); 34767 34768 Family 2.0 34769 Level 00 Revision 00.99 34770 34771 Published 34772 Copyright TCG 2006-2013 34773 34774 Page 427 34775 October 31, 2013 34776 34777 Part 3: Commands 34779 51 34780 52 34781 34782 Trusted Platform Module Library 34783 34784 return TPM_RC_SUCCESS; 34785 } 34786 34787 Page 428 34788 October 31, 2013 34789 34790 Published 34791 Copyright TCG 2006-2013 34792 34793 Family 2.0 34794 Level 00 Revision 00.99 34795 34796 Trusted Platform Module Library 34798 34799 Part 3: Commands 34800 34801 33.12 TPM2_NV_GlobalWriteLock 34802 33.12.1 34803 34804 General Description 34805 34806 The command will SET TPMA_NV_WRITELOCKED 34807 TPMA_NV_GLOBALLOCK attribute SET. 34808 34809 for 34810 34811 all 34812 34813 indexes 34814 34815 that 34816 34817 have 34818 34819 their 34820 34821 If an Index has both TPMA_NV_WRITELOCKED and TPMA_NV_WRITEDEFINE SET, then this 34822 command will permanently lock the NV Index for writing. 34823 NOTE 34824 34825 If an Index is defined with TPMA_NV_GLOBALLOCK SET, then the global lock does not apply until 34826 the next time this command is executed. 34827 34828 This command requires either platformAuth/platformPolicy or ownerAuth/ownerPolicy. 34829 34830 Family 2.0 34831 Level 00 Revision 00.99 34832 34833 Published 34834 Copyright TCG 2006-2013 34835 34836 Page 429 34837 October 31, 2013 34838 34839 Part 3: Commands 34841 34842 33.12.2 34843 34844 Trusted Platform Module Library 34845 34846 Command and Response 34847 Table 215 TPM2_NV_GlobalWriteLock Command 34848 34849 Type 34850 34851 Name 34852 34853 TPMI_ST_COMMAND_TAG 34854 34855 tag 34856 34857 UINT32 34858 34859 commandSize 34860 34861 TPM_CC 34862 34863 commandCode 34864 34865 TPM_CC_NV_GlobalWriteLock 34866 34867 TPMI_RH_PROVISION 34868 34869 @authHandle 34870 34871 TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} 34872 Auth Index: 1 34873 Auth Role: USER 34874 34875 Description 34876 34877 Table 216 TPM2_NV_GlobalWriteLock Response 34878 Type 34879 34880 Name 34881 34882 Description 34883 34884 TPM_ST 34885 34886 tag 34887 34888 see clause 8 34889 34890 UINT32 34891 34892 responseSize 34893 34894 TPM_RC 34895 34896 responseCode 34897 34898 Page 430 34899 October 31, 2013 34900 34901 Published 34902 Copyright TCG 2006-2013 34903 34904 Family 2.0 34905 Level 00 Revision 00.99 34906 34907 Trusted Platform Module Library 34909 34910 33.12.3 34911 1 34912 2 34913 3 34914 4 34915 5 34916 6 34917 7 34918 8 34919 9 34920 10 34921 11 34922 12 34923 13 34924 14 34925 15 34926 16 34927 17 34928 18 34929 19 34930 20 34931 21 34932 22 34933 23 34934 24 34935 25 34936 26 34937 34938 Part 3: Commands 34939 34940 Detailed Actions 34941 34942 #include "InternalRoutines.h" 34943 #include "NV_GlobalWriteLock_fp.h" 34944 34945 TPM_RC 34946 TPM2_NV_GlobalWriteLock( 34947 NV_GlobalWriteLock_In *in 34948 34949 // IN: input parameter list 34950 34951 ) 34952 { 34953 TPM_RC 34954 34955 result; 34956 34957 // Input parameter is not reference in command action 34958 in = NULL; // to silence compiler warnings. 34959 // The command needs NV update. Check if NV is available. 34960 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 34961 // this point 34962 result = NvIsAvailable(); 34963 if(result != TPM_RC_SUCCESS) 34964 return result; 34965 // Internal Data Update 34966 // Implementation dependent method of setting the global lock 34967 NvSetGlobalLock(); 34968 return TPM_RC_SUCCESS; 34969 } 34970 34971 Family 2.0 34972 Level 00 Revision 00.99 34973 34974 Published 34975 Copyright TCG 2006-2013 34976 34977 Page 431 34978 October 31, 2013 34979 34980 Part 3: Commands 34982 34983 Trusted Platform Module Library 34984 34985 33.13 TPM2_NV_Read 34986 33.13.1 34987 34988 General Description 34989 34990 This command reads a 34991 TPM2_NV_DefineSpace(). 34992 34993 value 34994 34995 from 34996 34997 an 34998 34999 area 35000 35001 in 35002 35003 NV 35004 35005 memory 35006 35007 previously 35008 35009 defined 35010 35011 by 35012 35013 Proper authorizations are required for this command as determined by TPMA_NV_PPREAD, 35014 TPMA_NV_OWNERREAD, TPMA_NV_AUTHREAD, and the authPolicy of the NV Index. 35015 If TPMA_NV_READLOCKED of the NV Index is SET, then the TPM shall return TPM_RC_NV_LOCKED. 35016 NOTE 35017 35018 If authorization sessions are present, they are checked before the read -lock status of the NV Index 35019 is checked. 35020 35021 If the size parameter plus the offset parameter adds to a value that is greater than the size of the NV 35022 Index data area, the TPM shall return TPM_RC_NV_RANGE and not read any data from the NV Index. 35023 If the NV Index has been defined but the TPMA_NV_WRITTEN attribute is CLEAR, then this command 35024 shall return TPM_RC_NV_UINITIALIZED even if size is zero. 35025 The data parameter in the response may be encrypted using parameter encryption. 35026 35027 Page 432 35028 October 31, 2013 35029 35030 Published 35031 Copyright TCG 2006-2013 35032 35033 Family 2.0 35034 Level 00 Revision 00.99 35035 35036 Trusted Platform Module Library 35038 35039 33.13.2 35040 35041 Part 3: Commands 35042 35043 Command and Response 35044 Table 217 TPM2_NV_Read Command 35045 35046 Type 35047 35048 Name 35049 35050 Description 35051 35052 TPMI_ST_COMMAND_TAG 35053 35054 tag 35055 35056 UINT32 35057 35058 commandSize 35059 35060 TPM_CC 35061 35062 commandCode 35063 35064 TPM_CC_NV_Read 35065 35066 TPMI_RH_NV_AUTH 35067 35068 @authHandle 35069 35070 the handle indicating the source of the authorization 35071 value 35072 Auth Index: 1 35073 Auth Role: USER 35074 35075 TPMI_RH_NV_INDEX 35076 35077 nvIndex 35078 35079 the NV Index to be read 35080 Auth Index: None 35081 35082 UINT16 35083 35084 size 35085 35086 number of octets to read 35087 35088 UINT16 35089 35090 offset 35091 35092 octet offset into the area 35093 This value shall be less than or equal to the size of the 35094 nvIndex data. 35095 35096 Table 218 TPM2_NV_Read Response 35097 Type 35098 35099 Name 35100 35101 Description 35102 35103 TPM_ST 35104 35105 tag 35106 35107 see clause 8 35108 35109 UINT32 35110 35111 responseSize 35112 35113 TPM_RC 35114 35115 responseCode 35116 35117 TPM2B_MAX_NV_BUFFER 35118 35119 data 35120 35121 Family 2.0 35122 Level 00 Revision 00.99 35123 35124 the data read 35125 35126 Published 35127 Copyright TCG 2006-2013 35128 35129 Page 433 35130 October 31, 2013 35131 35132 Part 3: Commands 35134 35135 33.13.3 35136 1 35137 2 35138 3 35139 35140 Trusted Platform Module Library 35141 35142 Detailed Actions 35143 35144 #include "InternalRoutines.h" 35145 #include "NV_Read_fp.h" 35146 #include "NV_spt_fp.h" 35147 Error Returns 35148 TPM_RC_NV_AUTHORIZATION 35149 35150 the authorization was valid but the authorizing entity (authHandle) is 35151 not allowed to read from the Index referenced by nvIndex 35152 35153 TPM_RC_NV_LOCKED 35154 35155 the Index referenced by nvIndex is read locked 35156 35157 TPM_RC_NV_RANGE 35158 35159 read range defined by size and offset is outside the range of the 35160 Index referenced by nvIndex 35161 35162 TPM_RC_NV_UNINITIALIZED 35163 4 35164 5 35165 6 35166 7 35167 8 35168 9 35169 10 35170 11 35171 12 35172 13 35173 14 35174 15 35175 16 35176 17 35177 18 35178 19 35179 20 35180 21 35181 22 35182 23 35183 24 35184 25 35185 26 35186 27 35187 28 35188 29 35189 30 35190 31 35191 32 35192 33 35193 34 35194 35 35195 36 35196 37 35197 35198 Meaning 35199 35200 the Index referenced by nvIndex has not been initialized (written) 35201 35202 TPM_RC 35203 TPM2_NV_Read( 35204 NV_Read_In 35205 NV_Read_Out 35206 35207 *in, 35208 *out 35209 35210 // IN: input parameter list 35211 // OUT: output parameter list 35212 35213 ) 35214 { 35215 NV_INDEX 35216 TPM_RC 35217 35218 nvIndex; 35219 result; 35220 35221 // Input Validation 35222 // Get NV index info 35223 NvGetIndexInfo(in->nvIndex, &nvIndex); 35224 // Common read access checks. NvReadAccessChecks() returns 35225 // TPM_RC_NV_AUTHORIZATION, TPM_RC_NV_LOCKED, or TPM_RC_NV_UNINITIALIZED 35226 // error may be returned at this point 35227 result = NvReadAccessChecks(in->authHandle, in->nvIndex); 35228 if(result != TPM_RC_SUCCESS) 35229 return result; 35230 // Too much data 35231 if((in->size + in->offset) > nvIndex.publicArea.dataSize) 35232 return TPM_RC_NV_RANGE; 35233 // Command Output 35234 // Set the return size 35235 out->data.t.size = in->size; 35236 // Perform the read 35237 NvGetIndexData(in->nvIndex, &nvIndex, in->offset, in->size, out->data.t.buffer); 35238 return TPM_RC_SUCCESS; 35239 } 35240 35241 Page 434 35242 October 31, 2013 35243 35244 Published 35245 Copyright TCG 2006-2013 35246 35247 Family 2.0 35248 Level 00 Revision 00.99 35249 35250 Trusted Platform Module Library 35252 35253 Part 3: Commands 35254 35255 33.14 TPM2_NV_ReadLock 35256 33.14.1 35257 35258 General Description 35259 35260 If TPMA_NV_READ_STCLEAR is SET in an Index, then this command may be used to prevent further 35261 reads of the NV Index until the next TPM2_Startup (TPM_SU_CLEAR). 35262 Proper authorizations are required for this command as determined by TPMA_NV_PPREAD, 35263 TPMA_NV_OWNERREAD, TPMA_NV_AUTHREAD, and the authPolicy of the NV Index. 35264 NOTE 35265 35266 Only an entity that may read an Index is allowed to lock the NV Index for read. 35267 35268 If the command is properly authorized and TPMA_NV_READ_STCLEAR of the NV Index is SET, then the 35269 TPM shall SET TPMA_NV_READLOCKED for the NV Index. If TPMA_NV_READ_STCLEAR of the NV 35270 Index is CLEAR, then the TPM shall return TPM_RC_NV_ATTRIBUTE. TPMA_NV_READLOCKED will 35271 be CLEAR by the next TPM2_Startup(TPM_SU_CLEAR). 35272 It is not an error to use this command for an Index that is already locked for reading. 35273 An Index that had not been written may be locked for reading. 35274 35275 Family 2.0 35276 Level 00 Revision 00.99 35277 35278 Published 35279 Copyright TCG 2006-2013 35280 35281 Page 435 35282 October 31, 2013 35283 35284 Part 3: Commands 35286 35287 33.14.2 35288 35289 Trusted Platform Module Library 35290 35291 Command and Response 35292 Table 219 TPM2_NV_ReadLock Command 35293 35294 Type 35295 35296 Name 35297 35298 Description 35299 35300 TPMI_ST_COMMAND_TAG 35301 35302 tag 35303 35304 UINT32 35305 35306 commandSize 35307 35308 TPM_CC 35309 35310 commandCode 35311 35312 TPM_CC_NV_ReadLock 35313 35314 TPMI_RH_NV_AUTH 35315 35316 @authHandle 35317 35318 the handle indicating the source of the authorization 35319 value 35320 Auth Index: 1 35321 Auth Role: USER 35322 35323 TPMI_RH_NV_INDEX 35324 35325 nvIndex 35326 35327 the NV Index to be locked 35328 Auth Index: None 35329 35330 Table 220 TPM2_NV_ReadLock Response 35331 Type 35332 35333 Name 35334 35335 Description 35336 35337 TPM_ST 35338 35339 tag 35340 35341 see clause 8 35342 35343 UINT32 35344 35345 responseSize 35346 35347 TPM_RC 35348 35349 responseCode 35350 35351 Page 436 35352 October 31, 2013 35353 35354 Published 35355 Copyright TCG 2006-2013 35356 35357 Family 2.0 35358 Level 00 Revision 00.99 35359 35360 Trusted Platform Module Library 35362 35363 33.14.3 35364 1 35365 2 35366 3 35367 35368 Part 3: Commands 35369 35370 Detailed Actions 35371 35372 #include "InternalRoutines.h" 35373 #include "NV_ReadLock_fp.h" 35374 #include "NV_spt_fp.h" 35375 Error Returns 35376 TPM_RC_ATTRIBUTES 35377 35378 TPMA_NV_READ_STCLEAR is not SET so Index referenced by 35379 nvIndex may not be write locked 35380 35381 TPM_RC_NV_AUTHORIZATION 35382 35383 4 35384 5 35385 6 35386 7 35387 8 35388 9 35389 10 35390 11 35391 12 35392 13 35393 14 35394 15 35395 16 35396 17 35397 18 35398 19 35399 20 35400 21 35401 22 35402 23 35403 24 35404 25 35405 26 35406 27 35407 28 35408 29 35409 30 35410 31 35411 32 35412 33 35413 34 35414 35 35415 36 35416 37 35417 38 35418 39 35419 40 35420 41 35421 42 35422 43 35423 44 35424 45 35425 46 35426 47 35427 48 35428 49 35429 50 35430 51 35431 35432 Meaning 35433 35434 the authorization was valid but the authorizing entity (authHandle) is 35435 not allowed to read from the Index referenced by nvIndex 35436 35437 TPM_RC 35438 TPM2_NV_ReadLock( 35439 NV_ReadLock_In *in 35440 35441 // IN: input parameter list 35442 35443 ) 35444 { 35445 TPM_RC 35446 NV_INDEX 35447 35448 result; 35449 nvIndex; 35450 35451 // The command needs NV update. Check if NV is available. 35452 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 35453 // this point 35454 result = NvIsAvailable(); 35455 if(result != TPM_RC_SUCCESS) return result; 35456 // Input Validation 35457 // Common read access checks. NvReadAccessChecks() returns 35458 // TPM_RC_NV_AUTHORIZATION, TPM_RC_NV_LOCKED, or TPM_RC_NV_UNINITIALIZED 35459 // error may be returned at this point 35460 result = NvReadAccessChecks(in->authHandle, in->nvIndex); 35461 if(result != TPM_RC_SUCCESS) 35462 { 35463 if(result == TPM_RC_NV_AUTHORIZATION) 35464 return TPM_RC_NV_AUTHORIZATION; 35465 // Index is already locked for write 35466 else if(result == TPM_RC_NV_LOCKED) 35467 return TPM_RC_SUCCESS; 35468 // If NvReadAccessChecks return TPM_RC_NV_UNINITALIZED, then continue. 35469 // It is not an error to read lock an uninitialized Index. 35470 } 35471 // Get NV index info 35472 NvGetIndexInfo(in->nvIndex, &nvIndex); 35473 // if TPMA_NV_READ_STCLEAR is not set, the index can not be read-locked 35474 if(nvIndex.publicArea.attributes.TPMA_NV_READ_STCLEAR == CLEAR) 35475 return TPM_RC_ATTRIBUTES + RC_NV_ReadLock_nvIndex; 35476 // Internal Data Update 35477 // Set the READLOCK attribute 35478 nvIndex.publicArea.attributes.TPMA_NV_READLOCKED = SET; 35479 // Write NV info back 35480 NvWriteIndexInfo(in->nvIndex, &nvIndex); 35481 return TPM_RC_SUCCESS; 35482 } 35483 35484 Family 2.0 35485 Level 00 Revision 00.99 35486 35487 Published 35488 Copyright TCG 2006-2013 35489 35490 Page 437 35491 October 31, 2013 35492 35493 Part 3: Commands 35495 35496 Trusted Platform Module Library 35497 35498 33.15 TPM2_NV_ChangeAuth 35499 33.15.1 35500 35501 General Description 35502 35503 This command allows the authorization secret for an NV Index to be changed. 35504 If successful, the authorization secret (authValue) of the NV Index associated with nvIndex is changed. 35505 This command requires that a policy session be used for authorization of nvIndex so that the ADMIN role 35506 may be asserted and that commandCode in the policy session context shall be 35507 TPM_CC_NV_ChangeAuth. That is, the policy must contain a specific authorization for changing the 35508 authorization value of the referenced object. 35509 NOTE 35510 35511 The reason for this restriction is to ensure that the admin istrative actions on nvIndex require explicit 35512 approval while other commands may use policy that is not command -dependent. 35513 35514 The size of the newAuth value may be no larger than the size of authorization indicated when the NV 35515 Index was defined. 35516 Since the NV Index authorization is changed before the response HMAC is calculated, the newAuth value 35517 is used when generating the response HMAC key if required. See Part 4 ComputeResponseHMAC(). 35518 35519 Page 438 35520 October 31, 2013 35521 35522 Published 35523 Copyright TCG 2006-2013 35524 35525 Family 2.0 35526 Level 00 Revision 00.99 35527 35528 Trusted Platform Module Library 35530 35531 33.15.2 35532 35533 Part 3: Commands 35534 35535 Command and Response 35536 Table 221 TPM2_NV_ChangeAuth Command 35537 35538 Type 35539 35540 Name 35541 35542 Description 35543 35544 TPMI_ST_COMMAND_TAG 35545 35546 tag 35547 35548 UINT32 35549 35550 commandSize 35551 35552 TPM_CC 35553 35554 commandCode 35555 35556 TPM_CC_NV_ChangeAuth {NV} 35557 35558 TPMI_RH_NV_INDEX 35559 35560 @nvIndex 35561 35562 handle of the object 35563 Auth Index: 1 35564 Auth Role: ADMIN 35565 35566 TPM2B_AUTH 35567 35568 newAuth 35569 35570 new authorization value 35571 35572 Table 222 TPM2_NV_ChangeAuth Response 35573 Type 35574 35575 Name 35576 35577 Description 35578 35579 TPM_ST 35580 35581 tag 35582 35583 see clause 8 35584 35585 UINT32 35586 35587 responseSize 35588 35589 TPM_RC 35590 35591 responseCode 35592 35593 Family 2.0 35594 Level 00 Revision 00.99 35595 35596 Published 35597 Copyright TCG 2006-2013 35598 35599 Page 439 35600 October 31, 2013 35601 35602 Part 3: Commands 35604 35605 33.15.3 35606 1 35607 2 35608 35609 Trusted Platform Module Library 35610 35611 Detailed Actions 35612 35613 #include "InternalRoutines.h" 35614 #include "NV_ChangeAuth_fp.h" 35615 Error Returns 35616 TPM_RC_SIZE 35617 35618 3 35619 4 35620 5 35621 6 35622 7 35623 8 35624 9 35625 10 35626 11 35627 12 35628 13 35629 14 35630 15 35631 16 35632 17 35633 18 35634 19 35635 20 35636 21 35637 22 35638 23 35639 24 35640 25 35641 26 35642 27 35643 28 35644 29 35645 30 35646 31 35647 32 35648 33 35649 34 35650 35 35651 35652 Meaning 35653 newAuth size is larger than the digest size of the Name algorithm for 35654 the Index referenced by 'nvIndex 35655 35656 TPM_RC 35657 TPM2_NV_ChangeAuth( 35658 NV_ChangeAuth_In 35659 35660 *in 35661 35662 // IN: input parameter list 35663 35664 ) 35665 { 35666 TPM_RC 35667 NV_INDEX 35668 35669 result; 35670 nvIndex; 35671 35672 // Input Validation 35673 // Check if NV is available. NvIsAvailable may return TPM_RC_NV_UNAVAILABLE 35674 // TPM_RC_NV_RATE or TPM_RC_SUCCESS. 35675 result = NvIsAvailable(); 35676 if(result != TPM_RC_SUCCESS) return result; 35677 // Read index info from NV 35678 NvGetIndexInfo(in->nvIndex, &nvIndex); 35679 // Remove any trailing zeros that might have been added by the caller 35680 // to obfuscate the size. 35681 MemoryRemoveTrailingZeros(&(in->newAuth)); 35682 // Make sure that the authValue is no larger than the nameAlg of the Index 35683 if(in->newAuth.t.size > CryptGetHashDigestSize(nvIndex.publicArea.nameAlg)) 35684 return TPM_RC_SIZE + RC_NV_ChangeAuth_newAuth; 35685 // Internal Data Update 35686 // Change auth 35687 nvIndex.authValue = in->newAuth; 35688 // Write index info back to NV 35689 NvWriteIndexInfo(in->nvIndex, &nvIndex); 35690 return TPM_RC_SUCCESS; 35691 } 35692 35693 Page 440 35694 October 31, 2013 35695 35696 Published 35697 Copyright TCG 2006-2013 35698 35699 Family 2.0 35700 Level 00 Revision 00.99 35701 35702 Trusted Platform Module Library 35704 35705 Part 3: Commands 35706 35707 33.16 TPM2_NV_Certify 35708 33.16.1 35709 35710 General Description 35711 35712 The purpose of this command is to certify the contents of an NV Index or portion of an NV Index. 35713 If proper authorization for reading the NV Index is provided, the portion of the NV Index selected by size 35714 and offset are included in an attestation block and signed using the key indicated by signHandle. The 35715 attestation also includes size and offset so that the range of the data can be determined. 35716 NOTE 35717 35718 See 20.1 for description of how the signing scheme is selected. 35719 35720 Family 2.0 35721 Level 00 Revision 00.99 35722 35723 Published 35724 Copyright TCG 2006-2013 35725 35726 Page 441 35727 October 31, 2013 35728 35729 Part 3: Commands 35731 35732 33.16.2 35733 35734 Trusted Platform Module Library 35735 35736 Command and Response 35737 Table 223 TPM2_NV_Certify Command 35738 35739 Type 35740 35741 Name 35742 35743 Description 35744 35745 TPMI_ST_COMMAND_TAG 35746 35747 tag 35748 35749 UINT32 35750 35751 commandSize 35752 35753 TPM_CC 35754 35755 commandCode 35756 35757 TPM_CC_NV_Certify 35758 35759 TPMI_DH_OBJECT+ 35760 35761 @signHandle 35762 35763 handle of the key used to sign the attestation structure 35764 Auth Index: 1 35765 Auth Role: USER 35766 35767 TPMI_RH_NV_AUTH 35768 35769 @authHandle 35770 35771 handle indicating the source of the authorization value 35772 for the NV Index 35773 Auth Index: 2 35774 Auth Role: USER 35775 35776 TPMI_RH_NV_INDEX 35777 35778 nvIndex 35779 35780 Index for the area to be certified 35781 Auth Index: None 35782 35783 TPM2B_DATA 35784 35785 qualifyingData 35786 35787 user-provided qualifying data 35788 35789 TPMT_SIG_SCHEME+ 35790 35791 inScheme 35792 35793 signing scheme to use if the scheme for signHandle is 35794 TPM_ALG_NULL 35795 35796 UINT16 35797 35798 size 35799 35800 number of octets to certify 35801 35802 UINT16 35803 35804 offset 35805 35806 octet offset into the area 35807 This value shall be less than or equal to the size of the 35808 nvIndex data. 35809 35810 Table 224 TPM2_NV_Certify Response 35811 Type 35812 35813 Name 35814 35815 Description 35816 35817 TPM_ST 35818 35819 tag 35820 35821 see clause 8 35822 35823 UINT32 35824 35825 responseSize 35826 35827 TPM_RC 35828 35829 responseCode 35830 35831 . 35832 35833 TPM2B_ATTEST 35834 35835 certifyInfo 35836 35837 the structure that was signed 35838 35839 TPMT_SIGNATURE 35840 35841 signature 35842 35843 the asymmetric signature over certifyInfo using the key 35844 referenced by signHandle 35845 35846 Page 442 35847 October 31, 2013 35848 35849 Published 35850 Copyright TCG 2006-2013 35851 35852 Family 2.0 35853 Level 00 Revision 00.99 35854 35855 Trusted Platform Module Library 35857 35858 33.16.3 35859 1 35860 2 35861 3 35862 4 35863 35864 Detailed Actions 35865 35866 #include 35867 #include 35868 #include 35869 #include 35870 35871 Part 3: Commands 35872 35873 "InternalRoutines.h" 35874 "Attest_spt_fp.h" 35875 "NV_spt_fp.h" 35876 "NV_Certify_fp.h" 35877 35878 Error Returns 35879 TPM_RC_NV_AUTHORIZATION 35880 35881 the authorization was valid but the authorizing entity (authHandle) is 35882 not allowed to read from the Index referenced by nvIndex 35883 35884 TPM_RC_KEY 35885 35886 signHandle does not reference a signing key 35887 35888 TPM_RC_NV_LOCKED 35889 35890 Index referenced by nvIndex is locked for reading 35891 35892 TPM_RC_NV_RANGE 35893 35894 offset plus size extends outside of the data range of the Index 35895 referenced by nvIndex 35896 35897 TPM_RC_NV_UNINITIALIZED 35898 35899 Index referenced by nvIndex has not been written 35900 35901 TPM_RC_SCHEME 35902 5 35903 6 35904 7 35905 8 35906 9 35907 10 35908 11 35909 12 35910 13 35911 14 35912 15 35913 16 35914 17 35915 18 35916 19 35917 20 35918 21 35919 22 35920 23 35921 24 35922 25 35923 26 35924 27 35925 28 35926 29 35927 30 35928 31 35929 32 35930 33 35931 34 35932 35 35933 36 35934 37 35935 38 35936 39 35937 40 35938 41 35939 42 35940 43 35941 44 35942 35943 Meaning 35944 35945 inScheme is not an allowed value for the key definition 35946 35947 TPM_RC 35948 TPM2_NV_Certify( 35949 NV_Certify_In 35950 NV_Certify_Out 35951 35952 *in, 35953 *out 35954 35955 // IN: input parameter list 35956 // OUT: output parameter list 35957 35958 ) 35959 { 35960 TPM_RC 35961 NV_INDEX 35962 TPMS_ATTEST 35963 35964 result; 35965 nvIndex; 35966 certifyInfo; 35967 35968 // Attestation command may cause the orderlyState to be cleared due to 35969 // the reporting of clock info. If this is the case, check if NV is 35970 // available first 35971 if(gp.orderlyState != SHUTDOWN_NONE) 35972 { 35973 // The command needs NV update. Check if NV is available. 35974 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at 35975 // this point 35976 result = NvIsAvailable(); 35977 if(result != TPM_RC_SUCCESS) 35978 return result; 35979 } 35980 // Input Validation 35981 // Get NV index info 35982 NvGetIndexInfo(in->nvIndex, &nvIndex); 35983 // Common access checks. A TPM_RC_NV_AUTHORIZATION or TPM_RC_NV_LOCKED 35984 // error may be returned at this point 35985 result = NvReadAccessChecks(in->authHandle, in->nvIndex); 35986 if(result != TPM_RC_SUCCESS) 35987 return result; 35988 // See if the range to be certified is out of the bounds of the defined 35989 // Index 35990 if((in->size + in->offset) > nvIndex.publicArea.dataSize) 35991 return TPM_RC_NV_RANGE; 35992 // Command Output 35993 35994 Family 2.0 35995 Level 00 Revision 00.99 35996 35997 Published 35998 Copyright TCG 2006-2013 35999 36000 Page 443 36001 October 31, 2013 36002 36003 Part 3: Commands 36005 45 36006 46 36007 47 36008 48 36009 49 36010 50 36011 51 36012 52 36013 53 36014 54 36015 55 36016 56 36017 57 36018 58 36019 59 36020 60 36021 61 36022 62 36023 63 36024 64 36025 65 36026 66 36027 67 36028 68 36029 69 36030 70 36031 71 36032 72 36033 73 36034 74 36035 75 36036 76 36037 77 36038 78 36039 79 36040 80 36041 81 36042 82 36043 83 36044 84 36045 85 36046 86 36047 87 36048 88 36049 89 36050 90 36051 91 36052 92 36053 93 36054 94 36055 95 36056 96 36057 97 36058 98 36059 99 36060 100 36061 36062 Trusted Platform Module Library 36063 36064 // Filling in attest information 36065 // Common fields 36066 // FillInAttestInfo can return TPM_RC_SCHEME or TPM_RC_KEY 36067 result = FillInAttestInfo(in->signHandle, 36068 &in->inScheme, 36069 &in->qualifyingData, 36070 &certifyInfo); 36071 if(result != TPM_RC_SUCCESS) 36072 { 36073 if(result == TPM_RC_KEY) 36074 return TPM_RC_KEY + RC_NV_Certify_signHandle; 36075 else 36076 return RcSafeAddToResult(result, RC_NV_Certify_inScheme); 36077 } 36078 // NV certify specific fields 36079 // Attestation type 36080 certifyInfo.type = TPM_ST_ATTEST_NV; 36081 // Get the name of the index 36082 certifyInfo.attested.nv.indexName.t.size = 36083 NvGetName(in->nvIndex, &certifyInfo.attested.nv.indexName.t.name); 36084 // Set the return size 36085 certifyInfo.attested.nv.nvContents.t.size = in->size; 36086 // Set the offset 36087 certifyInfo.attested.nv.offset = in->offset; 36088 // Perform the read 36089 NvGetIndexData(in->nvIndex, &nvIndex, 36090 in->offset, in->size, 36091 certifyInfo.attested.nv.nvContents.t.buffer); 36092 // Sign attestation structure. A NULL signature will be returned if 36093 // signHandle is TPM_RH_NULL. SignAttestInfo() may return TPM_RC_VALUE, 36094 // TPM_RC_SCHEME or TPM_RC_ATTRUBUTES. 36095 // Note: SignAttestInfo may return TPM_RC_ATTRIBUTES if the key is not a 36096 // signing key but that was checked above. TPM_RC_VALUE would mean that the 36097 // data to sign is too large but the data to sign is a digest 36098 result = SignAttestInfo(in->signHandle, 36099 &in->inScheme, 36100 &certifyInfo, 36101 &in->qualifyingData, 36102 &out->certifyInfo, 36103 &out->signature); 36104 if(result != TPM_RC_SUCCESS) 36105 return result; 36106 // orderly state should be cleared because of the reporting of clock info 36107 // if signing happens 36108 if(in->signHandle != TPM_RH_NULL) 36109 g_clearOrderly = TRUE; 36110 return TPM_RC_SUCCESS; 36111 } 36112 36113 Page 444 36114 October 31, 2013 36115 36116 Published 36117 Copyright TCG 2006-2013 36118 36119 Family 2.0 36120 Level 00 Revision 00.99 36121 36122 36124
