1 Trusted Platform Module Library 2 Part 2: Structures 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 2: Structures 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 owners. 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 2: Structures 88 89 CONTENTS 90 1 91 92 Scope .................................................................................................................................................... 1 93 94 2 95 96 Terms and definitions ............................................................................................................................ 1 97 98 3 99 100 Symbols and abbreviated terms ............................................................................................................ 1 101 102 4 103 104 Notation ................................................................................................................................................. 1 105 4.1 106 Introduction ................................................................................................................................ 1 107 4.2 108 Named Constants ...................................................................................................................... 2 109 4.3 110 Data Type Aliases (typedefs) .................................................................................................... 3 111 4.4 112 Enumerations............................................................................................................................. 3 113 4.5 114 Interface Type ............................................................................................................................ 4 115 4.6 116 Arrays ........................................................................................................................................ 5 117 4.7 118 Structure Definitions .................................................................................................................. 6 119 4.8 120 Conditional Types ...................................................................................................................... 7 121 4.9 122 Unions........................................................................................................................................ 8 123 4.9.1 124 Introduction...................................................................................................................... 8 125 4.9.2 126 Union Definition ............................................................................................................... 8 127 4.9.3 128 Union Instance ................................................................................................................ 9 129 4.9.4 130 Union Selector Definition ............................................................................................... 10 131 4.10 Bit Field Definitions .................................................................................................................. 11 132 4.11 Parameter Limits ..................................................................................................................... 11 133 4.12 Enumeration Macro ................................................................................................................. 13 134 4.13 Size Checking .......................................................................................................................... 13 135 4.14 Data Direction .......................................................................................................................... 14 136 4.15 Structure Validations ............................................................................................................... 14 137 4.16 Name Prefix Convention .......................................................................................................... 14 138 4.17 Data Alignment ........................................................................................................................ 15 139 4.18 Parameter Unmarshaling Errors .............................................................................................. 15 140 141 5 142 143 Base Types ......................................................................................................................................... 17 144 5.1 145 Primitive Types ........................................................................................................................ 17 146 5.2 147 Miscellaneous Types ............................................................................................................... 17 148 149 6 150 151 Constants ............................................................................................................................................ 18 152 6.1 153 TPM_SPEC (Specification Version Values) ............................................................................ 18 154 6.2 155 TPM_GENERATED ................................................................................................................. 18 156 6.3 157 TPM_ALG_ID .......................................................................................................................... 19 158 6.4 159 TPM_ECC_CURVE ................................................................................................................. 22 160 6.5 161 TPM_CC (Command Codes) .................................................................................................. 22 162 6.5.1 163 Format ........................................................................................................................... 22 164 6.5.2 165 Description .................................................................................................................... 23 166 6.5.3 167 TPM_CC Listing ............................................................................................................ 24 168 6.6 169 TPM_RC (Response Codes) ................................................................................................... 28 170 6.6.1 171 Description .................................................................................................................... 28 172 6.6.2 173 Response Code Formats .............................................................................................. 29 174 6.6.3 175 TPM_RC Values ........................................................................................................... 32 176 6.7 177 TPM_CLOCK_ADJUST ........................................................................................................... 37 178 6.8 179 TPM_EO (EA Arithmetic Operands) ........................................................................................ 37 180 6.9 181 TPM_ST (Structure Tags) ....................................................................................................... 38 182 6.10 TPM_SU (Startup Type) .......................................................................................................... 40 183 6.11 TPM_SE (Session Type) ......................................................................................................... 40 184 6.12 TPM_CAP (Capabilities) .......................................................................................................... 41 185 6.13 TPM_PT (Property Tag) .......................................................................................................... 41 186 6.14 TPM_PT_PCR (PCR Property Tag) ........................................................................................ 47 187 6.15 TPM_PS (Platform Specific) .................................................................................................... 49 188 189 Family 2.0 190 Level 00 Revision 00.99 191 192 Published 193 Copyright TCG 2006-2013 194 195 Page iii 196 October 31, 2013 197 198 Part 2: Structures 200 201 Trusted Platform Module Library 202 203 7 204 205 Handles ............................................................................................................................................... 50 206 7.1 207 Introduction .............................................................................................................................. 50 208 7.2 209 TPM_HT (Handle Types) ......................................................................................................... 50 210 7.3 211 Persistent Handle Sub-ranges................................................................................................. 51 212 7.4 213 TPM_RH (Permanent Handles)............................................................................................... 52 214 7.5 215 TPM_HC (Handle Value Constants) ....................................................................................... 53 216 217 8 218 219 Attribute Structures .............................................................................................................................. 55 220 8.1 221 Description ............................................................................................................................... 55 222 8.2 223 TPMA_ALGORITHM ............................................................................................................... 55 224 8.3 225 TPMA_OBJECT (Object Attributes) ........................................................................................ 55 226 8.3.1 227 Introduction.................................................................................................................... 55 228 8.3.2 229 Structure Definition ........................................................................................................ 56 230 8.3.3 231 Attribute Descriptions .................................................................................................... 57 232 8.3.3.1 233 Introduction ............................................................................................................ 57 234 8.3.3.2 235 Bit[1] fixedTPM ................................................................................................... 57 236 8.3.3.3 237 Bit[2] stClear ....................................................................................................... 58 238 8.3.3.4 239 Bit[4] fixedParent ................................................................................................ 58 240 8.3.3.5 241 Bit[5] sensitiveDataOrigin ................................................................................... 58 242 8.3.3.6 243 Bit[6] userWithAuth............................................................................................. 59 244 8.3.3.7 245 Bit[7] adminWithPolicy........................................................................................ 59 246 8.3.3.8 247 Bit[10] noDA ....................................................................................................... 59 248 8.3.3.9 249 Bit[11] encryptedDuplication .............................................................................. 60 250 8.3.3.10 251 Bit[16] restricted ................................................................................................. 60 252 8.3.3.11 253 Bit[17] decrypt .................................................................................................... 61 254 8.3.3.12 255 Bit[18] sign .......................................................................................................... 61 256 8.4 257 TPMA_SESSION (Session Attributes) .................................................................................... 62 258 8.5 259 TPMA_LOCALITY (Locality Attribute) ..................................................................................... 63 260 8.6 261 TPMA_PERMANENT .............................................................................................................. 64 262 8.7 263 TPMA_STARTUP_CLEAR ...................................................................................................... 65 264 8.8 265 TPMA_MEMORY .................................................................................................................... 66 266 8.9 267 TPMA_CC (Command Code Attributes) ................................................................................. 67 268 8.9.1 269 Introduction.................................................................................................................... 67 270 8.9.2 271 Structure Definition ........................................................................................................ 67 272 8.9.3 273 Field Descriptions .......................................................................................................... 67 274 8.9.3.1 275 Bits[15:0] commandIndex ................................................................................... 67 276 8.9.3.2 277 Bit[22] nv ............................................................................................................ 67 278 8.9.3.3 279 Bit[23] extensive ................................................................................................. 67 280 8.9.3.4 281 Bit[24] flushed ..................................................................................................... 68 282 8.9.3.5 283 Bits[27:25] cHandles .......................................................................................... 68 284 8.9.3.6 285 Bit[28] rHandle .................................................................................................... 68 286 8.9.3.7 287 Bit[29] V .............................................................................................................. 69 288 8.9.3.8 289 Bits[31:30] Res ................................................................................................... 69 290 291 9 292 293 Interface Types .................................................................................................................................... 70 294 9.1 295 Introduction .............................................................................................................................. 70 296 9.2 297 TPMI_YES_NO ....................................................................................................................... 70 298 9.3 299 TPMI_DH_OBJECT ................................................................................................................. 70 300 9.4 301 TPMI_DH_PERSISTENT ........................................................................................................ 71 302 9.5 303 TPMI_DH_ENTITY .................................................................................................................. 71 304 9.6 305 TPMI_DH_PCR ....................................................................................................................... 72 306 9.7 307 TPMI_SH_AUTH_SESSION ................................................................................................... 72 308 9.8 309 TPMI_SH_HMAC .................................................................................................................... 72 310 9.9 311 TPMI_SH_POLICY .................................................................................................................. 72 312 9.10 TPMI_DH_CONTEXT .............................................................................................................. 73 313 9.11 TPMI_RH_HIERARCHY .......................................................................................................... 73 314 9.12 TPMI_RH_ENABLES .............................................................................................................. 73 315 316 Page iv 317 October 31, 2013 318 319 Published 320 Copyright TCG 2006-2013 321 322 Family 2.0 323 Level 00 Revision 00.99 324 325 Trusted Platform Module Library 327 9.13 328 9.14 329 9.15 330 9.16 331 9.17 332 9.18 333 9.19 334 9.20 335 9.21 336 9.22 337 9.23 338 9.24 339 9.25 340 9.26 341 9.27 342 9.28 343 9.29 344 9.30 345 10 346 347 Part 2: Structures 348 349 TPMI_RH_HIERARCHY_AUTH .............................................................................................. 74 350 TPMI_RH_PLATFORM ........................................................................................................... 74 351 TPMI_RH_OWNER ................................................................................................................. 74 352 TPMI_RH_ENDORSEMENT ................................................................................................... 75 353 TPMI_RH_PROVISION ........................................................................................................... 75 354 TPMI_RH_CLEAR ................................................................................................................... 75 355 TPMI_RH_NV_AUTH .............................................................................................................. 76 356 TPMI_RH_LOCKOUT ............................................................................................................. 76 357 TPMI_RH_NV_INDEX ............................................................................................................. 76 358 TPMI_ALG_HASH ................................................................................................................... 77 359 TPMI_ALG_ASYM (Asymmetric Algorithms) .......................................................................... 77 360 TPMI_ALG_SYM (Symmetric Algorithms) .............................................................................. 78 361 TPMI_ALG_SYM_OBJECT ..................................................................................................... 78 362 TPMI_ALG_SYM_MODE ........................................................................................................ 79 363 TPMI_ALG_KDF (Key and Mask Generation Functions) ........................................................ 79 364 TPMI_ALG_SIG_SCHEME ..................................................................................................... 80 365 TPMI_ECC_KEY_EXCHANGE ............................................................................................... 80 366 TPMI_ST_COMMAND_TAG ................................................................................................... 80 367 368 Structure Definitions ............................................................................................................................ 81 369 10.1 TPMS_ALGORITHM_DESCRIPTION .................................................................................... 81 370 10.2 Hash/Digest Structures ............................................................................................................ 81 371 10.2.1 372 TPMU_HA (Hash) ......................................................................................................... 81 373 10.2.2 374 TPMT_HA...................................................................................................................... 82 375 10.3 Sized Buffers ........................................................................................................................... 82 376 10.3.1 377 Introduction.................................................................................................................... 82 378 10.3.2 379 TPM2B_DIGEST ........................................................................................................... 83 380 10.3.3 381 TPM2B_DATA ............................................................................................................... 83 382 10.3.4 383 TPM2B_NONCE ........................................................................................................... 83 384 10.3.5 385 TPM2B_AUTH .............................................................................................................. 83 386 10.3.6 387 TPM2B_OPERAND ...................................................................................................... 84 388 10.3.7 389 TPM2B_EVENT ............................................................................................................ 84 390 10.3.8 391 TPM2B_MAX_BUFFER ................................................................................................ 84 392 10.3.9 393 TPM2B_MAX_NV_BUFFER ......................................................................................... 84 394 10.3.10 TPM2B_TIMEOUT ........................................................................................................ 85 395 10.3.11 TPM2B_IV ..................................................................................................................... 85 396 10.4 Names ..................................................................................................................................... 85 397 10.4.1 398 Introduction.................................................................................................................... 85 399 10.4.2 400 TPMU_NAME ................................................................................................................ 85 401 10.4.3 402 TPM2B_NAME .............................................................................................................. 86 403 10.5 PCR Structures ........................................................................................................................ 86 404 10.5.1 405 TPMS_PCR_SELECT ................................................................................................... 86 406 10.5.2 407 TPMS_PCR_SELECTION ............................................................................................ 87 408 10.6 Tickets ..................................................................................................................................... 87 409 10.6.1 410 Introduction.................................................................................................................... 87 411 10.6.2 412 A NULL Ticket ............................................................................................................... 88 413 10.6.3 414 TPMT_TK_CREATION ................................................................................................. 89 415 10.6.4 416 TPMT_TK_VERIFIED ................................................................................................... 90 417 10.6.5 418 TPMT_TK_AUTH .......................................................................................................... 91 419 10.6.6 420 TPMT_TK_HASHCHECK ............................................................................................. 92 421 10.7 Property Structures .................................................................................................................. 92 422 10.7.1 423 TPMS_ALG_PROPERTY ............................................................................................. 92 424 10.7.2 425 TPMS_TAGGED_PROPERTY ..................................................................................... 92 426 10.7.3 427 TPMS_TAGGED_PCR_SELECT ................................................................................. 93 428 10.8 Lists ......................................................................................................................................... 93 429 430 Family 2.0 431 Level 00 Revision 00.99 432 433 Published 434 Copyright TCG 2006-2013 435 436 Page v 437 October 31, 2013 438 439 Part 2: Structures 441 442 Trusted Platform Module Library 443 444 10.8.1 445 TPML_CC...................................................................................................................... 93 446 10.8.2 447 TPML_CCA ................................................................................................................... 94 448 10.8.3 449 TPML_ALG.................................................................................................................... 94 450 10.8.4 451 TPML_HANDLE ............................................................................................................ 94 452 10.8.5 453 TPML_DIGEST ............................................................................................................. 95 454 10.8.6 455 TPML_DIGEST_VALUES ............................................................................................. 95 456 10.8.7 457 TPM2B_DIGEST_VALUES........................................................................................... 95 458 10.8.8 459 TPML_PCR_SELECTION............................................................................................. 96 460 10.8.9 461 TPML_ALG_PROPERTY.............................................................................................. 96 462 10.8.10 TPML_TAGGED_TPM_PROPERTY ............................................................................ 96 463 10.8.11 TPML_TAGGED_PCR_PROPERTY ............................................................................ 97 464 10.8.12 TPML_ECC_CURVE .................................................................................................... 97 465 10.9 Capabilities Structures ............................................................................................................. 97 466 10.9.1 467 TPMU_CAPABILITIES .................................................................................................. 97 468 10.9.2 469 TPMS_CAPABILITY_DATA .......................................................................................... 98 470 10.10 Clock/Counter Structures ........................................................................................................ 98 471 10.10.1 TPMS_CLOCK_INFO ................................................................................................... 98 472 10.10.2 Clock ............................................................................................................................. 98 473 10.10.3 ResetCount ................................................................................................................... 98 474 10.10.4 RestartCount ................................................................................................................. 99 475 10.10.5 Safe ............................................................................................................................... 99 476 10.10.6 TPMS_TIME_INFO ....................................................................................................... 99 477 10.11 TPM Attestation Structures .................................................................................................... 100 478 10.11.1 Introduction.................................................................................................................. 100 479 10.11.2 TPMS_TIME_ATTEST_INFO ..................................................................................... 100 480 10.11.3 TPMS_CERTIFY_INFO .............................................................................................. 100 481 10.11.1 TPMS_QUOTE_INFO ................................................................................................. 100 482 10.11.2 TPMS_COMMAND_AUDIT_INFO .............................................................................. 101 483 10.11.3 TPMS_SESSION_AUDIT_INFO ................................................................................. 101 484 10.11.4 TPMS_CREATION_INFO ........................................................................................... 101 485 10.11.5 TPMS_NV_CERTIFY_INFO ....................................................................................... 101 486 10.11.6 TPMI_ST_ATTEST ..................................................................................................... 102 487 10.11.7 TPMU_ATTEST .......................................................................................................... 102 488 10.11.8 TPMS_ATTEST .......................................................................................................... 103 489 10.11.9 TPM2B_ATTEST ........................................................................................................ 103 490 10.12 Authorization Structures ........................................................................................................ 104 491 10.12.1 TPMS_AUTH_COMMAND ......................................................................................... 104 492 10.12.2 TPMS_AUTH_RESPONSE ........................................................................................ 104 493 11 494 495 Algorithm Parameters and Structures ............................................................................................... 105 496 11.1 Symmetric .............................................................................................................................. 105 497 11.1.1 498 Introduction.................................................................................................................. 105 499 11.1.2 500 TPMI_AES_KEY_BITS ............................................................................................... 105 501 11.1.3 502 TPMI_SM4_KEY_BITS ............................................................................................... 105 503 11.1.4 504 TPMU_SYM_KEY_BITS ............................................................................................. 106 505 11.1.5 506 TPMU_SYM_MODE ................................................................................................... 106 507 11.1.6 508 TPMU_SYM_DETAILS ............................................................................................... 107 509 11.1.7 510 TPMT_SYM_DEF ....................................................................................................... 107 511 11.1.8 512 TPMT_SYM_DEF_OBJECT ....................................................................................... 107 513 11.1.9 514 TPM2B_SYM_KEY ..................................................................................................... 108 515 11.1.10 TPMS_SYMCIPHER_PARMS .................................................................................... 108 516 11.1.11 TPM2B_SENSITIVE_DATA ........................................................................................ 108 517 11.1.12 TPMS_SENSITIVE_CREATE ..................................................................................... 109 518 11.1.13 TPM2B_SENSITIVE_CREATE ................................................................................... 110 519 11.1.14 TPMS_SCHEME_SIGHASH....................................................................................... 110 520 11.1.15 TPMI_ALG_HASH_SCHEME ..................................................................................... 110 521 522 Page vi 523 October 31, 2013 524 525 Published 526 Copyright TCG 2006-2013 527 528 Family 2.0 529 Level 00 Revision 00.99 530 531 Trusted Platform Module Library 533 534 Part 2: Structures 535 536 11.1.16 HMAC_SIG_SCHEME ................................................................................................ 110 537 11.1.17 TPMS_SCHEME_XOR ............................................................................................... 111 538 11.1.18 TPMU_SCHEME_HMAC ............................................................................................ 111 539 11.1.19 TPMT_KEYEDHASH_SCHEME ................................................................................. 111 540 11.2 Asymmetric ............................................................................................................................ 112 541 11.2.1 542 Signing Schemes ........................................................................................................ 112 543 11.2.1.1 544 Introduction .......................................................................................................... 112 545 11.2.1.2 546 RSA_SIG_SCHEMES ......................................................................................... 112 547 11.2.1.3 548 ECC_SIG_SCHEMES ......................................................................................... 112 549 11.2.1.4 550 TPMS_SCHEME_ECDAA................................................................................... 112 551 11.2.1.5 552 TPMU_SIG_SCHEME......................................................................................... 113 553 11.2.1.6 554 TPMT_SIG_SCHEME ......................................................................................... 113 555 11.2.2 556 Encryption Schemes ................................................................................................... 114 557 11.2.2.1 558 Introduction .......................................................................................................... 114 559 11.2.2.2 560 TPMS_SCHEME_OAEP ..................................................................................... 114 561 11.2.2.3 562 TPMS_SCHEME_ECDH ..................................................................................... 114 563 11.2.3 564 Key Derivation Schemes ............................................................................................. 114 565 11.2.3.1 566 Introduction .......................................................................................................... 114 567 11.2.3.2 568 TPMS_SCHEME_MGF1 ..................................................................................... 114 569 11.2.3.3 570 TPMS_SCHEME_KDF1_SP800_56a ................................................................. 114 571 11.2.3.4 572 TPMS_SCHEME_KDF2 ...................................................................................... 115 573 11.2.3.5 574 TPMS_SCHEME_KDF1_SP800_108 ................................................................. 115 575 11.2.3.6 576 TPMU_KDF_SCHEME........................................................................................ 115 577 11.2.3.7 578 TPMT_KDF_SCHEME ........................................................................................ 115 579 11.2.3.8 580 TPMI_ALG_ASYM_SCHEME ............................................................................. 116 581 11.2.3.9 582 TPMU_ASYM_SCHEME..................................................................................... 116 583 11.2.3.10 TPMT_ASYM_SCHEME ..................................................................................... 117 584 11.2.4 585 RSA ............................................................................................................................. 117 586 11.2.4.1 587 TPMI_ALG_RSA_SCHEME ................................................................................ 117 588 11.2.4.2 589 TPMT_RSA_SCHEME ........................................................................................ 117 590 11.2.4.3 591 TPMI_ALG_RSA_DECRYPT .............................................................................. 118 592 11.2.4.4 593 TPMT_RSA_DECRYPT ...................................................................................... 118 594 11.2.4.5 595 TPM2B_PUBLIC_KEY_RSA ............................................................................... 118 596 11.2.4.6 597 TPMI_RSA_KEY_BITS ....................................................................................... 118 598 11.2.4.7 599 TPM2B_PRIVATE_KEY_RSA ............................................................................ 119 600 11.2.5 601 ECC ............................................................................................................................. 120 602 11.2.5.1 603 TPM2B_ECC_PARAMETER .............................................................................. 120 604 11.2.5.2 605 TPMS_ECC_POINT ............................................................................................ 120 606 11.2.5.3 607 TPM2B_ECC_POINT .......................................................................................... 120 608 11.2.5.4 609 TPMI_ALG_ECC_SCHEME ............................................................................... 121 610 11.2.5.5 611 TPMI_ECC_CURVE ............................................................................................ 121 612 11.2.5.6 613 TPMT_ECC_SCHEME........................................................................................ 121 614 11.2.5.7 615 TPMS_ALGORITHM_DETAIL_ECC ................................................................... 122 616 11.3 Signatures.............................................................................................................................. 122 617 11.3.1 618 TPMS_SIGNATURE_RSASSA .................................................................................. 122 619 11.3.2 620 TPMS_SIGNATURE_RSAPSS .................................................................................. 122 621 11.3.3 622 TPMS_SIGNATURE_ECDSA ..................................................................................... 123 623 11.3.4 624 TPMU_SIGNATURE ................................................................................................... 123 625 11.3.5 626 TPMT_SIGNATURE ................................................................................................... 124 627 11.4 Key/Secret Exchange ............................................................................................................ 124 628 11.4.1 629 Introduction.................................................................................................................. 124 630 11.4.2 631 TPMU_ENCRYPTED_SECRET ................................................................................. 124 632 11.4.3 633 TPM2B_ENCRYPTED_SECRET ............................................................................... 125 634 12 635 636 Key/Object Complex.......................................................................................................................... 126 637 638 Family 2.0 639 Level 00 Revision 00.99 640 641 Published 642 Copyright TCG 2006-2013 643 644 Page vii 645 October 31, 2013 646 647 Part 2: Structures 649 650 Trusted Platform Module Library 651 652 12.1 Introduction ............................................................................................................................ 126 653 12.2 Public Area Structures ........................................................................................................... 126 654 12.2.1 655 Description .................................................................................................................. 126 656 12.2.2 657 TPMI_ALG_PUBLIC ................................................................................................... 126 658 12.2.3 659 Type-Specific Parameters ........................................................................................... 126 660 12.2.3.1 661 Description .......................................................................................................... 126 662 12.2.3.2 663 TPMU_PUBLIC_ID .............................................................................................. 127 664 12.2.3.3 665 TPMS_KEYEDHASH_PARMS ........................................................................... 127 666 12.2.3.4 667 TPMS_ASYM_PARMS ....................................................................................... 127 668 12.2.3.5 669 TPMS_RSA_PARMS .......................................................................................... 128 670 12.2.3.6 671 TPMS_ECC_PARMS .......................................................................................... 129 672 12.2.3.7 673 TPMU_PUBLIC_PARMS .................................................................................... 129 674 12.2.3.8 675 TPMT_PUBLIC_PARMS ..................................................................................... 130 676 12.2.4 677 TPMT_PUBLIC ........................................................................................................... 130 678 12.2.5 679 TPM2B_PUBLIC ......................................................................................................... 131 680 12.3 Private Area Structures ......................................................................................................... 131 681 12.3.1 682 Introduction.................................................................................................................. 131 683 12.3.2 684 Sensitive Data Structures ............................................................................................ 131 685 12.3.2.1 686 Introduction .......................................................................................................... 131 687 12.3.2.2 688 TPM2B_PRIVATE_VENDOR_SPECIFIC ........................................................... 131 689 12.3.2.3 690 TPMU_SENSITIVE_COMPOSITE ...................................................................... 132 691 12.3.2.4 692 TPMT_SENSITIVE .............................................................................................. 132 693 12.3.3 694 TPM2B_SENSITIVE ................................................................................................... 132 695 12.3.4 696 Encryption ................................................................................................................... 133 697 12.3.5 698 Integrity........................................................................................................................ 133 699 12.3.6 700 _PRIVATE ................................................................................................................... 133 701 12.3.7 702 TPM2B_PRIVATE ....................................................................................................... 133 703 12.4 Identity Object ........................................................................................................................ 134 704 12.4.1 705 Description .................................................................................................................. 134 706 12.4.2 707 _ID_OBJECT .............................................................................................................. 134 708 12.4.3 709 TPM2B_ID_OBJECT .................................................................................................. 134 710 13 711 712 NV Storage Structures ...................................................................................................................... 135 713 13.1 TPM_NV_INDEX ................................................................................................................... 135 714 13.2 TPMA_NV (NV Index Attributes) ........................................................................................... 136 715 13.3 TPMS_NV_PUBLIC ............................................................................................................... 139 716 13.4 TPM2B_NV_PUBLIC ............................................................................................................. 139 717 718 14 719 720 Context Data ..................................................................................................................................... 140 721 14.1 Introduction ............................................................................................................................ 140 722 14.2 TPM2B_CONTEXT_SENSITIVE........................................................................................... 140 723 14.3 TPMS_CONTEXT_DATA ...................................................................................................... 140 724 14.4 TPM2B_CONTEXT_DATA .................................................................................................... 140 725 14.5 TPMS_CONTEXT ................................................................................................................. 141 726 14.6 Parameters of TPMS_CONTEXT .......................................................................................... 142 727 14.6.1 728 sequence ..................................................................................................................... 142 729 14.6.2 730 savedHandle ............................................................................................................... 142 731 14.6.3 732 hierarchy...................................................................................................................... 143 733 14.7 Context Protection ................................................................................................................. 143 734 14.7.1 735 Context Integrity .......................................................................................................... 143 736 14.7.2 737 Context Confidentiality ................................................................................................ 143 738 739 15 740 741 Creation Data .................................................................................................................................... 144 742 15.1 TPMS_CREATION_DATA .................................................................................................... 144 743 15.2 TPM2B_CREATION_DATA .................................................................................................. 144 744 745 Page viii 746 October 31, 2013 747 748 Published 749 Copyright TCG 2006-2013 750 751 Family 2.0 752 Level 00 Revision 00.99 753 754 Trusted Platform Module Library 756 757 Part 2: Structures 758 759 Annex A (informative) Algorithm Constants ............................................................................................. 145 760 A.1 761 Introduction ............................................................................................................................ 145 762 A.2 763 Allowed Hash Algorithms....................................................................................................... 145 764 A.2.1 765 SHA1 ........................................................................................................................... 145 766 A.2.2 767 SHA256 ....................................................................................................................... 145 768 A.2.3 769 SHA384 ....................................................................................................................... 145 770 A.2.4 771 SHA512 ....................................................................................................................... 146 772 A.2.5 773 SM3_256 ..................................................................................................................... 146 774 A.3 775 Architectural Limits ................................................................................................................ 146 776 Annex B (informative) Implementation Definitions ................................................................................... 147 777 B.1 778 Introduction ............................................................................................................................ 147 779 B.2 780 Logic Values .......................................................................................................................... 147 781 B.3 782 Processor Values .................................................................................................................. 147 783 B.4 784 Implemented Algorithms ........................................................................................................ 148 785 B.5 786 Implemented Commands ...................................................................................................... 148 787 B.6 788 Algorithm Constants .............................................................................................................. 151 789 B.6.1 790 RSA ............................................................................................................................. 152 791 B.6.2 792 ECC ............................................................................................................................. 152 793 B.6.3 794 AES ............................................................................................................................. 152 795 B.6.4 796 SM4 ............................................................................................................................. 152 797 B.6.5 798 Symmetric ................................................................................................................... 153 799 B.7 800 Implementation Specific Values ............................................................................................ 154 801 802 Family 2.0 803 Level 00 Revision 00.99 804 805 Published 806 Copyright TCG 2006-2013 807 808 Page ix 809 October 31, 2013 810 811 Part 2: Structures 813 814 Trusted Platform Module Library 815 816 Tables 817 Table 1 Name Prefix Convention ........................................................................................................... 15 818 Table 2 Unmarshaling Errors ................................................................................................................. 16 819 Table 3 Definition of Base Types ........................................................................................................... 17 820 Table 4 Definition of Types for Documentation Clarity ........................................................................... 17 821 Table 5 Definition of (UINT32) TPM_SPEC Constants <> ..................................................................... 18 822 Table 6 Definition of (UINT32) TPM_GENERATED Constants <O> ..................................................... 18 823 Table 7 Definition of (UINT16) TPM_ALG_ID Constants <IN/OUT, S> ................................................. 19 824 Table 8 Definition of (UINT16) {ECC} TPM_ECC_CURVE Constants <IN/OUT, S> ............................ 22 825 Table 9 TPM Command Format Fields Description ............................................................................... 22 826 Table 10 Legend for Command Code Tables ........................................................................................ 23 827 Table 11 Definition of (UINT32) TPM_CC Constants (Numeric Order) <IN/OUT, S> ........................... 24 828 Table 12 Format-Zero Response Codes ................................................................................................ 30 829 Table 13 Format-One Response Codes ................................................................................................ 31 830 Table 14 Response Code Groupings ..................................................................................................... 31 831 Table 15 Definition of (UINT32) TPM_RC Constants (Actions) <OUT> ................................................ 32 832 Table 16 Definition of (INT8) TPM_CLOCK_ADJUST Constants <IN> ................................................. 37 833 Table 17 Definition of (UINT16) TPM_EO Constants <IN/OUT> ........................................................... 37 834 Table 18 Definition of (UINT16) TPM_ST Constants <IN/OUT, S> ....................................................... 38 835 Table 19 Definition of (UINT16) TPM_SU Constants <IN> .................................................................... 40 836 Table 20 Definition of (UINT8) TPM_SE Constants <IN> ...................................................................... 40 837 Table 21 Definition of (UINT32) TPM_CAP Constants .......................................................................... 41 838 Table 22 Definition of (UINT32) TPM_PT Constants <IN/OUT, S> ....................................................... 41 839 Table 23 Definition of (UINT32) TPM_PT_PCR Constants <IN/OUT, S> ............................................. 47 840 Table 24 Definition of (UINT32) TPM_PS Constants <OUT> ................................................................ 49 841 Table 25 Definition of Types for Handles ............................................................................................... 50 842 Table 26 Definition of (UINT8) TPM_HT Constants <S> ....................................................................... 50 843 Table 27 Definition of (UINT32) TPM_RH Constants <IN, S> ............................................................... 52 844 Table 28 Definition of (TPM_HANDLE) TPM_HC Constants <IN, S> ................................................... 54 845 Table 29 Definition of (UINT32) TPMA_ALGORITHM Bits .................................................................... 55 846 Table 30 Definition of (UINT32) TPMA_OBJECT Bits ........................................................................... 56 847 Table 31 Definition of (UINT8) TPMA_SESSION Bits <IN/OUT> .......................................................... 62 848 Table 32 Definition of (UINT8) TPMA_LOCALITY Bits <IN/OUT> ........................................................ 64 849 Table 33 Definition of (UINT32) TPMA_PERMANENT Bits <OUT> ...................................................... 64 850 Table 34 Definition of (UINT32) TPMA_STARTUP_CLEAR Bits <OUT> .............................................. 65 851 Table 35 Definition of (UINT32) TPMA_MEMORY Bits <Out> .............................................................. 66 852 Table 36 Definition of (TPM_CC) TPMA_CC Bits <OUT> ..................................................................... 67 853 Table 37 Definition of (BYTE) TPMI_YES_NO Type ............................................................................. 70 854 855 Page x 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 2: Structures 868 869 Table 38 Definition of (TPM_HANDLE) TPMI_DH_OBJECT Type........................................................ 70 870 Table 39 Definition of (TPM_HANDLE) TPMI_DH_PERSISTENT Type ............................................... 71 871 Table 40 Definition of (TPM_HANDLE) TPMI_DH_ENTITY Type <IN> ................................................ 71 872 Table 41 Definition of (TPM_HANDLE) TPMI_DH_PCR Type <IN> ..................................................... 72 873 Table 42 Definition of (TPM_HANDLE) TPMI_SH_AUTH_SESSION Type <IN/OUT> ........................ 72 874 Table 43 Definition of (TPM_HANDLE) TPMI_SH_HMAC Type <IN/OUT> .......................................... 72 875 Table 44 Definition of (TPM_HANDLE) TPMI_SH_POLICY Type <IN/OUT> ....................................... 72 876 Table 45 Definition of (TPM_HANDLE) TPMI_DH_CONTEXT Type .................................................... 73 877 Table 46 Definition of (TPM_HANDLE) TPMI_RH_HIERARCHY Type ................................................ 73 878 Table 47 Definition of (TPM_HANDLE) TPMI_RH_ENABLES Type ..................................................... 73 879 Table 48 Definition of (TPM_HANDLE) TPMI_RH_HIERARCHY_AUTH Type <IN> ............................ 74 880 Table 49 Definition of (TPM_HANDLE) TPMI_RH_PLATFORM Type <IN> ......................................... 74 881 Table 50 Definition of (TPM_HANDLE) TPMI_RH_OWNER Type <IN> ............................................... 74 882 Table 51 Definition of (TPM_HANDLE) TPMI_RH_ENDORSEMENT Type <IN> ................................. 75 883 Table 52 Definition of (TPM_HANDLE) TPMI_RH_PROVISION Type <IN> ......................................... 75 884 Table 53 Definition of (TPM_HANDLE) TPMI_RH_CLEAR Type <IN> ................................................. 75 885 Table 54 Definition of (TPM_HANDLE) TPMI_RH_NV_AUTH Type <IN> ............................................ 76 886 Table 55 Definition of (TPM_HANDLE) TPMI_RH_LOCKOUT Type <IN> ........................................... 76 887 Table 56 Definition of (TPM_HANDLE) TPMI_RH_NV_INDEX Type <IN/OUT> .................................. 76 888 Table 57 Definition of (TPM_ALG_ID) TPMI_ALG_HASH Type............................................................ 77 889 Table 58 Definition of (TPM_ALG_ID) TPMI_ALG_ASYM Type ........................................................... 77 890 Table 59 Definition of (TPM_ALG_ID) TPMI_ALG_SYM Type .............................................................. 78 891 Table 60 Definition of (TPM_ALG_ID) TPMI_ALG_SYM_OBJECT Type ............................................. 78 892 Table 61 Definition of (TPM_ALG_ID) TPMI_ALG_SYM_MODE Type ................................................. 79 893 Table 62 Definition of (TPM_ALG_ID) TPMI_ALG_KDF Type .............................................................. 79 894 Table 63 Definition of (TPM_ALG_ID) TPMI_ALG_SIG_SCHEME Type .............................................. 80 895 Table 64 Definition of (TPM_ALG_ID) TPMI_ECC_KEY_EXCHANGE Type ........................................ 80 896 Table 65 Definition of (TPM_ST) TPMI_ST_COMMAND_TAG Type .................................................... 80 897 Table 66 Definition of TPMS_ALGORITHM_DESCRIPTION Structure <OUT> .................................... 81 898 Table 67 Definition of TPMU_HA Union <IN/OUT, S> ........................................................................... 81 899 Table 68 Definition of TPMT_HA Structure <IN/OUT> .......................................................................... 82 900 Table 69 Definition of TPM2B_DIGEST Structure ................................................................................. 83 901 Table 70 Definition of TPM2B_DATA Structure ..................................................................................... 83 902 Table 71 Definition of Types for TPM2B_NONCE ................................................................................. 83 903 Table 72 Definition of Types for TPM2B_AUTH .................................................................................... 83 904 Table 73 Definition of Types for TPM2B_OPERAND ............................................................................ 84 905 Table 74 Definition of TPM2B_EVENT Structure ................................................................................... 84 906 Table 75 Definition of TPM2B_MAX_BUFFER Structure ...................................................................... 84 907 908 Family 2.0 909 Level 00 Revision 00.99 910 911 Published 912 Copyright TCG 2006-2013 913 914 Page xi 915 October 31, 2013 916 917 Part 2: Structures 919 920 Trusted Platform Module Library 921 922 Table 76 Definition of TPM2B_MAX_NV_BUFFER Structure ............................................................... 84 923 Table 77 Definition of TPM2B_TIMEOUT Structure <IN/OUT> ............................................................. 85 924 Table 78 Definition of TPM2B_IV Structure <IN/OUT> .......................................................................... 85 925 Table 79 Definition of TPMU_NAME Union <> ...................................................................................... 85 926 Table 80 Definition of TPM2B_NAME Structure .................................................................................... 86 927 Table 81 Definition of TPMS_PCR_SELECT Structure ......................................................................... 87 928 Table 82 Definition of TPMS_PCR_SELECTION Structure ................................................................... 87 929 Table 83 Values for proof Used in Tickets ............................................................................................. 88 930 Table 84 General Format of a Ticket ...................................................................................................... 88 931 Table 85 Definition of TPMT_TK_CREATION Structure ........................................................................ 89 932 Table 86 Definition of TPMT_TK_VERIFIED Structure .......................................................................... 90 933 Table 87 Definition of TPMT_TK_AUTH Structure ................................................................................ 91 934 Table 88 Definition of TPMT_TK_HASHCHECK Structure .................................................................... 92 935 Table 89 Definition of TPMS_ALG_PROPERTY Structure <OUT> ....................................................... 92 936 Table 90 Definition of TPMS_TAGGED_PROPERTY Structure <OUT> ............................................... 92 937 Table 91 Definition of TPMS_TAGGED_PCR_SELECT Structure <OUT> ........................................... 93 938 Table 92 Definition of TPML_CC Structure ............................................................................................ 93 939 Table 93 Definition of TPML_CCA Structure <OUT> ............................................................................. 94 940 Table 94 Definition of TPML_ALG Structure .......................................................................................... 94 941 Table 95 Definition of TPML_HANDLE Structure <OUT>...................................................................... 94 942 Table 96 Definition of TPML_DIGEST Structure .................................................................................... 95 943 Table 97 Definition of TPML_DIGEST_VALUES Structure ................................................................... 95 944 Table 98 Definition of TPM2B_DIGEST_VALUES Structure ................................................................. 95 945 Table 99 Definition of TPML_PCR_SELECTION Structure ................................................................... 96 946 Table 100 Definition of TPML_ALG_PROPERTY Structure <OUT> ..................................................... 96 947 Table 101 Definition of TPML_TAGGED_TPM_PROPERTY Structure <OUT> ................................... 96 948 Table 102 Definition of TPML_TAGGED_PCR_PROPERTY Structure <OUT> ................................... 97 949 Table 103 Definition of {ECC} TPML_ECC_CURVE Structure <OUT> ................................................. 97 950 Table 104 Definition of TPMU_CAPABILITIES Union <OUT>............................................................... 97 951 Table 105 Definition of TPMS_CAPABILITY_DATA Structure <OUT> ................................................. 98 952 Table 106 Definition of TPMS_CLOCK_INFO Structure ........................................................................ 98 953 Table 107 Definition of TPMS_TIME_INFO Structure ........................................................................... 99 954 Table 108 Definition of TPMS_TIME_ATTEST_INFO Structure <OUT> ............................................. 100 955 Table 109 Definition of TPMS_CERTIFY_INFO Structure <OUT> ...................................................... 100 956 Table 110 Definition of TPMS_QUOTE_INFO Structure <OUT> ........................................................ 100 957 Table 111 Definition of TPMS_COMMAND_AUDIT_INFO Structure <OUT> ..................................... 101 958 Table 112 Definition of TPMS_SESSION_AUDIT_INFO Structure <OUT> ........................................ 101 959 Table 113 Definition of TPMS_CREATION_INFO Structure <OUT> .................................................. 101 960 Table 114 Definition of TPMS_NV_CERTIFY_INFO Structure <OUT> ............................................... 101 961 Page xii 962 October 31, 2013 963 964 Published 965 Copyright TCG 2006-2013 966 967 Family 2.0 968 Level 00 Revision 00.99 969 970 Trusted Platform Module Library 972 973 Part 2: Structures 974 975 Table 115 Definition of (TPM_ST) TPMI_ST_ATTEST Type <OUT> .................................................. 102 976 Table 116 Definition of TPMU_ATTEST Union <OUT> ....................................................................... 102 977 Table 117 Definition of TPMS_ATTEST Structure <OUT> .................................................................. 103 978 Table 118 Definition of TPM2B_ATTEST Structure <OUT> ................................................................ 103 979 Table 119 Definition of TPMS_AUTH_COMMAND Structure <IN> ..................................................... 104 980 Table 120 Definition of TPMS_AUTH_RESPONSE Structure <OUT> ................................................ 104 981 Table 121 Definition of {AES} (TPM_KEY_BITS) TPMI_AES_KEY_BITS Type ................................. 105 982 Table 122 Definition of {SM4} (TPM_KEY_BITS) TPMI_SM4_KEY_BITS Type ................................. 105 983 Table 123 Definition of TPMU_SYM_KEY_BITS Union ....................................................................... 106 984 Table 124 Definition of TPMU_SYM_MODE Union ............................................................................. 106 985 Table 125 xDefinition of TPMU_SYM_DETAILS Union ....................................................................... 107 986 Table 126 Definition of TPMT_SYM_DEF Structure ............................................................................ 107 987 Table 127 Definition of TPMT_SYM_DEF_OBJECT Structure ............................................................ 107 988 Table 128 Definition of TPM2B_SYM_KEY Structure .......................................................................... 108 989 Table 129 Definition of TPMS_SYMCIPHER_PARMS Structure ........................................................ 108 990 Table 130 Definition of TPM2B_SENSITIVE_DATA Structure ............................................................ 108 991 Table 131 Definition of TPMS_SENSITIVE_CREATE Structure <IN> ................................................ 109 992 Table 132 Definition of TPM2B_SENSITIVE_CREATE Structure <IN, S> .......................................... 110 993 Table 133 Definition of TPMS_SCHEME_SIGHASH Structure ........................................................... 110 994 Table 134 Definition of (TPM_ALG_ID) TPMI_ALG_KEYEDHASH_SCHEME Type .......................... 110 995 Table 135 Definition of Types for HMAC_SIG_SCHEME .................................................................... 110 996 Table 136 Definition of TPMS_SCHEME_XOR Structure ................................................................... 111 997 Table 137 Definition of TPMU_SCHEME_KEYEDHASH Union <IN/OUT, S> .................................... 111 998 Table 138 Definition of TPMT_KEYEDHASH_SCHEME Structure ..................................................... 111 999 Table 139 Definition of {RSA} Types for RSA_SIG_SCHEMES .......................................................... 112 1000 Table 140 Definition of {ECC} Types for ECC_SIG_SCHEMES.......................................................... 112 1001 Table 141 Definition of {ECC} TPMS_SCHEME_ECDAA Structure .................................................... 112 1002 Table 142 Definition of TPMU_SIG_SCHEME Union <IN/OUT, S> .................................................... 113 1003 Table 143 Definition of TPMT_SIG_SCHEME Structure ..................................................................... 113 1004 Table 144 Definition of {RSA} TPMS_SCHEME_OAEP Structure ...................................................... 114 1005 Table 145 Definition of {ECC} TPMS_SCHEME_ECDH Structure ...................................................... 114 1006 Table 146 Definition of TPMS_SCHEME_MGF1 Structure ................................................................. 114 1007 Table 147 Definition of {ECC} TPMS_SCHEME_KDF1_SP800_56a Structure .................................. 114 1008 Table 148 Definition of TPMS_SCHEME_KDF2 Structure .................................................................. 115 1009 Table 149 Definition of TPMS_SCHEME_KDF1_SP800_108 Structure ............................................. 115 1010 Table 150 Definition of TPMU_KDF_SCHEME Union <IN/OUT, S> ................................................... 115 1011 Table 151 Definition of TPMT_KDF_SCHEME Structure .................................................................... 115 1012 Table 152 Definition of (TPM_ALG_ID) TPMI_ALG_ASYM_SCHEME Type <> ................................. 116 1013 1014 Family 2.0 1015 Level 00 Revision 00.99 1016 1017 Published 1018 Copyright TCG 2006-2013 1019 1020 Page xiii 1021 October 31, 2013 1022 1023 Part 2: Structures 1025 1026 Trusted Platform Module Library 1027 1028 Table 153 Definition of TPMU_ASYM_SCHEME Union ...................................................................... 116 1029 Table 154 Definition of TPMT_ASYM_SCHEME Structure <> ............................................................ 117 1030 Table 155 Definition of (TPM_ALG_ID) {RSA} TPMI_ALG_RSA_SCHEME Type .............................. 117 1031 Table 156 Definition of {RSA} TPMT_RSA_SCHEME Structure ......................................................... 117 1032 Table 157 Definition of (TPM_ALG_ID) {RSA} TPMI_ALG_RSA_DECRYPT Type ............................ 118 1033 Table 158 Definition of {RSA} TPMT_RSA_DECRYPT Structure ....................................................... 118 1034 Table 159 Definition of {RSA} TPM2B_PUBLIC_KEY_RSA Structure ................................................ 118 1035 Table 160 Definition of {RSA} (TPM_KEY_BITS) TPMI_RSA_KEY_BITS Type ................................. 119 1036 Table 161 Definition of {RSA} TPM2B_PRIVATE_KEY_RSA Structure .............................................. 119 1037 Table 162 Definition of {ECC} TPM2B_ECC_PARAMETER Structure ............................................... 120 1038 Table 163 Definition of {ECC} TPMS_ECC_POINT Structure ............................................................. 120 1039 Table 164 Definition of {ECC} TPM2B_ECC_POINT Structure ........................................................... 120 1040 Table 165 Definition of (TPM_ALG_ID) {ECC} TPMI_ALG_ECC_SCHEME Type ............................. 121 1041 Table 166 Definition of {ECC} (TPM_ECC_CURVE) TPMI_ECC_CURVE Type ................................ 121 1042 Table 167 Definition of (TPMT_SIG_SCHEME) {ECC} TPMT_ECC_SCHEME Structure .................. 121 1043 Table 168 Definition of {ECC} TPMS_ALGORITHM_DETAIL_ECC Structure <OUT> ....................... 122 1044 Table 169 Definition of {RSA} TPMS_SIGNATURE_RSASSA Structure ............................................ 122 1045 Table 170 Definition of {RSA} TPMS_SIGNATURE_RSAPSS Structure ............................................ 123 1046 Table 171 Definition of {ECC} TPMS_SIGNATURE_ECDSA Structure .............................................. 123 1047 Table 172 Definition of TPMU_SIGNATURE Union <IN/OUT, S> ....................................................... 123 1048 Table 173 Definition of TPMT_SIGNATURE Structure ........................................................................ 124 1049 Table 174 Definition of TPMU_ENCRYPTED_SECRET Union <S> ................................................... 124 1050 Table 175 Definition of TPM2B_ENCRYPTED_SECRET Structure .................................................... 125 1051 Table 176 Definition of (TPM_ALG_ID) TPMI_ALG_PUBLIC Type .................................................... 126 1052 Table 177 Definition of TPMU_PUBLIC_ID Union <IN/OUT, S> ......................................................... 127 1053 Table 178 Definition of TPMS_KEYEDHASH_PARMS Structure........................................................ 127 1054 Table 179 Definition of TPMS_ASYM_PARMS Structure <> .............................................................. 128 1055 Table 180 Definition of {RSA} TPMS_RSA_PARMS Structure ............................................................ 128 1056 Table 181 Definition of {ECC} TPMS_ECC_PARMS Structure ........................................................... 129 1057 Table 182 Definition of TPMU_PUBLIC_PARMS Union <IN/OUT, S> ................................................ 129 1058 Table 183 Definition of TPMT_PUBLIC_PARMS Structure ................................................................. 130 1059 Table 184 Definition of TPMT_PUBLIC Structure ................................................................................ 130 1060 Table 185 Definition of TPM2B_PUBLIC Structure .............................................................................. 131 1061 Table 186 Definition of {RSA} TPM2B_PRIVATE_VENDOR_SPECIFIC Structure<> ........................ 131 1062 Table 187 Definition of TPMU_SENSITIVE_COMPOSITE Union <IN/OUT, S> ................................. 132 1063 Table 188 Definition of TPMT_SENSITIVE Structure .......................................................................... 132 1064 Table 189 Definition of TPM2B_SENSITIVE Structure <IN/OUT> ...................................................... 132 1065 Table 190 Definition of _PRIVATE Structure <> .................................................................................. 133 1066 Table 191 Definition of TPM2B_PRIVATE Structure <IN/OUT, S> ..................................................... 133 1067 Page xiv 1068 October 31, 2013 1069 1070 Published 1071 Copyright TCG 2006-2013 1072 1073 Family 2.0 1074 Level 00 Revision 00.99 1075 1076 Trusted Platform Module Library 1078 1079 Part 2: Structures 1080 1081 Table 192 Definition of _ID_OBJECT Structure <> .............................................................................. 134 1082 Table 193 Definition of TPM2B_ID_OBJECT Structure <IN/OUT> ..................................................... 134 1083 Table 194 Definition of (UINT32) TPM_NV_INDEX Bits <> ................................................................. 135 1084 Table 195 Options for space Field of TPM_NV_INDEX ....................................................................... 136 1085 Table 196 Definition of (UINT32) TPMA_NV Bits ................................................................................ 137 1086 Table 197 Definition of TPMS_NV_PUBLIC Structure ......................................................................... 139 1087 Table 198 Definition of TPM2B_NV_PUBLIC Structure ....................................................................... 139 1088 Table 199 Definition of TPM2B_CONTEXT_SENSITIVE Structure <IN/OUT> ................................... 140 1089 Table 200 Definition of TPMS_CONTEXT_DATA Structure <IN/OUT, S> .......................................... 140 1090 Table 201 Definition of TPM2B_CONTEXT_DATA Structure <IN/OUT> ............................................ 140 1091 Table 202 Definition of TPMS_CONTEXT Structure ........................................................................... 141 1092 Table 203 Context Handle Values ........................................................................................................ 142 1093 Table 204 Definition of TPMS_CREATION_DATA Structure <OUT> ................................................. 144 1094 Table 205 Definition of TPM2B_CREATION_DATA Structure <OUT> ............................................... 144 1095 Table 206 Defines for SHA1 Hash Values ........................................................................................... 145 1096 Table 207 Defines for SHA256 Hash Values ....................................................................................... 145 1097 Table 208 Defines for SHA384 Hash Values ....................................................................................... 145 1098 Table 209 Defines for SHA512 Hash Values ....................................................................................... 146 1099 Table 210 Defines for SM3_256 Hash Values ..................................................................................... 146 1100 Table 211 Defines for Architectural Limits Values ............................................................................... 146 1101 Table 212 Defines for Logic Values ..................................................................................................... 147 1102 Table 213 Defines for Processor Values .............................................................................................. 147 1103 Table 214 Defines for Implemented Algorithms ................................................................................... 148 1104 Table 215 Defines for Implemented Commands .................................................................................. 149 1105 Table 216 Defines for RSA Algorithm Constants ................................................................................. 152 1106 Table 217 Defines for ECC Algorithm Constants ................................................................................. 152 1107 Table 218 Defines for AES Algorithm Constants ................................................................................. 152 1108 Table 219 Defines for SM4 Algorithm Constants ................................................................................. 152 1109 Table 220 Defines for Symmetric Algorithm Constants ....................................................................... 153 1110 Table 221 Defines for Implementation Values ..................................................................................... 154 1111 1112 Family 2.0 1113 Level 00 Revision 00.99 1114 1115 Published 1116 Copyright TCG 2006-2013 1117 1118 Page xv 1119 October 31, 2013 1120 1121 Part 2: Structures 1123 1124 Trusted Platform Module Library 1125 1126 Figures 1127 Figure 1 Command Format .................................................................................................................... 22 1128 Figure 2 Format-Zero Response Codes ................................................................................................. 29 1129 Figure 3 Format-One Response Codes ................................................................................................. 30 1130 Figure 4 TPM 1.2 TPM_NV_INDEX ..................................................................................................... 135 1131 Figure 5 TPM 2.0 TPM_NV_INDEX ..................................................................................................... 135 1132 1133 Page xvi 1134 October 31, 2013 1135 1136 Published 1137 Copyright TCG 2006-2013 1138 1139 Family 2.0 1140 Level 00 Revision 00.99 1141 1142 Trusted Platform Module Library 1144 1145 Part 2: Structures 1146 1147 Trusted Platform Module Library 1148 Part 2: Structures 1149 1 1150 1151 Scope 1152 1153 This part of the Trusted Platform Module Library specification contains the definitions of the constants, 1154 flags, structure, and union definitions used to communicate with the TPM. Values defined in this 1155 document are used by the TPM commands defined in part 3: Commands and by the functions in part 4: 1156 Supporting Routines. 1157 NOTE 1158 1159 2 1160 1161 The structures in this document are the canonical form of the structures on the interface. All structures 1162 are "packed" with no octets of padding between structure elements. The TPM-internal form of the 1163 structures is dependent on the processor and compiler for the TPM implementation. 1164 1165 Terms and definitions 1166 1167 For the purposes of this document, the terms and definitions given in part 1 of this specification apply. 1168 3 1169 1170 Symbols and abbreviated terms 1171 1172 For the purposes of this document, the symbols and abbreviated terms given in part 1 apply. 1173 4 1174 4.1 1175 1176 Notation 1177 Introduction 1178 1179 The information in this document is formatted so that it may be converted to standard computer-language 1180 formats by an automated process. The purpose of this automated process is to minimize the transcription 1181 errors that often occur during the conversion process. 1182 For the purposes of this document, the conventions given in Part 1 apply. 1183 In addition, the conventions and notations in this clause describe the representation of various data so 1184 that it is both human readable and amenable to automated processing. 1185 When a table row contains the keyword reserved (all lower case) in columns 1 or 2, the tools will not 1186 produce any values for the row in the table. 1187 NOTE 1 1188 1189 In the examples in this clause 4, the unmarshaling routines are shown as returning bool. In the code of 1190 the reference implementation, the return value is a TPM_RC. A bool is used in the examples, because 1191 the meaning of a TPM_RC is not yet defined. 1192 1193 NOTE 2 1194 1195 The unmarshaling code examples are the actual code that would be produced by the automatic code 1196 generator used in the construction of the reference code. The actual code contains additional parameter 1197 checking that is omitted for clarity of the principle being illustrated. Actual examples of the code are found 1198 in Part 4. 1199 1200 Family 2.0 1201 Level 00 Revision 00.99 1202 1203 Published 1204 Copyright TCG 2006-2013 1205 1206 Page 1 1207 October 31, 2013 1208 1209 Part 2: Structures 1211 4.2 1212 1213 Trusted Platform Module Library 1214 1215 Named Constants 1216 1217 A named constant is a numeric value to which a name has been assigned. In the C language, this is done 1218 with a #define statement. In this specification, a named constant is defined in a table that has a title that 1219 starts with Definition and ends with Constants. 1220 The table title will indicate the name of the class of constants that are being defined in the table. The title 1221 will include the data type of the constants in parentheses. 1222 The table in Example 1 names a collection of 16-bit constants and Example 2 shows the C code that 1223 might be produced from that table by an automated process. 1224 NOTE 1225 1226 A named constant (#define) has no data type in C and an enumeration would be a better choice for 1227 many of the defined constants. However, the C language does not allow an enumerated type to have a 1228 storage type other than int so the method of using a combination of typedef and #define is used. 1229 1230 EXAMPLE 1 1231 1232 Table xx Definition of (UINT16) COUNTING Constants 1233 Parameter 1234 1235 Value 1236 1237 Description 1238 1239 first 1240 1241 1 1242 1243 decimal value is implicitly the size of the 1244 1245 second 1246 1247 0x0002 1248 1249 hex value will match the number of bits in the constant 1250 1251 third 1252 1253 3 1254 1255 fourth 1256 1257 0x0004 1258 1259 EXAMPLE 2 1260 /* The C language equivalent of the constants from the table above */ 1261 typedef 1262 UINT16 1263 COUNTING; 1264 #define 1265 first 1266 1 1267 #define 1268 second 1269 0x0002 1270 #define 1271 third 1272 3 1273 #define 1274 fourth 1275 0x0004 1276 1277 Page 2 1278 October 31, 2013 1279 1280 Published 1281 Copyright TCG 2006-2013 1282 1283 Family 2.0 1284 Level 00 Revision 00.99 1285 1286 Trusted Platform Module Library 1288 4.3 1289 1290 Part 2: Structures 1291 1292 Data Type Aliases (typedefs) 1293 1294 When a group of named items is assigned a type, it is placed in a table that has a title starting with 1295 Definition of Types. In this specification, defined types have names that use all upper-case characters. 1296 The table in Example 1 shows how typedefs would be defined in this specification and Example 2 shows 1297 the C-compatible code that might be produced from that table by an automated process. 1298 EXAMPLE 1 1299 1300 Table xx Definition of Types for Some Purpose 1301 Type 1302 1303 Name 1304 1305 Description 1306 1307 unsigned short 1308 1309 UINT16 1310 1311 UINT16 1312 1313 SOME_TYPE 1314 1315 unsigned long 1316 1317 UINT32 1318 1319 UINT32 1320 1321 LAST_TYPE 1322 1323 EXAMPLE 2 1324 /* C language equivalent of the typedefs from the table above */ 1325 typedef unsigned short 1326 UINT16; 1327 typedef UINT16 1328 SOME_TYPE; 1329 typedef unsigned long 1330 UINT32; 1331 typedef UINT32 1332 LAST_TYPE; 1333 1334 4.4 1335 1336 Enumerations 1337 1338 A table that defines an enumerated data type will start with the word Definition and end with Values. 1339 A value in parenthesis will denote the intrinsic data size of the value and may have the values "INT8", 1340 "UINT8", "INT16", UINT16, "INT32", and UINT32. If this value is not present, UINT16 is assumed. 1341 Most C compilers set the type of an enumerated value to be an integer on the machine often 16 bits 1342 but this is not always consistent. To ensure interoperability, the enumeration values may not exceed 1343 32,384. 1344 The table in Example 1 shows how an enumeration would be defined in this specification. Example 2 1345 shows the C code that might be produced from that table by an automated process. 1346 EXAMPLE 1 1347 1348 Table xx Definition of (UINT16) CARD_SUIT Values 1349 Suit Names 1350 1351 Value 1352 1353 CLUBS 1354 1355 0x0000 1356 1357 DIAMONDS 1358 1359 0x000D 1360 1361 HEARTS 1362 1363 0x001A 1364 1365 SPADES 1366 1367 Description 1368 1369 0x0027 1370 1371 EXAMPLE 2 1372 /* C language equivalent of the structure defined in the table above */ 1373 typedef enum { 1374 CLUBS 1375 = 1376 0x0000, 1377 DIAMONDS 1378 = 1379 0x000D, 1380 HEARTS 1381 = 1382 0x001A, 1383 SPADES 1384 = 1385 0x0027 1386 } CARD_SUIT; 1387 1388 Family 2.0 1389 Level 00 Revision 00.99 1390 1391 Published 1392 Copyright TCG 2006-2013 1393 1394 Page 3 1395 October 31, 2013 1396 1397 Part 2: Structures 1399 4.5 1400 1401 Trusted Platform Module Library 1402 1403 Interface Type 1404 1405 An interface type is used for an enumeration that is checked by the unmarshaling code. This type is 1406 defined for purposes of automatic generation of the code that will validate the type. The title will start with 1407 the keyword Definition and end with the keyword Type. A value in parenthesis indicates the base type 1408 of the interface. The table may contain an entry that is prefixed with the # character to indicate the 1409 response code if the validation code determines that the input parameter is the wrong type. 1410 EXAMPLE 1 1411 1412 Table xx Definition of (CARD_SUIT) RED_SUIT Type 1413 Values 1414 1415 Comments 1416 1417 HEARTS 1418 DIAMONDS 1419 #TPM_RC_SUIT 1420 1421 response code returned when the unmarshaling of this type fails 1422 NOTE 1423 1424 TPM_RC_SUIT is an example and no such response 1425 code is actually defined in this specification. 1426 1427 EXAMPLE 2 1428 /* Validation code that might be automatically generated from table above */ 1429 if((*target != HEARTS) && (*target != DIAMONDS)) 1430 return TPM_RC_SUIT; 1431 1432 In some cases, the allowed values are numeric values with no associated mnemonic. In such a case, the 1433 list of numeric values may be given a name. Then, when used in an interface definition, the name would 1434 have a "$" prefix to indicate that a named list of values should be substituted. 1435 To illustrate, assume that the implementation only supports two sizes (1024 and 2048 bits) for keys 1436 associated with some algorithm (MY algorithm). In the implementation section (Annex B a named list 1437 would be created. 1438 EXAMPLE 3 1439 1440 Table xx Defines for MY Algorithm Constants 1441 Name 1442 1443 Value 1444 1445 Comments 1446 1447 MY_KEY_SIZES_BITS 1448 1449 {1024, 2048} 1450 1451 braces because this is a list value 1452 1453 Page 4 1454 October 31, 2013 1455 1456 Published 1457 Copyright TCG 2006-2013 1458 1459 Family 2.0 1460 Level 00 Revision 00.99 1461 1462 Trusted Platform Module Library 1464 1465 Part 2: Structures 1466 1467 Then, whenever an input value would need to be a valid MY key size for the implementation, the value 1468 $MY_KEY_SIZES_BITS could be used. Given the definition for MY_KEY_SIZES_BITS in example 3 1469 above, the tables in example 4 and 5 below, are equivalent. 1470 EXAMPLE 4 1471 1472 Table xx Definition of (UINT16) MY_KEY_BITS Type 1473 Parameter 1474 1475 Description 1476 1477 {1024, 2048} 1478 1479 the number of bits in the supported key 1480 1481 EXAMPLE 5 1482 1483 Table xx Definition of (UINT16) MY_KEY_BITS Type 1484 Parameter 1485 $MY_KEY_SIZES_BITS 1486 1487 4.6 1488 1489 Description 1490 the number of bits in the supported key 1491 1492 Arrays 1493 1494 Arrays are denoted by a value in square brackets ([ ]) following a parameter name. The value in the 1495 brackets may be either an integer value such as [20] or the name of a component of the same structure 1496 that contains the array. 1497 The table in Example 1 shows how a structure containing fixed and variable-length arrays would be 1498 defined in this specification. Example 2 shows the C code that might be produced from that table by an 1499 automated process. 1500 EXAMPLE 1 1501 1502 Table xx Definition of A_STRUCT Structure 1503 Parameter 1504 1505 Type 1506 1507 Description 1508 1509 array1[20] 1510 1511 UINT16 1512 1513 an array of 20 UINT16s 1514 1515 a_size 1516 1517 UINT16 1518 1519 array2[a_size] 1520 1521 UINT32 1522 1523 an array of UINT32 values that has a 1524 number of elements determined by a_size 1525 above 1526 1527 EXAMPLE 2 1528 /* C language equivalent of the typedefs from the table above */ 1529 typedef struct { 1530 UINT16 1531 array1[20]; 1532 UINT16 1533 a_size; 1534 UINT32 1535 array2[]; 1536 } A_STRUCT; 1537 1538 Family 2.0 1539 Level 00 Revision 00.99 1540 1541 Published 1542 Copyright TCG 2006-2013 1543 1544 Page 5 1545 October 31, 2013 1546 1547 Part 2: Structures 1549 1550 4.7 1551 1552 Trusted Platform Module Library 1553 1554 Structure Definitions 1555 1556 The tables used to define structures have a title that starts with the word Definition and ends with 1557 Structure. The first column of the table will denote the reference names for the structure members; the 1558 second column the data type of the member; and the third column a synopsis of the use of the element. 1559 The table in Example 1 shows an example of how a structure would be defined in this specification and 1560 Example 2 shows the C code that might be produced from the table by an automated process. Example 3 1561 illustrates the type of unmarshaling code that could be generated using the information available in the 1562 table. 1563 EXAMPLE 1 1564 1565 Table xx Definition of SIMPLE_STRUCTURE Structure 1566 Parameter 1567 1568 Type 1569 1570 Description 1571 1572 tag 1573 1574 TPM_ST 1575 1576 value1 1577 1578 INT32 1579 1580 value2 1581 1582 INT32 1583 1584 EXAMPLE 2 1585 /* C language equivalent of the structure defined in the table above */ 1586 typedef struct { 1587 TPM_ST 1588 tag; 1589 INT32 1590 value1 1591 INT32 1592 value2; 1593 } SIMPLE_STRUCTURE; 1594 EXAMPLE 3 1595 bool SIMPLE_STRUCTURE_Unmarshal(SIMPLE_STRUCTURE *target, BYTE **buffer, INT32 *size) 1596 { 1597 // If unmarshal of tag succeeds 1598 if(TPM_ST_Unmarshal((TPM_ST *)&(target->tag), buffer, size)) 1599 // then umarshal value1, and if that succeeds... 1600 if(INT32_Unmarshal((INT32 *)&(target->value1, buffer, size)) 1601 // then return the results of unmarshaling values 1602 return(INT32_Unmarshal((INT32 *)&(target->value2, buffer, size)) 1603 // if unmarshal of tag or value failed, return failure 1604 return FALSE; 1605 } 1606 1607 Page 6 1608 October 31, 2013 1609 1610 Published 1611 Copyright TCG 2006-2013 1612 1613 Family 2.0 1614 Level 00 Revision 00.99 1615 1616 Trusted Platform Module Library 1618 4.8 1619 1620 Part 2: Structures 1621 1622 Conditional Types 1623 1624 An enumeration may contain an extended value indicated by + preceding the name in the "Value" 1625 column. This + indicates that this is a conditional value that may be allowed in certain situations. 1626 NOTE 1627 1628 In many cases, the input values are algorithm IDs. When two collections of algorithm IDs differ only 1629 because one collection allows TPM_ALG_NULL and the other does not, it is preferred that the re not be 1630 two completely different enumerations because this leads to many casts. To avoid this, the + can be 1631 added to a TPM_ALG_NULL value in the table defining the type. When the use of that type allows 1632 TPM_ALG_NULL to be in the set, the use would append a + to the instance. 1633 1634 EXAMPLE 1635 1636 Table xx Definition of (CARD_SUIT) TPMI_CARD_SUIT Type 1637 Values 1638 1639 Comments 1640 1641 SPADES 1642 HEARTS 1643 DIAMONDS 1644 CLUBS 1645 +JOKER 1646 1647 an optional value that may be allowed 1648 1649 #TPM_RC_SUIT 1650 1651 response code returned when the input value is not one of the 1652 values above 1653 1654 When an interface type is used, a + will be appended to the type specification for the parameter when 1655 the conditional value is allowed. If no + is present, then the conditional value is not allowed. 1656 EXAMPLE 1 1657 1658 Table xx Definition of POKER_CARD Structure 1659 Parameter 1660 1661 Type 1662 1663 Description 1664 1665 suit 1666 1667 TPMI_CARD_SUIT+ 1668 1669 allows joker 1670 1671 number 1672 1673 UINT8 1674 1675 the card value 1676 1677 EXAMPLE 2 1678 1679 Table xx Definition of BRIDGE_CARD Structure 1680 Parameter 1681 1682 Type 1683 1684 Description 1685 1686 suit 1687 1688 TPMI_CARD_SUIT 1689 1690 does not allow joker 1691 1692 number 1693 1694 UINT8 1695 1696 the card value 1697 1698 Family 2.0 1699 Level 00 Revision 00.99 1700 1701 Published 1702 Copyright TCG 2006-2013 1703 1704 Page 7 1705 October 31, 2013 1706 1707 Part 2: Structures 1709 4.9 1710 1711 Trusted Platform Module Library 1712 1713 Unions 1714 1715 4.9.1 1716 1717 Introduction 1718 1719 A union allows a structure to contain a variety of structures or types. The union has members, only one of 1720 which is present at a time. Three different tables are required to fully characterize a union so that it may 1721 be communicated on the TPM interface and used by the TPM: 1722 1) union definition; 1723 2) union instance; and 1724 3) union selector definition. 1725 4.9.2 1726 1727 Union Definition 1728 1729 The table in Example 1 illustrates a union definition. The title of a union definition table starts with 1730 Definition and ends with Union. The Parameter column of a union definition lists the different names 1731 that are used when referring a specific type. The Type column identifies the data type of the member. 1732 The Selector column identifies the value that is used by the marshaling and unmarshaling code to 1733 determine which case of the union is present. 1734 If a parameter is the keyword null, then this denotes a selector with no contents. The table in Example 1 1735 illustrates a union in which a conditional null selector is allowed to indicate an empty union member. 1736 Example 2 shows how the table would be converted into C-compatible code. 1737 The expectation is that the unmarshaling code for the union will validate that the selector for the union is 1738 one of values in the selector list. 1739 EXAMPLE 1 1740 1741 Table xx Definition of NUMBER_UNION Union 1742 Parameter 1743 1744 Type 1745 1746 Selector 1747 1748 a_byte 1749 1750 BYTE 1751 1752 BYTE_SELECT 1753 1754 an_int 1755 1756 int 1757 1758 INT_SELECT 1759 1760 a_float 1761 1762 float 1763 1764 FLOAT_SELECT 1765 1766 +null 1767 1768 NULL_SELECT 1769 1770 Description 1771 1772 the empty branch 1773 1774 EXAMPLE 2 1775 // C-compatible version of the union defined in the table above 1776 typedef union { 1777 BYTE 1778 a_byte; 1779 int 1780 an_int; 1781 float 1782 a_float; 1783 } NUMBER_UNION; 1784 EXAMPLE 3 1785 1786 Page 8 1787 October 31, 2013 1788 1789 Published 1790 Copyright TCG 2006-2013 1791 1792 Family 2.0 1793 Level 00 Revision 00.99 1794 1795 Trusted Platform Module Library 1797 1798 Part 2: Structures 1799 1800 // Possible auto-generated code to unmarshal a union in Example 2 based on the 1801 // input value of selector 1802 bool NUMBER_UNION_Unmarshal(NUMBER_UNION *target, BYTE **buffer, 1803 INT32 *size, UINT32 selector) 1804 { 1805 switch (selector) { 1806 case BYTE_SELECT: 1807 return BYTE_Unmarshal((BYTE *)&(target->a_byte), buffer, size); 1808 case INT_SELECT: 1809 return INT_Unmarshal((int *)&(target->an_int), buffer, size); 1810 case FLOAT_SELECT: 1811 return FLOAT_Unmarshal((float *)&(target->a_float), buffer, size); 1812 case NULL_SELECT: 1813 return; 1814 } 1815 1816 A table may have a type with no selector. This is used when the first part of the structure for all union 1817 members is identical. This type is a programming convenience, allowing code to reference the common 1818 members without requiring a case statement to determine the specific structure. In object oriented 1819 programming terms, this type is a superclass and the types with selectors are subclasses. 1820 4.9.3 1821 1822 Union Instance 1823 1824 When a union is used in a structure that is sent on the interface, the structure will minimally contain a 1825 selector and a union. The selector value indicates which of the possible union members is present so that 1826 the unmarshaling code can unmarshal the correct type. The selector may be any of the parameters that 1827 occur in the structure before the union instance. To denote the structure parameter that is used as the 1828 selector, its name is in brackets ([ ]) placed before the parameter name associated with the union. 1829 The table in Example 1 shows the definition of a structure that contains a union and a selector. Example 2 1830 shows how the table would be converted into C-compatible code and Example 3 shows how the 1831 unmarshaling code would handle the selector. 1832 EXAMPLE 1 1833 1834 Table xx Definition of STRUCTURE_WITH_UNION Structure 1835 Parameter 1836 1837 Type 1838 1839 Description 1840 1841 select 1842 1843 NUMBER_SELECT 1844 1845 a value indicating the type in number 1846 1847 [select] number 1848 1849 NUMBER_UNION 1850 1851 a union as shown in 4.9.2 1852 1853 EXAMPLE 2 1854 // C-compatible version of the union structure in the table above 1855 typedef struct { 1856 NUMBER_SELECT 1857 select; 1858 NUMBER_UNION 1859 number; 1860 } STRUCT_WITH_UNION; 1861 EXAMPLE 3 1862 1863 Family 2.0 1864 Level 00 Revision 00.99 1865 1866 Published 1867 Copyright TCG 2006-2013 1868 1869 Page 9 1870 October 31, 2013 1871 1872 Part 2: Structures 1874 1875 Trusted Platform Module Library 1876 1877 // Possible unmarshaling code for the structure above 1878 bool STRUCT_WITH_UNION_Unmarshal(STRUCT_WITH_UNION *target, BYTE **buffer, INT32 *size) 1879 { 1880 // Unmarshal the selector value 1881 if(!NUMBER_SELECT_Unmarshal((NUMBER_SELECT *)&target->select, buffer, size)) 1882 return FALSE; 1883 // Use the unmarshaled selector value to indicate to the union unmarshal 1884 // function which unmarshaling branch to follow. 1885 return(NUMBER_UNION_Unmarshal((NUMBER_UNION *)&(target->number), 1886 buffer, size, (UINT32)target->select); 1887 } 1888 1889 4.9.4 1890 1891 Union Selector Definition 1892 1893 The selector definition limits the values that are used in unmarshaling a union. Two different selector sets 1894 applied to the same union define different types. 1895 For the union in 4.9.2, a selector definition should be limited to no more than four values, one for each of 1896 the union members. The selector definition could have fewer than four values. 1897 In Example 1, the table defines a value for each of the union members. 1898 EXAMPLE 1 1899 1900 Table xx Definition of (INT8) NUMBER_SELECT Values <IN> 1901 Name 1902 1903 Value 1904 1905 BYTE_SELECT 1906 1907 3 1908 1909 INT_SELECT 1910 1911 2 1912 1913 FLOAT_SELECT 1914 1915 1 1916 1917 NULL_SELECT 1918 1919 Comments 1920 1921 0 1922 1923 The unmarshaling code would limit the input values to the defined values. When the NUMBER_SELECT 1924 is used in the union instance of 4.9.3, any of the allowed union members of NUMBER_UNION could be 1925 present. 1926 A different selection could be used to limit the values in a specific instance. To get the different selection, 1927 a new structure is defined with a different selector. The table in example 2 illustrates a way to subset the 1928 union. The base type of the selection is NUMBER_SELECT so a NUMBER_SELECT will be unmarshaled 1929 before the checks are made to see if the value is in the correct range for JUST_INTEGERS types. If the 1930 base type had been UINT8, then no checking would occur prior to checking that the value is in the 1931 allowed list. In this particular case, the effect is the same in either case since the only values that will be 1932 accepted by the unmarshaling code for JUST_INTEGER are BYTE_SELECT and INT_SELECT. 1933 EXAMPLE 2 1934 1935 Table xx Definition of (NUMBER_SELECT) AN_INTEGER Type <IN> 1936 Values 1937 {BYTE_SELECT, INT_SELECT} 1938 NOTE 1939 1940 Comments 1941 list of allowed values 1942 1943 Since NULL_SELECT is not in the list of values accepted as a JUST_INTEGER, the + modifier will have 1944 no effect if used for a JUST_INTEGERS type shown in Example 3. 1945 1946 Page 10 1947 October 31, 2013 1948 1949 Published 1950 Copyright TCG 2006-2013 1951 1952 Family 2.0 1953 Level 00 Revision 00.99 1954 1955 Trusted Platform Module Library 1957 1958 Part 2: Structures 1959 1960 The selector in Example 2 can then be used in a subset union as shown in Example 3. 1961 EXAMPLE 3 1962 1963 Table xx Definition of JUST_INTEGERS Structure 1964 Parameter 1965 1966 Type 1967 1968 Description 1969 1970 select 1971 1972 AN_INTEGER 1973 1974 a value indicating the type in number 1975 1976 [select] number 1977 1978 NUMBER_UNION 1979 1980 a union as shown in 4.9.2 1981 1982 4.10 Bit Field Definitions 1983 A table that defines a structure containing bit fields has a title that starts with Definition and ends with 1984 Bits. A type identifier in parentheses in the title indicates the size of the datum that contains the bit 1985 fields. 1986 When the bit fields do not occupy consecutive locations, a spacer field is defined with a name of 1987 Reserved. Bits in these spaces are reserved and shall be zero. 1988 The table in Example 1 shows how a structure containing bit fields would be defined in this specification. 1989 Example 2 shows the C code that might be produced from that table by an automated process. 1990 When a field has more than one bit, the range is indicated by a pair of numbers separated by a colon (:). 1991 The numbers will be in high:low order. 1992 EXAMPLE1 1993 1994 Table xx Definition of (UINT32) SOME_ATTRIBUTE Bits 1995 Bit 1996 0 1997 1998 Name 1999 2000 Action 2001 2002 zeroth_bit 2003 2004 SET (1): what to do if bit is 1 2005 CLEAR (0): what to do if bit is 0 2006 2007 1 2008 2009 first_bit 2010 2011 SET (1): what to do if bit is 1 2012 CLEAR (0): what to do if bit is 0 2013 2014 6:2 2015 7 2016 2017 Reserved 2018 2019 A placeholder that spans 5 bits 2020 2021 third_bit 2022 2023 SET (1): what to do if bit is 1 2024 CLEAR (0): what to do if bit is 0 2025 2026 31:8 2027 2028 Reserved 2029 2030 Placeholder to fill 32 bits 2031 2032 EXAMPLE 2 2033 /* C language equivalent of the attributes structure defined in the table above */ 2034 typedef struct { 2035 int zeroth_bit : 1; 2036 int first_bit : 1; 2037 int Reserved3 : 5; 2038 int third_bit : 1; 2039 int Reserved7 : 24; 2040 } SOME_ATTRIBUTE; 2041 2042 4.11 Parameter Limits 2043 A parameter used in a structure may be given a set of values that can be checked by the unmarshaling 2044 code. The allowed values for a parameter may be included in the definition of the parameter by 2045 appending the values and delimiting them with braces ({ }). The values are comma-separated 2046 expressions. A range of numbers may be indicated by separating two expressions with a colon (:). The 2047 Family 2.0 2048 Level 00 Revision 00.99 2049 2050 Published 2051 Copyright TCG 2006-2013 2052 2053 Page 11 2054 October 31, 2013 2055 2056 Part 2: Structures 2058 2059 Trusted Platform Module Library 2060 2061 first number is an expression that represents the minimum allowed value and the second number 2062 indicates the maximum. If the minimum or maximum value expression is omitted, then the range is openended. 2063 Parameter limits expressed using braces apply only to inputs to the TPM. Any value returned by the 2064 TPM is assumed to be valid. 2065 The maximum size of an array may be indicated by putting a {} delimited expression following the 2066 square brackets ([ ]) that indicate that the value is an array. 2067 EXAMPLE 2068 2069 Table xx Definition of B_STRUCT Structure 2070 Parameter 2071 2072 Type 2073 2074 Description 2075 2076 value1 {20:25} 2077 2078 UINT16 2079 2080 a parameter that must have a value between 20 2081 and 25 2082 2083 value2 {20} 2084 2085 UINT16 2086 2087 a parameter that must have a value of 20 2088 2089 value3 {:25} 2090 2091 INT16 2092 2093 a parameter that may be no larger than 25 2094 Since the parameter is signed, the minimum value 2095 is the largest negative integer that may be 2096 expressed in 16 bits. 2097 2098 value4 {20:} 2099 2100 a parameter that must be at least 20 2101 2102 value5 {1,2,3,5} 2103 2104 UINT16 2105 2106 a parameter that may only have one of the four 2107 listed values 2108 2109 value6 {1, 2, 10:(10+10)} 2110 2111 UINT32 2112 2113 a parameter that may have a value of 1, 2, or be 2114 between 10 and 20 2115 2116 array1[value1] 2117 2118 BYTE 2119 2120 Because the index refers to value1, which is a 2121 value limited to be between 20 and 25 inclusive, 2122 array1 is an array that may have between 20 and 2123 25 octets. This is not the preferred way to indicate 2124 the upper limit for an array as it does not indicate 2125 the upper bound of the size. 2126 NOTE 2127 2128 array2[value4]{:25} 2129 2130 BYTE 2131 2132 This is a limitation of the current 2133 parser. A different parser could 2134 associate the range of value1 with this 2135 value and compute the maximum size 2136 of the array. 2137 2138 an array that may have between 20 and 25 octets 2139 This arrangement is used to allow the automatic 2140 code generation to allocate 25 octets to store the 2141 largest array2 that can be unmarshaled. The code 2142 generation can determine from this expression that 2143 value4 shall have a value of 25 or less. From the 2144 definition of value4 above, it can determine that 2145 value4 must have a value of at least 20. 2146 2147 Page 12 2148 October 31, 2013 2149 2150 Published 2151 Copyright TCG 2006-2013 2152 2153 Family 2.0 2154 Level 00 Revision 00.99 2155 2156 Trusted Platform Module Library 2158 2159 Part 2: Structures 2160 2161 4.12 Enumeration Macro 2162 An enumeration can be a list of allowed numeric values. For example, the allowed sizes for an RSA key 2163 might be expressed as: 2164 2165 4.13 Size Checking 2166 In some structures, a size field is present to indicate the number of octets in some subsequent part of the 2167 structure. In the B_STRUCT table in 4.11, value4 indicates how many octets to unmarshal for array2. This 2168 semantic applies when the size field determines the number of octets to unmarshal. However, in some 2169 cases, the subsequent structure is self-defining. If the size precedes a parameter that is not an octet 2170 array, then the unmarshaled size of that parameter is determined by its data type. The table in Example 1 2171 shows a structure where the size parameter would nominally indicate the number of octets in the 2172 remainder of the structure. 2173 EXAMPLE 1 2174 2175 Table xx Definition of C_STRUCT Structure 2176 Parameter 2177 2178 Type 2179 2180 Comments 2181 2182 size 2183 2184 UINT16 2185 2186 the expected size of the remainder of the structure 2187 2188 anInteger 2189 2190 UINT32 2191 2192 a 4-octet value 2193 2194 In this particular case, the value of size would be incorrect if it had any value other than 4. So that the 2195 table parser is able to know that the purpose of the size parameter is to define the number of octets 2196 expected in the remainder of the structure, an equal sign (=) is appended to the parameter name. 2197 In the example below, the size= causes the parser to generate validation code that will check that the 2198 unmarshaled size of someStructure and someData adds to the value unmarshaled for size. When the = 2199 decoration is present, a value of zero is not allowed for the size. 2200 EXAMPLE 2 2201 2202 Table xx Definition of D_STRUCT Structure 2203 Parameter 2204 2205 Type 2206 2207 Comments 2208 2209 size= 2210 2211 UINT16 2212 2213 the size of a structure 2214 The = indicates that the TPM is required to 2215 validate that the remainder of the D_STRUCT 2216 structure is exactly the value in size. That is, the 2217 number of bytes in the input buffer used to 2218 successfully unmarshal someStructure must be the 2219 same as size. 2220 2221 someStructure 2222 2223 A_STRUCT 2224 2225 a structure to be unmarshaled 2226 The size of the structure is computed when it is 2227 unmarshaled. Because an = is present on the 2228 definition of size, the TPM is required to validate 2229 that the unmarshaled size exactly matches size. 2230 2231 someData 2232 2233 Family 2.0 2234 Level 00 Revision 00.99 2235 2236 UINT32 2237 2238 a value 2239 2240 Published 2241 Copyright TCG 2006-2013 2242 2243 Page 13 2244 October 31, 2013 2245 2246 Part 2: Structures 2248 2249 Trusted Platform Module Library 2250 2251 4.14 Data Direction 2252 A structure or union may be input (IN), output (OUT), or internal. An input structure is sent to the TPM and 2253 is unmarshaled by the TPM. An output structure is sent from the TPM and is marshaled by the TPM. An 2254 internal structure is not used outside of the TPM except that it may be included in a saved context. 2255 By default, structures are assumed to be both IN and OUT and the code generation tool will generate 2256 both marshaling and unmarshaling code for the structure. This default may be changed by using values 2257 enclosed in angle brackets (<>) as part of the table title. If the angle brackets are empty, then the 2258 structure is internal and neither marshaling nor unmarshaling code is generated. If the angle brackets 2259 contain the letter I (such as in IN or in or i), then the structure is input and unmarshaling code will be 2260 generated. If the angle brackets contain the letter O (such as in OUT or out or o), then the structure 2261 is output and marshaling code will be generated. 2262 EXAMPLE 1 2263 2264 Both of the following table titles would indicate a structure that is used in both input and output 2265 Table xx Definition of TPMS_A Structure 2266 Table xx Definition of TPMS_A Structure <IN/OUT> 2267 2268 EXAMPLE 2 2269 2270 The following table title would indicate a structure that is used only for input 2271 Table xx Definition of TPMS_A Structure <IN> 2272 2273 EXAMPLE 3 2274 2275 The following table title would indicate a structure that is used only for output 2276 Table xx Definition of TPMS_A Structure <OUT> 2277 2278 4.15 Structure Validations 2279 By default, when a structure is used for input to the TPM, the code generation tool will generate the 2280 unmarshaling code for that structure. Auto-generation may be suppressed by adding an S within the 2281 angle brackets. 2282 EXAMPLE 2283 2284 The following table titles indicate a structure for which the auto -generation of the validation code is to be 2285 suppressed. 2286 Table xx Definition of TPMT_A Structure <S> 2287 Table xx Definition of TPMT_A Structure <IN, S> 2288 Table xx Definition of TPMT_A Structure <IN/OUT, S> 2289 2290 4.16 Name Prefix Convention 2291 Parameters are constants, variables, structures, unions, and structure members. Structure members are 2292 given a name that is indicative of its use, with no special prefix. The other parameter types are named 2293 according to their type with their name starting with TPMx_, where x is an optional character to indicate 2294 the data type. 2295 In some cases, additional qualifying characters will follow the underscore. These are generally used when 2296 dealing with an enumerated data type. 2297 TPMA_ This is an attribute structure, where bits are associated with particular attributes 2298 2299 Page 14 2300 October 31, 2013 2301 2302 Published 2303 Copyright TCG 2006-2013 2304 2305 Family 2.0 2306 Level 00 Revision 00.99 2307 2308 Trusted Platform Module Library 2310 2311 Part 2: Structures 2312 2313 Table 1 Name Prefix Convention 2314 Prefix 2315 2316 Description 2317 2318 _TPM_ 2319 2320 an indication/signal from the TPMs system interface 2321 2322 TPM_ 2323 2324 a constant or an enumerated type 2325 2326 TPM2_ 2327 2328 a command defined by this specification 2329 2330 TPM2B_ 2331 2332 a structure that is a sized buffer where the size of the buffer is contained in a 16-bit, unsigned 2333 value 2334 The first parameter is the size in octets of the second parameter. The second parameter may be 2335 any type. 2336 2337 TPMA_ 2338 2339 a structure where each of the fields defines an attribute and each field is usually a single bit 2340 All the attributes in an attribute structure are packed with the overall size of the structure 2341 indicated in the heading of the attribute description (UINT8, UINT16, or UINT32). 2342 2343 TPM_ALG_ 2344 2345 an enumerated type that indicates an algorithm 2346 A TPM_ALG_ is often used as a selector for a union. 2347 2348 TPMI_ 2349 2350 an interface type 2351 The value is specified for purposes of dynamic type checking when unmarshaled. 2352 2353 TPML_ 2354 2355 a list length followed by the indicated number of entries of the indicated type 2356 This is an array with a length field. 2357 2358 TPMS_ 2359 2360 a structure that is not a size buffer or a tagged buffer or a list 2361 2362 TPMT_ 2363 2364 a structure with the first parameter being a structure tag, indicating the type of the structure that 2365 follows 2366 A structure tag may be either a TPMT_ST_ or TPM_ALG_ depending on context. 2367 2368 TPMU_ 2369 2370 a union of structures, lists, or unions 2371 If a union exists, there will normally be a companion TPMT_ that is the expression of the union 2372 in a tagged structure, where the tag is the selector indicating which member of the union is 2373 present. 2374 2375 TPM_xx_ 2376 2377 an enumeration value of a particular type 2378 The value of xx will be indicative of the use of the enumerated type. A table of TPM_xx 2379 constant definitions will exist to define each of the TPM_xx_ values. 2380 EXAMPLE 1 2381 2382 TPM_CC_ indicates that the type is used for a commandCode. The allowed enumeration 2383 values will be found in the table defining the TPM_CC constants (Table 11). 2384 2385 EXAMPLE 2 2386 2387 TPM_RC_ indicates that the type is used for a responseCode. The allowed enumeration 2388 values are in Table 15. 2389 2390 4.17 Data Alignment 2391 The data structures in this Part 2 use octet alignment for all structures. When used in a table to indicate a 2392 maximum size, the sizeof() function returns the octet-aligned size of the structure, with no padding. 2393 4.18 2394 2395 Parameter Unmarshaling Errors 2396 2397 The TPM commands are defined in Part 3. The command definition included C code that details the 2398 actions performed by that command. The code is written assuming that the parameters of the command 2399 have been unmarshaled. 2400 NOTE 1 2401 2402 An implementation is not required to process parameters in this manner or to separate the parameter 2403 parsing from the command actions. This method was chosen for the specification so that the normative 2404 behavior described by the detailed actions would be clear and unencumbered. 2405 2406 Family 2.0 2407 Level 00 Revision 00.99 2408 2409 Published 2410 Copyright TCG 2006-2013 2411 2412 Page 15 2413 October 31, 2013 2414 2415 Part 2: Structures 2417 2418 Trusted Platform Module Library 2419 2420 Unmarshaling is the process of processing the parameters in the input buffer and preparing the 2421 parameters for use by the command-specific action code. No data movement need take place but it is 2422 required that the TPM validate that the parameters meet the requirements of the expected data type as 2423 defined in this Part 2. 2424 When an error is encountered while unmarshaling a command parameter, an error response code is 2425 returned and no command processing occurs. A table defining a data type may have response codes 2426 embedded in the table to indicate the error returned when the input value does not match the parameters 2427 of the table. 2428 EXAMPLE 1 2429 2430 Table 11 has a listing of TPM command code values. The last row in the table contains 2431 "#TPM_RC_COMMAND_CODE" indicating the response code that is returned if the TPM is unmarshaling 2432 a value that it expects to be a TPM_CC and the input value is not in the table. 2433 2434 NOTE 2 2435 2436 In the reference implementation, a parameter number is added to the response code so that the offending 2437 parameter can be isolated. 2438 2439 In many cases, the table contains no specific response code value and the return code will be determined 2440 as defined in Table 2. 2441 Table 2 Unmarshaling Errors 2442 Response code 2443 2444 Usage 2445 2446 TPM_RC_INSUFFICIENT 2447 2448 the input buffer did not contain enough octets to allow unmarshaling of the 2449 expected data type; 2450 2451 TPM_RC_RESERVED 2452 2453 a non-zero value was found in a reserved field of an attribute structure (TPMA_) 2454 2455 TPM_RC_SIZE 2456 2457 the value of a size parameter is larger or smaller than allowed 2458 2459 TPM_RC_VALUE 2460 2461 A parameter does not have one of its allowed values 2462 2463 TPM_RC_TAG 2464 2465 A parameter that should be a structure tag has a value that is not supported by 2466 the TPM 2467 2468 In some commands, a parameter may not be used because of various options of that command. 2469 However, the unmarshaling code is required to validate that all parameters have values that are allowed 2470 by the Part 2 definition of the parameter type even if that parameter is not used in the command actions. 2471 2472 Page 16 2473 October 31, 2013 2474 2475 Published 2476 Copyright TCG 2006-2013 2477 2478 Family 2.0 2479 Level 00 Revision 00.99 2480 2481 Trusted Platform Module Library 2483 2484 5 2485 2486 Part 2: Structures 2487 2488 Base Types 2489 2490 5.1 2491 2492 Primitive Types 2493 2494 The types listed in Table 3 are the primitive types on which all of the other types and structures are 2495 based. The values in the Type column should be edited for the compiler and computer on which the 2496 TPM is implemented. The values in the Name column should remain the same because these values 2497 are used in the remainder of the specification. 2498 NOTE 2499 2500 The types are compatible with the C99 standard and should be defined in stdint.h that is provided with a 2501 C99-compliant compiler; 2502 2503 The parameters in the Name column should remain in the order shown. 2504 Table 3 Definition of Base Types 2505 Type 2506 2507 Name 2508 2509 Description 2510 2511 uint8_t 2512 2513 UINT8 2514 2515 unsigned, 8-bit integer 2516 2517 uint8_t 2518 2519 BYTE 2520 2521 unsigned 8-bit integer 2522 2523 int8_t 2524 2525 INT8 2526 2527 signed, 8-bit integer 2528 2529 int 2530 2531 BOOL 2532 2533 a bit in an int 2534 This is not used across the interface but is used in many places in the code. If 2535 the type were sent on the interface, it would have to have a type with a specific 2536 number of bytes. 2537 2538 uint16_t 2539 2540 UINT16 2541 2542 unsigned, 16-bit integer 2543 2544 int16_t 2545 2546 INT16 2547 2548 signed, 16-bit integer 2549 2550 uint32_t 2551 2552 UINT32 2553 2554 unsigned, 32-bit integer 2555 2556 int32_t 2557 2558 INT32 2559 2560 signed, 32-bit integer 2561 2562 uint64_t 2563 2564 UINT64 2565 2566 unsigned, 64-bit integer 2567 2568 int64_t 2569 2570 INT64 2571 2572 signed, 64-bit integer 2573 2574 5.2 2575 2576 Miscellaneous Types 2577 2578 These types are defined either for compatibility with previous versions of this specification or for clarity of 2579 this specification. 2580 Table 4 Definition of Types for Documentation Clarity 2581 Type 2582 2583 Name 2584 2585 Description 2586 2587 UINT32 2588 2589 TPM_ALGORITHM_ID 2590 2591 this is the 1.2 compatible form of the TPM_ALG_ID 2592 2593 UINT32 2594 2595 TPM_MODIFIER_INDICATOR 2596 2597 UINT32 2598 2599 TPM_AUTHORIZATION_SIZE 2600 2601 the authorizationSize parameter in a command 2602 2603 UINT32 2604 2605 TPM_PARAMETER_SIZE 2606 2607 the parameterSizeset parameter in a command 2608 2609 UINT16 2610 2611 TPM_KEY_SIZE 2612 2613 a key size in octets 2614 2615 UINT16 2616 2617 TPM_KEY_BITS 2618 2619 a key size in bits 2620 2621 1.1.1.1.1 2622 2623 Family 2.0 2624 Level 00 Revision 00.99 2625 2626 Published 2627 Copyright TCG 2006-2013 2628 2629 Page 17 2630 October 31, 2013 2631 2632 Part 2: Structures 2634 2635 6 2636 2637 Trusted Platform Module Library 2638 2639 Constants 2640 2641 6.1 2642 2643 TPM_SPEC (Specification Version Values) 2644 2645 These values are readable with TPM2_GetCapability(). 2646 NOTE 2647 2648 This table will require editing when the specification is updated. 2649 2650 Table 5 Definition of (UINT32) TPM_SPEC Constants <> 2651 Name 2652 2653 Value 2654 2655 Comments 2656 ASCII 2.0 with null terminator 2657 2658 TPM_SPEC_FAMILY 2659 2660 0x322E3000 2661 2662 TPM_SPEC_LEVEL 2663 2664 00 2665 2666 the level number for the specification 2667 2668 TPM_SPEC_VERSION 2669 2670 99 2671 2672 the version number of the spec (00.99 * 100) 2673 2674 TPM_SPEC_YEAR 2675 2676 2013 2677 2678 the year of the version 2679 2680 TPM_SPEC_DAY_OF_YEAR 2681 2682 304 2683 2684 the day of the year (October 31, 2013) 2685 2686 6.2 2687 2688 TPM_GENERATED 2689 2690 This constant value differentiates TPM-generated structures from non-TPM structures. 2691 Table 6 Definition of (UINT32) TPM_GENERATED Constants <O> 2692 Name 2693 2694 Value 2695 2696 Comments 2697 2698 TPM_GENERATED_VALUE 2699 2700 0xff544347 2701 2702 0xFF TCG (FF 54 43 4716) 2703 2704 Page 18 2705 October 31, 2013 2706 2707 Published 2708 Copyright TCG 2006-2013 2709 2710 Family 2.0 2711 Level 00 Revision 00.99 2712 2713 Trusted Platform Module Library 2715 6.3 2716 2717 Part 2: Structures 2718 2719 TPM_ALG_ID 2720 2721 The TCG maintains a registry of all algorithms that have an assigned algorithm ID. That registry is the 2722 definitive list of algorithms that may be supported by a TPM. 2723 NOTE 2724 2725 Inclusion of an algorithm does NOT indicate that the necessary claims of the algorithm are av ailable 2726 under RAND terms from a TCG member. 2727 2728 Table 7 is a copy of the TPM_ALG_ID constants table in the TCG registry as of the date of publication of 2729 this specification. Table 7 is provided for illustrative purposes only. 2730 {{Note for TCG Admin: Table 7 and the text in the paragraph above should be updated to reflect the final 2731 decisions by the TCG Board of Directors about inclusion of the table and the contents of the table. The 2732 desired approach is to leave the text as is and, immediately before publication of this specification for 2733 TCG admin to verify that Table 7 is the same as the algorithm registry table published by the TCG.}} 2734 An algorithm ID is often used like a tag to determine the type of a structure in a context-sensitive way. 2735 The values for TPM_ALG_ID shall be in the range of 00 0016 7F FF16. Other structure tags will be in the 2736 range 80 0016 FF FF16. 2737 NOTE 2738 2739 In TPM 1.2, these were defined as 32-bit constants. This specification limits the future size of the 2740 algorithm ID to 16 bits. The TPM_ALGORITHM_ID data type will continue to be a 32-bit number. 2741 2742 An algorithm shall not be assigned a value in the range 00 C116 00 C616 in order to prevent any overlap 2743 with the command structure tags used in TPM 1.2. 2744 The implementation of some algorithms is dependent on the presence of other algorithms. When there is 2745 a dependency, the algorithm that is required is listed in column labeled "D" (dependent) in Table 7. 2746 EXAMPLE 2747 2748 Implementation of TPM_ALG_RSASSA requires that the RSA algorithm be implemented. 2749 2750 TPM_ALG_KEYEDHASH and TPM_ALG_NULL are required of all TPM implementations. 2751 Table 7 Definition of (UINT16) TPM_ALG_ID Constants <IN/OUT, S> 2752 Algorithm Name 2753 2754 Value 2755 2756 Type 2757 2758 a 2759 2760 D 2761 2762 Comments 2763 2764 TPM_ALG_ERROR 2765 2766 0x0000 2767 2768 should not occur 2769 2770 TPM_ALG_FIRST 2771 2772 0x0001 2773 2774 TPM_ALG_RSA 2775 2776 0x0001 2777 2778 AO 2779 2780 the RSA algorithm 2781 2782 TPM_ALG_SHA 2783 2784 0x0004 2785 2786 H 2787 2788 the SHA1 algorithm 2789 2790 TPM_ALG_SHA1 2791 2792 0x0004 2793 2794 H 2795 2796 redefinition for documentation consistency 2797 OID 30 21 30 09 06 05 2B 0E 03 02 1A 05 00 04 14 16 2798 2799 TPM_ALG_HMAC 2800 2801 0x0005 2802 2803 HX 2804 2805 the RFC 2104 Hash Message Authentication Code 2806 (HMAC) algorithm 2807 2808 TPM_ALG_AES 2809 2810 0x0006 2811 2812 S 2813 2814 2815 TPM_ALG_MGF1 2816 2817 0x0007 2818 2819 HM 2820 2821 the mask-generation function defined in IEEE Std 2822 1363-2000 2823 2824 TPM_ALG_KEYEDHASH 2825 2826 0x0008 2827 2828 HEXO 2829 2830 an encryption or signing algorithm using a keyed hash, 2831 defined by TCG in the TPM 2.0 specification 2832 may also refer to a data object that is neither signing 2833 nor encrypting 2834 2835 TPM_ALG_XOR 2836 2837 0x000A 2838 2839 HS 2840 2841 marker value 2842 2843 the XOR obfuscation algorithm 2844 NOTE 2845 2846 Family 2.0 2847 Level 00 Revision 00.99 2848 2849 Published 2850 Copyright TCG 2006-2013 2851 2852 Page 19 2853 October 31, 2013 2854 2855 Part 2: Structures 2857 Algorithm Name 2858 2859 Trusted Platform Module Library 2860 a 2861 2862 Value 2863 2864 Type 2865 2866 TPM_ALG_SHA256 2867 2868 0x000B 2869 2870 H 2871 2872 D 2873 2874 Comments 2875 the SHA 256 algorithm 2876 OID 30 31 30 0d 06 09 60 86 48 01 65 03 04 02 01 05 2877 00 04 2016 2878 2879 TPM_ALG_SHA384 2880 2881 0x000C 2882 2883 H 2884 2885 the SHA 384 algorithm 2886 OID 30 41 30 0d 06 09 60 86 48 01 65 03 04 02 02 05 2887 00 04 3016 2888 2889 TPM_ALG_SHA512 2890 2891 0x000D 2892 2893 H 2894 2895 the SHA 512 algorithm 2896 OID 30 51 30 0d 06 09 60 86 48 01 65 03 04 02 03 05 2897 00 04 4016 2898 2899 TPM_ALG_NULL 2900 2901 0x0010 2902 2903 TPM_ALG_SM3_256 2904 2905 0x0012 2906 2907 H 2908 2909 hash algorithm standardized by OSCCA 2910 Block size is 512 bits. 2911 Output size is 256 bits. 2912 2913 TPM_ALG_SM4 2914 2915 0x0013 2916 2917 S 2918 2919 symmetric algorithm standardized by OSCCA 2920 Key and block size are 128 bits. 2921 2922 TPM_ALG_RSASSA 2923 2924 0x0014 2925 2926 AX 2927 2928 RSA a signature algorithm according to PKCS#1v2.1, 8.2 2929 2930 TPM_ALG_RSAES 2931 2932 0x0015 2933 2934 AE 2935 2936 RSA a padding algorithm according to PKCS#1v2.1, 7.2 2937 2938 TPM_ALG_RSAPSS 2939 2940 0x0016 2941 2942 AX 2943 2944 RSA signature algorithm (RSSASSA-PSS) according to 2945 PKCS#1v2.1, 8.1 2946 2947 TPM_ALG_OAEP 2948 2949 0x0017 2950 2951 AE 2952 2953 RSA padding algorithm 2954 PKCS#1v2.1, 7.1 2955 2956 TPM_ALG_ECDSA 2957 2958 0x0018 2959 2960 AX 2961 2962 ECC signature algorithm using elliptic curve cryptography 2963 (ECC) 2964 2965 TPM_ALG_ECDH 2966 2967 0x0019 2968 2969 AM 2970 2971 ECC secret sharing using ECC from SP800-56A 2972 Based on context, this can be either One-Pass DiffieHellman, C(1, 1, ECC CDH) defined in 6.2.2.2 or Full 2973 Unified Model C(2, 2, ECC CDH) defined in 6.1.1.2 2974 2975 TPM_ALG_ECDAA 2976 2977 0x001A 2978 2979 AX 2980 2981 ECC elliptic-curve based, anonymous signing scheme 2982 2983 TPM_ALG_SM2 2984 2985 0x001B 2986 2987 AXE 2988 2989 Null algorithm 2990 2991 (RSAES_OAEP) 2992 2993 according 2994 2995 to 2996 2997 ECC depending on context, either an elliptic-curve based, 2998 signature algorithm or a key exchange protocol 2999 NOTE 3000 3001 This would be one of the algorithms specified in 3002 CM/T 0002 2012. 3003 3004 TPM_ALG_ECSCHNORR 3005 3006 0x001C 3007 3008 AX 3009 3010 ECC elliptic-curve-based Schnorr signature 3011 3012 TPM_ALG_ECMQV 3013 3014 0x001D 3015 3016 AE 3017 3018 ECC two-phase elliptic-curve key exchange -- C(2, 2, ECC 3019 MQV) from SP800-56A 3020 3021 TPM_ALG_KDF1_SP800_56a 3022 3023 0x0020 3024 3025 HM 3026 3027 ECC key derivation alternative #1 from SP800-56A 3028 3029 TPM_ALG_KDF2 3030 3031 0x0021 3032 3033 HM 3034 3035 key derivation function from IEEE Std 1363a-2004 3036 3037 TPM_ALG_KDF1_SP800_108 3038 3039 0x0022 3040 3041 HM 3042 3043 a key derivation method according to SP 800-108, "5.1 3044 KDF in Counter Mode 3045 3046 TPM_ALG_ECC 3047 3048 0x0023 3049 3050 AO 3051 3052 prime field ECC 3053 3054 TPM_ALG_SYMCIPHER 3055 3056 0x0025 3057 3058 O 3059 3060 TPM_ALG_CTR 3061 3062 0x0040 3063 3064 SE 3065 3066 Counter mode if implemented, all symmetric block 3067 ciphers (S type) implemented shall be capable of using 3068 this mode. 3069 3070 TPM_ALG_OFB 3071 3072 0x0041 3073 3074 SE 3075 3076 Output Feedback mode if implemented, all 3077 symmetric block ciphers (S type) implemented shall be 3078 capable of using this mode. 3079 3080 TPM_ALG_CBC 3081 3082 0x0042 3083 3084 SE 3085 3086 Cipher Block Chaining mode if implemented, all 3087 symmetric block ciphers (S type) implemented shall be 3088 capable of using this mode. 3089 3090 Page 20 3091 October 31, 2013 3092 3093 the object type for a symmetric block cipher 3094 3095 Published 3096 Copyright TCG 2006-2013 3097 3098 Family 2.0 3099 Level 00 Revision 00.99 3100 3101 Trusted Platform Module Library 3103 3104 Part 2: Structures 3105 a 3106 3107 Algorithm Name 3108 3109 Value 3110 3111 Type 3112 3113 TPM_ALG_CFB 3114 3115 0x0043 3116 3117 SE 3118 3119 D 3120 3121 Comments 3122 Cipher Feedback mode if implemented, all 3123 symmetric block ciphers (S type) implemented shall be 3124 capable of using this mode. 3125 3126 TPM_ALG_ECB 3127 3128 0x0044 3129 3130 SE 3131 3132 Electronic Codebook mode if implemented, all 3133 symmetric block ciphers (S type) implemented shall be 3134 capable of using this mode. 3135 NOTE 3136 3137 This mode is not recommended for uses unless 3138 the key is frequently rotated such as in video 3139 codecs. 3140 3141 TPM_ALG_LAST 3142 3143 0x0044 3144 3145 marker value 3146 3147 reserved 3148 3149 0x00C1 3150 3151 0x00C1 0x00C6 are reserved 3152 3153 reserved 3154 3155 0x00C2 3156 3157 reserved 3158 3159 0x00C3 3160 3161 reserved 3162 3163 0x00C4 3164 3165 reserved 3166 3167 0x00C5 3168 3169 reserved 3170 3171 0x00C6 3172 3173 NOTE a Column Indicates the algorithm type and use of the algorithm inside of the TPM. The values are: 3174 A asymmetric algorithm with a public and private key 3175 S symmetric algorithm with only a private key 3176 H hash algorithm that compresses input data to a digest value 3177 X signing algorithm 3178 E an encryption algorithm 3179 M a method such as a mask generation function 3180 O an object type 3181 3182 Family 2.0 3183 Level 00 Revision 00.99 3184 3185 Published 3186 Copyright TCG 2006-2013 3187 3188 Page 21 3189 October 31, 2013 3190 3191 Part 2: Structures 3193 6.4 3194 3195 Trusted Platform Module Library 3196 3197 TPM_ECC_CURVE 3198 3199 The TCG maintains a registry of all curves that have an assigned curve identifier. That registry is the 3200 definitive list of curves that may be supported by a TPM. 3201 Table 8 is a copy of the TPM_ECC_CURVE constants table in the TCG registry as of the date of 3202 publication of this specification. Table 8 is provided for illustrative purposes only. 3203 {{Note for TCG Admin: Table 8 and the text in the paragraph above should be updated to reflect the final 3204 decisions by the TCG Board of Directors about inclusion of the table and the contents of the table. The 3205 desired approach is to leave the text as is and, immediately before publication of this specification for 3206 TCG admin to verify that Table 8 is the same as the curve registry table published by the TCG.}} 3207 Table 8 Definition of (UINT16) {ECC} TPM_ECC_CURVE Constants <IN/OUT, S> 3208 Name 3209 3210 Value 3211 3212 Comments 3213 3214 TPM_ECC_NONE 3215 3216 0x0000 3217 3218 TPM_ECC_NIST_P192 3219 3220 0x0001 3221 3222 TPM_ECC_NIST_P224 3223 3224 0x0002 3225 3226 TPM_ECC_NIST_P256 3227 3228 0x0003 3229 3230 TPM_ECC_NIST_P384 3231 3232 0x0004 3233 3234 TPM_ECC_NIST_P521 3235 3236 0x0005 3237 3238 TPM_ECC_BN_P256 3239 3240 0x0010 3241 3242 curve to support ECDAA 3243 3244 TPM_ECC_BN_P638 3245 3246 0x0011 3247 3248 curve to support ECDAA 3249 3250 TPM_ECC_SM2_P256 3251 3252 0x0020 3253 3254 #TPM_RC_CURVE 3255 3256 6.5 3257 6.5.1 3258 3259 TPM_CC (Command Codes) 3260 Format 3261 3262 A command is a 32-bit structure with fields assigned as shown in Figure 1. 3263 3 3 2 2 3264 1 0 9 8 3265 3266 Res V 3267 3268 1 1 3269 6 5 3270 3271 Reserved 3272 3273 0 3274 0 3275 3276 Command Index 3277 3278 Figure 1 Command Format 3279 Table 9 TPM Command Format Fields Description 3280 Bit 3281 15:0 3282 3283 Name 3284 3285 Definition 3286 3287 Command Index 3288 3289 the index of the command 3290 3291 28:16 Reserved 3292 29 3293 3294 V 3295 3296 31:30 Res 3297 3298 Page 22 3299 October 31, 2013 3300 3301 shall be zero 3302 SET(1): the command is vendor specific 3303 CLEAR(0): the command is not vendor specific 3304 shall be zero 3305 3306 Published 3307 Copyright TCG 2006-2013 3308 3309 Family 2.0 3310 Level 00 Revision 00.99 3311 3312 Trusted Platform Module Library 3314 6.5.2 3315 3316 Part 2: Structures 3317 3318 Description 3319 3320 Table 10 provides the legend for the interpretation of the column data in Table 11. 3321 Table 10 Legend for Command Code Tables 3322 Column 3323 3324 Allowed 3325 Values 3326 3327 Comments 3328 3329 Name 3330 3331 Command 3332 Code Name 3333 3334 Name of the command 3335 3336 Command Code 3337 3338 Numeric value 3339 3340 the numeric value for the commandCode 3341 3342 NV Write 3343 3344 blank, Y, O 3345 3346 indicates whether the command may cause an NV write operation 3347 If this column contains a Y, then successful completion of the 3348 command is expected to cause modification of the NV memory 3349 because of the command actions. 3350 If the column contains an O, then the command may cause a 3351 modification to NV associated with an orderly shutdown. That is, the 3352 command may modify the orderly save state of NV, in which case, an 3353 NV write will be necessary. 3354 NOTE 1 3355 3356 Any command may be delayed in order for the TPM to complete 3357 NV actions due to a previous command or because of an 3358 asynchronous update of Clock. 3359 3360 NOTE 2 3361 3362 Any command with an authorization value may cause an NV write 3363 on an authorization failure but the command does not complete 3364 successfully. 3365 3366 If the entry is blank, then writing to NV is not allowed in the command 3367 actions. 3368 Physical Presence 3369 3370 blank, Y 3371 3372 indicates whether the platformAuth for this command may require 3373 confirmation through a physical presence indication 3374 3375 Encrypted 3376 3377 blank, 2, 4 3378 3379 A numeric value that indicates the number of octets in the size field of 3380 the first parameter of a command 3381 Blank indicates that no size field is present and no parameter 3382 encryption is allowed. 3383 3384 Encrypt 3385 3386 blank, 2, 4 3387 3388 A numeric value that indicates the number of octets in the size field of 3389 the first parameter of a response 3390 Blank indicates that no size field is present and no parameter 3391 encryption is allowed. 3392 3393 Family 2.0 3394 Level 00 Revision 00.99 3395 3396 Published 3397 Copyright TCG 2006-2013 3398 3399 Page 23 3400 October 31, 2013 3401 3402 Part 2: Structures 3404 6.5.3 3405 3406 Trusted Platform Module Library 3407 3408 TPM_CC Listing 3409 3410 Table 11 lists the command codes and their attributes. The only normative column in this table is the 3411 column indicating the command code assigned to a specific command (the "Command Code" column). 3412 For all other columns, the command and response tables in Part 3 are definitive. 3413 3414 Encrypt 3415 3416 Encrypted 3417 3418 Physical Presence 3419 3420 NV Write 3421 3422 Table 11 Definition of (UINT32) TPM_CC Constants (Numeric Order) <IN/OUT, S> 3423 3424 Name 3425 3426 Command 3427 Code 3428 3429 TPM_CC_FIRST 3430 3431 0x0000011F 3432 3433 Compile variable. May decrease 3434 based on implementation. 3435 3436 TPM_CC_PP_FIRST 3437 3438 0x0000011F 3439 3440 Compile variable. Would decrease 3441 if new PP commands are added 3442 3443 TPM_CC_NV_UndefineSpaceSpecial 3444 3445 0x0000011F 3446 3447 Y 3448 3449 Y 3450 3451 TPM_CC_EvictControl 3452 3453 0x00000120 3454 3455 Y 3456 3457 Y 3458 3459 TPM_CC_HierarchyControl 3460 3461 0x00000121 3462 3463 Y 3464 3465 Y 3466 3467 TPM_CC_NV_UndefineSpace 3468 3469 0x00000122 3470 3471 Y 3472 3473 Y 3474 3475 TPM_CC_ChangeEPS 3476 3477 0x00000124 3478 3479 Y 3480 3481 Y 3482 3483 TPM_CC_ChangePPS 3484 3485 0x00000125 3486 3487 Y 3488 3489 Y 3490 3491 TPM_CC_Clear 3492 3493 0x00000126 3494 3495 Y 3496 3497 Y 3498 3499 TPM_CC_ClearControl 3500 3501 0x00000127 3502 3503 Y 3504 3505 Y 3506 3507 TPM_CC_ClockSet 3508 3509 0x00000128 3510 3511 Y 3512 3513 Y 3514 3515 TPM_CC_HierarchyChangeAuth 3516 3517 0x00000129 3518 3519 Y 3520 3521 Y 3522 3523 2 3524 3525 TPM_CC_NV_DefineSpace 3526 3527 0x0000012A 3528 3529 Y 3530 3531 Y 3532 3533 2 3534 3535 TPM_CC_PCR_Allocate 3536 3537 0x0000012B 3538 3539 Y 3540 3541 Y 3542 3543 TPM_CC_PCR_SetAuthPolicy 3544 3545 0x0000012C 3546 3547 Y 3548 3549 Y 3550 3551 TPM_CC_PP_Commands 3552 3553 0x0000012D 3554 3555 Y 3556 3557 Y 3558 3559 TPM_CC_SetPrimaryPolicy 3560 3561 0x0000012E 3562 3563 Y 3564 3565 Y 3566 3567 2 3568 3569 TPM_CC_FieldUpgradeStart 3570 3571 0x0000012F 3572 3573 O 3574 3575 Y 3576 3577 2 3578 3579 TPM_CC_ClockRateAdjust 3580 3581 0x00000130 3582 3583 O 3584 3585 Y 3586 3587 TPM_CC_CreatePrimary 3588 3589 0x00000131 3590 3591 TPM_CC_NV_GlobalWriteLock 3592 3593 0x00000132 3594 3595 TPM_CC_PP_LAST 3596 3597 0x00000132 3598 3599 TPM_CC_GetCommandAuditDigest 3600 3601 0x00000133 3602 3603 Y 3604 3605 TPM_CC_NV_Increment 3606 3607 0x00000134 3608 3609 Y 3610 3611 Page 24 3612 October 31, 2013 3613 3614 Y 3615 O 3616 3617 Comments 3618 3619 2 3620 3621 2 3622 3623 2 3624 3625 Y 3626 Compile variable 3627 2 3628 3629 Published 3630 Copyright TCG 2006-2013 3631 3632 Family 2.0 3633 Level 00 Revision 00.99 3634 3635 Command 3637 Code 3638 3639 TPM_CC_NV_SetBits 3640 3641 0x00000135 3642 3643 Y 3644 3645 TPM_CC_NV_Extend 3646 3647 0x00000136 3648 3649 Y 3650 3651 TPM_CC_NV_Write 3652 3653 0x00000137 3654 3655 Y 3656 3657 TPM_CC_NV_WriteLock 3658 3659 0x00000138 3660 3661 Y 3662 3663 TPM_CC_DictionaryAttackLockReset 3664 3665 0x00000139 3666 3667 O 3668 3669 TPM_CC_DictionaryAttackParameters 3670 3671 0x0000013A 3672 3673 Y 3674 3675 TPM_CC_NV_ChangeAuth 3676 3677 0x0000013B 3678 3679 Y 3680 3681 2 3682 3683 TPM_CC_PCR_Event 3684 3685 0x0000013C 3686 3687 O 3688 3689 2 3690 3691 TPM_CC_PCR_Reset 3692 3693 0x0000013D 3694 3695 O 3696 3697 TPM_CC_SequenceComplete 3698 3699 0x0000013E 3700 3701 O 3702 3703 TPM_CC_SetAlgorithmSet 3704 3705 0x0000013F 3706 3707 Y 3708 3709 TPM_CC_SetCommandCodeAuditStatus 3710 3711 0x00000140 3712 3713 Y 3714 3715 TPM_CC_FieldUpgradeData 3716 3717 0x00000141 3718 3719 O 3720 3721 TPM_CC_IncrementalSelfTest 3722 3723 0x00000142 3724 3725 O 3726 3727 TPM_CC_SelfTest 3728 3729 0x00000143 3730 3731 O 3732 3733 TPM_CC_Startup 3734 3735 0x00000144 3736 3737 Y 3738 3739 TPM_CC_Shutdown 3740 3741 0x00000145 3742 3743 Y 3744 3745 TPM_CC_StirRandom 3746 3747 0x00000146 3748 3749 Y 3750 3751 TPM_CC_ActivateCredential 3752 3753 0x00000147 3754 3755 TPM_CC_Certify 3756 3757 0x00000148 3758 3759 TPM_CC_PolicyNV 3760 3761 0x00000149 3762 3763 TPM_CC_CertifyCreation 3764 3765 0x0000014A 3766 3767 TPM_CC_Duplicate 3768 3769 0x0000014B 3770 3771 TPM_CC_GetTime 3772 3773 0x0000014C 3774 3775 O 3776 3777 2 3778 3779 TPM_CC_GetSessionAuditDigest 3780 3781 0x0000014D 3782 3783 O 3784 3785 2 3786 3787 TPM_CC_NV_Read 3788 3789 0x0000014E 3790 3791 TPM_CC_NV_ReadLock 3792 3793 0x0000014F 3794 3795 TPM_CC_ObjectChangeAuth 3796 3797 0x00000150 3798 3799 2 3800 3801 TPM_CC_PolicySecret 3802 3803 0x00000151 3804 3805 2 3806 3807 TPM_CC_Rewrap 3808 3809 0x00000152 3810 3811 2 3812 3813 Family 2.0 3814 Level 00 Revision 00.99 3815 3816 Encrypt 3817 3818 Name 3819 3820 NV Write 3821 3822 Encrypted 3823 3824 Part 2: Structures 3825 3826 Physical Presence 3827 3828 Trusted Platform Module Library 3829 3830 2 3831 3832 PCR 3833 PCR 3834 3835 2 3836 3837 2 3838 3839 2 3840 3841 2 3842 2 3843 3844 O 3845 3846 2 3847 3848 2 3849 3850 2 3851 3852 2 3853 O 3854 3855 Comments 3856 3857 Policy 3858 3859 2 3860 3861 2 3862 3863 2 3864 3865 2 3866 3867 2 3868 O 3869 3870 Published 3871 Copyright TCG 2006-2013 3872 3873 2 3874 Policy 3875 2 3876 3877 Page 25 3878 October 31, 2013 3879 3880 Trusted Platform Module Library 3882 3883 Command 3884 Code 3885 3886 Encrypt 3887 3888 TPM_CC_Create 3889 3890 0x00000153 3891 3892 2 3893 3894 2 3895 3896 TPM_CC_ECDH_ZGen 3897 3898 0x00000154 3899 3900 2 3901 3902 2 3903 3904 TPM_CC_HMAC 3905 3906 0x00000155 3907 3908 2 3909 3910 2 3911 3912 TPM_CC_Import 3913 3914 0x00000156 3915 3916 2 3917 3918 2 3919 3920 TPM_CC_Load 3921 3922 0x00000157 3923 3924 2 3925 3926 2 3927 3928 TPM_CC_Quote 3929 3930 0x00000158 3931 3932 2 3933 3934 2 3935 3936 TPM_CC_RSA_Decrypt 3937 3938 0x00000159 3939 3940 TPM_CC_HMAC_Start 3941 3942 0x0000015B 3943 3944 2 3945 3946 TPM_CC_SequenceUpdate 3947 3948 0x0000015C 3949 3950 2 3951 3952 TPM_CC_Sign 3953 3954 0x0000015D 3955 3956 2 3957 3958 TPM_CC_Unseal 3959 3960 0x0000015E 3961 3962 TPM_CC_PolicySigned 3963 3964 0x00000160 3965 3966 TPM_CC_ContextLoad 3967 3968 0x00000161 3969 3970 O 3971 3972 Context 3973 3974 TPM_CC_ContextSave 3975 3976 0x00000162 3977 3978 O 3979 3980 Context 3981 3982 TPM_CC_ECDH_KeyGen 3983 3984 0x00000163 3985 3986 2 3987 3988 TPM_CC_EncryptDecrypt 3989 3990 0x00000164 3991 3992 2 3993 3994 TPM_CC_FlushContext 3995 3996 0x00000165 3997 3998 TPM_CC_LoadExternal 3999 4000 0x00000167 4001 4002 2 4003 4004 2 4005 4006 TPM_CC_MakeCredential 4007 4008 0x00000168 4009 4010 2 4011 4012 2 4013 4014 TPM_CC_NV_ReadPublic 4015 4016 0x00000169 4017 4018 TPM_CC_PolicyAuthorize 4019 4020 0x0000016A 4021 4022 TPM_CC_PolicyAuthValue 4023 4024 0x0000016B 4025 4026 Policy 4027 4028 TPM_CC_PolicyCommandCode 4029 4030 0x0000016C 4031 4032 Policy 4033 4034 TPM_CC_PolicyCounterTimer 4035 4036 0x0000016D 4037 4038 2 4039 4040 Policy 4041 4042 TPM_CC_PolicyCpHash 4043 4044 0x0000016E 4045 4046 2 4047 4048 Policy 4049 4050 TPM_CC_PolicyLocality 4051 4052 0x0000016F 4053 4054 TPM_CC_PolicyNameHash 4055 4056 0x00000170 4057 4058 TPM_CC_PolicyOR 4059 4060 0x00000171 4061 4062 TPM_CC_PolicyTicket 4063 4064 0x00000172 4065 4066 TPM_CC_ReadPublic 4067 4068 0x00000173 4069 4070 Page 26 4071 October 31, 2013 4072 4073 NV Write 4074 4075 Name 4076 4077 Encrypted 4078 4079 Physical Presence 4080 4081 Part 2: Structures 4082 4083 O 4084 4085 Comments 4086 4087 2 4088 2 4089 4090 2 4091 2 4092 4093 Policy 4094 4095 O 4096 4097 Context 4098 4099 NV 4100 2 4101 4102 Policy 4103 4104 Policy 4105 2 4106 4107 Policy 4108 Policy 4109 4110 2 4111 4112 Published 4113 Copyright TCG 2006-2013 4114 4115 Policy 4116 2 4117 4118 Family 2.0 4119 Level 00 Revision 00.99 4120 4121 Encrypt 4123 4124 2 4125 4126 NV Write 4127 4128 Encrypted 4129 4130 Part 2: Structures 4131 4132 Physical Presence 4133 4134 Trusted Platform Module Library 4135 4136 2 4137 4138 2 4139 4140 2 4141 4142 Name 4143 4144 Command 4145 Code 4146 4147 TPM_CC_RSA_Encrypt 4148 4149 0x00000174 4150 4151 TPM_CC_StartAuthSession 4152 4153 0x00000176 4154 4155 TPM_CC_VerifySignature 4156 4157 0x00000177 4158 4159 TPM_CC_ECC_Parameters 4160 4161 0x00000178 4162 4163 TPM_CC_FirmwareRead 4164 4165 0x00000179 4166 4167 TPM_CC_GetCapability 4168 4169 0x0000017A 4170 4171 TPM_CC_GetRandom 4172 4173 0x0000017B 4174 4175 TPM_CC_GetTestResult 4176 4177 0x0000017C 4178 4179 TPM_CC_Hash 4180 4181 0x0000017D 4182 4183 TPM_CC_PCR_Read 4184 4185 0x0000017E 4186 4187 PCR 4188 4189 TPM_CC_PolicyPCR 4190 4191 0x0000017F 4192 4193 Policy 4194 4195 TPM_CC_PolicyRestart 4196 4197 0x00000180 4198 4199 TPM_CC_ReadClock 4200 4201 0x00000181 4202 4203 TPM_CC_PCR_Extend 4204 4205 0x00000182 4206 4207 O 4208 4209 2 4210 4211 TPM_CC_PCR_SetAuthValue 4212 4213 0x00000183 4214 4215 N 4216 4217 2 4218 4219 TPM_CC_NV_Certify 4220 4221 0x00000184 4222 4223 O 4224 4225 TPM_CC_EventSequenceComplete 4226 4227 0x00000185 4228 4229 O 4230 4231 TPM_CC_HashSequenceStart 4232 4233 0x00000186 4234 4235 TPM_CC_PolicyPhysicalPresence 4236 4237 0x00000187 4238 4239 Policy 4240 4241 TPM_CC_PolicyDuplicationSelect 4242 4243 0x00000188 4244 4245 Policy 4246 4247 TPM_CC_PolicyGetDigest 4248 4249 0x00000189 4250 4251 Policy 4252 4253 TPM_CC_TestParms 4254 4255 0x0000018A 4256 4257 TPM_CC_Commit 4258 4259 0x0000018B 4260 4261 TPM_CC_PolicyPassword 4262 4263 0x0000018C 4264 4265 TPM_CC_ZGen_2Phase 4266 4267 0x0000018D 4268 4269 TPM_CC_EC_Ephemeral 4270 4271 0x0000018E 4272 4273 TPM_CC_PolicyNvWritten 4274 4275 0x0000018F 4276 4277 Policy 4278 4279 TPM_CC_LAST 4280 4281 0x0000018F 4282 4283 Compile variable. May increase 4284 based on implementation. 4285 4286 O 4287 4288 Comments 4289 4290 2 4291 4292 2 4293 4294 2 4295 4296 O 4297 4298 2 4299 4300 2 4301 4302 2 4303 Policy 4304 4305 2 4306 4307 2 4308 4309 NOTE 4310 4311 #TPM_RC_COMMAND_CODE 4312 4313 Family 2.0 4314 Level 00 Revision 00.99 4315 4316 Published 4317 Copyright TCG 2006-2013 4318 4319 This is not a FMT1 code 4320 and a parameter indicator 4321 value may not be added to 4322 4323 Page 27 4324 October 31, 2013 4325 4326 Encrypt 4328 4329 Encrypted 4330 4331 Command 4332 Code 4333 4334 Name 4335 4336 Physical Presence 4337 4338 Trusted Platform Module Library 4339 4340 NV Write 4341 4342 Part 2: Structures 4343 4344 Comments 4345 this value. 4346 4347 6.6 4348 4349 TPM_RC (Response Codes) 4350 4351 6.6.1 4352 4353 Description 4354 4355 Each return from the TPM has a 32-bit response code. The TPM will always set the upper 20 bits (31:12) 4356 of the response code to 0 00 0016 and the low-order 12 bits (11:00) will contain the response code. 4357 When a command succeeds, the TPM shall return TPM_RC_SUCCESS (0 0016) and will update any 4358 authorization-session nonce associated with the command. 4359 When a command fails to complete for any reason, the TPM shall return 4360 4361 4362 a TPM_ST (UINT16) with a value of TPM_TAG_RSP_COMMAND or TPM_ST_NO_SESSIONS, 4363 followed by 4364 4365 4366 4367 a UINT32 (responseSize) with a value of 10, followed by 4368 4369 4370 4371 a UINT32 containing a response code with a value other than TPM_RC_SUCCESS. 4372 4373 Commands defined in this specification will use a tag of either TPM_ST_NO_SESSIONS or 4374 TPM_ST_SESSIONS. Error responses will use a tag value of TPM_ST_NO_SESSIONS and the 4375 response code will be as defined in this specification. Commands that use tags defined in the TPM 1.2 4376 specification will use TPM_TAG_RSP_COMMAND in an error and a response code defined in TPM 1.2. 4377 If the tag of the command is not a recognized command tag, the TPM error response will differ depending 4378 on TPM 1.2 compatibility. If the TPM supports 1.2 compatibility, the TPM shall return a tag of 4379 TPM_TAG_RSP_COMMAND and an appropriate TPM 1.2 response code (TPM_BADTAG = 4380 00 00 00 1E16). If the TPM does not have compatibility with TPM 1.2, the TPM shall return 4381 TPM_ST_NO_SESSION and a response code of TPM_RC_TAG. 4382 When a command fails, the TPM shall not update the authorization-session nonces associated with the 4383 command and will not close the authorization sessions used by the command. Audit digests will not be 4384 updated on an error. Unless noted in the command actions, a command that returns an error shall leave 4385 the state of the TPM as if the command had not been attempted. The exception to this principle is that a 4386 failure due to an authorization failure may update the dictionary-attack protection values. 4387 4388 Page 28 4389 October 31, 2013 4390 4391 Published 4392 Copyright TCG 2006-2013 4393 4394 Family 2.0 4395 Level 00 Revision 00.99 4396 4397 Trusted Platform Module Library 4399 6.6.2 4400 4401 Part 2: Structures 4402 4403 Response Code Formats 4404 4405 The response codes for this specification are defined such that there is no overlap between the response 4406 codes used for this specification and those assigned in previous TPM specifications. 4407 The formats defined in this clause only apply when the tag for the response is TPM_ST_NO_SESSIONS. 4408 The response codes use two different format groups. One group contains the TPM 1.2 compatible 4409 response codes and the response codes for this specification that are not related to command 4410 parameters. The second group contains the errors that may be associated with a command parameter, 4411 handle, or session. 4412 Figure 2 shows the format for the response codes when bit 7 is zero. 4413 1 4414 1 4415 4416 1 4417 0 4418 4419 0 4420 9 4421 4422 0 4423 8 4424 4425 0 4426 7 4427 4428 S 4429 4430 bit 4431 4432 T 4433 4434 r 4435 4436 V 4437 4438 0 4439 6 4440 4441 0 4442 5 4443 4444 F 4445 4446 0 4447 4 4448 4449 0 4450 3 4451 4452 0 4453 2 4454 4455 0 4456 1 4457 4458 0 4459 0 4460 4461 E 4462 4463 Figure 2 Format-Zero Response Codes 4464 4465 Family 2.0 4466 Level 00 Revision 00.99 4467 4468 Published 4469 Copyright TCG 2006-2013 4470 4471 Page 29 4472 October 31, 2013 4473 4474 Part 2: Structures 4476 4477 Trusted Platform Module Library 4478 4479 The field definitions are: 4480 Table 12 Format-Zero Response Codes 4481 Bit 4482 4483 Name 4484 4485 Definition 4486 4487 06:00 4488 4489 E 4490 4491 the error number 4492 The interpretation of this field is dependent on the setting of the G and S fields. 4493 4494 07 4495 4496 F 4497 4498 format selector 4499 CLEAR when the format is as defined in this Table 12 or when the response code is 4500 TPM_RC_BAD_TAG. 4501 4502 08 4503 4504 V 4505 4506 version 4507 SET (1): The error number is defined in this specification and is returned when the response tag 4508 is TPM_ST_NO_SESSIONS. 4509 CLEAR (0): The error number is defined by a previous TPM specification. The error number is 4510 returned when the response tag is TPM_TAG_RSP_COMMAND. 4511 NOTE 4512 4513 09 4514 4515 In any error number returned by a TPM, the F (bit 7) and V (bit 8) attributes shall be CLEAR 4516 when the response tag is TPM_TAG_RSP_COMMAND value used in TPM 1.2. 4517 4518 Reserved shall be zero. 4519 4520 10 4521 4522 T 4523 4524 TCG/Vendor indicator 4525 SET (1): The response code is defined by the TPM vendor. 4526 CLEAR (0): The response code is defined by the TCG (a value in this specification). 4527 NOTE 4528 4529 11 4530 4531 S 4532 4533 This attribute does not indicate a vendor-specific code unless the F attribute (bit[07]) is CLEAR. 4534 4535 severity 4536 SET (1): The response code is a warning and the command was not necessarily in error. This 4537 command indicates that the TPM is busy or that the resources of the TPM have to be adjusted in 4538 order to allow the command to execute. 4539 CLEAR (0): The response code indicates that the command had an error that would prevent it 4540 from running. 4541 4542 When the format bit (bit 7) is SET, then the error occurred during the unmarshaling or validation of an 4543 input parameter to the TPM. Figure 3 shows the format for the response codes when bit 7 is one. 4544 bit 4545 4546 1 4547 1 4548 4549 1 4550 0 4551 4552 0 4553 9 4554 4555 N 4556 4557 0 4558 8 4559 4560 0 4561 7 4562 4563 0 4564 6 4565 4566 1 4567 4568 0 4569 5 4570 4571 P 4572 4573 0 4574 4 4575 4576 0 4577 3 4578 4579 0 4580 2 4581 4582 0 4583 1 4584 4585 0 4586 0 4587 4588 E 4589 4590 Figure 3 Format-One Response Codes 4591 There are 64 errors with this format. The errors can be associated with a parameter, handle, or session. 4592 The error number for this format is in bits[05:00]. When an error is associated with a parameter, 0 40 16 is 4593 added and N is set to the parameter number. 4594 For an error associated with a handle, a parameter number (1 to 7) is added to the N field. For an error 4595 associated with a session, a value of 8 plus the session number (1 to 7) is added to the N field. In other 4596 words, if P is clear, then a value of 0 to 7 in the N field will indicate a handle error, and a value of 8 15 4597 will indicate a session error. 4598 NOTE 4599 4600 If an implementation is not able to designate the handle, session, or parameter in error, then P and N will 4601 be zero. 4602 4603 Page 30 4604 October 31, 2013 4605 4606 Published 4607 Copyright TCG 2006-2013 4608 4609 Family 2.0 4610 Level 00 Revision 00.99 4611 4612 Trusted Platform Module Library 4614 4615 Part 2: Structures 4616 4617 The field definitions are: 4618 Table 13 Format-One Response Codes 4619 Bit 4620 4621 Name Definition 4622 4623 05:00 4624 4625 E 4626 4627 the error number 4628 The error number is independent of the other settings. 4629 4630 06 4631 4632 P 4633 4634 SET (1): The error is associated with a parameter. 4635 CLEAR (0): The error is associated with a handle or a session. 4636 4637 07 4638 4639 F 4640 4641 the response code format selector 4642 This field shall be SET for the format in this table. 4643 4644 11:08 4645 4646 N 4647 4648 the number of the handle, session, or parameter in error 4649 If P is SET, then this field is the parameter in error. If P is CLEAR, then this field indicates the 4650 handle or session in error. Handles use values of N between 0000 2 and 01112. Sessions use 4651 values between 10002 and 11112. 4652 4653 The groupings of response codes are determined by bits 08, 07, and 06 of the response code as 4654 summarized in Table 14. 4655 Table 14 Response Code Groupings 4656 Bit 4657 0 4658 8 4659 4660 0 4661 7 4662 4663 0 4664 6 4665 4666 Definition 4667 4668 0 4669 4670 0 4671 4672 x 4673 4674 a response code defined by TPM 1.2 4675 NOTE 4676 4677 An x in a column indicates that this may be either 0 or 1 and not affect the grouping of the response 4678 code. 4679 4680 1 4681 4682 0 4683 4684 x 4685 4686 a response code defined by this specification with no handle, session, or parameter number modifier 4687 4688 x 4689 4690 1 4691 4692 0 4693 4694 a response code defined by this specification with either a handle or session number modifier 4695 4696 x 4697 4698 1 4699 4700 1 4701 4702 a response code defined by this specification with a parameter number modifier 4703 4704 Family 2.0 4705 Level 00 Revision 00.99 4706 4707 Published 4708 Copyright TCG 2006-2013 4709 4710 Page 31 4711 October 31, 2013 4712 4713 Part 2: Structures 4715 6.6.3 4716 4717 Trusted Platform Module Library 4718 4719 TPM_RC Values 4720 4721 In general, response codes defined in Part 2 will be unmarshaling errors and will have the F (format) bit 4722 SET. Codes that are unique to Part 3 will have the F bit CLEAR but the V (version) attribute will be SET to 4723 indicate that it is a TPM 2.0 response code. 4724 NOTE 4725 4726 The constant RC_VER1 is used to indicate that the V attribute is SET and the constant RC_ FMT1 is used 4727 to indicate that the F attribute is SET and that the return code is variable based on handle, session, and 4728 parameter modifiers. 4729 4730 Table 15 Definition of (UINT32) TPM_RC Constants (Actions) <OUT> 4731 Name 4732 4733 Value 4734 4735 Description 4736 4737 TPM_RC_SUCCESS 4738 4739 0x000 4740 4741 TPM_RC_BAD_TAG 4742 4743 0x01E 4744 4745 defined for compatibility with TPM 1.2 4746 4747 RC_VER1 4748 4749 0x100 4750 4751 set for all format 0 response codes 4752 4753 TPM_RC_INITIALIZE 4754 4755 RC_VER1 + 0x000 4756 4757 TPM not initialized 4758 commands not being accepted because of a TPM 4759 failure 4760 4761 TPM_RC_FAILURE 4762 4763 RC_VER1 + 0x001 4764 4765 NOTE 4766 4767 TPM_RC_SEQUENCE 4768 4769 RC_VER1 + 0x003 4770 4771 improper use of a sequence handle 4772 4773 TPM_RC_PRIVATE 4774 4775 RC_VER1 + 0x00B 4776 4777 TPM_RC_HMAC 4778 4779 RC_VER1 + 0x019 4780 4781 TPM_RC_DISABLED 4782 4783 RC_VER1 + 0x020 4784 4785 TPM_RC_EXCLUSIVE 4786 4787 RC_VER1 + 0x021 4788 4789 command failed because audit sequence required 4790 exclusivity 4791 4792 TPM_RC_AUTH_TYPE 4793 4794 RC_VER1 + 0x024 4795 4796 authorization handle is not correct for command 4797 4798 TPM_RC_AUTH_MISSING 4799 4800 RC_VER1 + 0x025 4801 4802 command requires an authorization session for 4803 handle and it is not present. 4804 4805 TPM_RC_POLICY 4806 4807 RC_VER1 + 0x026 4808 4809 policy Failure In Math Operation or an invalid 4810 authPolicy value 4811 4812 TPM_RC_PCR 4813 4814 RC_VER1 + 0x027 4815 4816 PCR check fail 4817 4818 TPM_RC_PCR_CHANGED 4819 4820 RC_VER1 + 0x028 4821 4822 PCR have changed since checked. 4823 4824 TPM_RC_UPGRADE 4825 4826 RC_VER1 + 0x02D 4827 4828 for 4829 all 4830 commands 4831 other 4832 than 4833 TPM2_FieldUpgradeData(), this code indicates 4834 that the TPM is in field upgrade mode; for 4835 TPM2_FieldUpgradeData(), this code indicates 4836 that the TPM is not in field upgrade mode 4837 4838 TPM_RC_TOO_MANY_CONTEXTS 4839 4840 RC_VER1 + 0x02E 4841 4842 context ID counter is at maximum. 4843 4844 TPM_RC_AUTH_UNAVAILABLE 4845 4846 RC_VER1 + 0x02F 4847 4848 authValue or authPolicy is not available for 4849 selected entity. 4850 4851 TPM_RC_REBOOT 4852 4853 RC_VER1 + 0x030 4854 4855 a _TPM_Init and Startup(CLEAR) is required 4856 before the TPM can resume operation. 4857 4858 TPM_RC_UNBALANCED 4859 4860 RC_VER1 + 0x031 4861 4862 the protection algorithms (hash and symmetric) are 4863 not reasonably balanced. The digest size of the 4864 hash must be larger than the key size of the 4865 symmetric algorithm. 4866 4867 Page 32 4868 October 31, 2013 4869 4870 This 4871 may 4872 be 4873 returned 4874 by 4875 TPM2_GetTestResult() as the testResult 4876 parameter. 4877 4878 Published 4879 Copyright TCG 2006-2013 4880 4881 Family 2.0 4882 Level 00 Revision 00.99 4883 4884 Trusted Platform Module Library 4886 Name 4887 4888 Part 2: Structures 4889 Value 4890 4891 Description 4892 4893 TPM_RC_COMMAND_SIZE 4894 4895 RC_VER1 + 0x042 4896 4897 command commandSize value is inconsistent with 4898 contents of the command buffer; either the size is 4899 not the same as the octets loaded by the hardware 4900 interface layer or the value is not large enough to 4901 hold a command header 4902 4903 TPM_RC_COMMAND_CODE 4904 4905 RC_VER1 + 0x043 4906 4907 command code not supported 4908 4909 TPM_RC_AUTHSIZE 4910 4911 RC_VER1 + 0x044 4912 4913 the value of authorizationSize is out of range or the 4914 number of octets in the Authorization Area is 4915 greater than required 4916 4917 TPM_RC_AUTH_CONTEXT 4918 4919 RC_VER1 + 0x045 4920 4921 use of an authorization session with a context 4922 command 4923 4924 TPM_RC_NV_RANGE 4925 4926 RC_VER1 + 0x046 4927 4928 NV offset+size is out of range. 4929 4930 TPM_RC_NV_SIZE 4931 4932 RC_VER1 + 0x047 4933 4934 Requested allocation size is larger than allowed. 4935 4936 TPM_RC_NV_LOCKED 4937 4938 RC_VER1 + 0x048 4939 4940 NV access locked. 4941 4942 TPM_RC_NV_AUTHORIZATION 4943 4944 RC_VER1 + 0x049 4945 4946 NV access authorization fails in command actions 4947 (this failure does not affect lockout.action) 4948 4949 TPM_RC_NV_UNINITIALIZED 4950 4951 RC_VER1 + 0x04A 4952 4953 an NV Index is used before being initialized or the 4954 state saved by TPM2_Shutdown(STATE) could not 4955 be restored 4956 4957 TPM_RC_NV_SPACE 4958 4959 RC_VER1 + 0x04B 4960 4961 insufficient space for NV allocation 4962 4963 TPM_RC_NV_DEFINED 4964 4965 RC_VER1 + 0x04C 4966 4967 NV Index or persistend object already defined 4968 4969 TPM_RC_BAD_CONTEXT 4970 4971 RC_VER1 + 0x050 4972 4973 context in TPM2_ContextLoad() is not valid 4974 4975 TPM_RC_CPHASH 4976 4977 RC_VER1 + 0x051 4978 4979 cpHash value already set or not correct for use 4980 4981 TPM_RC_PARENT 4982 4983 RC_VER1 + 0x052 4984 4985 handle for parent is not a valid parent 4986 4987 TPM_RC_NEEDS_TEST 4988 4989 RC_VER1 + 0x053 4990 4991 some function needs testing. 4992 4993 TPM_RC_NO_RESULT 4994 4995 RC_VER1 + 0x054 4996 4997 returned when an internal function cannot process 4998 a request due to an unspecified problem. This 4999 code is usually related to invalid parameters that 5000 are not properly filtered by the input unmarshaling 5001 code. 5002 5003 TPM_RC_SENSITIVE 5004 5005 RC_VER1 + 0x055 5006 5007 the sensitive area did not unmarshal correctly after 5008 decryption this code is used in lieu of the other 5009 unmarshaling errors so that an attacker cannot 5010 determine where the unmarshaling error occurred 5011 5012 RC_MAX_FM0 5013 5014 RC_VER1 + 0x07F 5015 5016 largest version 1 code that is not a warning 5017 5018 New Subsection 5019 5020 RC_FMT1 5021 5022 0x080 5023 5024 This bit is SET in all format 1 response codes 5025 The codes in this group may have a value added to 5026 them to indicate the handle, session, or parameter 5027 to which they apply. 5028 5029 TPM_RC_ASYMMETRIC 5030 5031 RC_FMT1 + 0x001 5032 5033 asymmetric algorithm not supported or not correct 5034 5035 TPM_RC_ATTRIBUTES 5036 5037 RC_FMT1 + 0x002 5038 5039 inconsistent attributes 5040 5041 TPM_RC_HASH 5042 5043 RC_FMT1 + 0x003 5044 5045 hash algrithm not supported or not appropriate 5046 5047 TPM_RC_VALUE 5048 5049 RC_FMT1 + 0x004 5050 5051 value is out of range or is not correct for the 5052 context 5053 5054 TPM_RC_HIERARCHY 5055 5056 RC_FMT1 + 0x005 5057 5058 hierarchy is not enabled or is not correct for the 5059 use 5060 5061 Family 2.0 5062 Level 00 Revision 00.99 5063 5064 Published 5065 Copyright TCG 2006-2013 5066 5067 Page 33 5068 October 31, 2013 5069 5070 Part 2: Structures 5072 5073 Trusted Platform Module Library 5074 5075 Name 5076 5077 Value 5078 5079 Description 5080 5081 TPM_RC_KEY_SIZE 5082 5083 RC_FMT1 + 0x007 5084 5085 key size is not supported 5086 5087 TPM_RC_MGF 5088 5089 RC_FMT1 + 0x008 5090 5091 mask generation function not supported 5092 5093 TPM_RC_MODE 5094 5095 RC_FMT1 + 0x009 5096 5097 mode of operation not supported 5098 5099 TPM_RC_TYPE 5100 5101 RC_FMT1 + 0x00A 5102 5103 the type of the value is not appropriate for the use 5104 5105 TPM_RC_HANDLE 5106 5107 RC_FMT1 + 0x00B 5108 5109 the handle is not correct for the use 5110 5111 TPM_RC_KDF 5112 5113 RC_FMT1 + 0x00C 5114 5115 unsupported key derivation function or function not 5116 appropriate for use 5117 5118 TPM_RC_RANGE 5119 5120 RC_FMT1 + 0x00D 5121 5122 value was out of allowed range. 5123 5124 TPM_RC_AUTH_FAIL 5125 5126 RC_FMT1 + 0x00E 5127 5128 the authorization HMAC check failed and DA 5129 counter incremented 5130 5131 TPM_RC_NONCE 5132 5133 RC_FMT1 + 0x00F 5134 5135 invalid nonce size 5136 5137 TPM_RC_PP 5138 5139 RC_FMT1 + 0x010 5140 5141 authorization requires assertion of PP 5142 5143 TPM_RC_SCHEME 5144 5145 RC_FMT1 + 0x012 5146 5147 unsupported or incompatible scheme 5148 5149 TPM_RC_SIZE 5150 5151 RC_FMT1 + 0x015 5152 5153 structure is the wrong size 5154 5155 TPM_RC_SYMMETRIC 5156 5157 RC_FMT1 + 0x016 5158 5159 unsupported symmetric algorithm or key size, or 5160 not appropriate for instance 5161 5162 TPM_RC_TAG 5163 5164 RC_FMT1 + 0x017 5165 5166 incorrect structure tag 5167 5168 TPM_RC_SELECTOR 5169 5170 RC_FMT1 + 0x018 5171 5172 union selector is incorrect 5173 5174 TPM_RC_INSUFFICIENT 5175 5176 RC_FMT1 + 0x01A 5177 5178 the TPM was unable to unmarshal a value 5179 because there were not enough octets in the input 5180 buffer 5181 5182 TPM_RC_SIGNATURE 5183 5184 RC_FMT1 + 0x01B 5185 5186 the signature is not valid 5187 5188 TPM_RC_KEY 5189 5190 RC_FMT1 + 0x01C 5191 5192 key fields are not compatible with the selected use 5193 5194 TPM_RC_POLICY_FAIL 5195 5196 RC_FMT1 + 0x01D 5197 5198 a policy check failed 5199 5200 TPM_RC_INTEGRITY 5201 5202 RC_FMT1 + 0x01F 5203 5204 integrity check failed 5205 5206 TPM_RC_TICKET 5207 5208 RC_FMT1 + 0x020 5209 5210 invalid ticket 5211 5212 TPM_RC_RESERVED_BITS 5213 5214 RC_FMT1 + 0x021 5215 5216 reserved bits not set to zero as required 5217 5218 TPM_RC_BAD_AUTH 5219 5220 RC_FMT1 + 0x022 5221 5222 authroization failure without DA implications 5223 5224 TPM_RC_EXPIRED 5225 5226 RC_FMT1 + 0x023 5227 5228 the policy has expired 5229 5230 TPM_RC_POLICY_CC 5231 5232 RC_FMT1 + 0x024 5233 5234 the commandCode in the policy is not the 5235 commandCode of the command or the command 5236 code in a policy command references a command 5237 that is not implemented 5238 5239 TPM_RC_BINDING 5240 5241 RC_FMT1 + 0x025 5242 5243 public and sensitive portions of an object are not 5244 cryptographically bound 5245 5246 TPM_RC_CURVE 5247 5248 RC_FMT1 + 0x026 5249 5250 curve not supported 5251 5252 TPM_RC_ECC_POINT 5253 5254 RC_FMT1 + 0x027 5255 5256 point is not on the required curve. 5257 5258 New Subsection 5259 RC_WARN 5260 5261 0x900 5262 5263 set for warning response codes 5264 5265 TPM_RC_CONTEXT_GAP 5266 5267 RC_WARN + 0x001 5268 5269 gap for context ID is too large 5270 5271 TPM_RC_OBJECT_MEMORY 5272 5273 RC_WARN + 0x002 5274 5275 out of memory for object contexts 5276 5277 Page 34 5278 October 31, 2013 5279 5280 Published 5281 Copyright TCG 2006-2013 5282 5283 Family 2.0 5284 Level 00 Revision 00.99 5285 5286 Trusted Platform Module Library 5288 5289 Part 2: Structures 5290 5291 Name 5292 5293 Value 5294 5295 Description 5296 5297 TPM_RC_SESSION_MEMORY 5298 5299 RC_WARN + 0x003 5300 5301 out of memory for session contexts 5302 5303 TPM_RC_MEMORY 5304 5305 RC_WARN + 0x004 5306 5307 out of shared object/session memory or need 5308 space for internal operations 5309 5310 TPM_RC_SESSION_HANDLES 5311 5312 RC_WARN + 0x005 5313 5314 out of session handles a session must be flushed 5315 before a new session may be created 5316 out of object handles the handle space for 5317 objects is depleted and a reboot is required 5318 NOTE 5319 5320 This cannot occur 5321 implementation. 5322 5323 NOTE 5324 5325 There is no reason why an implementation 5326 would implement a design that would deplete 5327 handle space. Platform specifications are 5328 encouraged to forbid it. 5329 5330 TPM_RC_OBJECT_HANDLES 5331 5332 RC_WARN + 0x006 5333 5334 TPM_RC_LOCALITY 5335 5336 RC_WARN + 0x007 5337 5338 TPM_RC_YIELDED 5339 5340 RC_WARN + 0x008 5341 5342 on 5343 5344 the 5345 5346 reference 5347 5348 bad locality 5349 the TPM has suspended operation on the 5350 command; forward progress was made and the 5351 command may be retried. 5352 See Part 1, Multi-tasking. 5353 NOTE 5354 5355 This cannot occur 5356 implementation. 5357 5358 on 5359 5360 the 5361 5362 reference 5363 5364 TPM_RC_CANCELED 5365 5366 RC_WARN + 0x009 5367 5368 the command was canceled 5369 5370 TPM_RC_TESTING 5371 5372 RC_WARN + 0x00A 5373 5374 TPM is performing self-tests 5375 5376 TPM_RC_REFERENCE_H0 5377 5378 RC_WARN + 0x010 5379 5380 the 1 handle in the handle area references a 5381 transient object or session that is not loaded 5382 5383 TPM_RC_REFERENCE_H1 5384 5385 RC_WARN + 0x011 5386 5387 the 2 handle in the handle area references a 5388 transient object or session that is not loaded 5389 5390 TPM_RC_REFERENCE_H2 5391 5392 RC_WARN + 0x012 5393 5394 the 3 handle in the handle area references a 5395 transient object or session that is not loaded 5396 5397 TPM_RC_REFERENCE_H3 5398 5399 RC_WARN + 0x013 5400 5401 the 4 handle in the handle area references a 5402 transient object or session that is not loaded 5403 5404 TPM_RC_REFERENCE_H4 5405 5406 RC_WARN + 0x014 5407 5408 the 5 handle in the handle area references a 5409 transient object or session that is not loaded 5410 5411 TPM_RC_REFERENCE_H5 5412 5413 RC_WARN + 0x015 5414 5415 the 6 handle in the handle area references a 5416 transient object or session that is not loaded 5417 5418 TPM_RC_REFERENCE_H6 5419 5420 RC_WARN + 0x016 5421 5422 the 7 handle in the handle area references a 5423 transient object or session that is not loaded 5424 5425 TPM_RC_REFERENCE_S0 5426 5427 RC_WARN + 0x018 5428 5429 the 1 authorization session handle references a 5430 session that is not loaded 5431 5432 TPM_RC_REFERENCE_S1 5433 5434 RC_WARN + 0x019 5435 5436 the 2 authorization session handle references a 5437 session that is not loaded 5438 5439 TPM_RC_REFERENCE_S2 5440 5441 RC_WARN + 0x01A 5442 5443 the 3 authorization session handle references a 5444 session that is not loaded 5445 5446 TPM_RC_REFERENCE_S3 5447 5448 RC_WARN + 0x01B 5449 5450 the 4th authorization session handle references a 5451 session that is not loaded 5452 5453 TPM_RC_REFERENCE_S4 5454 5455 RC_WARN + 0x01C 5456 5457 the 5 session handle references a session that is 5458 not loaded 5459 5460 TPM_RC_REFERENCE_S5 5461 5462 RC_WARN + 0x01D 5463 5464 the 6 session handle references a session that is 5465 not loaded 5466 5467 st 5468 5469 nd 5470 5471 rd 5472 5473 th 5474 5475 th 5476 5477 th 5478 5479 th 5480 5481 st 5482 5483 nd 5484 5485 rd 5486 5487 th 5488 5489 th 5490 5491 Family 2.0 5492 Level 00 Revision 00.99 5493 5494 Published 5495 Copyright TCG 2006-2013 5496 5497 Page 35 5498 October 31, 2013 5499 5500 Part 2: Structures 5502 5503 Trusted Platform Module Library 5504 5505 Name 5506 5507 Value 5508 5509 Description 5510 5511 TPM_RC_REFERENCE_S6 5512 5513 RC_WARN + 0x01E 5514 5515 the 7 authorization session handle references a 5516 session that is not loaded 5517 5518 TPM_RC_NV_RATE 5519 5520 RC_WARN + 0x020 5521 5522 the TPM is rate-limiting accesses to prevent 5523 wearout of NV 5524 5525 TPM_RC_LOCKOUT 5526 5527 RC_WARN + 0x021 5528 5529 authorizations for objects subject to DA protection 5530 are not allowed at this time because the TPM is in 5531 DA lockout mode 5532 5533 TPM_RC_RETRY 5534 5535 RC_WARN + 0x022 5536 5537 the TPM was not able to start the command 5538 5539 TPM_RC_NV_UNAVAILABLE 5540 5541 RC_WARN + 0x023 5542 5543 the command may require writing of NV and NV is 5544 not current accessible 5545 5546 TPM_RC_NOT_USED 5547 5548 RC_WARN + 0x7F 5549 5550 this value is reserved and shall not be returned by 5551 the TPM 5552 5553 th 5554 5555 Additional Defines 5556 TPM_RC_H 5557 5558 0x000 5559 5560 add to a handle-related error 5561 5562 TPM_RC_P 5563 5564 0x040 5565 5566 add to a parameter-related error 5567 5568 TPM_RC_S 5569 5570 0x800 5571 5572 add to a session-related error 5573 5574 TPM_RC_1 5575 5576 0x100 5577 5578 add to a parameter-, handle-, or session-related 5579 error 5580 5581 TPM_RC_2 5582 5583 0x200 5584 5585 add to a parameter-, handle-, or session-related 5586 error 5587 5588 TPM_RC_3 5589 5590 0x300 5591 5592 add to a parameter-, handle-, or session-related 5593 error 5594 5595 TPM_RC_4 5596 5597 0x400 5598 5599 add to a parameter-, handle-, or session-related 5600 error 5601 5602 TPM_RC_5 5603 5604 0x500 5605 5606 add to a parameter-, handle-, or session-related 5607 error 5608 5609 TPM_RC_6 5610 5611 0x600 5612 5613 add to a parameter-, handle-, or session-related 5614 error 5615 5616 TPM_RC_7 5617 5618 0x700 5619 5620 add to a parameter-, handle-, or session-related 5621 error 5622 5623 TPM_RC_8 5624 5625 0x800 5626 5627 add to a parameter-related error 5628 5629 TPM_RC_9 5630 5631 0x900 5632 5633 add to a parameter-related error 5634 5635 TPM_RC_A 5636 5637 0xA00 5638 5639 add to a parameter-related error 5640 5641 TPM_RC_B 5642 5643 0xB00 5644 5645 add to a parameter-related error 5646 5647 TPM_RC_C 5648 5649 0xC00 5650 5651 add to a parameter-related error 5652 5653 TPM_RC_D 5654 5655 0xD00 5656 5657 add to a parameter-related error 5658 5659 TPM_RC_E 5660 5661 0xE00 5662 5663 add to a parameter-related error 5664 5665 TPM_RC_F 5666 5667 0xF00 5668 5669 add to a parameter-related error 5670 5671 TPM_RC_N_MASK 5672 5673 0xF00 5674 5675 number mask 5676 5677 Page 36 5678 October 31, 2013 5679 5680 Published 5681 Copyright TCG 2006-2013 5682 5683 Family 2.0 5684 Level 00 Revision 00.99 5685 5686 Trusted Platform Module Library 5688 6.7 5689 5690 Part 2: Structures 5691 5692 TPM_CLOCK_ADJUST 5693 5694 A TPM_CLOCK_ADJUST value is used to change the rate at which the TPM internal oscillator is divided. 5695 A change to the divider will change the rate at which Clock and Time change. 5696 NOTE 5697 5698 The recommended adjustments are approximately 1% for a course adjustment, 0.1% for a medium 5699 adjustment, and the minimum possible on the implementation for the fine adjustment (e.g., one count of 5700 the pre-scalar if possible). 5701 5702 Table 16 Definition of (INT8) TPM_CLOCK_ADJUST Constants <IN> 5703 Name 5704 5705 Value 5706 5707 Comments 5708 5709 TPM_CLOCK_COARSE_SLOWER 5710 5711 -3 5712 5713 Slow the Clock update rate by one coarse adjustment step. 5714 5715 TPM_CLOCK_MEDIUM_SLOWER 5716 5717 -2 5718 5719 Slow the Clock update rate by one medium adjustment step. 5720 5721 TPM_CLOCK_FINE_SLOWER 5722 5723 -1 5724 5725 Slow the Clock update rate by one fine adjustment step. 5726 5727 TPM_CLOCK_NO_CHANGE 5728 5729 0 5730 5731 No change to the Clock update rate. 5732 5733 TPM_CLOCK_FINE_FASTER 5734 5735 1 5736 5737 Speed the Clock update rate by one fine adjustment step. 5738 5739 TPM_CLOCK_MEDIUM_FASTER 5740 5741 2 5742 5743 Speed the Clock update rate by one medium adjustment step. 5744 5745 TPM_CLOCK_COARSE_FASTER 5746 5747 3 5748 5749 Speed the Clock update rate by one coarse adjustment step. 5750 5751 #TPM_RC_VALUE 5752 5753 6.8 5754 5755 TPM_EO (EA Arithmetic Operands) 5756 Table 17 Definition of (UINT16) TPM_EO Constants <IN/OUT> 5757 5758 Operation Name 5759 5760 Value 5761 5762 Comments 5763 5764 TPM_EO_EQ 5765 5766 0x0000 5767 5768 A=B 5769 5770 TPM_EO_NEQ 5771 5772 0x0001 5773 5774 AB 5775 5776 TPM_EO_SIGNED_GT 5777 5778 0x0002 5779 5780 A > B signed 5781 5782 TPM_EO_UNSIGNED_GT 5783 5784 0x0003 5785 5786 A > B unsigned 5787 5788 TPM_EO_SIGNED_LT 5789 5790 0x0004 5791 5792 A < B signed 5793 5794 TPM_EO_UNSIGNED_LT 5795 5796 0x0005 5797 5798 A < B unsigned 5799 5800 TPM_EO_SIGNED_GE 5801 5802 0x0006 5803 5804 A B signed 5805 5806 TPM_EO_UNSIGNED_GE 5807 5808 0x0007 5809 5810 A B unsigned 5811 5812 TPM_EO_SIGNED_LE 5813 5814 0x0008 5815 5816 A B signed 5817 5818 TPM_EO_UNSIGNED_LE 5819 5820 0x0009 5821 5822 A B unsigned 5823 5824 TPM_EO_BITSET 5825 5826 0x000A 5827 5828 All bits SET in B are SET in A. ((A&B)=B) 5829 5830 TPM_EO_BITCLEAR 5831 5832 0x000B 5833 5834 All bits SET in B are CLEAR in A. ((A&B)=0) 5835 5836 #TPM_RC_VALUE 5837 5838 Family 2.0 5839 Level 00 Revision 00.99 5840 5841 Response code returned when unmarshaling of this type fails 5842 5843 Published 5844 Copyright TCG 2006-2013 5845 5846 Page 37 5847 October 31, 2013 5848 5849 Part 2: Structures 5851 5852 6.9 5853 5854 Trusted Platform Module Library 5855 5856 TPM_ST (Structure Tags) 5857 5858 Structure tags are used to disambiguate structures. They are 16-bit values with the most significant bit 5859 SET so that they do not overlap TPM_ALG_ID values. A single exception is made for the value 5860 associated with TPM_ST_RSP_COMMAND (0x00C4), which has the same value as the 5861 TPM_TAG_RSP_COMMAND tag from earlier versions of this specification. This value is used when the 5862 TPM is compatible with a previous TPM specification and the TPM cannot determine which family of 5863 response code to return because the command tag is not valid. 5864 Many of the structures defined in this document have parameters that are unions of other structures. That 5865 is, a parameter may be one of several structures. The parameter will have a selector value that indicates 5866 which of the options is actually present. 5867 In order to allow the marshaling and unmarshaling code to determine which of the possible structures is 5868 allowed, each selector will have a unique interface type and will constrain the number of possible tag 5869 values. 5870 Table 18 defines the structure tags values. The definition of many structures is context-sensitive using an 5871 algorithm ID. In cases where an algorithm ID is not a meaningful way to designate the structure, the 5872 values in this table are used. 5873 Table 18 Definition of (UINT16) TPM_ST Constants <IN/OUT, S> 5874 Name 5875 TPM_ST_RSP_COMMAND 5876 5877 Value 5878 5879 Comments 5880 5881 0x00C4 5882 5883 5884 TPM_ST_NULL 5885 5886 0X8000 5887 5888 no structure type specified 5889 5890 TPM_ST_NO_SESSIONS 5891 5892 0x8001 5893 5894 tag value for a command/response for a command 5895 defined in this specification; indicating that the 5896 command/response has no attached sessions and no 5897 authorizationSize/parameterSize value is present 5898 If the responseCode from the TPM is not 5899 TPM_RC_SUCCESS, then the response tag shall 5900 have this value. 5901 5902 TPM_ST_SESSIONS 5903 5904 0x8002 5905 5906 tag value for a command/response for a command 5907 defined in this specification; indicating that the 5908 command/response has one or more attached 5909 sessions and the authorizationSize/parameterSize 5910 field is present 5911 5912 Page 38 5913 October 31, 2013 5914 5915 Published 5916 Copyright TCG 2006-2013 5917 5918 Family 2.0 5919 Level 00 Revision 00.99 5920 5921 Trusted Platform Module Library 5923 Name 5924 reserved 5925 5926 Part 2: Structures 5927 Value 5928 5929 Comments 5930 5931 0x8003 5932 5933 When used between application software and the TPM 5934 resource manager, this tag indicates that the 5935 command has no sessions and the handles are using 5936 the Name format rather than the 32-bit handle format. 5937 NOTE 1 5938 5939 The response to application software will have a 5940 tag of TPM_ST_NO_SESSIONS. 5941 5942 Between the TRM and TPM, this tag would occur in a 5943 response from a TPM that overlaps the tag parameter 5944 of a request with the tag parameter of a response, 5945 when the response has no associated sessions. 5946 NOTE 2 5947 5948 reserved 5949 5950 0x8004 5951 5952 This tag is not used by all TPM or TRM 5953 implementations. 5954 5955 When used between application software and the TPM 5956 resource manager, this tag indicates that the 5957 command has sessions and the handles are using the 5958 Name format rather than the 32-bit handle format. 5959 NOTE 1 5960 5961 If the command completes successfully, the 5962 response to application software will have a tag 5963 of TPM_ST_SESSIONS. 5964 5965 Between the TRM and TPM, would occur in a 5966 response from a TPM that overlaps the tag parameter 5967 of a request with the tag parameter of a response, 5968 when the response has authorization sessions. 5969 NOTE 2 5970 5971 This tag is not used by all TPM or TRM 5972 implementations. 5973 5974 TPM_ST_ATTEST_NV 5975 5976 0x8014 5977 5978 tag for an attestation structure 5979 5980 TPM_ST_ATTEST_COMMAND_AUDIT 5981 5982 0x8015 5983 5984 tag for an attestation structure 5985 5986 TPM_ST_ATTEST_SESSION_AUDIT 5987 5988 0x8016 5989 5990 tag for an attestation structure 5991 5992 TPM_ST_ATTEST_CERTIFY 5993 5994 0x8017 5995 5996 tag for an attestation structure 5997 5998 TPM_ST_ATTEST_QUOTE 5999 6000 0x8018 6001 6002 tag for an attestation structure 6003 6004 TPM_ST_ATTEST_TIME 6005 6006 0x8019 6007 6008 tag for an attestation structure 6009 6010 TPM_ST_ATTEST_CREATION 6011 6012 0x801A 6013 6014 tag for an attestation structure 6015 6016 reserved 6017 6018 0x801B 6019 6020 do not use 6021 NOTE 6022 6023 This 6024 was 6025 previously 6026 assigned 6027 to 6028 TPM_ST_ATTEST_NV. The tag is changed 6029 because the structure has changed 6030 6031 TPM_ST_CREATION 6032 6033 0x8021 6034 6035 tag for a ticket type 6036 6037 TPM_ST_VERIFIED 6038 6039 0x8022 6040 6041 tag for a ticket type 6042 6043 TPM_ST_AUTH_SECRET 6044 6045 0x8023 6046 6047 tag for a ticket type 6048 6049 TPM_ST_HASHCHECK 6050 6051 0x8024 6052 6053 tag for a ticket type 6054 6055 TPM_ST_AUTH_SIGNED 6056 6057 0x8025 6058 6059 tag for a ticket type 6060 6061 TPM_ST_FU_MANIFEST 6062 6063 0x8029 6064 6065 tag for a structure describing a Field Upgrade Policy 6066 6067 Family 2.0 6068 Level 00 Revision 00.99 6069 6070 Published 6071 Copyright TCG 2006-2013 6072 6073 Page 39 6074 October 31, 2013 6075 6076 Part 2: Structures 6078 6079 Trusted Platform Module Library 6080 6081 6.10 TPM_SU (Startup Type) 6082 These values are used in TPM2_Startup() to indicate the shutdown and startup mode. The defined 6083 startup sequences are: 6084 a) TPM Reset Two cases: 6085 1) Shutdown(CLEAR) followed by Startup(CLEAR) 6086 2) Startup(CLEAR) with no Shutdown() 6087 b) TPM Restart Shutdown(STATE) followed by Startup(CLEAR) 6088 c) TPM Resume Shutdown(STATE) followed by Startup(STATE) 6089 TPM_SU values of 80 0016 and above are reserved for internal use of the TPM and may not be assigned 6090 values. 6091 NOTE 6092 6093 In the reference code, a value of FF FF 16 indicates that the startup state has not been set. If this was 6094 defined in this table to be, say, TPM_SU_NONE, then TPM_SU_NONE would be a valid input value but 6095 the caller is not allowed to indicate the that the startup type is TPM_SU_NONE so the reserved value is 6096 defined in the implementation as required for internal TPM uses. 6097 6098 Table 19 Definition of (UINT16) TPM_SU Constants <IN> 6099 Name 6100 6101 Value 6102 6103 Description 6104 6105 TPM_SU_CLEAR 6106 6107 0x0000 6108 6109 on TPM2_Shutdown(), indicates that the TPM should prepare 6110 for loss of power and save state required for an orderly startup 6111 (TPM Reset). 6112 on TPM2_Startup(), indicates that the TPM should start from 6113 perform TPM Reset or TPM Restart 6114 6115 TPM_SU_STATE 6116 6117 0x0001 6118 6119 on TPM2_Shutdown(), indicates that the TPM should prepare 6120 for loss of power and save state required for an orderly startup 6121 (TPM Restart or TPM Resume) 6122 on TPM2_Startup(), indicates that the TPM should restore the 6123 state saved by TPM2_Shutdown(TPM_SU_STATE) 6124 6125 #TPM_RC_VALUE 6126 6127 response code when incorrect value is used 6128 6129 6.11 TPM_SE (Session Type) 6130 This type is used in TPM2_StartAuthSession() to indicate the type of the session to be created. 6131 Table 20 Definition of (UINT8) TPM_SE Constants <IN> 6132 Name 6133 6134 Value 6135 6136 TPM_SE_HMAC 6137 6138 0x00 6139 6140 TPM_SE_POLICY 6141 6142 0x01 6143 6144 TPM_SE_TRIAL 6145 6146 0x03 6147 6148 #TPM_RC_VALUE 6149 6150 Page 40 6151 October 31, 2013 6152 6153 Description 6154 6155 The policy session is being used to compute the policyHash and 6156 not for command authorization. 6157 This setting modifies some policy commands and prevents 6158 session from being used to authorize a command. 6159 response code when incorrect value is used 6160 6161 Published 6162 Copyright TCG 2006-2013 6163 6164 Family 2.0 6165 Level 00 Revision 00.99 6166 6167 Trusted Platform Module Library 6169 6170 Part 2: Structures 6171 6172 6.12 TPM_CAP (Capabilities) 6173 The TPM_CAP values are used in TPM2_GetCapability() to select the type of the value to be returned. 6174 The format of the response varies according to the type of the value. 6175 Table 21 Definition of (UINT32) TPM_CAP Constants 6176 Capability Name 6177 6178 Value 6179 6180 Property Type 6181 6182 Return Type 6183 6184 TPM_CAP_FIRST 6185 6186 0x00000000 6187 6188 TPM_CAP_ALGS 6189 6190 0x00000000 6191 6192 TPM_CAP_HANDLES 6193 6194 0x00000001 6195 6196 TPML_HANDLE 6197 6198 TPM_CAP_COMMANDS 6199 6200 0x00000002 6201 6202 TPML_CCA 6203 6204 TPM_CAP_PP_COMMANDS 6205 6206 0x00000003 6207 6208 TPML_CC 6209 6210 TPM_CAP_AUDIT_COMMANDS 6211 6212 0x00000004 6213 6214 TPML_CC 6215 6216 TPM_CAP_PCRS 6217 6218 0x00000005 6219 6220 TPML_PCR_SELECTION 6221 6222 TPM_CAP_TPM_PROPERTIES 6223 6224 0x00000006 6225 6226 TPML_TAGGED_TPM_PROPERTY 6227 6228 TPM_CAP_PCR_PROPERTIES 6229 6230 0x00000007 6231 6232 (1) 6233 6234 TPM_CAP_ECC_CURVES 6235 6236 0x00000008 6237 6238 TPML_ALG_PROPERTY 6239 6240 TPML_TAGGED_PCR_PROPERTY 6241 (1) 6242 6243 TPM_CAP_LAST 6244 6245 0x00000008 6246 6247 TPM_CAP_VENDOR_PROPERTY 6248 0x00000100 6249 6250 TPML_ECC_CURVE 6251 6252 manufacturer-specific values 6253 6254 #TPM_RC_VALUE 6255 NOTES: 6256 (1) The TPM_ALG_ID or TPM_ECC_CURVE is cast to a UINT32 6257 6258 6.13 TPM_PT (Property Tag) 6259 The TPM_PT constants are used in TPM2_GetCapability(capability = TPM_CAP_TPM_PROPERTIES) to 6260 indicate the property being selected or returned. 6261 The values in the fixed group (PT_FIXED) are not changeable through programmatic means other than a 6262 firmware update. The values in the variable group (PT_VAR) may be changed with TPM commands but 6263 should be persistent over power cycles and only changed when indicated by the detailed actions code. 6264 Table 22 Definition of (UINT32) TPM_PT Constants <IN/OUT, S> 6265 Capability Name 6266 6267 Value 6268 6269 Comments 6270 6271 TPM_PT_NONE 6272 6273 0x00000000 6274 6275 indicates no property type 6276 6277 PT_GROUP 6278 6279 0x00000100 6280 6281 The number of properties in each group. 6282 NOTE The first group with any properties is group 1 6283 (PT_GROUP * 1). Group 0 is reserved. 6284 6285 PT_FIXED 6286 6287 PT_GROUP * 1 6288 the 6289 group 6290 of 6291 fixed 6292 properties 6293 returned 6294 as 6295 TPMS_TAGGED_PROPERTY 6296 The values in this group are only changed due to a 6297 firmware change in the TPM. 6298 6299 TPM_PT_FAMILY_INDICATOR 6300 6301 PT_FIXED + 0 6302 a 4-octet character string containing the TPM Family value 6303 (TPM_SPEC_FAMILY) 6304 6305 Family 2.0 6306 Level 00 Revision 00.99 6307 6308 Published 6309 Copyright TCG 2006-2013 6310 6311 Page 41 6312 October 31, 2013 6313 6314 Part 2: Structures 6316 6317 Capability Name 6318 TPM_PT_LEVEL 6319 6320 Trusted Platform Module Library 6321 6322 Value 6323 6324 Comments 6325 6326 PT_FIXED + 1 6327 the level of the specification 6328 NOTE 1 6329 6330 TPM_PT_REVISION 6331 6332 PT_FIXED + 2 6333 For this specification, the level is zero. 6334 6335 NOTE 2 6336 6337 The level is on the title page of the specification. 6338 6339 the specification Revision times 100 6340 EXAMPLE Revision 01.01 would have a value of 101. 6341 NOTE 6342 6343 TPM_PT_DAY_OF_YEAR 6344 6345 PT_FIXED + 3 6346 The Revision value is on the title page of the 6347 specification. 6348 6349 the specification day of year using TCG calendar 6350 EXAMPLE November 15, 2010, has a day of year value of 319 6351 (00 00 01 3F16). 6352 NOTE 6353 6354 TPM_PT_YEAR 6355 6356 PT_FIXED + 4 6357 The specification date is on the title page of the 6358 specification. 6359 6360 the specification year using the CE 6361 EXAMPLE The year 2010 has a value of 00 00 07 DA16. 6362 NOTE 6363 6364 The specification date is on the title page of the 6365 specification. 6366 6367 TPM_PT_MANUFACTURER 6368 6369 PT_FIXED + 5 6370 the vendor ID unique to each TPM manufacturer 6371 6372 TPM_PT_VENDOR_STRING_1 6373 6374 PT_FIXED + 6 6375 the first four characters of the vendor ID string 6376 NOTE 6377 6378 When the vendor string is fewer than 16 octets, the 6379 additional property values do not have to be present. 6380 A vendor string of 4 octets can be represented in one 6381 32-bit value and no null terminating character is 6382 required. 6383 6384 TPM_PT_VENDOR_STRING_2 6385 6386 PT_FIXED + 7 6387 the second four characters of the vendor ID string 6388 6389 TPM_PT_VENDOR_STRING_3 6390 6391 PT_FIXED + 8 6392 the third four characters of the vendor ID string 6393 6394 TPM_PT_VENDOR_STRING_4 6395 6396 PT_FIXED + 9 6397 the fourth four characters of the vendor ID sting 6398 6399 TPM_PT_VENDOR_TPM_TYPE 6400 6401 PT_FIXED + 10 6402 vendor-defined value indicating the TPM model 6403 6404 TPM_PT_FIRMWARE_VERSION_1 6405 6406 PT_FIXED + 11 6407 the most-significant 32 bits of a vendor-specific value 6408 indicating the version of the firmware 6409 6410 TPM_PT_FIRMWARE_VERSION_2 6411 6412 PT_FIXED + 12 6413 the least-significant 32 bits of a vendor-specific value 6414 indicating the version of the firmware 6415 6416 TPM_PT_INPUT_BUFFER 6417 6418 PT_FIXED + 13 6419 the maximum size of 6420 TPM2B_MAX_BUFFER) 6421 6422 TPM_PT_HR_TRANSIENT_MIN 6423 6424 PT_FIXED + 14 6425 the minimum number of transient objects that can be held 6426 in TPM RAM 6427 NOTE 6428 6429 TPM_PT_HR_PERSISTENT_MIN 6430 6431 PT_FIXED + 15 6432 parameter 6433 6434 (typically, 6435 6436 a 6437 6438 This minimum shall be no less than the minimum 6439 value required by the platform-specific specification 6440 to which the TPM is built. 6441 6442 the minimum number of persistent objects that can be 6443 held in TPM NV memory 6444 NOTE 6445 6446 TPM_PT_HR_LOADED_MIN 6447 6448 PT_FIXED + 16 6449 a 6450 6451 This minimum shall be no less than the minimum 6452 value required by the platform-specific specification 6453 to which the TPM is built. 6454 6455 the minimum number of authorization sessions that can 6456 be held in TPM RAM 6457 NOTE 6458 6459 Page 42 6460 October 31, 2013 6461 6462 This minimum shall be no less than the minimum 6463 value required by the platform-specific specification 6464 to which the TPM is built. 6465 6466 Published 6467 6468 Family 2.0 6469 6470 Copyright TCG 2006-2013 6471 6472 Level 00 Revision 00.99 6473 6474 Trusted Platform Module Library 6476 Capability Name 6477 TPM_PT_ACTIVE_SESSIONS_MAX 6478 6479 Part 2: Structures 6480 Value 6481 6482 Comments 6483 6484 PT_FIXED + 17 6485 the number of authorization sessions that may be active at 6486 a time 6487 A session is active when it has a context associated with 6488 its handle. The context may either be in TPM RAM or be 6489 context saved. 6490 NOTE 6491 6492 This value shall be no less than the minimum value 6493 required by the platform-specific specification to 6494 which the TPM is built. 6495 6496 TPM_PT_PCR_COUNT 6497 6498 PT_FIXED + 18 6499 the number of PCR implemented 6500 NOTE This number is determined by the defined 6501 attributes, not the number of PCR that are populated. 6502 6503 TPM_PT_PCR_SELECT_MIN 6504 6505 PT_FIXED + 19 6506 the 6507 minimum 6508 number 6509 of 6510 TPMS_PCR_SELECT.sizeOfSelect 6511 NOTE 6512 6513 TPM_PT_CONTEXT_GAP_MAX 6514 6515 PT_FIXED + 20 6516 octets 6517 6518 in 6519 6520 a 6521 6522 This value is not determined by the number of PCR 6523 implemented but by the number of PCR required by 6524 the platform-specific specification with which the TPM 6525 is compliant. 6526 6527 the maximum allowed difference (unsigned) between the 6528 contextID values of two saved session contexts 6529 16 6530 6531 This value shall be at least 2 -1 (65535). 6532 PT_FIXED + 21 6533 skipped 6534 TPM_PT_NV_COUNTERS_MAX 6535 6536 PT_FIXED + 22 6537 the maximum number of NV Indexes that are allowed to 6538 have the TPMA_NV_COUNTER attribute SET 6539 NOTE 6540 6541 It is allowed for this value to be larger than the 6542 number of NV Indexes that can be defined. This 6543 would be indicative of a TPM implementation that did 6544 not use different implementation technology for 6545 different NV Index types. 6546 6547 TPM_PT_NV_INDEX_MAX 6548 6549 PT_FIXED + 23 6550 the maximum size of an NV Index data area 6551 6552 TPM_PT_MEMORY 6553 6554 PT_FIXED + 24 6555 a TPMA_MEMORY indicating the memory management 6556 method for the TPM 6557 6558 TPM_PT_CLOCK_UPDATE 6559 6560 PT_FIXED + 25 6561 interval, in milliseconds, between updates to the copy of 6562 TPMS_CLOCK_INFO.clock in NV 6563 6564 TPM_PT_CONTEXT_HASH 6565 6566 PT_FIXED + 26 6567 the algorithm used for the integrity HMAC on saved 6568 contexts 6569 and 6570 for 6571 hashing 6572 the 6573 fuData 6574 of 6575 TPM2_FirmwareRead() 6576 6577 TPM_PT_CONTEXT_SYM 6578 6579 PT_FIXED + 27 6580 the algorithm used for encryption of saved contexts 6581 6582 TPM_PT_CONTEXT_SYM_SIZE 6583 6584 PT_FIXED + 28 6585 the size of the key used for encryption of saved contexts 6586 6587 TPM_PT_ORDERLY_COUNT 6588 6589 PT_FIXED + 29 6590 the modulus - 1 of the count for NV update of an orderly 6591 counter 6592 The returned value is MAX_ORDERLY_COUNT. 6593 N 6594 This will have a value of 2 1 where 1 N 32 6595 NOTE 6596 6597 An orderly counter is an NV Index with 6598 TPMA_NV_COUNTER and TPMA_NV_ORDERLY 6599 both SET. 6600 6601 TPM_PT_MAX_COMMAND_SIZE 6602 6603 PT_FIXED + 30 6604 the maximum value for commandSize in a command 6605 6606 TPM_PT_MAX_RESPONSE_SIZE 6607 6608 PT_FIXED + 31 6609 the maximum value for responseSize in a response 6610 6611 TPM_PT_MAX_DIGEST 6612 6613 PT_FIXED + 32 6614 the maximum size of a digest that can be produced by the 6615 TPM 6616 6617 TPM_PT_MAX_OBJECT_CONTEXT 6618 6619 PT_FIXED + 33 6620 the maximum size of an object context that will be 6621 returned by TPM2_ContextSave 6622 6623 Family 2.0 6624 Level 00 Revision 00.99 6625 6626 Published 6627 Copyright TCG 2006-2013 6628 6629 Page 43 6630 October 31, 2013 6631 6632 Part 2: Structures 6634 6635 Capability Name 6636 6637 Trusted Platform Module Library 6638 6639 Value 6640 6641 Comments 6642 6643 TPM_PT_MAX_SESSION_CONTEXT 6644 PT_FIXED + 34 6645 the maximum size of a session context that will be 6646 returned by TPM2_ContextSave 6647 TPM_PT_PS_FAMILY_INDICATOR 6648 6649 PT_FIXED + 35 6650 platform-specific family (a TPM_PS value)(see Table 24) 6651 NOTE 6652 6653 The platform-specific values for the TPM_PT_PS 6654 parameters are in the relevant platform-specific 6655 specification. In the reference implementation, all of 6656 these values are 0. 6657 6658 TPM_PT_PS_LEVEL 6659 6660 PT_FIXED + 36 6661 the level of the platform-specific specification 6662 6663 TPM_PT_PS_REVISION 6664 6665 PT_FIXED + 37 6666 the specification Revision times 100 for the platformspecific specification 6667 6668 TPM_PT_PS_DAY_OF_YEAR 6669 6670 PT_FIXED + 38 6671 the platform-specific specification day of year using TCG 6672 calendar 6673 6674 TPM_PT_PS_YEAR 6675 6676 PT_FIXED + 39 6677 the platform-specific specification year using the CE 6678 6679 TPM_PT_SPLIT_MAX 6680 6681 PT_FIXED + 40 6682 the number of split signing operations supported by the 6683 TPM 6684 6685 TPM_PT_TOTAL_COMMANDS 6686 6687 PT_FIXED + 41 6688 total number of commands implemented in the TPM 6689 6690 TPM_PT_LIBRARY_COMMANDS 6691 6692 PT_FIXED + 42 6693 number of commands from the TPM library that are 6694 implemented 6695 6696 TPM_PT_VENDOR_COMMANDS 6697 6698 PT_FIXED + 43 6699 number of vendor commands that are implemented 6700 6701 TPM_PT_NV_BUFFER_MAX 6702 6703 PT_FIXED + 44 6704 the maximum data size in one NV write command 6705 6706 PT_VAR 6707 6708 PT_GROUP * 2 6709 the group of variable properties returned as 6710 TPMS_TAGGED_PROPERTY 6711 The properties in this group change because of a 6712 Protected Capability other than a firmware update. The 6713 values are not necessarily persistent across all power 6714 transitions. 6715 6716 TPM_PT_PERMANENT 6717 6718 PT_VAR + 0 6719 6720 TPMA_PERMANENT 6721 6722 TPM_PT_STARTUP_CLEAR 6723 6724 PT_VAR + 1 6725 6726 TPMA_STARTUP_CLEAR 6727 6728 TPM_PT_HR_NV_INDEX 6729 6730 PT_VAR + 2 6731 6732 the number of NV Indexes currently defined 6733 6734 TPM_PT_HR_LOADED 6735 6736 PT_VAR + 3 6737 6738 the number of authorization sessions currently loaded into 6739 TPM RAM 6740 6741 TPM_PT_HR_LOADED_AVAIL 6742 6743 PT_VAR + 4 6744 6745 the number of additional authorization sessions, of any 6746 type, that could be loaded into TPM RAM 6747 This value is an estimate. If this value is at least 1, then at 6748 least one authorization session of any type may be 6749 loaded. Any command that changes the RAM memory 6750 allocation can make this estimate invalid. 6751 NOTE 6752 6753 TPM_PT_HR_ACTIVE 6754 6755 Page 44 6756 October 31, 2013 6757 6758 PT_VAR + 5 6759 6760 A valid implementation may return 1 even if more 6761 than one authorization session would fit into RAM. 6762 6763 the number of active authorization sessions currently 6764 being tracked by the TPM 6765 This is the sum of the loaded and saved sessions. 6766 6767 Published 6768 Copyright TCG 2006-2013 6769 6770 Family 2.0 6771 Level 00 Revision 00.99 6772 6773 Trusted Platform Module Library 6775 Capability Name 6776 TPM_PT_HR_ACTIVE_AVAIL 6777 6778 Part 2: Structures 6779 Value 6780 6781 Comments 6782 6783 PT_VAR + 6 6784 6785 the number of additional authorization sessions, of any 6786 type, that could be created 6787 This value is an estimate. If this value is at least 1, then at 6788 least one authorization session of any type may be 6789 created. Any command that changes the RAM memory 6790 allocation can make this estimate invalid. 6791 NOTE 6792 6793 TPM_PT_HR_TRANSIENT_AVAIL 6794 6795 PT_VAR + 7 6796 6797 A valid implementation may return 1 even if more 6798 than one authorization session could be created. 6799 6800 estimate of the number of additional transient objects that 6801 could be loaded into TPM RAM 6802 This value is an estimate. If this value is at least 1, then at 6803 least one object of any type may be loaded. Any 6804 command that changes the memory allocation can make 6805 this estimate invalid. 6806 NOTE 6807 6808 A valid implementation may return 1 even if more 6809 than one transient object would fit into RAM. 6810 6811 TPM_PT_HR_PERSISTENT 6812 6813 PT_VAR + 8 6814 6815 the number of persistent objects currently loaded into 6816 TPM NV memory 6817 6818 TPM_PT_HR_PERSISTENT_AVAIL 6819 6820 PT_VAR + 9 6821 6822 the number of additional persistent objects that could be 6823 loaded into NV memory 6824 This value is an estimate. If this value is at least 1, then at 6825 least one object of any type may be made persistent. Any 6826 command that changes the NV memory allocation can 6827 make this estimate invalid. 6828 NOTE 6829 6830 A valid implementation may return 1 even if more 6831 than one persistent object would fit into NV memory. 6832 6833 TPM_PT_NV_COUNTERS 6834 6835 PT_VAR + 10 6836 6837 the number of defined NV Indexes that have NV 6838 TPMA_NV_COUNTER attribute SET 6839 6840 TPM_PT_NV_COUNTERS_AVAIL 6841 6842 PT_VAR + 11 6843 6844 the number of additional NV Indexes that can be defined 6845 with 6846 their 6847 TPMA_NV_COUNTER 6848 and 6849 TPMA_NV_ORDERLY attribute SET 6850 This value is an estimate. If this value is at least 1, then at 6851 least one NV Index may be created with the 6852 TPMA_NV_COUNTER 6853 and 6854 TPMA_NV_ORDERLY 6855 attributes SET. Any command that changes the NV 6856 memory allocation can make this estimate invalid. 6857 NOTE A valid implementation may return 1 even if more 6858 than one NV counter could be defined. 6859 6860 TPM_PT_ALGORITHM_SET 6861 6862 PT_VAR + 12 6863 6864 code that limits the algorithms that may be used with the 6865 TPM 6866 6867 TPM_PT_LOADED_CURVES 6868 6869 PT_VAR + 13 6870 6871 the number of loaded ECC curves 6872 6873 TPM_PT_LOCKOUT_COUNTER 6874 6875 PT_VAR + 14 6876 6877 the current value of the lockout counter (failedTries) 6878 6879 TPM_PT_MAX_AUTH_FAIL 6880 6881 PT_VAR + 15 6882 6883 the number of authorization failures before DA lockout is 6884 invoked 6885 6886 TPM_PT_LOCKOUT_INTERVAL 6887 6888 PT_VAR + 16 6889 6890 the number of seconds before the value reported by 6891 TPM_PT_LOCKOUT_COUNTER is decremented 6892 6893 TPM_PT_LOCKOUT_RECOVERY 6894 6895 PT_VAR + 17 6896 6897 the number of seconds after a lockoutAuth failure before 6898 use of lockoutAuth may be attempted again 6899 6900 TPM_PT_NV_WRITE_RECOVERY 6901 6902 PT_VAR + 18 6903 6904 number of milliseconds before the TPM will accept 6905 another command that will modify NV 6906 This value is an approximation and may go up or down 6907 over time. 6908 6909 Family 2.0 6910 Level 00 Revision 00.99 6911 6912 Published 6913 Copyright TCG 2006-2013 6914 6915 Page 45 6916 October 31, 2013 6917 6918 Part 2: Structures 6920 6921 Capability Name 6922 6923 Trusted Platform Module Library 6924 6925 Value 6926 6927 Comments 6928 6929 TPM_PT_AUDIT_COUNTER_0 6930 6931 PT_VAR + 19 6932 6933 the high-order 32 bits of the command audit counter 6934 6935 TPM_PT_AUDIT_COUNTER_1 6936 6937 PT_VAR + 20 6938 6939 the low-order 32 bits of the command audit counter 6940 6941 Page 46 6942 October 31, 2013 6943 6944 Published 6945 Copyright TCG 2006-2013 6946 6947 Family 2.0 6948 Level 00 Revision 00.99 6949 6950 Trusted Platform Module Library 6952 6953 Part 2: Structures 6954 6955 6.14 TPM_PT_PCR (PCR Property Tag) 6956 The TPM_PT_PCR constants are used in TPM2_GetCapability() to indicate the property being selected 6957 or returned. The PCR properties can be read when capability == TPM_CAP_PCR_PROPERTIES. 6958 Table 23 Definition of (UINT32) TPM_PT_PCR Constants <IN/OUT, S> 6959 Capability Name 6960 6961 Value 6962 6963 Comments 6964 6965 TPM_PT_PCR_FIRST 6966 6967 0x00000000 6968 6969 bottom of the range of TPM_PT_PCR properties 6970 6971 TPM_PT_PCR_SAVE 6972 6973 0x00000000 6974 6975 a SET bit in the TPMS_PCR_SELECT indicates that the PCR is 6976 saved and restored by TPM_SU_STATE 6977 6978 TPM_PT_PCR_EXTEND_L0 6979 6980 0x00000001 6981 6982 a SET bit in the TPMS_PCR_SELECT indicates that the PCR 6983 may be extended from locality 0 6984 This property is only present if a locality other than 0 is 6985 implemented. 6986 6987 TPM_PT_PCR_RESET_L0 6988 6989 0x00000002 6990 6991 a SET bit in the TPMS_PCR_SELECT indicates that the PCR 6992 may be reset by TPM2_PCR_Reset() from locality 0 6993 6994 TPM_PT_PCR_EXTEND_L1 6995 6996 0x00000003 6997 6998 a SET bit in the TPMS_PCR_SELECT indicates that the PCR 6999 may be extended from locality 1 7000 This property is only present if locality 1 is implemented. 7001 7002 TPM_PT_PCR_RESET_L1 7003 7004 0x00000004 7005 7006 a SET bit in the TPMS_PCR_SELECT indicates that the PCR 7007 may be reset by TPM2_PCR_Reset() from locality 1 7008 This property is only present if locality 1 is implemented. 7009 7010 TPM_PT_PCR_EXTEND_L2 7011 7012 0x00000005 7013 7014 a SET bit in the TPMS_PCR_SELECT indicates that the PCR 7015 may be extended from locality 2 7016 This property is only present if localities 1 and 2 are 7017 implemented. 7018 7019 TPM_PT_PCR_RESET_L2 7020 7021 0x00000006 7022 7023 a SET bit in the TPMS_PCR_SELECT indicates that the PCR 7024 may be reset by TPM2_PCR_Reset() from locality 2 7025 This property is only present if localities 1 and 2 are 7026 implemented. 7027 7028 TPM_PT_PCR_EXTEND_L3 7029 7030 0x00000007 7031 7032 a SET bit in the TPMS_PCR_SELECT indicates that the PCR 7033 may be extended from locality 3 7034 This property is only present if localities 1, 2, and 3 are 7035 implemented. 7036 7037 TPM_PT_PCR_RESET_L3 7038 7039 0x00000008 7040 7041 a SET bit in the TPMS_PCR_SELECT indicates that the PCR 7042 may be reset by TPM2_PCR_Reset() from locality 3 7043 This property is only present if localities 1, 2, and 3 are 7044 implemented. 7045 7046 TPM_PT_PCR_EXTEND_L4 7047 7048 0x00000009 7049 7050 a SET bit in the TPMS_PCR_SELECT indicates that the PCR 7051 may be extended from locality 4 7052 This property is only present if localities 1, 2, 3, and 4 are 7053 implemented. 7054 7055 TPM_PT_PCR_RESET_L4 7056 7057 0x0000000A 7058 7059 a SET bit in the TPMS_PCR_SELECT indicates that the PCR 7060 may be reset by TPM2_PCR_Reset() from locality 4 7061 This property is only present if localities 1, 2, 3, and 4 are 7062 implemented. 7063 7064 Family 2.0 7065 Level 00 Revision 00.99 7066 7067 Published 7068 Copyright TCG 2006-2013 7069 7070 Page 47 7071 October 31, 2013 7072 7073 Part 2: Structures 7075 7076 Capability Name 7077 reserved 7078 7079 Trusted Platform Module Library 7080 7081 Value 7082 7083 Comments 7084 7085 0x0000000B the values in this range are reserved 7086 0x00000010 They correspond to values that may be used to describe 7087 attributes associated with the extended localities (32255).synthesize additional software localities. The meaning of 7088 these properties need not be the same as the meaning for the 7089 Extend and Reset properties above. 7090 7091 TPM_PT_PCR_NO_INCREMENT 7092 7093 0x00000011 7094 7095 a SET bit in the TPMS_PCR_SELECT indicates that 7096 modifications to this PCR (reset or Extend) will not increment 7097 the pcrUpdateCounter 7098 7099 TPM_PT_PCR_DRTM_RESET 7100 7101 0x00000012 7102 7103 a SET bit in the TPMS_PCR_SELECT indicates that the PCR is 7104 reset by a DRTM event 7105 These PCR are reset to -1 on TPM2_Startup() and reset to 0 on 7106 a _TPM_Hash_End event following a _TPM_Hash_Start event. 7107 7108 TPM_PT_PCR_POLICY 7109 7110 0x00000013 7111 7112 a SET bit in the TPMS_PCR_SELECT indicates that the PCR is 7113 controlled by policy 7114 This property is only present if the TPM supports policy control 7115 of a PCR. 7116 7117 TPM_PT_PCR_AUTH 7118 7119 0x00000014 7120 7121 a SET bit in the TPMS_PCR_SELECT indicates that the PCR is 7122 controlled by an authorization value 7123 This property is only present if the TPM supports authorization 7124 control of a PCR. 7125 7126 reserved 7127 7128 0x00000015 7129 7130 reserved for the next (2 ) TPM_PT_PCR_POLICY set 7131 7132 reserved 7133 7134 0x00000016 7135 7136 reserved for the next (2 ) TPM_PT_PCR_AUTH set 7137 7138 reserved 7139 7140 nd 7141 nd 7142 7143 nd 7144 7145 th 7146 7147 0x00000017 reserved for the 2 through 255 TPM_PT_PCR_POLICY and 7148 0x00000210 TPM_PT_PCR_AUTH values 7149 th 7150 7151 and 7152 7153 highest 7154 7155 allowed, 7156 7157 th 7158 7159 and 7160 7161 highest 7162 7163 allowed, 7164 7165 reserved 7166 7167 0x00000211 7168 7169 reserved 7170 to 7171 the 7172 256 , 7173 TPM_PT_PCR_POLICY set 7174 7175 reserved 7176 7177 0x00000212 7178 7179 reserved 7180 to 7181 the 7182 256 , 7183 TPM_PT_PCR_AUTH set 7184 7185 reserved 7186 7187 0x00000213 7188 7189 new PCR property values may be assigned starting with this 7190 value 7191 7192 TPM_PT_PCR_LAST 7193 7194 0x00000014 7195 7196 top of the range of TPM_PT_PCR properties of the 7197 implementation 7198 If the TPM receives a request for a PCR property with a value 7199 larger than this, the TPM will return a zero length list and set the 7200 moreData parameter to NO. 7201 NOTE 7202 7203 Page 48 7204 October 31, 2013 7205 7206 This is an implementation-specific value. The value shown 7207 reflects the reference code implementation. 7208 7209 Published 7210 Copyright TCG 2006-2013 7211 7212 Family 2.0 7213 Level 00 Revision 00.99 7214 7215 Trusted Platform Module Library 7217 7218 Part 2: Structures 7219 7220 6.15 TPM_PS (Platform Specific) 7221 The platform values in Table 24 are used for the TPM_PT_PS_FAMILY_INDICATOR. 7222 NOTE 7223 7224 Values below six (6) have the same values as the purview assignments in TPM 1.2. 7225 7226 Table 24 Definition of (UINT32) TPM_PS Constants <OUT> 7227 Capability Name 7228 7229 Value 7230 7231 Comments 7232 7233 TPM_PS_MAIN 7234 7235 0x00000000 7236 7237 not platform specific 7238 7239 TPM_PS_PC 7240 7241 0x00000001 7242 7243 PC Client 7244 7245 TPM_PS_PDA 7246 7247 0x00000002 7248 7249 PDA (includes all mobile devices that are not specifically cell 7250 phones) 7251 7252 TPM_PS_CELL_PHONE 7253 7254 0x00000003 7255 7256 Cell Phone 7257 7258 TPM_PS_SERVER 7259 7260 0x00000004 7261 7262 Server WG 7263 7264 TPM_PS_PERIPHERAL 7265 7266 0x00000005 7267 7268 Peripheral WG 7269 7270 TPM_PS_TSS 7271 7272 0x00000006 7273 7274 TSS WG 7275 7276 TPM_PS_STORAGE 7277 7278 0x00000007 7279 7280 Storage WG 7281 7282 TPM_PS_AUTHENTICATION 7283 7284 0x00000008 7285 7286 Authentication WG 7287 7288 TPM_PS_EMBEDDED 7289 7290 0x00000009 7291 7292 Embedded WG 7293 7294 TPM_PS_HARDCOPY 7295 7296 0x0000000A 7297 7298 Hardcopy WG 7299 7300 TPM_PS_INFRASTRUCTURE 7301 7302 0x0000000B 7303 7304 Infrastructure WG 7305 7306 TPM_PS_VIRTUALIZATION 7307 7308 0x0000000C 7309 Virtualization WG 7310 7311 TPM_PS_TNC 7312 7313 0x0000000D 7314 Trusted Network Connect WG 7315 7316 TPM_PS_MULTI_TENANT 7317 7318 0x0000000E 7319 7320 Multi-tenant WG 7321 7322 TPM_PS_TC 7323 7324 0x0000000F 7325 7326 Technical Committee 7327 7328 Family 2.0 7329 Level 00 Revision 00.99 7330 7331 Published 7332 Copyright TCG 2006-2013 7333 7334 Page 49 7335 October 31, 2013 7336 7337 Part 2: Structures 7339 7340 7 7341 7342 Trusted Platform Module Library 7343 7344 Handles 7345 7346 7.1 7347 7348 Introduction 7349 7350 Handles are 32-bit values used to reference shielded locations of various types within the TPM. 7351 Table 25 Definition of Types for Handles 7352 Type 7353 7354 Name 7355 7356 Description 7357 7358 UINT32 7359 7360 TPM_HANDLE 7361 7362 Handles may refer to objects (keys or data blobs), authorization sessions (HMAC and policy), NV 7363 Indexes, permanent TPM locations, and PCR. 7364 7.2 7365 7366 TPM_HT (Handle Types) 7367 7368 The 32-bit handle space is divided into 256 regions of equal size with 2 7369 ranges represents a handle type. 7370 7371 24 7372 7373 values in each. Each of these 7374 7375 The type of the entity is indicated by the MSO of its handle. The values for the MSO and the entity 7376 referenced are shown in Table 26. 7377 Table 26 Definition of (UINT8) TPM_HT Constants <S> 7378 Name 7379 7380 Value 7381 7382 Comments 7383 7384 TPM_HT_PCR 7385 7386 0x00 7387 7388 PCR consecutive numbers, starting at 0, that reference the PCR 7389 registers 7390 A platform-specific specification will set the minimum number of PCR 7391 and an implementation may have more. 7392 7393 TPM_HT_NV_INDEX 7394 7395 0x01 7396 7397 NV Index assigned by the caller 7398 7399 TPM_HT_HMAC_SESSION 7400 7401 0x02 7402 7403 HMAC Authorization Session assigned by the TPM when the 7404 session is created 7405 7406 TPM_HT_LOADED_SESSION 7407 7408 0x02 7409 7410 Loaded Authorization Session used only in the context of 7411 TPM2_GetCapability 7412 This type references both loaded HMAC and loaded policy 7413 authorization sessions. 7414 7415 TPM_HT_POLICY_SESSION 7416 7417 0x03 7418 7419 Policy Authorization Session assigned by the TPM when the 7420 session is created 7421 7422 TPM_HT_ACTIVE_SESSION 7423 7424 0x03 7425 7426 Active Authorization Session used only in the context of 7427 TPM2_GetCapability 7428 This type references saved authorization session contexts for which 7429 the TPM is maintaining tracking information. 7430 7431 TPM_HT_PERMANENT 7432 7433 0x40 7434 7435 Permanent Values assigned by this specification in Table 27 7436 7437 TPM_HT_TRANSIENT 7438 7439 0x80 7440 7441 Transient Objects assigned by the TPM when an object is loaded 7442 into transient-object memory or when a persistent object is converted 7443 to a transient object 7444 7445 TPM_HT_PERSISTENT 7446 7447 0x81 7448 7449 Persistent Objects assigned by the TPM when a loaded transient 7450 object is made persistent 7451 7452 Page 50 7453 October 31, 2013 7454 7455 Published 7456 Copyright TCG 2006-2013 7457 7458 Family 2.0 7459 Level 00 Revision 00.99 7460 7461 Trusted Platform Module Library 7463 7464 Part 2: Structures 7465 7466 When a transient object is loaded, the TPM shall assign a handle with an MSO of TPM_HT_TRANSIENT. 7467 The object may be assigned a different handle each time it is loaded. The TPM shall ensure that handles 7468 assigned to transient objects are unique and assigned to only one transient object at a time. 7469 EXAMPLE 7470 7471 If a TPM is only able to hold 4 transient objects in internal memory, it might choose to assign handles to 7472 those objects with the values 80 00 00 0016 80 00 00 0316. 7473 7474 When a transient object is converted to a persistent object (TPM2_EvictControl()), the TPM shall validate 7475 that the handle provided by the caller has an MSO of TPM_HT_PERSISTENT and that the handle is not 7476 already assigned to a persistent object. 7477 A handle is assigned to a session when the session is started. The handle shall have an MSO equal to 7478 TPM_HT_SESSION and remain associated with that session until the session is closed or flushed. The 7479 TPM shall ensure that a session handle is only associated with one session at a time. When the session 7480 is loaded into the TPM using TPM2_LoadContext(), it will have the same handle each time it is loaded. 7481 EXAMPLE 7482 7483 7.3 7484 7485 If a TPM is only able to track 64 active sessions at a time, it could number those sessions using the 7486 values xx 00 01 0016 xx 00 01 3F 16 where xx is either 02 16 or 03 16 depending on the session type. 7487 7488 Persistent Handle Sub-ranges 7489 7490 Persistent handles are assigned by the caller of TPM2_EvictControl(). ownerAuth or platformAuth is 7491 required to authorize allocation of space for a persistent object. These entities are given separate ranges 7492 of persistent handles so that they do not have to allocate from a common range of handles. 7493 NOTE 7494 7495 While this namespace allocation of the handle ranges could have been handled by convention, TPM 7496 enforcement is used to prevent errors by the OS or malicious software from affecting the platforms use of 7497 the NV memory. 7498 7499 The Owner is allocated persistent handles in the range of 81 00 00 0016 to 81 7F FF FF16 inclusive and 7500 the TPM will return an error if ownerAuth is used to attempt to assign a persistent handle outside of this 7501 range. 7502 7503 Family 2.0 7504 Level 00 Revision 00.99 7505 7506 Published 7507 Copyright TCG 2006-2013 7508 7509 Page 51 7510 October 31, 2013 7511 7512 Part 2: Structures 7514 7.4 7515 7516 Trusted Platform Module Library 7517 7518 TPM_RH (Permanent Handles) 7519 7520 Table 27 lists the architecturally defined handles that cannot be changed. The handles include 7521 authorization handles, and special handles. 7522 Table 27 Definition of (UINT32) TPM_RH Constants <IN, S> 7523 Name 7524 7525 Value 7526 7527 Type 7528 7529 TPM_RH_FIRST 7530 7531 0x40000000 7532 7533 R 7534 7535 TPM_RH_SRK 7536 7537 0x40000000 7538 7539 R 7540 7541 TPM_RH_OWNER 7542 7543 0x40000001 7544 7545 K, A, P 7546 7547 TPM_RH_REVOKE 7548 7549 0x40000002 7550 7551 R 7552 7553 not used 7554 7555 1 7556 7557 TPM_RH_TRANSPORT 7558 7559 0x40000003 7560 7561 R 7562 7563 not used 7564 7565 1 7566 7567 TPM_RH_OPERATOR 7568 7569 0x40000004 7570 7571 R 7572 7573 not used 7574 7575 1 7576 7577 TPM_RH_ADMIN 7578 7579 0x40000005 7580 7581 R 7582 7583 not used 7584 7585 1 7586 7587 TPM_RH_EK 7588 7589 0x40000006 7590 7591 R 7592 7593 not used 7594 7595 1 7596 7597 TPM_RH_NULL 7598 7599 0x40000007 7600 7601 K, A, P 7602 7603 a handle associated with the null hierarchy, an EmptyAuth 7604 authValue, and an Empty Policy authPolicy. 7605 7606 TPM_RH_UNASSIGNED 7607 7608 0x40000008 7609 7610 R 7611 7612 value reserved to the TPM to indicate a handle location that 7613 has not been initialized or assigned 7614 7615 TPM_RS_PW 7616 7617 0x40000009 7618 7619 S 7620 7621 authorization value 7622 authorization session 7623 7624 TPM_RH_LOCKOUT 7625 7626 0x4000000A 7627 7628 A 7629 7630 references the authorization associated with the dictionary 7631 attack lockout reset 7632 7633 TPM_RH_ENDORSEMENT 7634 7635 0x4000000B 7636 7637 K, A, P 7638 7639 references the Endorsement Primary 7640 endorsementAuth, and endorsementPolicy 7641 7642 TPM_RH_PLATFORM 7643 7644 0x4000000C 7645 7646 K, A, P 7647 7648 references the Platform Primary Seed (PPS), platformAuth, 7649 and platformPolicy 7650 7651 TPM_RH_PLATFORM_NV 7652 7653 0x4000000D 7654 7655 C 7656 7657 for phEnableNV 7658 7659 R 7660 7661 the top of the reserved handle area 7662 This is set to allow TPM2_GetCapability() to know where to 7663 stop. It may vary as implementations add to the permanent 7664 handle area. 7665 7666 TPM_RH_LAST 7667 7668 0x4000000D 7669 7670 Comments 7671 7672 not used 7673 7674 1 7675 7676 handle references the Storage Primary Seed (SPS), the 7677 ownerAuth, and the ownerPolicy 7678 7679 used 7680 7681 to 7682 7683 indicate 7684 7685 a 7686 7687 password 7688 7689 Seed 7690 7691 (EPS), 7692 7693 Type definitions: 7694 R a reserved value 7695 K a Primary Seed 7696 A an authorization value 7697 P a policy value 7698 S a session handle 7699 C - a controlNote 1 The handle is only used in a TPM that is compatible with a previous version of this specification. It is not used 7700 in any command defined in this version of the specification. 7701 7702 Page 52 7703 October 31, 2013 7704 7705 Published 7706 Copyright TCG 2006-2013 7707 7708 Family 2.0 7709 Level 00 Revision 00.99 7710 7711 Trusted Platform Module Library 7713 7.5 7714 7715 Part 2: Structures 7716 7717 TPM_HC (Handle Value Constants) 7718 7719 The definitions in Table 28 are used to define many of the interface data types. However, the values of 7720 these constants, other than PCR_FIRST, are informative and may be changed by an implementation as 7721 long as the values stay within the prescribed ranges for the handle type. 7722 NOTE 7723 7724 PCR0 is architecturally defined to have a handle value of 0. 7725 7726 For the reference implementation, the handle range for sessions starts at the lowest allowed value for a 7727 session handle. The highest value for a session handle is determined by how many active sessions are 7728 allowed by the implementation. The MSO of the session handle will be set according to the session type. 7729 A similar approach is used for transient objects with the first assigned handle at the bottom of the range 7730 defined by TPM_HT_TRANSIENT and the top of the range determined by the implementation-dependent 7731 value of MAX_LOADED_OBJECTS. 7732 The first assigned handle for evict objects is also at the bottom of the allowed range defined by 7733 TPM_HT_PERSISTENT and the top of the range determined by the implementation-dependent value of 7734 MAX_EVICT_OBJECTS. 7735 NOTE 7736 7737 The values in Table 28 are intended to facilitate the process of making the handle larger than 32 bits in 7738 the future. It is intended that HR_MASK and HR_SHIFT are the only values that need change to resize 7739 the handle space. 7740 7741 Family 2.0 7742 Level 00 Revision 00.99 7743 7744 Published 7745 Copyright TCG 2006-2013 7746 7747 Page 53 7748 October 31, 2013 7749 7750 Part 2: Structures 7752 7753 Trusted Platform Module Library 7754 7755 Table 28 Definition of (TPM_HANDLE) TPM_HC Constants <IN, S> 7756 Name 7757 7758 Value 7759 7760 Comments 7761 7762 HR_HANDLE_MASK 7763 7764 0x00FFFFFF 7765 7766 to mask off the HR 7767 7768 HR_RANGE_MASK 7769 7770 0xFF000000 7771 7772 to mask off the variable 7773 part 7774 7775 HR_SHIFT 7776 7777 24 7778 7779 HR_PCR 7780 7781 (TPM_HT_PCR << HR_SHIFT) 7782 7783 HR_HMAC_SESSION 7784 7785 (TPM_HT_HMAC_SESSION << HR_SHIFT) 7786 7787 HR_POLICY_SESSION 7788 7789 (TPM_HT_POLICY_SESSION << HR_SHIFT) 7790 7791 HR_TRANSIENT 7792 7793 (TPM_HT_TRANSIENT << HR_SHIFT) 7794 7795 HR_PERSISTENT 7796 7797 (TPM_HT_PERSISTENT << HR_SHIFT) 7798 7799 HR_NV_INDEX 7800 7801 (TPM_HT_NV_INDEX << HR_SHIFT) 7802 7803 HR_PERMANENT 7804 7805 (TPM_HT_PERMANENT << HR_SHIFT) 7806 7807 PCR_FIRST 7808 7809 (HR_PCR + 0) 7810 7811 first PCR 7812 7813 PCR_LAST 7814 7815 (PCR_FIRST + IMPLEMENTATION_PCR-1) 7816 7817 last PCR 7818 7819 HMAC_SESSION_FIRST 7820 7821 (HR_HMAC_SESSION + 0) 7822 7823 first HMAC session 7824 7825 HMAC_SESSION_LAST 7826 7827 (HMAC_SESSION_FIRST+MAX_ACTIVE_SESSIONS-1) 7828 7829 last HMAC session 7830 7831 LOADED_SESSION_FIRST HMAC_SESSION_FIRST 7832 7833 used in GetCapability 7834 7835 LOADED_SESSION_LAST 7836 7837 HMAC_SESSION_LAST 7838 7839 used in GetCapability 7840 7841 POLICY_SESSION_FIRST 7842 7843 (HR_POLICY_SESSION + 0) 7844 7845 first policy session 7846 7847 POLICY_SESSION_LAST 7848 7849 (POLICY_SESSION_FIRST + MAX_ACTIVE_SESSIONS-1) 7850 last policy session 7851 7852 TRANSIENT_FIRST 7853 7854 (HR_TRANSIENT + 0) 7855 7856 first transient object 7857 7858 ACTIVE_SESSION_FIRST 7859 7860 POLICY_SESSION_FIRST 7861 7862 used in GetCapability 7863 7864 ACTIVE_SESSION_LAST 7865 7866 POLICY_SESSION_LAST 7867 7868 used in GetCapability 7869 7870 TRANSIENT_LAST 7871 7872 (TRANSIENT_FIRST+MAX_LOADED_OBJECTS-1) 7873 7874 last transient object 7875 7876 PERSISTENT_FIRST 7877 7878 (HR_PERSISTENT + 0) 7879 7880 first persistent object 7881 7882 PERSISTENT_LAST 7883 7884 (PERSISTENT_FIRST + 0x00FFFFFF) 7885 7886 last persistent object 7887 7888 PLATFORM_PERSISTENT 7889 7890 (PERSISTENT_FIRST + 0x00800000) 7891 7892 first platform persistent 7893 object 7894 7895 NV_INDEX_FIRST 7896 7897 (HR_NV_INDEX + 0) 7898 7899 first allowed NV Index 7900 7901 NV_INDEX_LAST 7902 7903 (NV_INDEX_FIRST + 0x00FFFFFF) 7904 7905 last allowed NV Index 7906 7907 PERMANENT_FIRST 7908 7909 TPM_RH_FIRST 7910 7911 PERMANENT_LAST 7912 7913 TPM_RH_LAST 7914 7915 Page 54 7916 October 31, 2013 7917 7918 Published 7919 Copyright TCG 2006-2013 7920 7921 Family 2.0 7922 Level 00 Revision 00.99 7923 7924 Trusted Platform Module Library 7926 7927 Part 2: Structures 7928 7929 Attribute Structures 7930 7931 8 7932 8.1 7933 7934 Description 7935 7936 Attributes are expressed as bit fields of varying size. An attribute field structure may be 1, 2, or 4 octets in 7937 length. 7938 The bit numbers for an attribute structure are assigned with the number 0 assigned to the least-significant 7939 bit of the structure and the highest number assigned to the most-significant bit of the structure. 7940 The least significant bit is determined by treating the attribute structure as an integer. The least-significant 7941 bit would be the bit that is set when the value of the integer is 1. 7942 When any reserved bit in an attribute is SET, the TPM shall return TPM_RC_RESERVED_BITS. This 7943 response code is not shown in the tables for attributes. 7944 8.2 7945 7946 TPMA_ALGORITHM 7947 7948 This structure defines the attributes of an algorithm. 7949 Each algorithm has a fundamental attribute: asymmetric, symmetric, or hash. In some cases (e.g., 7950 TPM_ALG_RSA or TPM_ALG_AES), this is the only attribute. 7951 A mode, method, or scheme may have an associated asymmetric, symmetric, or hash algorithm. 7952 Table 29 Definition of (UINT32) TPMA_ALGORITHM Bits 7953 Bit 7954 7955 Name 7956 7957 Definition 7958 7959 0 7960 7961 asymmetric 7962 7963 SET (1): an asymmetric algorithm with public and private portions 7964 CLEAR (0): not an asymmetric algorithm 7965 7966 1 7967 7968 symmetric 7969 7970 SET (1): a symmetric block cipher 7971 CLEAR (0): not a symmetric block cipher 7972 7973 2 7974 7975 hash 7976 7977 SET (1): a hash algorithm 7978 CLEAR (0): not a hash algorithm 7979 7980 3 7981 7982 object 7983 7984 SET (1): an algorithm that may be used as an object type 7985 CLEAR (0): an algorithm that is not used as an object type 7986 7987 7:4 7988 7989 Reserved 7990 7991 8 7992 7993 signing 7994 7995 SET (1): a signing algorithm. The setting of asymmetric, symmetric, and hash 7996 will indicate the type of signing algorithm. 7997 CLEAR (0): not a signing algorithm 7998 7999 9 8000 8001 encrypting 8002 8003 SET (1): an encryption/decryption algorithm. The setting of asymmetric, 8004 symmetric, and hash will indicate the type of encryption/decryption algorithm. 8005 CLEAR (0): not an encryption/decryption algorithm 8006 8007 10 8008 8009 method 8010 8011 SET (1): a method such as a key derivative function (KDF) 8012 CLEAR (0): not a method 8013 8014 31:11 Reserved 8015 8016 8.3 8017 8.3.1 8018 8019 TPMA_OBJECT (Object Attributes) 8020 Introduction 8021 8022 Family 2.0 8023 Level 00 Revision 00.99 8024 8025 Published 8026 Copyright TCG 2006-2013 8027 8028 Page 55 8029 October 31, 2013 8030 8031 Part 2: Structures 8033 8034 Trusted Platform Module Library 8035 8036 This attribute structure indicates an objects use, its authorization types, and it relationship to other 8037 objects. 8038 The state of the attributes is determined when the object is created and they are never changed by the 8039 TPM. Additionally, the setting of these structures is reflected in the integrity value of the private area of an 8040 object in order to allow the TPM to detect modifications of the Protected Object when stored off the TPM. 8041 8.3.2 8042 8043 Structure Definition 8044 Table 30 Definition of (UINT32) TPMA_OBJECT Bits 8045 8046 Bit 8047 8048 Name 8049 8050 Definition 8051 8052 0 8053 8054 Reserved 8055 8056 shall be zero 8057 8058 1 8059 8060 fixedTPM 8061 8062 SET (1): The hierarchy of the object, as indicated by its Qualified Name, may 8063 not change. 8064 CLEAR (0): The hierarchy of the object may change as a result of this object or 8065 an ancestor key being duplicated for use in another hierarchy. 8066 8067 2 8068 8069 stClear 8070 8071 SET (1): Previously saved contexts of this object may not be loaded after 8072 Startup(CLEAR). 8073 CLEAR (0): Saved contexts of this object may be used after a 8074 Shutdown(STATE) and subsequent Startup(). 8075 8076 3 8077 8078 Reserved 8079 8080 shall be zero 8081 8082 4 8083 8084 fixedParent 8085 8086 SET (1): The parent of the object may not change. 8087 CLEAR (0): The parent of the object may change as the result of a 8088 TPM2_Duplicate() of the object. 8089 8090 5 8091 8092 sensitiveDataOrigin 8093 8094 SET (1): Indicates that, when the object was created with TPM2_Create() or 8095 TPM2_CreatePrimary(), the TPM generated all of the sensitive data other than 8096 the authValue. 8097 CLEAR (0): A portion of the sensitive data, other than the authValue, was 8098 provided by the caller. 8099 8100 6 8101 8102 userWithAuth 8103 8104 SET (1): Approval of USER role actions with this object may be with an HMAC 8105 session or with a password using the authValue of the object or a policy 8106 session. 8107 CLEAR (0): Approval of USER role actions with this object may only be done 8108 with a policy session. 8109 8110 7 8111 8112 adminWithPolicy 8113 8114 SET (1): Approval of ADMIN role actions with this object may only be done with 8115 a policy session. 8116 CLEAR (0): Approval of ADMIN role actions with this object may be with an 8117 HMAC session or with a password using the authValue of the object or a policy 8118 session. 8119 8120 9:8 8121 8122 Reserved 8123 8124 shall be zero 8125 8126 10 8127 8128 noDA 8129 8130 SET (1): The object is not subject to dictionary attack protections. 8131 CLEAR (0): The object is subject to dictionary attack protections. 8132 8133 11 8134 8135 encryptedDuplication 8136 8137 SET (1): If the object is duplicated, then symmetricAlg shall not be 8138 TPM_ALG_NULL and newParentHandle shall not be TPM_RH_NULL. 8139 CLEAR (0): The object may be duplicated without an inner wrapper on the 8140 private portion of the object and the new parent may be TPM_RH_NULL. 8141 8142 15:12 Reserved 8143 16 8144 8145 restricted 8146 8147 Page 56 8148 October 31, 2013 8149 8150 shall be zero 8151 SET (1): Key usage is restricted to manipulate structures of known format; the 8152 parent of this key shall have restricted SET. 8153 CLEAR (0): Key usage is not restricted to use on special formats. 8154 8155 Published 8156 Copyright TCG 2006-2013 8157 8158 Family 2.0 8159 Level 00 Revision 00.99 8160 8161 Trusted Platform Module Library 8163 8164 Part 2: Structures 8165 8166 Bit 8167 8168 Name 8169 8170 Definition 8171 8172 17 8173 8174 decrypt 8175 8176 SET (1): The private portion of the key may be used to decrypt. 8177 CLEAR (0): The private portion of the key may not be used to decrypt. 8178 8179 18 8180 8181 sign 8182 8183 SET (1): The private portion of the key may be used to sign. 8184 CLEAR (0): The private portion of the key may not be used to sign. 8185 8186 31:19 Reserved 8187 8188 8.3.3 8189 8.3.3.1 8190 8191 shall be zero 8192 8193 Attribute Descriptions 8194 Introduction 8195 8196 The following remaining paragraphs in this clause describe the use and settings for each of the 8197 TPMA_OBJECT attributes. The description includes checks that are performed on the objectAttributes 8198 when an object is created, when it is loaded, and when it is imported. In these descriptions: 8199 Creation 8200 8201 indicates 8202 settings 8203 for 8204 TPM2_CreatePrimary() 8205 8206 the 8207 8208 template 8209 8210 parameter 8211 8212 in 8213 8214 TPM2_Create() 8215 8216 or 8217 8218 Load 8219 8220 8221 8222 indicates settings for the inPublic parameter in TPM2_Load() 8223 8224 Import 8225 8226 8227 8228 indicates settings for the objectPublic parameter in TPM2_Import() 8229 8230 External 8231 8232 8233 8234 indicates settings that apply to the inPublic parameter in TPM2_LoadExternal() if both the 8235 public and sensitive portions of the object are loaded 8236 8237 NOTE 8238 8239 For TPM2_LoadExternal() when only the public portion of the object is loaded, the only attribute checks 8240 are the checks in the validation code following Table 30 and the reserved attributes check. 8241 8242 For any consistency error of attributes in TPMA_OBJECT, the TPM shall return TPM_RC_ATTRIBUTES. 8243 8.3.3.2 8244 8245 Bit[1] fixedTPM 8246 8247 When SET, the object cannot be duplicated for use on a different TPM, either directly or indirectly and the 8248 Qualified Name of the object cannot change. When CLEAR, the objects Qualified Name may change if 8249 the object or an ancestor is duplicated. 8250 NOTE 8251 8252 This attribute is the logical inverse of the migratable attribute in 1.2. That is, when this attribute is C LEAR, 8253 it is the equivalent to a 1.2 object with migratable SET. 8254 8255 Creation 8256 8257 If fixedTPM is SET in the object's parent, then fixedTPM and fixedParent shall both be 8258 set to the same value in template. If fixedTPM is CLEAR in the parent, this attribute shall 8259 also be CLEAR in template. 8260 NOTE 8261 8262 For a Primary Object, the parent is considered to have fixedTPM SET. 8263 8264 Load 8265 8266 8267 8268 If fixedTPM is SET in the object's parent, then fixedTPM and fixedParent shall both be 8269 set to the same value. If fixedTPM is CLEAR in the parent, this attribute shall also be 8270 CLEAR. 8271 8272 Import 8273 8274 8275 8276 shall be CLEAR 8277 8278 External 8279 8280 8281 8282 shall be CLEAR if both the public and sensitive portions are loaded or if fixedParent is 8283 CLEAR, otherwise may be SET or CLEAR 8284 8285 Family 2.0 8286 Level 00 Revision 00.99 8287 8288 Published 8289 Copyright TCG 2006-2013 8290 8291 Page 57 8292 October 31, 2013 8293 8294 Part 2: Structures 8296 8.3.3.3 8297 8298 Trusted Platform Module Library 8299 8300 Bit[2] stClear 8301 8302 If this attribute is SET, then saved contexts of this object will be invalidated on 8303 TPM2_Startup(TPM_SU_CLEAR). If the attribute is CLEAR, then the TPM shall not invalidate the saved 8304 context if the TPM received TPM2_Shutdown(TPM_SU_STATE). If the saved state is valid when checked 8305 at the next TPM2_Startup(), then the TPM shall continue to be able to use the saved contexts. 8306 Creation 8307 8308 may be SET or CLEAR in template 8309 8310 Load 8311 8312 8313 8314 may be SET or CLEAR 8315 8316 Import 8317 8318 8319 8320 may be SET or CLEAR 8321 8322 External 8323 8324 8325 8326 may be SET or CLEAR 8327 8328 8.3.3.4 8329 8330 Bit[4] fixedParent 8331 8332 If this attribute is SET, the objects parent may not be changed. That is, this object may not be the object 8333 of a TPM2_Duplicate(). If this attribute is CLEAR, then this object may be the object of a 8334 TPM2_Duplicate(). 8335 Creation 8336 8337 may be SET or CLEAR in template 8338 8339 Load 8340 8341 8342 8343 may be SET or CLEAR 8344 8345 Import 8346 8347 8348 8349 shall be CLEAR 8350 8351 External 8352 8353 8354 8355 shall be CLEAR if both the public and sensitive portions are loaded; otherwise it may be 8356 SET or CLEAR 8357 8358 8.3.3.5 8359 8360 Bit[5] sensitiveDataOrigin 8361 8362 This attribute is SET for any key that was generated by TPM in TPM2_Create() or 8363 TPM2_CreatePrimary(). If CLEAR, it indicates that the sensitive part of the object (other than the 8364 obfuscation value) was provided by the caller. 8365 NOTE 1 8366 8367 If the fixedTPM attribute is SET, then this attribute is authoritative and accurately reflects the source of 8368 the sensitive area data. If the fixedTPM attribute is CLEAR, then validation of this attribute requires 8369 evaluation of the properties of the ancestor keys. 8370 8371 Creation 8372 8373 If inSensitive.sensitive.data.size is zero, then this attribute shall be SET in the template; 8374 otherwise, it shall be CLEAR in the template. 8375 8376 NOTE 2 8377 8378 The inSensitive.sensitive.data.size parameter is required to be zero for an asymmetric key so 8379 sensitiveDataOrigin is required to be SET. 8380 8381 NOTE 3 8382 8383 The inSensitive.sensitive.data.size parameter may not be zero for a data object so sensitiveDataOrigin is 8384 required to be CLEAR. A data object has type = TPM_ALG_KEYEDHASH and its sign and decrypt 8385 attributes are CLEAR. 8386 8387 Load 8388 8389 8390 8391 may be SET or CLEAR 8392 8393 Import 8394 8395 8396 8397 may be SET or CLEAR 8398 8399 External 8400 8401 8402 8403 may be SET or CLEAR 8404 8405 Page 58 8406 October 31, 2013 8407 8408 Published 8409 Copyright TCG 2006-2013 8410 8411 Family 2.0 8412 Level 00 Revision 00.99 8413 8414 Trusted Platform Module Library 8416 8.3.3.6 8417 8418 Part 2: Structures 8419 8420 Bit[6] userWithAuth 8421 8422 If SET, authorization for operations that require USER role authorization may be given if the caller 8423 provides proof of knowledge of the authValue of the object with an HMAC authorization session or a 8424 password. 8425 If this attribute is CLEAR, then then HMAC or password authorizations may not be used for USER role 8426 authorizations. 8427 NOTE 1 8428 8429 Regardless of the setting of this attribute, authorizations for operations th at require USER role 8430 authorizations may be provided with a policy session that satisfies the object's authPolicy. 8431 8432 NOTE 2 8433 8434 Regardless of the setting of this attribute, the authValue may be referenced in a policy session or used to 8435 provide the bind value in TPM2_StartAuthSession(). However, if userWithAuth is CLEAR, then the object 8436 may be used as the bind object in TPM2_StartAuthSession() but the session cannot be used to authorize 8437 actions on the object. If this were allowed, then the userWithAuth control could be circumvented simply by 8438 using the object as the bind object. 8439 8440 Creation 8441 8442 may be SET or CLEAR in template 8443 8444 Load 8445 8446 8447 8448 may be SET or CLEAR 8449 8450 Import 8451 8452 8453 8454 may be SET or CLEAR 8455 8456 External 8457 8458 8459 8460 may be SET or CLEAR 8461 8462 8.3.3.7 8463 8464 Bit[7] adminWithPolicy 8465 8466 If CLEAR, authorization for operations that require ADMIN role may be given if the caller provides proof of 8467 knowledge of the authValue of the object with an HMAC authorization session or a password. 8468 If this attribute is SET, then then HMAC or password authorizations may not be used for ADMIN role 8469 authorizations. 8470 NOTE 1 8471 8472 Regardless of the setting of this attribute, operations that require ADMIN role authorization may be 8473 provided by a policy session that satisfies the object's authPolicy. 8474 8475 NOTE 2 8476 8477 This attribute is similar to userWithAuth but the logic is a bit different. When userWithAuth is CLEAR, the 8478 authValue may not be used for USER mode authorizations. When adminWithPolicy is CLEAR, it means 8479 that the authValue may be used for ADMIN role. Policy may always be used regardless of t he setting of 8480 userWithAuth or adminWithPolicy. 8481 8482 Actions that always require policy (TPM2_Duplicate()) are not affected by the setting of this attribute. 8483 Creation 8484 8485 may be SET or CLEAR in template 8486 8487 Load 8488 8489 8490 8491 may be SET or CLEAR 8492 8493 Import 8494 8495 8496 8497 may be SET or CLEAR 8498 8499 External 8500 8501 8502 8503 may be SET or CLEAR 8504 8505 8.3.3.8 8506 8507 Bit[10] noDA 8508 8509 If SET, then authorization failures for the object do not affect the dictionary attack protection logic and 8510 authorization of the object is not blocked if the TPM is in lockout. 8511 Creation 8512 8513 may be SET or CLEAR in template 8514 8515 Load 8516 8517 8518 8519 may be SET or CLEAR 8520 8521 Import 8522 8523 8524 8525 may be SET or CLEAR 8526 8527 External 8528 8529 8530 8531 may be SET or CLEAR 8532 8533 Family 2.0 8534 Level 00 Revision 00.99 8535 8536 Published 8537 Copyright TCG 2006-2013 8538 8539 Page 59 8540 October 31, 2013 8541 8542 Part 2: Structures 8544 8.3.3.9 8545 8546 Trusted Platform Module Library 8547 8548 Bit[11] encryptedDuplication 8549 8550 If SET, then when the object is duplicated, the sensitive portion of the object is required to be encrypted 8551 with an inner wrapper and the new parent shall be an asymmetric key and not TPM_RH_NULL 8552 NOTE 1 8553 8554 Enforcement of these requirements in TPM2_Duplicate() is by not allowing symmetricAlg to be 8555 TPM_ALG_NULL and newParentHandle may not be TPM_RH_NULL. 8556 8557 This attribute shall not be SET in any object that has fixedTPM SET. 8558 NOTE 2 8559 8560 This requirement means that encryptedDuplication may not be SET if the object cannot be directly or 8561 indirectly duplicated. 8562 8563 If an object's parent has fixedTPM SET, and the object is duplicable (fixedParent == CLEAR), then 8564 encryptedDuplication may be SET or CLEAR in the object. 8565 NOTE 3 8566 8567 This allows the object at the boundary between duplicable and non -duplicable objects to have either 8568 setting. 8569 8570 If an object's parent has fixedTPM CLEAR, then the object is required to have the same setting of 8571 encryptedDuplication as its parent. 8572 NOTE 4 8573 8574 This requirement forces all 8575 encryptedDuplication setting. 8576 8577 duplicable 8578 8579 objects 8580 8581 in 8582 8583 a 8584 8585 duplication 8586 8587 group 8588 8589 to 8590 8591 have 8592 8593 the 8594 8595 same 8596 8597 Creation 8598 8599 shall be CLEAR if fixedTPM is SET. If fixedTPM is CLEAR, then this attribute shall have 8600 the same value as its parent unless fixedTPM is SET in the object's parent, in which 8601 case, it may be SET or CLEAR. 8602 8603 Load 8604 8605 8606 8607 shall be CLEAR if fixedTPM is SET. If fixedTPM is CLEAR, then this attribute shall have 8608 the same value as its parent, unless fixedTPM is SET the parent, in which case, it may 8609 be SET or CLEAR. 8610 8611 Import 8612 8613 8614 8615 if fixedTPM is SET in the object's new parent, then this attribute may be SET or CLEAR, 8616 otherwise, it shall have the same setting as the new parent. 8617 8618 External 8619 8620 8621 8622 may be SET or CLEAR. 8623 8624 8.3.3.10 8625 8626 Bit[16] restricted 8627 8628 This this attribute modifies the decrypt and sign attributes of an object. 8629 NOTE 8630 8631 A key with this object CLEAR may not be a parent for another object. 8632 8633 Creation 8634 8635 shall be CLEAR in template if neither sign nor decrypt is SET in template. 8636 8637 Load 8638 8639 8640 8641 shall be CLEAR if neither sign nor decrypt is SET in the object 8642 8643 Import 8644 8645 8646 8647 may be SET or CLEAR 8648 8649 External 8650 8651 8652 8653 shall be CLEAR 8654 8655 Page 60 8656 October 31, 2013 8657 8658 Published 8659 Copyright TCG 2006-2013 8660 8661 Family 2.0 8662 Level 00 Revision 00.99 8663 8664 Trusted Platform Module Library 8666 8.3.3.11 8667 8668 Part 2: Structures 8669 8670 Bit[17] decrypt 8671 8672 When SET, the private portion of this key can be used to decrypt an external blob. If restricted is SET, 8673 then the TPM will return an error if the external decrypted blob is not formatted as appropriate for the 8674 command. 8675 NOTE 1 8676 8677 Since TPM-generated keys and sealed data will contain a hash and a structure tag, the TPM can ensure 8678 that it is not being used to improperly decrypt and return sensitive data that should not be returned. The 8679 only type of data that may be returned after decryption is a Sealed Data Object (a keyedHash object with 8680 decrypt and sign CLEAR). 8681 8682 When restricted is CLEAR, there are no restrictions on the use of the private portion of the key for 8683 decryption and the key may be used to decrypt and return any structure encrypted by the public portion of 8684 the key. 8685 NOTE 2 8686 8687 A key with this attribute SET may be a parent for another object if restricted is SET and sign is CLEAR. 8688 8689 If decrypt is SET on an object with type set to TPM_ALG_KEYEDHASH, it indicates that the object is an 8690 XOR encryption key. 8691 Creation 8692 8693 may be SET or CLEAR in template 8694 8695 Load 8696 8697 8698 8699 may be SET or CLEAR 8700 8701 Import 8702 8703 8704 8705 may be SET or CLEAR 8706 8707 External 8708 8709 8710 8711 may be SET or CLEAR 8712 8713 8.3.3.12 8714 8715 Bit[18] sign 8716 8717 When this attribute is SET, the private portion of this key may be used to sign a digest. If restricted is 8718 SET, then the key may only be used to sign a digest that was computed by the TPM. A restricted signing 8719 key may be used to sign a TPM-generated digest. If a structure is generated by the TPM, it will begin with 8720 TPM_GENERATED_VALUE and the TPM may sign the digest of that structure. If the data is externally 8721 supplied and has TPM_GENERATED_VALUE as its first octets, then the TPM will not sign a digest of 8722 that data with a restricted signing key. 8723 If restricted is CLEAR, then the key may be used to sign any digest, whether generated by the TPM or 8724 externally provided. 8725 NOTE 1 8726 8727 Some asymmetric algorithms may not support both sign and decrypt being SET in the same key. 8728 8729 If sign is SET on an object with type set to TPM_ALG_KEYEDHASH, it indicates that the object is an 8730 HMAC key. 8731 NOTE 2 8732 8733 A key with this attribute SET may not be a parent for another object. 8734 8735 Creation 8736 8737 shall not be SET if decrypt and restricted are both SET 8738 8739 Load 8740 8741 8742 8743 shall not be SET if decrypt and restricted are both SET 8744 8745 Import 8746 8747 8748 8749 shall not be SET if decrypt and restricted are both SET 8750 8751 External 8752 8753 8754 8755 shall not be SET if decrypt and restricted are both SET 8756 8757 Family 2.0 8758 Level 00 Revision 00.99 8759 8760 Published 8761 Copyright TCG 2006-2013 8762 8763 Page 61 8764 October 31, 2013 8765 8766 Part 2: Structures 8768 8.4 8769 8770 Trusted Platform Module Library 8771 8772 TPMA_SESSION (Session Attributes) 8773 8774 This octet in each session is used to identify the session type, indicate its relationship to any handles in 8775 the command, and indicate its use in parameter encryption. 8776 Table 31 Definition of (UINT8) TPMA_SESSION Bits <IN/OUT> 8777 Bit 8778 8779 Name 8780 8781 Meaning 8782 8783 0 8784 8785 continueSession 8786 8787 SET (1): In a command, this setting indicates that the session is to remain active 8788 after successful completion of the command. In a response, it indicates that the 8789 session is still active. If SET in the command, this attribute shall be SET in the 8790 response. 8791 CLEAR (0): In a command, this setting indicates that the TPM should close the 8792 session and flush any related context when the command completes successfully. In 8793 a response, it indicates that the session is closed and the context is no longer active. 8794 This attribute has no meaning for a password authorization and the TPM will allow 8795 any setting of the attribute in the command and SET the attribute in the response. 8796 This attribute will only be CLEAR in one response for a logical session. If the attribute 8797 is CLEAR, the context associated with the session is no longer in use and the space 8798 is available. A session created after another session is ended may have the same 8799 handle but logically is not the same session. 8800 This attribute has no effect if the command does not complete successfully. 8801 8802 1 8803 8804 auditExclusive 8805 8806 SET (1): In a command, this setting indicates that the command should only be 8807 executed if the session is exclusive at the start of the command. In a response, it 8808 indicates that the session is exclusive. This setting is only allowed if the audit 8809 attribute is SET. 8810 CLEAR (0): If audit is CLEAR, then this field is reserved but the error is 8811 TPM_RC_ATTRIBUTES rather than TPM_RC_RESERVED_BITS. 8812 See "Exclusive Audit Session" clause in Part 1. 8813 8814 2 8815 8816 auditReset 8817 8818 SET (1): In a command, this setting indicates that the audit digest of the session 8819 should be initialized and the exclusive status of the session SET. 8820 CLEAR (0): If audit is CLEAR, then this field is reserved but the error is 8821 TPM_RC_ATTRIBUTES rather than TPM_RC_RESERVED_BITS. This setting is 8822 always used for a response. 8823 8824 4:3 8825 8826 Reserved 8827 8828 shall be CLEAR 8829 8830 decrypt 8831 8832 SET (1): In a command, this setting indicates that the first parameter in the command 8833 is symmetrically encrypted using the parameter encryption scheme described in Part 8834 1. The TPM will decrypt the parameter after performing any HMAC computations and 8835 before unmarshaling the parameter. In a response, the attribute is copied from the 8836 request but has no effect on the response. 8837 CLEAR (0): Session not used for encryption. 8838 8839 5 8840 8841 For a password authorization, this attribute will be CLEAR in both the command and 8842 response. 8843 This attribute may only be SET in one session per command. 8844 This attribute may be SET in a session that is not associated with a command 8845 handle. Such a session is provided for purposes of encrypting a parameter and not 8846 for authorization. 8847 This attribute may be SET in combination with any other session attributes. 8848 This attribute may only be SET if the first parameter of the command is a sized buffer 8849 (TPM2B_). 8850 8851 Page 62 8852 October 31, 2013 8853 8854 Published 8855 Copyright TCG 2006-2013 8856 8857 Family 2.0 8858 Level 00 Revision 00.99 8859 8860 Trusted Platform Module Library 8862 8863 Part 2: Structures 8864 8865 Bit 8866 8867 Name 8868 8869 Meaning 8870 8871 6 8872 8873 encrypt 8874 8875 SET (1): In a command, this setting indicates that the TPM should use this session to 8876 encrypt the first parameter in the response. In a response, it indicates that the 8877 attribute was set in the command and that the TPM used the session to encrypt the 8878 first parameter in the response using the parameter encryption scheme described in 8879 Part 1 of this specification. 8880 CLEAR (0): Session not used for encryption. 8881 For a password authorization, this attribute will be CLEAR in both the command and 8882 response. 8883 This attribute may only be SET in one session per command. 8884 This attribute may be SET in a session that is not associated with a command 8885 handle. Such a session is provided for purposes of encrypting a parameter and not 8886 for authorization. 8887 This attribute may only be SET if the first parameter of a response is a sized buffer 8888 (TPM2B_). 8889 8890 7 8891 8892 SET (1): In a command or response, this setting indicates that the session is for audit 8893 and that auditExclusive and auditReset have meaning. This session may also be 8894 used for authorization, encryption, or decryption. The encrypted and encrypt fields 8895 may be SET or CLEAR. 8896 CLEAR (0): Session is not used for audit. 8897 8898 audit 8899 8900 This attribute may only be SET in one session per command or response. If SET in 8901 the command, then this attribute will be SET in the response. 8902 8903 8.5 8904 8905 TPMA_LOCALITY (Locality Attribute) 8906 8907 In a TPMS_CREATION_DATA structure, this structure is used to indicate the locality of the command that 8908 created the object. No more than one of the locality attributes shall be set in the creation data. 8909 When used in TPM2_PolicyLocality(), this structure indicates which localities are approved by the policy. 8910 When a policy is started, all localities are allowed. If TPM2_PolicyLocality() is executed, it indicates that 8911 the command may only be executed at specific localities. More than one locality may be selected. 8912 EXAMPLE 1 8913 8914 TPM_LOC_TWO would indicate that only locality 2 is authorized. 8915 8916 EXAMPLE 2 8917 8918 TPM_LOC_ONE + TPM_LOC_TWO would indicate that locality 1 or 2 is authorized. 8919 8920 EXAMPLE 3 8921 8922 TPM_LOC_FOUR + TPM_LOC_THREE would indicate that localities 3 or 4 are authorized. 8923 8924 EXAMPLE 4 8925 8926 A value of 21 16 would represent a locality of 33. 8927 8928 NOTE 8929 8930 Locality values of 5 through 31 are not selectable. 8931 8932 Family 2.0 8933 Level 00 Revision 00.99 8934 8935 Published 8936 Copyright TCG 2006-2013 8937 8938 Page 63 8939 October 31, 2013 8940 8941 Part 2: Structures 8943 8944 Trusted Platform Module Library 8945 8946 If Extended is non-zero, then an extended locality is indicated and the TPMA_LOCALITY contains an 8947 integer value. 8948 Table 32 Definition of (UINT8) TPMA_LOCALITY Bits <IN/OUT> 8949 Bit 8950 8951 Name 8952 8953 Definition 8954 8955 0 8956 8957 TPM_LOC_ZERO 8958 8959 1 8960 8961 TPM_LOC_ONE 8962 8963 2 8964 8965 TPM_LOC_TWO 8966 8967 3 8968 8969 TPM_LOC_THREE 8970 8971 4 8972 8973 TPM_LOC_FOUR 8974 8975 7:5 8976 8977 8.6 8978 8979 Extended 8980 8981 If any of these bits is set, an extended locality is indicated 8982 8983 TPMA_PERMANENT 8984 8985 The attributes in this structure are persistent and are not changed as a result of _TPM_Init or any 8986 TPM2_Startup(). Some of the attributes in this structure may change as the result of specific Protected 8987 Capabilities. 8988 This 8989 structure 8990 may 8991 be 8992 read 8993 using 8994 TPM2_GetCapability(capability 8995 = 8996 TPM_CAP_TPM_PROPERTIES, property = TPM_PT_PERMANENT). 8997 Table 33 Definition of (UINT32) TPMA_PERMANENT Bits <OUT> 8998 Bit 8999 9000 Parameter 9001 9002 Description 9003 9004 0 9005 9006 ownerAuthSet 9007 9008 SET (1): TPM2_HierarchyChangeAuth() with ownerAuth has been executed since 9009 the last TPM2_Clear(). 9010 CLEAR (0): ownerAuth has not been changed since TPM2_Clear(). 9011 9012 1 9013 9014 endorsementAuthSet 9015 9016 SET (1): TPM2_HierarchyChangeAuth() with endorsementAuth has been executed 9017 since the last TPM2_Clear(). 9018 CLEAR (0): endorsementAuth has not been changed since TPM2_Clear(). 9019 9020 2 9021 9022 lockoutAuthSet 9023 9024 SET (1): TPM2_HierarchyChangeAuth() with lockoutAuth has been executed since 9025 the last TPM2_Clear(). 9026 CLEAR (0): lockoutAuth has not been changed since TPM2_Clear(). 9027 9028 7:3 9029 8 9030 9031 Reserved 9032 disableClear 9033 9034 SET (1): TPM2_Clear() is disabled. 9035 CLEAR (0): TPM2_Clear() is enabled. 9036 NOTE 9037 9038 See TPM2_ClearControl in Part 3 of this specification for details on changing 9039 this attribute. 9040 9041 9 9042 9043 inLockout 9044 9045 SET (1): The TPM is in lockout and commands that require authorization with other 9046 than platformAuth will not succeed. 9047 9048 10 9049 9050 tpmGeneratedEPS 9051 9052 SET (1): The EPS was created by the TPM. 9053 CLEAR (0): The EPS was created outside of the TPM using a manufacturerspecific process. 9054 9055 31:11 Reserved 9056 9057 Page 64 9058 October 31, 2013 9059 9060 Published 9061 Copyright TCG 2006-2013 9062 9063 Family 2.0 9064 Level 00 Revision 00.99 9065 9066 Trusted Platform Module Library 9068 8.7 9069 9070 Part 2: Structures 9071 9072 TPMA_STARTUP_CLEAR 9073 9074 These attributes are set to their default state on reset on each TPM Reset or TPM Restart. The attributes 9075 are preserved on TPM Resume. 9076 On each TPM2_Startup(TPM_SU_CLEAR), the TPM will set these attributes to their indicated defaults. 9077 This structure may be read using TPM2_GetCapability(capability = TPM_CAP_TPM_PROPERTIES, 9078 property = TPM_PT_STARTUP_CLEAR). 9079 Some of attributes may be changed as the result of specific Protected Capabilities. 9080 Table 34 Definition of (UINT32) TPMA_STARTUP_CLEAR Bits <OUT> 9081 Bit 9082 0 9083 9084 Parameter 9085 9086 Description 9087 9088 phEnable 9089 9090 SET (1): (default) The platform hierarchy is enabled and platformAuth or 9091 platformPolicy may be used for authorization. 9092 CLEAR (0): platformAuth and platformPolicy may not be used for authorizations, 9093 and objects in the platform hierarchy, including NV Indexes and persistent objects, 9094 cannot be used. 9095 NOTE 9096 9097 1 9098 9099 shEnable 9100 9101 SET (1): (default) The Storage hierarchy is enabled and ownerAuth or ownerPolicy 9102 may be used for authorization. 9103 CLEAR (0): ownerAuth and ownerPolicy may not be used for authorizations, and 9104 objects in the Storage hierarchy, including NV Indexes and persistent objects, 9105 cannot be used. 9106 NOTE 9107 9108 2 9109 9110 ehEnable 9111 9112 phEnableNV 9113 9114 See TPM2_HierarchyControl in Part 3 of this specification for details on 9115 changing this attribute. 9116 9117 SET (1): (default) The EPS hierarchy is enabled and endorsementAuth may be 9118 used to authorize commands. 9119 CLEAR (0): endorsementAuth and endorsementPolicy may not be used for 9120 authorizations, and objects in the endorsement hierarchy, including persistent 9121 objects, cannot be used. 9122 NOTE 9123 9124 3 9125 9126 See TPM2_HierarchyControl in Part 3 of this specification for details on 9127 changing this attribute. 9128 9129 See TPM2_HierarchyControl in Part 3 of this specification for details on 9130 changing this attribute. 9131 9132 SET (1): (default) NV indices that have TPMA_PLATFORM_CREATE SET may be 9133 read or written. The platform can create define and undefine indices. 9134 CLEAR (0): NV indices that have TPMA_PLATFORM_CREATE SET may not be 9135 read or written (TPM_RC_HANDLE). The platform cannot 9136 define 9137 (TPM_RC_HIERARCHY) or undefined (TPM_RC_HANDLE) indices. 9138 NOTE 9139 See TPM2_HierarchyControl in Part 3 of this specification for details on changing 9140 this attribute. 9141 NOTE 9142 read refers to these commands: TPM2_NV_Read, TPM2_NV_ReadPublic, TPM_NV_Certify, 9143 TPM2_PolicyNV 9144 write refers to thse commands: TPM2_NV_Write, TPM2_NV_Increment, TPM2_NV_Extend, 9145 TPM2_NV_SetBits 9146 NOTE The TPM must query the index TPMA_PLATFORM_CREATE attribute to determine 9147 whether phEnableNV is applicable. Since the TPM will return TPM_RC_HANDLE if the index 9148 does not exist, it also returns this error code if the index is disabled. Otherwise, the TPM 9149 would leak the existence of an index even when disabled. 9150 9151 30:4 Reserved 9152 9153 Family 2.0 9154 Level 00 Revision 00.99 9155 9156 shall be zero 9157 9158 Published 9159 Copyright TCG 2006-2013 9160 9161 Page 65 9162 October 31, 2013 9163 9164 Part 2: Structures 9166 9167 Trusted Platform Module Library 9168 9169 Bit 9170 9171 Parameter 9172 9173 Description 9174 9175 31 9176 9177 orderly 9178 9179 SET (1): The TPM received a TPM2_Shutdown() and a matching TPM2_Startup(). 9180 CLEAR (0): TPM2_Startup(TPM_SU_CLEAR) was not preceded by a 9181 TPM2_Shutdown() of any type. 9182 NOTE 9183 9184 8.8 9185 9186 A shutdown is orderly if the TPM receives a TPM2_Shutdown() of any type 9187 followed by a TPM2_Startup() of any type. However, the TPM will return an error if 9188 TPM2_Startup(TPM_SU_STATE) 9189 was 9190 not 9191 preceded 9192 by 9193 TPM2_State_Save(TPM_SU_STATE). 9194 9195 TPMA_MEMORY 9196 9197 This structure of this attribute is used to report the memory management method used by the TPM for 9198 transient 9199 objects 9200 and 9201 authorization 9202 sessions. 9203 This 9204 structure 9205 may be 9206 read 9207 using 9208 TPM2_GetCapability(capability = TPM_CAP_TPM_PROPERTIES, property = TPM_PT_MEMORY). 9209 If the RAM memory is shared, then context save of a session may make it possible to load an additional 9210 transient object. 9211 Table 35 Definition of (UINT32) TPMA_MEMORY Bits <Out> 9212 Bit 9213 9214 Name 9215 9216 Definition 9217 9218 0 9219 9220 sharedRAM 9221 9222 SET (1): indicates that the RAM memory used for authorization session 9223 contexts is shared with the memory used for transient objects 9224 CLEAR (0): indicates that the memory used for authorization sessions is not 9225 shared with memory used for transient objects 9226 9227 1 9228 9229 sharedNV 9230 9231 SET (1): indicates that the NV memory used for persistent objects is shared 9232 with the NV memory used for NV Index values 9233 CLEAR (0): indicates that the persistent objects and NV Index values are 9234 allocated from separate sections of NV 9235 9236 2 9237 9238 objectCopiedToRam 9239 9240 SET (1): indicates that the TPM copies persistent objects to a transient-object 9241 slot in RAM when the persistent object is referenced in a command. The TRM 9242 is required to make sure that an object slot is available. 9243 CLEAR (0): indicates that the TPM does not use transient-object slots when 9244 persistent objects are referenced 9245 9246 31:3 9247 9248 Reserved 9249 9250 shall be zero 9251 9252 Page 66 9253 October 31, 2013 9254 9255 Published 9256 Copyright TCG 2006-2013 9257 9258 Family 2.0 9259 Level 00 Revision 00.99 9260 9261 Trusted Platform Module Library 9263 8.9 9264 9265 Part 2: Structures 9266 9267 TPMA_CC (Command Code Attributes) 9268 9269 8.9.1 9270 9271 Introduction 9272 9273 This structure defines the attributes of a command from a context management perspective. The fields of 9274 the structure indicate to the TPM Resource Manager (TRM) the number of resources required by a 9275 command and how the command affects the TPMs resources. 9276 This structure is only used in a list returned by the TPM in response to TPM2_GetCapability(capability = 9277 TPM_CAP_COMMANDS). 9278 For a command to the TPM, only the commandIndex field and V attribute are allowed to be non-zero. 9279 8.9.2 9280 9281 Structure Definition 9282 Table 36 Definition of (TPM_CC) TPMA_CC Bits <OUT> 9283 9284 Bit 9285 15:0 9286 9287 Name 9288 9289 Definition 9290 9291 commandIndex 9292 9293 indicates the command being selected 9294 9295 21:16 Reserved 9296 9297 shall be zero 9298 9299 22 9300 9301 nv 9302 9303 SET (1): indicates that the command may write to NV 9304 CLEAR (0): indicates that the command does not write to NV 9305 9306 23 9307 9308 extensive 9309 9310 SET (1): This command could flush any number of loaded contexts. 9311 CLEAR (0): no additional changes other than indicated by the flushed attribute 9312 9313 24 9314 9315 flushed 9316 9317 SET (1): The context associated with any transient handle in the command will 9318 be flushed when this command completes. 9319 CLEAR (0): No context is flushed as a side effect of this command. 9320 9321 27:25 cHandles 9322 9323 indicates the number of the handles in the handle area for this command 9324 9325 28 9326 9327 rHandle 9328 9329 SET (1): indicates the presence of the handle area in the input 9330 9331 29 9332 9333 V 9334 9335 SET (1): indicates that the command is vendor-specific 9336 CLEAR (0): indicates that the command is defined in a version of this 9337 specification 9338 9339 31:30 Res 9340 9341 8.9.3 9342 8.9.3.1 9343 9344 allocated for software; shall be zero 9345 9346 Field Descriptions 9347 Bits[15:0] commandIndex 9348 9349 This is the command index of the command in the set of commands. The two sets are defined by the V 9350 attribute. If V is zero, then the commandIndex shall be in the set of commands defined in a version of this 9351 specification. If V is one, then the meaning of commandIndex is as determined by the TPM vendor. 9352 8.9.3.2 9353 9354 Bit[22] nv 9355 9356 If this attribute is SET, then the TPM may perform an NV write as part of the command actions. This write 9357 is independent of any write that may occur as a result of dictionary attack protection. If this attribute is 9358 CLEAR, then the TPM shall not perform an NV write as part of the command actions. 9359 8.9.3.3 9360 9361 Bit[23] extensive 9362 9363 Family 2.0 9364 Level 00 Revision 00.99 9365 9366 Published 9367 Copyright TCG 2006-2013 9368 9369 Page 67 9370 October 31, 2013 9371 9372 Part 2: Structures 9374 9375 Trusted Platform Module Library 9376 9377 If this attribute is SET, then the TPM may flush many transient objects as a side effect of this command. 9378 In Part 3, a command that has this attribute is indicated by using a {E} decoration in the Description 9379 column of the commandCode parameter. 9380 EXAMPLE 9381 9382 See TPM2_Clear in Part 3. 9383 9384 NOTE 9385 9386 The {E} decoration may be combined with other decorations such as {NV} in which case the decoration 9387 would be {NV E}. 9388 9389 8.9.3.4 9390 9391 Bit[24] flushed 9392 9393 If this attribute is SET, then the TPM will flush transient objects as a side effect of this command. Any 9394 transient objects listed in the handle area of the command will be flushed from TPM memory. Handles 9395 associated with persistent objects, sessions, PCR, or other fixed TPM resources are not flushed. 9396 NOTE 9397 9398 The TRM is expected to use this value to determine how many objects are loaded into transient TPM 9399 memory. 9400 9401 NOTE 9402 9403 The {F} decoration may be combined with other decorations such as {NV} in which case the decoration 9404 would be {NV F}. 9405 9406 If this attribute is SET for a command, and the handle of the command is associated with a hierarchy 9407 (TPM_RH_PLATFORM, TPM_RH_OWNER, or TPM_RH_ENDORSEMENT), all loaded objects in the 9408 indicated hierarchy are flushed. 9409 The TRM is expected to know the behaviour of TPM2_ContextSave(), and sessions are flushed when 9410 context saved, but objects are not. The flushed attribute for that command shall be CLEAR. 9411 In Part 3, a command that has this attribute is indicated by using a {F} decoration in the Description 9412 column of the commandCode parameter. 9413 EXAMPLE 9414 9415 8.9.3.5 9416 9417 See TPM2_SequenceComplete in Part 3. 9418 9419 Bits[27:25] cHandles 9420 9421 This field indicates the number of handles in the handle area of the command. This number allows the 9422 TRM to enumerate the handles in the handle area and find the position of the authorizations (if any). 9423 8.9.3.6 9424 9425 Bit[28] rHandle 9426 9427 If this attribute is SET, then the response to this command has a handle area. This area will contain no 9428 more than one handle. This field is necessary to allow the TRM to locate the parameterSize field in the 9429 response, which is then used to locate the authorizations. 9430 NOTE 9431 9432 The TRM is expected to virtualize the handle value for any returned handle. 9433 9434 Page 68 9435 October 31, 2013 9436 9437 Published 9438 Copyright TCG 2006-2013 9439 9440 Family 2.0 9441 Level 00 Revision 00.99 9442 9443 Trusted Platform Module Library 9445 9446 Part 2: Structures 9447 9448 A TPM command is only allowed to have one handle in the session area. 9449 8.9.3.7 9450 9451 Bit[29] V 9452 9453 When this attribute is SET, it indicates that the command operation is defined by the TPM vendor. When 9454 CLEAR, it indicates that the command is defined by a version of this specification. 9455 8.9.3.8 9456 9457 Bits[31:30] Res 9458 9459 This field is reserved for system software. This field is required to be zero for a command to the TPM. 9460 9461 Family 2.0 9462 Level 00 Revision 00.99 9463 9464 Published 9465 Copyright TCG 2006-2013 9466 9467 Page 69 9468 October 31, 2013 9469 9470 Part 2: Structures 9472 9473 9 9474 9475 Trusted Platform Module Library 9476 9477 Interface Types 9478 9479 9.1 9480 9481 Introduction 9482 9483 This clause contains definitions for interface types. An interface type is type checked when it is 9484 unmarshaled. These types are based on an underlying type that is indicated in the table title by the value 9485 in parentheses. When an interface type is used, the base type is unmarshaled and then checked to see if 9486 it has one of the allowed values. 9487 9.2 9488 9489 TPMI_YES_NO 9490 9491 This interface type is used in place of a Boolean type in order to eliminate ambiguity in the handling of a 9492 octet that conveys a single bit of information. This type only has two allowed values, YES (1) and NO (0). 9493 NOTE 9494 9495 This list is not used as input to the TPM. 9496 9497 Table 37 Definition of (BYTE) TPMI_YES_NO Type 9498 Value 9499 9500 Description 9501 9502 NO 9503 9504 a value of 0 9505 9506 YES 9507 9508 a value of 1 9509 9510 #TPM_RC_VALUE 9511 9512 9.3 9513 9514 TPMI_DH_OBJECT 9515 9516 The TPMI_DH_OBJECT interface type is a handle that references a loaded object. The handles in this 9517 set are used to refer to either transient or persistent object. The range of these values would change 9518 according to the TPM implementation. 9519 NOTE 9520 9521 These interface types should not be used by system software to qualify the keys produced by the TPM. 9522 The value returned by the TPM shall be used to reference the object. 9523 9524 Table 38 Definition of (TPM_HANDLE) TPMI_DH_OBJECT Type 9525 Values 9526 9527 Comments 9528 9529 {TRANSIENT_FIRST:TRANSIENT_LAST} 9530 9531 allowed range for transient objects 9532 9533 {PERSISTENT_FIRST:PERSISTENT_LAST} 9534 9535 allowed range for persistent objects 9536 9537 +TPM_RH_NULL 9538 9539 the conditional value 9540 9541 #TPM_RC_VALUE 9542 9543 Page 70 9544 October 31, 2013 9545 9546 Published 9547 Copyright TCG 2006-2013 9548 9549 Family 2.0 9550 Level 00 Revision 00.99 9551 9552 Trusted Platform Module Library 9554 9.4 9555 9556 Part 2: Structures 9557 9558 TPMI_DH_PERSISTENT 9559 9560 The TPMI_DH_PERSISTENT interface type is a handle that references a location for a transient object. 9561 This type is used in TPM2_EvictControl() to indicate the handle to be assigned to the persistent object. 9562 Table 39 Definition of (TPM_HANDLE) TPMI_DH_PERSISTENT Type 9563 Values 9564 9565 Comments 9566 9567 {PERSISTENT_FIRST:PERSISTENT_LAST} 9568 9569 allowed range for persistent objects 9570 9571 #TPM_RC_VALUE 9572 9573 9.5 9574 9575 TPMI_DH_ENTITY 9576 9577 The TPMI_DH_ENTITY interface type is TPM-defined values that are used to indicate that the handle 9578 refers to an authValue. The range of these values would change according to the TPM implementation. 9579 Table 40 Definition of (TPM_HANDLE) TPMI_DH_ENTITY Type <IN> 9580 Values 9581 9582 Comments 9583 9584 TPM_RH_OWNER 9585 TPM_RH_ENDORSEMENT 9586 TPM_RH_PLATFORM 9587 TPM_RH_LOCKOUT 9588 {TRANSIENT_FIRST : TRANSIENT_LAST} 9589 9590 range of object handles 9591 9592 {PERSISTENT_FIRST : PERSISTENT_LAST} 9593 {NV_INDEX_FIRST : NV_INDEX_LAST} 9594 {PCR_FIRST : PCR_LAST} 9595 +TPM_RH_NULL 9596 9597 conditional value 9598 9599 #TPM_RC_VALUE 9600 9601 Family 2.0 9602 Level 00 Revision 00.99 9603 9604 Published 9605 Copyright TCG 2006-2013 9606 9607 Page 71 9608 October 31, 2013 9609 9610 Part 2: Structures 9612 9.6 9613 9614 Trusted Platform Module Library 9615 9616 TPMI_DH_PCR 9617 9618 This interface type consists of the handles that may be used as PCR references. The upper end of this 9619 range of values would change according to the TPM implementation. 9620 NOTE 1 9621 9622 Typically, the 0 th PCR will have a handle value of zero. 9623 9624 NOTE 2 9625 9626 The handle range for PCR is defined to be the same as the handle range for PCR in previous versions of 9627 TPM specifications. 9628 9629 Table 41 Definition of (TPM_HANDLE) TPMI_DH_PCR Type <IN> 9630 Values 9631 9632 Comments 9633 9634 {PCR_FIRST:PCR_LAST} 9635 +TPM_RH_NULL 9636 9637 conditional value 9638 9639 #TPM_RC_VALUE 9640 9641 9.7 9642 9643 TPMI_SH_AUTH_SESSION 9644 9645 The TPMI_SH_AUTH_SESSION interface type is TPM-defined values that are used to indicate that the 9646 handle refers to an authorization session. 9647 Table 42 Definition of (TPM_HANDLE) TPMI_SH_AUTH_SESSION Type <IN/OUT> 9648 Values 9649 9650 Comments 9651 9652 {HMAC_SESSION_FIRST : HMAC_SESSION_LAST} 9653 9654 range of HMAC authorization session handles 9655 9656 {POLICY_SESSION_FIRST: POLICY_SESSION_LAST} 9657 9658 range of policy authorization session handles 9659 9660 +TPM_RS_PW 9661 9662 a password authorization 9663 9664 #TPM_RC_VALUE 9665 9666 error returned if the handle is out of range 9667 9668 9.8 9669 9670 TPMI_SH_HMAC 9671 9672 This interface type is used for an authorization handle when the authorization session uses an HMAC. 9673 Table 43 Definition of (TPM_HANDLE) TPMI_SH_HMAC Type <IN/OUT> 9674 Values 9675 9676 Comments 9677 9678 {HMAC_SESSION_FIRST: HMAC_SESSION_LAST} 9679 9680 range of HMAC authorization session handles 9681 9682 #TPM_RC_VALUE 9683 9684 error returned if the handle is out of range 9685 9686 9.9 9687 9688 TPMI_SH_POLICY 9689 9690 This interface type is used for a policy handle when it appears in a policy command. 9691 Table 44 Definition of (TPM_HANDLE) TPMI_SH_POLICY Type <IN/OUT> 9692 Values 9693 9694 Comments 9695 9696 {POLICY_SESSION_FIRST: POLICY_SESSION_LAST} 9697 9698 range of policy authorization session handles 9699 9700 #TPM_RC_VALUE 9701 9702 error returned if the handle is out of range 9703 9704 Page 72 9705 October 31, 2013 9706 9707 Published 9708 Copyright TCG 2006-2013 9709 9710 Family 2.0 9711 Level 00 Revision 00.99 9712 9713 Trusted Platform Module Library 9715 9716 Part 2: Structures 9717 9718 9.10 TPMI_DH_CONTEXT 9719 This type defines the handle values that may be used in TPM2_ContextSave() or TPM2_Flush(). 9720 Table 45 Definition of (TPM_HANDLE) TPMI_DH_CONTEXT Type 9721 Values 9722 9723 Comments 9724 9725 {HMAC_SESSION_FIRST : HMAC_SESSION_LAST} 9726 {POLICY_SESSION_FIRST:POLICY_SESSION_LAST} 9727 {TRANSIENT_FIRST:TRANSIENT_LAST} 9728 #TPM_RC_VALUE 9729 9730 9.11 TPMI_RH_HIERARCHY 9731 The TPMI_RH_HIERARCHY interface type is used as the type of a handle in a command when the 9732 handle is required to be one of the hierarchy selectors. 9733 Table 46 Definition of (TPM_HANDLE) TPMI_RH_HIERARCHY Type 9734 Values 9735 9736 Comments 9737 9738 TPM_RH_OWNER 9739 9740 Storage hierarchy 9741 9742 TPM_RH_PLATFORM 9743 9744 Platform hierarchy 9745 9746 TPM_RH_ENDORSEMENT 9747 9748 Endorsement hierarchy 9749 9750 +TPM_RH_NULL 9751 9752 no hierarchy 9753 9754 #TPM_RC_VALUE 9755 9756 response code returned when the unmarshaling of this type fails 9757 9758 9.12 TPMI_RH_ENABLES 9759 The TPMI_RH_ENABLES interface type is used as the type of a handle in a command when the handle 9760 is required to be one of the hierarchy or NV enables. 9761 Table 47 Definition of (TPM_HANDLE) TPMI_RH_ENABLES Type 9762 Values 9763 9764 Comments 9765 9766 TPM_RH_OWNER 9767 9768 Storage hierarchy 9769 9770 TPM_RH_PLATFORM 9771 9772 Platform hierarchy 9773 9774 TPM_RH_ENDORSEMENT 9775 9776 Endorsement hierarchy 9777 9778 TPM_RH_PLATFORM_NV 9779 9780 Platform NV 9781 9782 +TPM_RH_NULL 9783 9784 no hierarchy 9785 9786 #TPM_RC_VALUE 9787 9788 response code returned when the unmarshaling of this type fails 9789 9790 Family 2.0 9791 Level 00 Revision 00.99 9792 9793 Published 9794 Copyright TCG 2006-2013 9795 9796 Page 73 9797 October 31, 2013 9798 9799 Part 2: Structures 9801 9802 Trusted Platform Module Library 9803 9804 9.13 TPMI_RH_HIERARCHY_AUTH 9805 This interface type is used as the type of a handle in a command when the handle is required to be one of 9806 the hierarchy selectors or the Lockout Authorization. 9807 Table 48 Definition of (TPM_HANDLE) TPMI_RH_HIERARCHY_AUTH Type <IN> 9808 Values 9809 9810 Comments 9811 9812 TPM_RH_OWNER 9813 9814 Storage hierarchy 9815 9816 TPM_RH_PLATFORM 9817 9818 Platform hierarchy 9819 9820 TPM_RH_ENDORSEMENT 9821 9822 Endorsement hierarchy 9823 9824 TPM_RH_LOCKOUT 9825 9826 Lockout Authorization 9827 9828 #TPM_RC_VALUE 9829 9830 response code returned when the unmarshaling of this type fails 9831 9832 9.14 TPMI_RH_PLATFORM 9833 The TPMI_RH_PLATFORM interface type is used as the type of a handle in a command when the only 9834 allowed handle is TPM_RH_PLATFORM indicating that platformAuth is required. 9835 Table 49 Definition of (TPM_HANDLE) TPMI_RH_PLATFORM Type <IN> 9836 Values 9837 9838 Comments 9839 9840 TPM_RH_PLATFORM 9841 9842 Platform hierarchy 9843 9844 #TPM_RC_VALUE 9845 9846 response code returned when the unmarshaling of this type fails 9847 9848 9.15 TPMI_RH_OWNER 9849 This interface type is used as the type of a handle in a command when the only allowed handle is 9850 TPM_RH_OWNER indicating that ownerAuth is required. 9851 Table 50 Definition of (TPM_HANDLE) TPMI_RH_OWNER Type <IN> 9852 Values 9853 9854 Comments 9855 9856 TPM_RH_OWNER 9857 9858 Owner hierarchy 9859 9860 +TPM_RH_NULL 9861 9862 may allow the null handle 9863 9864 #TPM_RC_VALUE 9865 9866 response code returned when the unmarshaling of this type fails 9867 9868 Page 74 9869 October 31, 2013 9870 9871 Published 9872 Copyright TCG 2006-2013 9873 9874 Family 2.0 9875 Level 00 Revision 00.99 9876 9877 Trusted Platform Module Library 9879 9880 Part 2: Structures 9881 9882 9.16 TPMI_RH_ENDORSEMENT 9883 This interface type is used as the type of a handle in a command when the only allowed handle is 9884 TPM_RH_ENDORSEMENT indicating that endorsementAuth is required. 9885 Table 51 Definition of (TPM_HANDLE) TPMI_RH_ENDORSEMENT Type <IN> 9886 Values 9887 9888 Comments 9889 9890 TPM_RH_ENDORSEMENT 9891 9892 Endorsement hierarchy 9893 9894 +TPM_RH_NULL 9895 9896 may allow the null handle 9897 9898 #TPM_RC_VALUE 9899 9900 response code returned when the unmarshaling of this type fails 9901 9902 9.17 TPMI_RH_PROVISION 9903 The TPMI_RH_PROVISION interface type is used as the type of the handle in a command when the only 9904 allowed handles are either TPM_RH_OWNER or TPM_RH_PLATFORM indicating that either 9905 platformAuth or ownerAuth are allowed. 9906 In most cases, either platformAuth or ownerAuth may be used to authorize the commands used for 9907 management of the resources of the TPM and this interface type will be used. 9908 Table 52 Definition of (TPM_HANDLE) TPMI_RH_PROVISION Type <IN> 9909 Value 9910 9911 Comments 9912 9913 TPM_RH_OWNER 9914 9915 handle for ownerAuth 9916 9917 TPM_RH_PLATFORM 9918 9919 handle for platformAuth 9920 9921 #TPM_RC_VALUE 9922 9923 response code returned when the unmarshaling of this type fails 9924 9925 9.18 TPMI_RH_CLEAR 9926 The TPMI_RH_CLEAR interface type is used as the type of the handle in a command when the only 9927 allowed handles are either TPM_RH_LOCKOUT or TPM_RH_PLATFORM indicating that either 9928 platformAuth or lockoutAuth are allowed. 9929 This interface type is normally used for performing or controlling TPM2_Clear(). 9930 Table 53 Definition of (TPM_HANDLE) TPMI_RH_CLEAR Type <IN> 9931 Value 9932 9933 Comments 9934 9935 TPM_RH_LOCKOUT 9936 9937 handle for lockoutAuth 9938 9939 TPM_RH_PLATFORM 9940 9941 handle for platformAuth 9942 9943 #TPM_RC_VALUE 9944 9945 response code returned when the unmarshaling of this type fails 9946 9947 Family 2.0 9948 Level 00 Revision 00.99 9949 9950 Published 9951 Copyright TCG 2006-2013 9952 9953 Page 75 9954 October 31, 2013 9955 9956 Part 2: Structures 9958 9959 Trusted Platform Module Library 9960 9961 9.19 TPMI_RH_NV_AUTH 9962 This interface type is used to identify the source of the authorization for access to an NV location. The 9963 handle value of a TPMI_RH_NV_AUTH shall indicate that the authorization value is either platformAuth, 9964 ownerAuth, or the authValue. This type is used in the commands that access an NV Index (commands of 9965 the form TPM2_NV_xxx) other than TPM2_NV_DefineSpace() and TPM2_NV_UndefineSpace(). 9966 Table 54 Definition of (TPM_HANDLE) TPMI_RH_NV_AUTH Type <IN> 9967 Value 9968 9969 Comments 9970 9971 TPM_RH_PLATFORM 9972 9973 platformAuth is allowed 9974 9975 TPM_RH_OWNER 9976 9977 ownerAuth is allowed 9978 9979 {NV_INDEX_FIRST:NV_INDEX_LAST} 9980 9981 range for NV locations 9982 9983 #TPM_RC_VALUE 9984 9985 response code returned when unmarshaling of this type fails 9986 9987 9.20 TPMI_RH_LOCKOUT 9988 The TPMI_RH_LOCKOUT interface type is used as the type of a handle in a command when the only 9989 allowed handle is TPM_RH_LOCKOUT indicating that lockoutAuth is required. 9990 Table 55 Definition of (TPM_HANDLE) TPMI_RH_LOCKOUT Type <IN> 9991 Value 9992 9993 Comments 9994 9995 TPM_RH_LOCKOUT 9996 #TPM_RC_VALUE 9997 9998 response code returned when the unmarshaling of this type fails 9999 10000 9.21 TPMI_RH_NV_INDEX 10001 This interface type is used to identify an NV location. This type is used in the NV commands. 10002 Table 56 Definition of (TPM_HANDLE) TPMI_RH_NV_INDEX Type <IN/OUT> 10003 Value 10004 10005 Comments 10006 10007 {NV_INDEX_FIRST:NV_INDEX_LAST} 10008 10009 Range of NV Indexes 10010 10011 #TPM_RC_VALUE 10012 10013 error returned if the handle is out of range 10014 10015 Page 76 10016 October 31, 2013 10017 10018 Published 10019 Copyright TCG 2006-2013 10020 10021 Family 2.0 10022 Level 00 Revision 00.99 10023 10024 Trusted Platform Module Library 10026 10027 Part 2: Structures 10028 10029 9.22 TPMI_ALG_HASH 10030 A TPMI_ALG_HASH is an interface type of all the hash algorithms implemented on a specific TPM. Table 10031 57 is a list of the hash algorithms that have an algorithm ID assigned by the TCG and does not indicate 10032 the algorithms that will be accepted by a TPM. 10033 NOTE 10034 10035 An implementation would modify this table according to the implemented algorithms, changing the values 10036 that are accepted as hash algorithms. 10037 10038 Table 57 Definition of (TPM_ALG_ID) TPMI_ALG_HASH Type 10039 Values 10040 10041 Comments 10042 10043 TPM_ALG_SHA1 10044 10045 example 10046 10047 TPM_ALG_SHA256 10048 10049 example 10050 10051 TPM_ALG_SM3_256 10052 10053 example 10054 10055 TPM_ALG_SHA384 10056 10057 example 10058 10059 TPM_ALG_SHA512 10060 10061 example 10062 10063 +TPM_ALG_NULL 10064 #TPM_RC_HASH 10065 10066 9.23 TPMI_ALG_ASYM (Asymmetric Algorithms) 10067 A TPMI_ALG_ASYM is an interface type of all the asymmetric algorithms implemented on a specific TPM. 10068 Table 58 lists each of the asymmetric algorithms that have an algorithm ID assigned by the TCG. 10069 Table 58 Definition of (TPM_ALG_ID) TPMI_ALG_ASYM Type 10070 Values 10071 10072 Comments 10073 10074 TPM_ALG_RSA 10075 TPM_ALG_ECC 10076 +TPM_ALG_NULL 10077 #TPM_RC_ASYMMETRIC 10078 10079 Family 2.0 10080 Level 00 Revision 00.99 10081 10082 Published 10083 Copyright TCG 2006-2013 10084 10085 Page 77 10086 October 31, 2013 10087 10088 Part 2: Structures 10090 10091 Trusted Platform Module Library 10092 10093 9.24 TPMI_ALG_SYM (Symmetric Algorithms) 10094 A TPMI_ALG_SYM is an interface type of all the symmetric algorithms that have an algorithm ID assigned 10095 by the TCG and are implemented on the TPM. 10096 The list in the table below is illustrative and will change according to the implementation. The validation 10097 code will only accept the subset of algorithms implemented on a TPM. 10098 NOTE 10099 10100 The validation code produced by an example script will produce a CASE statement with a case for each of 10101 the values in the Values column. The case for a value is delimited by a #ifdef/#endif pair so that if the 10102 algorithm is not implemented on the TPM, then the case for the algorithm is not generated, and use of the 10103 algorithm will cause a TPM error (TPM_RC_SYMMETRIC). 10104 10105 Table 59 Definition of (TPM_ALG_ID) TPMI_ALG_SYM Type 10106 Values 10107 10108 Comments 10109 10110 TPM_ALG_AES 10111 10112 example 10113 10114 TPM_ALG_SM4 10115 10116 example 10117 10118 TPM_ALG_XOR 10119 10120 example 10121 10122 +TPM_ALG_NULL 10123 10124 required to be present in all versions of this table 10125 10126 #TPM_RC_SYMMETRIC 10127 10128 9.25 TPMI_ALG_SYM_OBJECT 10129 A TPMI_ALG_SYM_OBJECT is an interface type of all the TCG-defined symmetric algorithms that may 10130 be used as companion symmetric encryption algorithm for an asymmetric object. All algorithms in this list 10131 shall be block ciphers usable in Cipher Feedback (CFB). 10132 Table 60 is illustrative. It would be modified to indicate the algorithms of the TPM. 10133 NOTE 10134 10135 TPM_ALG_XOR is not allowed in this list. 10136 10137 Table 60 Definition of (TPM_ALG_ID) TPMI_ALG_SYM_OBJECT Type 10138 Values 10139 10140 Comments 10141 10142 TPM_ALG_AES 10143 10144 example 10145 10146 TPM_ALG_SM4 10147 10148 example 10149 10150 +TPM_ALG_NULL 10151 10152 required to be present in all versions of this table 10153 10154 #TPM_RC_SYMMETRIC 10155 10156 Page 78 10157 October 31, 2013 10158 10159 Published 10160 Copyright TCG 2006-2013 10161 10162 Family 2.0 10163 Level 00 Revision 00.99 10164 10165 Trusted Platform Module Library 10167 10168 Part 2: Structures 10169 10170 9.26 TPMI_ALG_SYM_MODE 10171 A TPMI_ALG_SYM_MODE is an interface type of all the TCG-defined block-cipher modes of operation. 10172 This version of the table is not expected to be the table checked by the validation code. Rather, the table 10173 would be replaced by one containing the algorithms implemented on the TPM and that the values in that 10174 table would be checked by the input validation code. 10175 Table 61 Definition of (TPM_ALG_ID) TPMI_ALG_SYM_MODE Type 10176 Values 10177 10178 Comments 10179 10180 TPM_ALG_CTR 10181 10182 IV will be determined by use. 10183 If the outside provides the nonce and initial counter, then the caller can 10184 know what IV to provide for chaining. 10185 10186 TPM_ALG_OFB 10187 10188 XOR last cipher text block with last plaintext to create IV for next block 10189 10190 TPM_ALG_CBC 10191 10192 IV will be determined by use. 10193 indefinite chaining using previous output block as IV for next block 10194 10195 TPM_ALG_CFB 10196 10197 shall be implemented in all TPM compliant with this specification 10198 IV will be determined by use. 10199 indefinite chaining using previous cipher text as IV 10200 10201 TPM_ALG_ECB 10202 10203 no IV or chaining value required 10204 10205 +TPM_ALG_NULL 10206 #TPM_RC_MODE 10207 10208 9.27 TPMI_ALG_KDF (Key and Mask Generation Functions) 10209 A TPMI_ALG_KDF is an interface type of all the key derivation functions implemented on a specific TPM. 10210 Table 62 is exemplary and would change based on the algorithms implemented in a TPM. 10211 Table 62 Definition of (TPM_ALG_ID) TPMI_ALG_KDF Type 10212 Values 10213 10214 Comments 10215 10216 TPM_ALG_MGF1 10217 TPM_ALG_KDF1_SP800_108 10218 TPM_ALG_KDF1_SP800_56a 10219 TPM_ALG_KDF2 10220 +TPM_ALG_NULL 10221 #TPM_RC_KDF 10222 10223 Family 2.0 10224 Level 00 Revision 00.99 10225 10226 Published 10227 Copyright TCG 2006-2013 10228 10229 Page 79 10230 October 31, 2013 10231 10232 Part 2: Structures 10234 10235 Trusted Platform Module Library 10236 10237 9.28 TPMI_ALG_SIG_SCHEME 10238 This is the definition of the interface type for a signature scheme. This table would change according to 10239 the algorithms implemented on the TPM. 10240 Table 63 Definition of (TPM_ALG_ID) TPMI_ALG_SIG_SCHEME Type 10241 Values 10242 10243 Comments 10244 10245 TPM_ALG_RSASSA 10246 10247 requires that RSA be implemented 10248 10249 TPM_ALG_RSAPSS 10250 10251 requires that RSA be implemented 10252 10253 TPM_ALG_ECDSA 10254 10255 requires that ECC be implemented 10256 10257 TPM_ALG_ECDAA 10258 10259 requires that ECC and ECDAA be implemented 10260 10261 TPM_ALG_ECSCHNORR 10262 TPM_ALG_SM2 10263 10264 requires that ECC be implemented 10265 10266 TPM_ALG_HMAC 10267 10268 present on all TPM 10269 10270 +TPM_ALG_NULL 10271 #TPM_RC_SCHEME 10272 10273 response code when a signature scheme is not correct 10274 10275 9.29 TPMI_ECC_KEY_EXCHANGE 10276 This is the definition of the interface type for an ECC key exchange scheme. This table would change 10277 according to the algorithms implemented on the TPM. 10278 Table 64 Definition of (TPM_ALG_ID) TPMI_ECC_KEY_EXCHANGE Type 10279 Values 10280 10281 Comments 10282 10283 TPM_ALG_ECDH 10284 10285 used for single and two phase key exchange 10286 10287 TPM_ALG_ECMQV 10288 TPM_ALG_SM2 10289 10290 requires that ECC be implemented 10291 10292 +TPM_ALG_NULL 10293 #TPM_RC_SCHEME 10294 10295 response code when a key exchange scheme is not correct 10296 10297 9.30 TPMI_ST_COMMAND_TAG 10298 This interface type is used for the command tags. 10299 The response code for a bad command tag has the same value as the TPM 1.2 response code 10300 (TPM_BAD_TAG). This value is used in case the software is not compatible with this specification and an 10301 unexpected response code might have unexpected side effects. 10302 Table 65 Definition of (TPM_ST) TPMI_ST_COMMAND_TAG Type 10303 Values 10304 10305 Comments 10306 10307 TPM_ST_NO_SESSIONS 10308 TPM_ST_SESSIONS 10309 #TPM_RC_BAD_TAG 10310 10311 Page 80 10312 October 31, 2013 10313 10314 Published 10315 Copyright TCG 2006-2013 10316 10317 Family 2.0 10318 Level 00 Revision 00.99 10319 10320 Trusted Platform Module Library 10322 10323 Part 2: Structures 10324 10325 10 Structure Definitions 10326 10.1 TPMS_ALGORITHM_DESCRIPTION 10327 This structure is a return value for a TPM2_GetCapability() that reads the installed algorithms. 10328 Table 66 Definition of TPMS_ALGORITHM_DESCRIPTION Structure <OUT> 10329 Parameter 10330 10331 Type 10332 10333 Description 10334 10335 alg 10336 10337 TPM_ALG_ID 10338 10339 an algorithm 10340 10341 attributes 10342 10343 TPMA_ALGORITHM 10344 10345 the attributes of the algorithm 10346 10347 10.2 Hash/Digest Structures 10348 10.2.1 TPMU_HA (Hash) 10349 A TPMU_HA is a union of all the hash algorithms implemented on a TPM. Table 67 is exemplary and 10350 would change based on the algorithms implemented in a TPM. 10351 NOTE 10352 10353 If processed by an automated tool, each entry of the table should be qualified (with #ifdef/#endif) so that if 10354 the hash algorithm is not implemented on the TPM, the parameter associated with that hash is not 10355 present. This will keep the union from being larger than the largest digest of a hash implemented on that 10356 TPM. 10357 10358 Table 67 Definition of TPMU_HA Union <IN/OUT, S> 10359 Parameter 10360 10361 Type 10362 10363 Selector 10364 10365 sha1 [SHA1_DIGEST_SIZE] 10366 10367 BYTE 10368 10369 TPM_ALG_SHA1 10370 10371 sha256 [SHA256_DIGEST_SIZE] 10372 10373 BYTE 10374 10375 TPM_ALG_SHA256 10376 10377 sm3_256 [SM3_256_DIGEST_SIZE] 10378 10379 BYTE 10380 10381 TPM_ALG_SM3_256 10382 10383 sha384 [SHA384_DIGEST_SIZE] 10384 10385 BYTE 10386 10387 TPM_ALG_SHA384 10388 10389 sha512 [SHA512_DIGEST_SIZE] 10390 10391 BYTE 10392 10393 TPM_ALG_SHA512 10394 10395 null 10396 10397 Family 2.0 10398 Level 00 Revision 00.99 10399 10400 Description 10401 10402 TPM_ALG_NULL 10403 10404 Published 10405 Copyright TCG 2006-2013 10406 10407 Page 81 10408 October 31, 2013 10409 10410 Part 2: Structures 10412 10413 Trusted Platform Module Library 10414 10415 10.2.2 TPMT_HA 10416 Table 68 shows the basic hash-agile structure used in this specification. To handle hash agility, this 10417 structure uses the hashAlg parameter to indicate the algorithm used to compute the digest and, by 10418 implication, the size of the digest. 10419 When transmitted, only the number of octets indicated by hashAlg is sent. 10420 NOTE 10421 10422 In the exemplary code, when a TPMT_HA is allocated, the digest field is large enough to support the 10423 largest hash algorithm in the TPMU_HA union. 10424 10425 Table 68 Definition of TPMT_HA Structure <IN/OUT> 10426 Parameter 10427 10428 Type 10429 10430 Description 10431 10432 hashAlg 10433 10434 +TPMI_ALG_HASH 10435 10436 selector of the hash contained in the digest that implies the 10437 size of the digest 10438 NOTE 10439 10440 [hashAlg] digest 10441 10442 TPMU_HA 10443 10444 The leading + on the type indicates that this structure 10445 should pass an indication to the unmarshaling function for 10446 TPMI_ALG_HASH so that TPM_ALG_NULL will be 10447 allowed if a use of a TPMT_HA allows TPM_ALG_NULL. 10448 10449 the digest data 10450 10451 10.3 Sized Buffers 10452 10.3.1 Introduction 10453 The TPM2B_ prefix is used for a structure that has a size field followed by a data buffer with the 10454 indicated number of octets. The size field is 16 bits. 10455 When the type of the second parameter in a TPM2B_ structure is BYTE, the TPM shall unmarshal the 10456 indicated number of octets, which may be zero. 10457 When the type of the second parameter in the TPM2B_ structure is not BYTE, the value of the size field 10458 shall either be zero indicating that no structure is to be unmarshaled; or it shall be identical to the number 10459 of octets unmarshaled for the second parameter. 10460 NOTE 1 10461 10462 If the TPM2B_ defines a structure and not an array of octets, then the structure is self-describing and the 10463 TPM will be able to determine how many octets are in the structure when it is unmarshaled. If that number 10464 of octets is not equal to the size parameter, then it is an error. 10465 10466 NOTE 2 10467 10468 The reason that a structure may be put into a TPM2B_ is that the parts of the structure may be handled 10469 as separate opaque blocks by the application/system software. Rather than require that all of the 10470 structures in a command or response be marshaled or unmarshaled sequentially, the size field allows the 10471 structure to be manipulated as an opaque block. Placing a structure in a TPM2B_ also makes it possible 10472 to use parameter encryption on the structure. 10473 10474 If a TPM2B_ is encrypted, the TPM will encrypt/decrypt the data field of the TPM2B_ but not the size 10475 parameter. The TPM will encrypt/decrypt the number of octets indicated by the size field. 10476 NOTE 3 10477 10478 In the reference implementation, a TPM2B type is defined that is a 16-bit size field followed by a single 10479 byte of data. The TPM2B_ is then defined as a union that contains a TPM2B (union member b) and the 10480 structure in the definition table (union member t). This union is used for internally generated structures 10481 so that there is a way to define a structure of the correct size (forced by the t member) while giving a way 10482 to pass the structure generically as a b. Most function calls use the 't' member so that the compiler will 10483 generate a warning if there is a type error (a TPM2B_ of the wrong type). Having the type checked helps 10484 avoid many issues with buffer overflow caused by a too small buffer being passed to a function. 10485 10486 Page 82 10487 October 31, 2013 10488 10489 Published 10490 Copyright TCG 2006-2013 10491 10492 Family 2.0 10493 Level 00 Revision 00.99 10494 10495 Trusted Platform Module Library 10497 10498 Part 2: Structures 10499 10500 10.3.2 TPM2B_DIGEST 10501 This structure is used for a sized buffer that cannot be larger than the largest digest produced by any 10502 hash algorithm implemented on the TPM. 10503 As with all sized buffers, the size is checked to see if it is within the prescribed range. If not, the response 10504 code is TPM_RC_SIZE. 10505 NOTE 10506 10507 For any structure, like the one below, that contains an implied size check, it is implied that TPM_RC_SIZE 10508 is a possible response code and the response code will not be listed in the table. 10509 10510 Table 69 Definition of TPM2B_DIGEST Structure 10511 Parameter 10512 10513 Type 10514 10515 Description 10516 10517 size 10518 10519 UINT16 10520 10521 size in octets of the buffer field; may be 0 10522 10523 buffer[size]{:sizeof(TPMU_HA)} 10524 10525 BYTE 10526 10527 the buffer area that can be no larger than a digest 10528 10529 10.3.3 TPM2B_DATA 10530 This structure is used for a data buffer that is required to be no larger than the size of the Name of an 10531 object. This size limit includes the algorithm ID of the hash and the hash data. 10532 Table 70 Definition of TPM2B_DATA Structure 10533 Parameter 10534 10535 Type 10536 10537 Description 10538 10539 size 10540 10541 UINT16 10542 10543 size in octets of the buffer field; may be 0 10544 10545 buffer[size]{:sizeof(TPMT_HA)} 10546 10547 BYTE 10548 10549 the buffer area that contains the algorithm ID and the 10550 digest 10551 10552 10.3.4 TPM2B_NONCE 10553 Table 71 Definition of Types for TPM2B_NONCE 10554 Type 10555 10556 Name 10557 10558 Description 10559 10560 TPM2B_DIGEST 10561 10562 TPM2B_NONCE 10563 10564 size limited to the same as the digest structure 10565 10566 10.3.5 TPM2B_AUTH 10567 This structure is used for an authorization value and limits an authValue to being no larger than the 10568 largest digest produced by a TPM. In order to ensure consistency within an object, the authValue may be 10569 no larger than the size of the digest produced by the objects nameAlg. This ensures that any TPM that 10570 can load the object will be able to handle the authValue of the object. 10571 Table 72 Definition of Types for TPM2B_AUTH 10572 Type 10573 10574 Name 10575 10576 Description 10577 10578 TPM2B_DIGEST 10579 10580 TPM2B_AUTH 10581 10582 size limited to the same as the digest structure 10583 10584 Family 2.0 10585 Level 00 Revision 00.99 10586 10587 Published 10588 Copyright TCG 2006-2013 10589 10590 Page 83 10591 October 31, 2013 10592 10593 Part 2: Structures 10595 10596 Trusted Platform Module Library 10597 10598 10.3.6 TPM2B_OPERAND 10599 This type is a sized buffer that can hold an operand for a comparison with an NV Index location. The 10600 maximum size of the operand is implementation dependent but a TPM is required to support an operand 10601 size that is at least as big as the digest produced by any of the hash algorithms implemented on the TPM. 10602 Table 73 Definition of Types for TPM2B_OPERAND 10603 Type 10604 10605 Name 10606 10607 Description 10608 10609 TPM2B_DIGEST 10610 10611 TPM2B_OPERAND 10612 10613 size limited to the same as the digest structure 10614 10615 10.3.7 TPM2B_EVENT 10616 This type is a sized buffer that can hold event data. 10617 Table 74 Definition of TPM2B_EVENT Structure 10618 Parameter 10619 10620 Type 10621 10622 Description 10623 10624 size 10625 10626 UINT16 10627 10628 size of the operand buffer 10629 10630 buffer [size] {:1024} 10631 10632 BYTE 10633 10634 the operand 10635 10636 10.3.8 TPM2B_MAX_BUFFER 10637 This type is a sized buffer that can hold a maximally sized buffer for commands that use a large data 10638 buffer 10639 such 10640 as 10641 TPM2_PCR_Event(), 10642 TPM2_Hash(), 10643 TPM2_SequenceUpdate(), 10644 or 10645 TPM2_FieldUpgradeData(). 10646 NOTE 10647 10648 The above list is not comprehensive and other commands may use this buffer type. 10649 10650 Table 75 Definition of TPM2B_MAX_BUFFER Structure 10651 Parameter 10652 10653 Type 10654 10655 Description 10656 10657 size 10658 10659 UINT16 10660 10661 size of the buffer 10662 10663 buffer [size] {:MAX_DIGEST_BUFFER} 10664 10665 BYTE 10666 10667 the operand 10668 NOTE 10669 MAX_DIGEST_BUFFER 10670 is 10671 TPMdependent but is required to be at least 1,024. 10672 10673 10.3.9 TPM2B_MAX_NV_BUFFER 10674 This type is a sized buffer that can hold a maximally sized buffer for NV data commands such as 10675 TPM2_NV_Read(), TPM2_NV_Write(), and TPM2_NV_Certify(). 10676 Table 76 Definition of TPM2B_MAX_NV_BUFFER Structure 10677 Parameter 10678 10679 Type 10680 10681 Description 10682 10683 size 10684 10685 UINT16 10686 10687 size of the buffer 10688 10689 buffer [size] {:MAX_NV_BUFFER_SIZE} 10690 10691 BYTE 10692 10693 the operand 10694 NOTE 10695 MAX_NV_BUFFER_SIZE 10696 dependent 10697 10698 Page 84 10699 October 31, 2013 10700 10701 Published 10702 Copyright TCG 2006-2013 10703 10704 is 10705 10706 TPM- 10707 10708 Family 2.0 10709 Level 00 Revision 00.99 10710 10711 Trusted Platform Module Library 10713 10714 Part 2: Structures 10715 10716 10.3.10 TPM2B_TIMEOUT 10717 This TPM-dependent structure is used to provide the timeout value for an authorization. 10718 Table 77 Definition of TPM2B_TIMEOUT Structure <IN/OUT> 10719 Parameter 10720 10721 Type 10722 10723 Description 10724 10725 size 10726 10727 UINT16 10728 10729 size of the timeout value 10730 This value is fixed for a TPM implementation. 10731 10732 buffer [size] {:sizeof(UINT64)} 10733 10734 BYTE 10735 10736 the timeout value 10737 10738 10.3.11 TPM2B_IV 10739 This structure is used for passing an initial value for a symmetric block cipher to or from the TPM. The 10740 size is set to be the largest block size of any implemented symmetric cipher implemented on the TPM. 10741 Table 78 Definition of TPM2B_IV Structure <IN/OUT> 10742 Parameter 10743 10744 Type 10745 10746 Description 10747 10748 size 10749 10750 UINT16 10751 10752 size of the timeout value 10753 This value is fixed for a TPM implementation. 10754 10755 buffer [size] {:MAX_SYM_BLOCK_SIZE} 10756 10757 BYTE 10758 10759 the timeout value 10760 10761 10.4 Names 10762 10.4.1 Introduction 10763 The Name of an entity is used in place of the handle in authorization computations. The substitution 10764 occurs in cpHash and policyHash computations. 10765 For an entity that is defined by a public area (objects and NV Indexes), the Name is the hash of the public 10766 structure that defines the entity. The hash is done using the nameAlg of the entity. 10767 NOTE 10768 10769 For an object, a TPMT_PUBLIC defines the entity. For an NV Index, a TPMS_NV_PUBLIC defines the 10770 entity. 10771 10772 For entities not defined by a public area, the Name is the handle that is used to refer to the entity. 10773 10.4.2 TPMU_NAME 10774 Table 79 Definition of TPMU_NAME Union <> 10775 Parameter 10776 10777 Type 10778 10779 digest 10780 10781 TPMT_HA 10782 10783 when the Name is a digest 10784 10785 handle 10786 10787 TPM_HANDLE 10788 10789 when the Name is a handle 10790 10791 Family 2.0 10792 Level 00 Revision 00.99 10793 10794 Selector 10795 10796 Description 10797 10798 Published 10799 Copyright TCG 2006-2013 10800 10801 Page 85 10802 October 31, 2013 10803 10804 Part 2: Structures 10806 10807 Trusted Platform Module Library 10808 10809 10.4.3 TPM2B_NAME 10810 This buffer holds a Name for any entity type. 10811 The type of Name in the structure is determined by context and the size parameter. If size is four, then 10812 the Name is a handle. If size is zero, then no Name is present. Otherwise, the size shall be the size of a 10813 TPM_ALG_ID plus the size of the digest produced by the indicated hash algorithm. 10814 Table 80 Definition of TPM2B_NAME Structure 10815 Parameter 10816 10817 Type 10818 10819 Description 10820 10821 size 10822 10823 UINT16 10824 10825 size of the Name structure 10826 10827 name[size]{:sizeof(TPMU_NAME)} 10828 10829 BYTE 10830 10831 the Name structure 10832 10833 10.5 PCR Structures 10834 10.5.1 TPMS_PCR_SELECT 10835 This structure provides a standard method of specifying a list of PCR. 10836 PCR numbering starts at zero. 10837 PcrSelect is an array of octets. The octet containing the bit corresponding to a specific PCR is found by 10838 dividing the PCR number by 8. 10839 EXAMPLE 1 10840 10841 The bit in pcrSelect corresponding to PCR 19 is in pcrSelect [2] (19/8 = 2). 10842 10843 The least significant bit in a octet is bit number 0. The bit in the octet associated with a PCR is the 10844 remainder after division by 8. 10845 EXAMPLE 2 10846 10847 The bit in pcrSelect [2] corresponding to PCR 19 is bit 3 (19 mod 8). If sizeofSelect is 3, then the 10848 pcrSelect array that would specify PCR 19 and no other PCR is 00 00 08 16. 10849 10850 Each bit in pcrSelect indicates whether the corresponding PCR is selected (1) or not (0). If the pcrSelect 10851 is all zero bits, then no PCR is selected. 10852 SizeofSelect indicates the number of octets in pcrSelect. The allowable values for sizeofSelect is 10853 determined by the number of PCR required by the applicable platform-specific specification and the 10854 number of PCR implemented in the TPM. The minimum value for sizeofSelect is: 10855 PCR_SELECT_MIN (PLATFORM_PCR + 7) / 8 10856 10857 (1) 10858 10859 where 10860 PLATFORM_PCR 10861 10862 the number of PCR required by the platform-specific specification 10863 10864 The maximum value for sizeofSelect is: 10865 PCR_SELECT_MAX (IMPLEMENTATION_PCR + 7) / 8 10866 10867 (2) 10868 10869 where 10870 IMPLEMENTATION_PCR 10871 10872 Page 86 10873 October 31, 2013 10874 10875 the number of PCR implemented on the TPM 10876 10877 Published 10878 Copyright TCG 2006-2013 10879 10880 Family 2.0 10881 Level 00 Revision 00.99 10882 10883 Trusted Platform Module Library 10885 10886 Part 2: Structures 10887 10888 If the TPM implements more PCR than there are bits in pcrSelect, the additional PCR are not selected. 10889 EXAMPLE 3 10890 10891 If the applicable platform-specific specification requires that the TPM have a minimum of 24 PCR but the 10892 TPM implements 32, then a PCR select of 3 octets would imply that PCR 24-31 are not selected. 10893 10894 Table 81 Definition of TPMS_PCR_SELECT Structure 10895 Parameter 10896 10897 Type 10898 10899 Description 10900 10901 sizeofSelect {PCR_SELECT_MIN:} 10902 10903 UINT8 10904 10905 the size in octets of the pcrSelect array 10906 10907 pcrSelect [sizeofSelect] {:PCR_SELECT_MAX} 10908 10909 BYTE 10910 10911 the bit map of selected PCR 10912 10913 #TPM_RC_VALUE 10914 10915 10.5.2 TPMS_PCR_SELECTION 10916 Table 82 Definition of TPMS_PCR_SELECTION Structure 10917 Parameter 10918 10919 Type 10920 10921 Description 10922 10923 hash 10924 10925 TPMI_ALG_HASH 10926 10927 the hash algorithm associated with the 10928 selection 10929 10930 sizeofSelect {PCR_SELECT_MIN:} 10931 10932 UINT8 10933 10934 the size in octets of the pcrSelect array 10935 10936 pcrSelect [sizeofSelect] {:PCR_SELECT_MAX} 10937 10938 BYTE 10939 10940 the bit map of selected PCR 10941 10942 #TPM_RC_VALUE 10943 10944 10.6 Tickets 10945 10.6.1 Introduction 10946 Tickets are evidence that the TPM has previously processed some information. A ticket is an HMAC over 10947 the data using a secret key known only to the TPM. A ticket is a way to expand the state memory of the 10948 TPM. A ticket is only usable by the TPM that produced it. 10949 The formulations for tickets shown in this clause are to be used by a TPM that is compliant with this 10950 specification. 10951 The method of creating the ticket data is: 10952 10953 HMACcontexAlg(proof, (ticketType || param { || param {})) 10954 10955 (3) 10956 10957 where 10958 10959 HMACcontexAlg() 10960 10961 an HMAC using the hash used for context integrity 10962 10963 proof 10964 10965 a TPM secret value (depends on hierarchy) 10966 10967 ticketType 10968 10969 a value to differentiate the tickets 10970 10971 param 10972 10973 one or more values that were checked by the TPM 10974 10975 Family 2.0 10976 Level 00 Revision 00.99 10977 10978 Published 10979 Copyright TCG 2006-2013 10980 10981 Page 87 10982 October 31, 2013 10983 10984 Part 2: Structures 10986 10987 Trusted Platform Module Library 10988 10989 The proof value used for each hierarchy is shown in Table 83. 10990 Table 83 Values for proof Used in Tickets 10991 Hierarchy 10992 10993 proof 10994 10995 Description 10996 10997 None 10998 10999 Empty Buffer 11000 11001 Platform 11002 11003 phProof 11004 11005 a value that changes with each change of the PPS 11006 11007 Owner 11008 11009 shProof 11010 11011 a value that changes with each change of the SPS 11012 11013 Endorsement 11014 11015 ehProof 11016 11017 a value that changes with each change of either the EPS or SPS 11018 11019 The format for a ticket is shown in Table 84. This is a template for the tickets shown in the remainder of 11020 this clause. 11021 Table 84 General Format of a Ticket 11022 Parameter 11023 11024 Type 11025 11026 Description 11027 11028 tag 11029 11030 TPM_ST 11031 11032 structure tag indicating the type of the ticket 11033 11034 hierarchy 11035 11036 TPMI_RH_HIERARCHY+ 11037 11038 the hierarchy of the proof value 11039 11040 digest 11041 11042 TPM2B_DIGEST 11043 11044 the HMAC over the ticket-specific data 11045 11046 10.6.2 A NULL Ticket 11047 When a command requires a ticket and no ticket is available, the caller is required to provide a structure 11048 with a ticket tag that is correct for the context. The hierarchy shall be set to TPM_RH_NULL, and digest 11049 shall be the Empty Buffer (a buffer with a size field of zero). This construct is the NULL Ticket. When a 11050 response indicates that a ticket is returned, the TPM may return a NULL Ticket. 11051 NOTE 11052 11053 Because each use of a ticket requires that the structure tag for the ticket be appropriate for the use, t here 11054 is no single representation of a NULL Ticket that will work in all circumstances. Minimally, a NULL ticket 11055 will have a structure type that is appropriate for the context. 11056 11057 Page 88 11058 October 31, 2013 11059 11060 Published 11061 Copyright TCG 2006-2013 11062 11063 Family 2.0 11064 Level 00 Revision 00.99 11065 11066 Trusted Platform Module Library 11068 11069 Part 2: Structures 11070 11071 10.6.3 TPMT_TK_CREATION 11072 This ticket is produced by TPM2_Create() or TPM2_CreatePrimary(). It is used to bind the creation data 11073 to the object to which it applies. The ticket is computed by 11074 11075 HMACcontextAlg(proof, (TPM_ST_CREATION || name || HnameAlg(TPMS_CREATION_DATA))) 11076 11077 (4) 11078 11079 where 11080 11081 HMACcontextAlg() 11082 11083 an HMAC using the context integrity hash algorithm 11084 11085 proof 11086 11087 a TPM secret value associated with the hierarchy associated with name 11088 11089 TPM_ST_CREATION 11090 11091 a value used to ensure that the ticket is properly used 11092 11093 name 11094 11095 the Name of the object to which the creation data is to be associated 11096 11097 HnameAlg() 11098 11099 hash using the nameAlg of the created object 11100 11101 TPMS_CREATION_DATA the creation data structure associated with name 11102 Table 85 Definition of TPMT_TK_CREATION Structure 11103 Parameter 11104 11105 Type 11106 11107 Description 11108 11109 tag {TPM_ST_CREATION} 11110 11111 TPM_ST 11112 11113 ticket structure tag 11114 error returned when tag is not TPM_ST_CREATION 11115 11116 #TPM_RC_TAG 11117 hierarchy 11118 11119 TPMI_RH_HIERARCHY+ 11120 11121 the hierarchy containing name 11122 11123 digest 11124 11125 TPM2B_DIGEST 11126 11127 This shall be the HMAC produced using a proof value 11128 of hierarchy. 11129 11130 EXAMPLE 11131 11132 A NULL Creation Ticket is the tuple <TPM_ST_CREATION, TPM_RH_NULL, 0x0000>. 11133 11134 Family 2.0 11135 Level 00 Revision 00.99 11136 11137 Published 11138 Copyright TCG 2006-2013 11139 11140 Page 89 11141 October 31, 2013 11142 11143 Part 2: Structures 11145 11146 Trusted Platform Module Library 11147 11148 10.6.4 TPMT_TK_VERIFIED 11149 This ticket is produced by TPM2_VerifySignature(). This formulation is used for multiple ticket uses. The 11150 ticket provides evidence that the TPM has validated that a digest was signed by a key with the Name of 11151 keyName. The ticket is computed by 11152 11153 HMACcontextAlg(proof, (TPM_ST_VERIFIED || digest || keyName)) 11154 11155 (5) 11156 11157 where 11158 11159 HMACcontextAlg() 11160 11161 an HMAC using the context integrity hash 11162 11163 proof 11164 11165 a TPM secret value associated with the hierarchy associated with 11166 11167 TPM_ST_VERIFIED 11168 11169 a value used to ensure that the ticket is properly used 11170 11171 digest 11172 11173 the signed digest 11174 11175 keyName 11176 11177 Name of the key that signed digest 11178 11179 keyName 11180 11181 Table 86 Definition of TPMT_TK_VERIFIED Structure 11182 Parameter 11183 11184 Type 11185 11186 Description 11187 11188 tag {TPM_ST_VERIFIED} 11189 11190 TPM_ST 11191 11192 ticket structure tag 11193 error returned when tag is not TPM_ST_VERIFIED 11194 11195 #TPM_RC_TAG 11196 hierarchy 11197 11198 TPMI_RH_HIERARCHY+ 11199 11200 the hierarchy containing keyName 11201 11202 digest 11203 11204 TPM2B_DIGEST 11205 11206 This shall be the HMAC produced using a proof value 11207 of hierarchy. 11208 11209 EXAMPLE 11210 11211 A NULL Verified Ticket is the tuple <TPM_ST_VERIFIED, TPM_RH_NULL, 0x0000>. 11212 11213 Page 90 11214 October 31, 2013 11215 11216 Published 11217 Copyright TCG 2006-2013 11218 11219 Family 2.0 11220 Level 00 Revision 00.99 11221 11222 Trusted Platform Module Library 11224 11225 Part 2: Structures 11226 11227 10.6.5 TPMT_TK_AUTH 11228 This ticket is produced by TPM2_PolicySigned() and TPM2_PolicySecret() when the authorization has an 11229 expiration time. The ticket is computed by 11230 11231 HMACcontextAlg(proof, (TPM_ST_AUTH_xxx || timeout || cpHash || policyRef || keyName)) 11232 11233 (6) 11234 11235 where 11236 11237 HMACcontextAlg() 11238 11239 an HMAC using the context integrity hash 11240 11241 proof 11242 11243 a TPM secret value associated with the hierarchy of the key associated 11244 with keyName 11245 11246 TPM_ST_AUTH_xxx 11247 11248 either TPM_ST_AUTH_SIGNED or TPM_ST_AUTH_SECRET; used to 11249 ensure that the ticket is properly used 11250 11251 timeout 11252 11253 implementation-specific value indicating when the authorization expires 11254 11255 cpHash 11256 11257 optional hash of the authorized command 11258 11259 policyRef 11260 11261 optional reference to a policy value 11262 11263 keyName 11264 11265 Name of the key that signed the authorization 11266 Table 87 Definition of TPMT_TK_AUTH Structure 11267 11268 Parameter 11269 11270 Type 11271 11272 Description 11273 11274 tag {TPM_ST_AUTH_SIGNED, TPM_ST_AUTH_SECRET} TPM_ST 11275 11276 ticket structure tag 11277 11278 #TPM_RC_TAG 11279 11280 error returned when tag is 11281 not TPM_ST_AUTH 11282 11283 hierarchy 11284 11285 TPMI_RH_HIERARCHY+ 11286 11287 the hierarchy of the object 11288 used to produce the ticket 11289 11290 digest 11291 11292 TPM2B_DIGEST 11293 11294 This shall be the HMAC 11295 produced using a proof 11296 value of hierarchy. 11297 11298 EXAMPLE 11299 11300 A NULL Auth Ticket is the tuple <TPM_ST_AUTH_SIGNED, TPM_RH_NULL, 0x0000> or the tuple 11301 <TPM_ST_AUTH_SIGNED, TPM_RH_NULL, 0x0000> 11302 11303 Family 2.0 11304 Level 00 Revision 00.99 11305 11306 Published 11307 Copyright TCG 2006-2013 11308 11309 Page 91 11310 October 31, 2013 11311 11312 Part 2: Structures 11314 11315 Trusted Platform Module Library 11316 11317 10.6.6 TPMT_TK_HASHCHECK 11318 This ticket is produced by TPM2_SequenceComplete() when the message that was digested did not start 11319 with TPM_GENERATED_VALUE. The ticket is computed by 11320 11321 HMACcontexAlg(proof, (TPM_ST_HASHCHECK || digest)) 11322 11323 (7) 11324 11325 where 11326 11327 HMACcontexAlg () 11328 11329 an HMAC using the context integrity hash 11330 11331 proof 11332 11333 a TPM secret value associated with the hierarchy indicated by the 11334 command 11335 11336 TPM_ST_HASHCHECK 11337 11338 a value used to ensure that the ticket is properly used 11339 11340 digest 11341 11342 the digest of the data 11343 Table 88 Definition of TPMT_TK_HASHCHECK Structure 11344 11345 Parameter 11346 11347 Type 11348 11349 Description 11350 11351 tag {TPM_ST_HASHCHECK} 11352 11353 TPM_ST 11354 11355 ticket structure tag 11356 11357 #TPM_RC_TAG 11358 11359 error returned when is not TPM_ST_HASHCHECK 11360 11361 hierarchy 11362 11363 TPMI_RH_HIERARCHY+ 11364 11365 the hierarchy 11366 11367 digest 11368 11369 TPM2B_DIGEST 11370 11371 This shall be the HMAC produced using a proof value 11372 of hierarchy. 11373 11374 10.7 Property Structures 11375 10.7.1 TPMS_ALG_PROPERTY 11376 This structure is used to report the properties of an algorithm identifier. It is returned in response to a 11377 TPM2_GetCapability() with capability = TPM_CAP_ALG. 11378 Table 89 Definition of TPMS_ALG_PROPERTY Structure <OUT> 11379 Parameter 11380 11381 Type 11382 11383 Description 11384 11385 alg 11386 11387 TPM_ALG_ID 11388 11389 an algorithm identifier 11390 11391 algProperties 11392 11393 TPMA_ALGORITHM 11394 11395 the attributes of the algorithm 11396 11397 10.7.2 TPMS_TAGGED_PROPERTY 11398 This structure is used to report the properties that are UINT32 values. It is returned in response to a 11399 TPM2_GetCapability(). 11400 Table 90 Definition of TPMS_TAGGED_PROPERTY Structure <OUT> 11401 Parameter 11402 11403 Type 11404 11405 Description 11406 11407 property 11408 11409 TPM_PT 11410 11411 a property identifier 11412 11413 value 11414 11415 UINT32 11416 11417 the value of the property 11418 11419 Page 92 11420 October 31, 2013 11421 11422 Published 11423 Copyright TCG 2006-2013 11424 11425 Family 2.0 11426 Level 00 Revision 00.99 11427 11428 Trusted Platform Module Library 11430 11431 Part 2: Structures 11432 11433 10.7.3 TPMS_TAGGED_PCR_SELECT 11434 This structure is used in TPM2_GetCapability() to return the attributes of the PCR. 11435 Table 91 Definition of TPMS_TAGGED_PCR_SELECT Structure <OUT> 11436 Parameter 11437 11438 Type 11439 11440 Description 11441 11442 tag 11443 11444 TPM_PT 11445 11446 the property identifier 11447 11448 sizeofSelect {PCR_SELECT_MIN:} 11449 11450 UINT8 11451 11452 the size in octets of the pcrSelect array 11453 11454 pcrSelect [sizeofSelect] {:PCR_SELECT_MAX} 11455 11456 BYTE 11457 11458 the bit map of PCR with the identified property 11459 11460 10.8 Lists 11461 10.8.1 TPML_CC 11462 A list of command codes may be input to the TPM or returned by the TPM depending on the command. 11463 Table 92 Definition of TPML_CC Structure 11464 Parameter 11465 11466 Type 11467 11468 Description 11469 11470 count 11471 11472 UINT32 11473 11474 number of commands in the commandCode list; 11475 may be 0 11476 11477 commandCodes[count]{:MAX_CAP_CC} 11478 11479 TPM_CC 11480 11481 a list of command codes 11482 The maximum only applies to a command code 11483 list in a command. The response size is limited 11484 only by the size of the parameter buffer. 11485 11486 #TPM_RC_SIZE 11487 11488 Family 2.0 11489 Level 00 Revision 00.99 11490 11491 response code when count is greater than the 11492 maximum allowed list size 11493 11494 Published 11495 Copyright TCG 2006-2013 11496 11497 Page 93 11498 October 31, 2013 11499 11500 Part 2: Structures 11502 11503 Trusted Platform Module Library 11504 11505 10.8.2 TPML_CCA 11506 This list is only used in TPM2_GetCapability(capability = TPM_CAP_COMMANDS). 11507 The values in the list are returned in commandIndex order with vendor-specific commands returned after 11508 other commands. Because of the other attributes, the commands may not be returned in strict numerical 11509 order. They will be in commandIndex order. 11510 Table 93 Definition of TPML_CCA Structure <OUT> 11511 Parameter 11512 11513 Type 11514 11515 Description 11516 11517 count 11518 11519 UINT32 11520 11521 number of values in the commandAttributes list; 11522 may be 0 11523 11524 commandAttributes[count]{:MAX_CAP_CC} 11525 11526 TPMA_CC 11527 11528 a list of command codes attributes 11529 11530 10.8.3 TPML_ALG 11531 This list is returned by TPM2_IncrementalSelfTest(). 11532 Table 94 Definition of TPML_ALG Structure 11533 Parameter 11534 11535 Type 11536 11537 Description 11538 11539 count 11540 11541 UINT32 11542 11543 number of algorithms in the algorithms list; may be 0 11544 11545 algorithms[count]{:MAX_ALG_LIST_SIZE} 11546 11547 TPM_ALG_ID 11548 11549 a list of algorithm IDs 11550 The maximum only applies to an algorithm list in a 11551 command. The response size is limited only by the 11552 size of the parameter buffer. 11553 response code when count is greater than the 11554 maximum allowed list size 11555 11556 #TPM_RC_SIZE 11557 11558 10.8.4 TPML_HANDLE 11559 This structure is used when the TPM returns a list of loaded handles when the capability in 11560 TPM2_GetCapability() is TPM_CAP_HANDLE. 11561 NOTE 11562 11563 This list is not used as input to the TPM. 11564 11565 Table 95 Definition of TPML_HANDLE Structure <OUT> 11566 Name 11567 11568 Type 11569 11570 Description 11571 11572 count 11573 11574 UINT32 11575 11576 the number of handles in the list 11577 may have a value of 0 11578 11579 handle[count]{: MAX_CAP_HANDLES} 11580 11581 TPM_HANDLE 11582 11583 an array of handles 11584 11585 #TPM_RC_SIZE 11586 11587 Page 94 11588 October 31, 2013 11589 11590 response code when count is greater than the 11591 maximum allowed list size 11592 11593 Published 11594 Copyright TCG 2006-2013 11595 11596 Family 2.0 11597 Level 00 Revision 00.99 11598 11599 Trusted Platform Module Library 11601 11602 Part 2: Structures 11603 11604 10.8.5 TPML_DIGEST 11605 This list is used to convey a list of digest values. This type is used in TPM2_PolicyOR() and in 11606 TPM2_PCR_Read(). 11607 Table 96 Definition of TPML_DIGEST Structure 11608 Parameter 11609 11610 Type 11611 11612 Description 11613 11614 count {2:} 11615 11616 UINT32 11617 11618 number of digests in the list, minimum is two for 11619 TPM2_PolicyOR(). 11620 11621 digests[count]{:8} 11622 11623 TPM2B_DIGEST 11624 11625 a list of digests 11626 For TPM2_PolicyOR(), all digests will have been 11627 computed using the digest of the policy session. For 11628 TPM2_PCR_Read(), each digest will be the size of the 11629 digest for the bank containing the PCR. 11630 11631 #TPM_RC_SIZE 11632 11633 response code when count is not at least two or is 11634 greater than eight 11635 11636 10.8.6 TPML_DIGEST_VALUES 11637 This list is used to convey a list of digest values. This type is returned by TPM2_Event() and 11638 TPM2_SequenceComplete() and is an input for TPM2_PCR_Extend(). 11639 NOTE 1 11640 11641 This construct limits the number of hashes in the list to the number of digests implemented in the TPM 11642 rather than the number of PCR banks. This allows extra values to appear in a call t o 11643 TPM2_PCR_Extend(). 11644 11645 NOTE 2 11646 11647 The digest for an unimplemented hash algorithm may not be in a list because the TPM may not recognize 11648 the algorithm as being a hash and it may not know the digest size. 11649 11650 Table 97 Definition of TPML_DIGEST_VALUES Structure 11651 Parameter 11652 11653 Type 11654 11655 Description 11656 11657 count 11658 11659 UINT32 11660 11661 number of digests in the list 11662 11663 digests[count]{:HASH_COUNT} 11664 11665 TPMT_HA 11666 11667 a list of tagged digests 11668 response code when count is greater than the possible 11669 number of banks 11670 11671 #TPM_RC_SIZE 11672 11673 10.8.7 TPM2B_DIGEST_VALUES 11674 Digest list in a sized buffer. This list is returned by TPM2_PCR_SequenceComplete(). 11675 Table 98 Definition of TPM2B_DIGEST_VALUES Structure 11676 Parameter 11677 11678 Type 11679 11680 Description 11681 11682 size 11683 11684 UINT16 11685 11686 size of the operand buffer 11687 11688 buffer [size] {:sizeof(TPML_DIGEST_VALUES)} 11689 11690 BYTE 11691 11692 the operand 11693 11694 Family 2.0 11695 Level 00 Revision 00.99 11696 11697 Published 11698 Copyright TCG 2006-2013 11699 11700 Page 95 11701 October 31, 2013 11702 11703 Part 2: Structures 11705 11706 Trusted Platform Module Library 11707 11708 10.8.8 TPML_PCR_SELECTION 11709 This list is used to indicate the PCR that are included in a selection when more than one PCR value may 11710 be selected. 11711 This structure is an input parameter to TPM2_PolicyPCR() to indicate the PCR that will be included in the 11712 digest of PCR for the authorization. The structure is used in TPM2_PCR_Read() command to indicate the 11713 PCR values to be returned and in the response to indicate which PCR are included in the list of returned 11714 digests. The structure is an output parameter from TPM2_Create() and indicates the PCR used in the 11715 digest of the PCR state when the object was created. The structure is also contained in the attestation 11716 structure of TPM2_Quote(). 11717 When this structure is used to select PCR to be included in a digest, the selected PCR are concatenated 11718 to create a message containing all of the PCR, and then the message is hashed using the contextspecific hash algorithm. 11719 Table 99 Definition of TPML_PCR_SELECTION Structure 11720 Parameter 11721 11722 Type 11723 11724 Description 11725 11726 count 11727 11728 UINT32 11729 11730 number of selection structures 11731 A value of zero is allowed. 11732 11733 pcrSelections[count]{:HASH_COUNT} 11734 11735 TPMS_PCR_SELECTION 11736 11737 list of selections 11738 response code when count is greater 11739 than the possible number of banks 11740 11741 #TPM_RC_SIZE 11742 11743 10.8.9 TPML_ALG_PROPERTY 11744 This list is used to report on a list of algorithm attributes. It is returned in a TPM2_GetCapability(). 11745 Table 100 Definition of TPML_ALG_PROPERTY Structure <OUT> 11746 Parameter 11747 11748 Type 11749 11750 Description 11751 11752 count 11753 11754 UINT32 11755 11756 number of algorithm properties structures 11757 A value of zero is allowed. 11758 11759 algProperties[count]{:MAX_CAP_ALGS} 11760 11761 TPMS_ALG_PROPERTY 11762 11763 list of properties 11764 11765 10.8.10 TPML_TAGGED_TPM_PROPERTY 11766 This list is used to report on a list of properties that are TPMS_TAGGED_PROPERTY values. It is 11767 returned by a TPM2_GetCapability(). 11768 Table 101 Definition of TPML_TAGGED_TPM_PROPERTY Structure <OUT> 11769 Parameter 11770 11771 Type 11772 11773 Description 11774 11775 count 11776 11777 UINT32 11778 11779 number of properties 11780 A value of zero is allowed. 11781 11782 tpmProperty[count]{:MAX_TPM_PROPERTIES} 11783 11784 TPMS_TAGGED_PROPERTY 11785 11786 Page 96 11787 October 31, 2013 11788 11789 Published 11790 Copyright TCG 2006-2013 11791 11792 an array of tagged properties 11793 11794 Family 2.0 11795 Level 00 Revision 00.99 11796 11797 Trusted Platform Module Library 11799 11800 Part 2: Structures 11801 11802 10.8.11 TPML_TAGGED_PCR_PROPERTY 11803 This list is used to report on a list of properties that are TPMS_PCR_SELECT values. It is returned by a 11804 TPM2_GetCapability(). 11805 Table 102 Definition of TPML_TAGGED_PCR_PROPERTY Structure <OUT> 11806 Parameter 11807 11808 Type 11809 11810 Description 11811 11812 count 11813 11814 UINT32 11815 11816 number of properties 11817 A value of zero is allowed. 11818 11819 pcrProperty[count]{:MAX_PCR_PROPERTIES} 11820 11821 TPMS_TAGGED_PCR_SELECT 11822 11823 a tagged PCR selection 11824 11825 10.8.12 TPML_ECC_CURVE 11826 This list is used to report the ECC curve ID values supported by the TPM. It is returned by a 11827 TPM2_GetCapability(). 11828 Table 103 Definition of {ECC} TPML_ECC_CURVE Structure <OUT> 11829 Parameter 11830 11831 Type 11832 11833 Description 11834 11835 count 11836 11837 UINT32 11838 11839 number of curves 11840 A value of zero is allowed. 11841 11842 eccCurves[count]{:MAX_ECC_CURVES} 11843 11844 TPM_ECC_CURVE 11845 11846 array of ECC curve identifiers 11847 11848 10.9 Capabilities Structures 11849 10.9.1 TPMU_CAPABILITIES 11850 Table 104 Definition of TPMU_CAPABILITIES Union <OUT> 11851 Parameter 11852 11853 Type 11854 11855 Selector 11856 11857 algorithms 11858 11859 TPML_ALG_PROPERTY 11860 11861 TPM_CAP_ALGS 11862 11863 handles 11864 11865 TPML_HANDLE 11866 11867 TPM_CAP_HANDLES 11868 11869 command 11870 11871 TPML_CCA 11872 11873 TPM_CAP_COMMANDS 11874 11875 ppCommands 11876 11877 TPML_CC 11878 11879 TPM_CAP_PP_COMMANDS 11880 11881 auditCommands 11882 11883 TPML_CC 11884 11885 TPM_CAP_AUDIT_COMMANDS 11886 11887 assignedPCR 11888 11889 TPML_PCR_SELECTION 11890 11891 TPM_CAP_PCRS 11892 11893 tpmProperties 11894 11895 TPML_TAGGED_TPM_PROPERTY 11896 11897 TPM_CAP_TPM_PROPERTIES 11898 11899 pcrProperties 11900 11901 TPML_TAGGED_PCR_PROPERTY 11902 11903 TPM_CAP_PCR_PROPERTIES 11904 11905 eccCurves 11906 11907 TPML_ECC_CURVE 11908 11909 TPM_CAP_ECC_CURVES 11910 11911 Family 2.0 11912 Level 00 Revision 00.99 11913 11914 Published 11915 Copyright TCG 2006-2013 11916 11917 Description 11918 11919 TPM_ALG_ECC 11920 11921 Page 97 11922 October 31, 2013 11923 11924 Part 2: Structures 11926 11927 Trusted Platform Module Library 11928 11929 10.9.2 TPMS_CAPABILITY_DATA 11930 This data area is returned in response to a TPM2_GetCapability(). 11931 Table 105 Definition of TPMS_CAPABILITY_DATA Structure <OUT> 11932 Parameter 11933 11934 Type 11935 11936 Description 11937 11938 capability 11939 11940 TPM_CAP 11941 11942 the capability 11943 11944 [capability]data 11945 11946 TPMU_CAPABILITIES 11947 11948 the capability data 11949 11950 10.10 Clock/Counter Structures 11951 10.10.1 TPMS_CLOCK_INFO 11952 This structure is used in each of the attestation commands. 11953 Table 106 Definition of TPMS_CLOCK_INFO Structure 11954 Parameter 11955 11956 Type 11957 11958 Description 11959 11960 clock 11961 11962 UINT64 11963 11964 time in milliseconds during which the TPM has been powered 11965 This structure element is used to report on the TPM's Clock value. 11966 The value of Clock shall be recorded in non-volatile memory no 11967 22 11968 less often than once per 2 milliseconds (~69.9 minutes) of TPM 11969 operation. The reference for the millisecond timer is the TPM 11970 oscillator. 11971 This value is reset to zero when the Storage Primary Seed is 11972 changed (TPM2_Clear()). 11973 This value may be advanced by TPM2_AdvanceClock(). 11974 11975 resetCount 11976 11977 UINT32 11978 11979 number of occurrences of TPM Reset since the last TPM2_Clear() 11980 11981 restartCount 11982 11983 UINT32 11984 11985 number of times that TPM2_Shutdown() or _TPM_Hash_Start have 11986 occurred since the last TPM Reset or TPM2_Clear(). 11987 11988 safe 11989 11990 TPMI_YES_NO 11991 11992 no value of Clock greater than the current value of Clock has been 11993 previously reported by the TPM. Set to YES on TPM2_Clear(). 11994 11995 10.10.2 Clock 11996 Clock is a monotonically increasing counter that advances whenever power is applied to the TPM. The 11997 value of Clock may be set forward with TPM2_ClockSet() if ownerAuth or platformAuth is provided. The 11998 value of Clock is incremented each millisecond. 11999 TPM2_Clear() will set Clock to zero. 12000 Clock will be non-volatile but may have a volatile component that is updated every millisecond with the 12001 non-volatile component updated at a lower rate. If the implementation uses a volatile component, the non22 12002 volatile component shall be updated no less frequently than every 2 milliseconds (~69.9 minutes). The 12003 update rate of the non-volatile portion of Clock shall be reported by a TPM2_GetCapability() with 12004 capability = TPM_CAP_TPM_PROPERTIES and property = TPM_PT_CLOCK_UPDATE. 12005 10.10.3 ResetCount 12006 This counter shall increment on each TPM Reset. This counter shall be reset to zero by TPM2_Clear(). 12007 12008 Page 98 12009 October 31, 2013 12010 12011 Published 12012 Copyright TCG 2006-2013 12013 12014 Family 2.0 12015 Level 00 Revision 00.99 12016 12017 Trusted Platform Module Library 12019 12020 Part 2: Structures 12021 12022 10.10.4 RestartCount 12023 This counter shall increment by one for each TPM Restart or TPM Resume. The restartCount shall be 12024 reset to zero on a TPM Reset or TPM2_Clear(). 12025 10.10.5 Safe 12026 This parameter is set to YES when the value reported in Clock is guaranteed to be unique for the current 12027 Owner. It is set to NO when the value of Clock may have been reported in a previous attestation or 12028 access. 12029 This parameter will be YES if a TPM2_Startup() was preceded by TPM2_Shutdown() with no intervening 12030 commands. It will also be YES after an update of the non-volatile bits of Clock have been updated at the 12031 end of an update interval. 12032 If a TPM implementation does not implement 12033 TPMS_CLOCK_INFO.clock shall always be zero. 12034 12035 Clock, 12036 12037 Safe 12038 12039 shall 12040 12041 always 12042 12043 be 12044 12045 NO 12046 12047 and 12048 12049 This parameter will be set to YES by TPM2_Clear(). 12050 10.10.6 TPMS_TIME_INFO 12051 This structure is used in the TPM2_TICK attestation. 12052 The Time value reported in this structure is reset whenever the TPM is reset. An implementation may 12053 reset the value of Time any time after _TPM_Init and before the TPM returns after TPM2_Start(). The 12054 value of Time shall increment continuously while power is applied to the TPM. 12055 Table 107 Definition of TPMS_TIME_INFO Structure 12056 Parameter 12057 12058 Type 12059 12060 Description 12061 12062 time 12063 12064 UINT64 12065 12066 time in milliseconds since the last _TPM_Init() or TPM2_Startup() 12067 This structure element is used to report on the TPM's Time value. 12068 12069 clockInfo 12070 12071 TPMS_CLOCK_INFO 12072 12073 a structure containing the clock information 12074 12075 Family 2.0 12076 Level 00 Revision 00.99 12077 12078 Published 12079 Copyright TCG 2006-2013 12080 12081 Page 99 12082 October 31, 2013 12083 12084 Part 2: Structures 12086 12087 Trusted Platform Module Library 12088 12089 10.11 TPM Attestation Structures 12090 10.11.1 Introduction 12091 This clause describes the structures that are used when a TPM creates a structure to be signed. The 12092 signing structures follow a standard format TPM2B_ATTEST with case-specific information embedded. 12093 10.11.2 TPMS_TIME_ATTEST_INFO 12094 This structure is used when the TPM performs TPM2_GetClock. 12095 Table 108 Definition of TPMS_TIME_ATTEST_INFO Structure <OUT> 12096 Parameter 12097 12098 Type 12099 12100 Description 12101 12102 time 12103 12104 TPMS_TIME_INFO 12105 12106 the Time, clock, resetCount, restartCount, and Safe indicator 12107 12108 firmwareVersion 12109 12110 UINT64 12111 12112 a vendor-specific value indicating the version number of the 12113 firmware 12114 12115 10.11.3 TPMS_CERTIFY_INFO 12116 This is the attested data for TPM2_Certify(). 12117 Table 109 Definition of TPMS_CERTIFY_INFO Structure <OUT> 12118 Parameter 12119 12120 Type 12121 12122 Description 12123 12124 name 12125 12126 TPM2B_NAME 12127 12128 Name of the certified object 12129 12130 qualifiedName 12131 12132 TPM2B_NAME 12133 12134 Qualified Name of the certified object 12135 12136 10.11.1 TPMS_QUOTE_INFO 12137 This is the attested data for TPM2_Quote(). 12138 Table 110 Definition of TPMS_QUOTE_INFO Structure <OUT> 12139 Parameter 12140 12141 Type 12142 12143 Description 12144 12145 pcrSelect 12146 12147 TPML_PCR_SELECTION 12148 12149 information on algID, PCR selected and digest 12150 12151 pcrDigest 12152 12153 TPM2B_DIGEST 12154 12155 digest of the selected PCR using the hash of the signing key 12156 12157 Page 100 12158 October 31, 2013 12159 12160 Published 12161 Copyright TCG 2006-2013 12162 12163 Family 2.0 12164 Level 00 Revision 00.99 12165 12166 Trusted Platform Module Library 12168 12169 Part 2: Structures 12170 12171 10.11.2 TPMS_COMMAND_AUDIT_INFO 12172 This is the attested data for TPM2_GetCommandAuditDigest(). 12173 Table 111 Definition of TPMS_COMMAND_AUDIT_INFO Structure <OUT> 12174 Parameter 12175 12176 Type 12177 12178 Description 12179 12180 auditCounter 12181 12182 UINT64 12183 12184 the monotonic audit counter 12185 12186 digestAlg 12187 12188 TPM_ALG_ID 12189 12190 hash algorithm used for the command audit 12191 12192 auditDigest 12193 12194 TPM2B_DIGEST 12195 12196 the current value of the audit digest 12197 12198 commandDigest 12199 12200 TPM2B_DIGEST 12201 12202 digest of the command codes being audited using digestAlg 12203 12204 10.11.3 TPMS_SESSION_AUDIT_INFO 12205 This is the attested data for TPM2_GetSessionAuditDigest(). 12206 Table 112 Definition of TPMS_SESSION_AUDIT_INFO Structure <OUT> 12207 Parameter 12208 12209 Type 12210 12211 Description 12212 12213 exclusiveSession 12214 12215 TPMI_YES_NO 12216 12217 current exclusive status of the session 12218 TRUE if all of the commands recorded in the sessionDigest were 12219 executed without any intervening TPM command that did not use 12220 this transport session 12221 12222 sessionDigest 12223 12224 TPM2B_DIGEST 12225 12226 the current value of the session audit digest 12227 12228 10.11.4 TPMS_CREATION_INFO 12229 This is the attested data for TPM2_CertifyCreation(). 12230 Table 113 Definition of TPMS_CREATION_INFO Structure <OUT> 12231 Parameter 12232 12233 Type 12234 12235 Description 12236 12237 objectName 12238 12239 TPM2B_NAME 12240 12241 Name of the object 12242 12243 creationHash 12244 12245 TPM2B_DIGEST 12246 12247 creationHash 12248 12249 10.11.5 TPMS_NV_CERTIFY_INFO 12250 This structure contains the Name and contents of the selected NV Index that is certified by 12251 TPM2_NV_Certify(). 12252 Table 114 Definition of TPMS_NV_CERTIFY_INFO Structure <OUT> 12253 Parameter 12254 12255 Type 12256 12257 Description 12258 12259 indexName 12260 12261 TPM2B_NAME 12262 12263 Name of the NV Index 12264 12265 offset 12266 12267 UINT16 12268 12269 the offset parameter of TPM2_NV_Certify() 12270 12271 nvContents 12272 12273 TPM2B_MAX_NV_BUFFER 12274 12275 contents of the NV Index 12276 12277 Family 2.0 12278 Level 00 Revision 00.99 12279 12280 Published 12281 Copyright TCG 2006-2013 12282 12283 Page 101 12284 October 31, 2013 12285 12286 Part 2: Structures 12288 12289 Trusted Platform Module Library 12290 12291 10.11.6 TPMI_ST_ATTEST 12292 Table 115 Definition of (TPM_ST) TPMI_ST_ATTEST Type <OUT> 12293 Value 12294 12295 Description 12296 12297 TPM_ST_ATTEST_CERTIFY 12298 12299 generated by TPM2_Certify() 12300 12301 TPM_ST_ATTEST_QUOTE 12302 12303 generated by TPM2_Quote() 12304 12305 TPM_ST_ATTEST_SESSION_AUDIT 12306 12307 generated by TPM2_GetSessionAuditDigest() 12308 12309 TPM_ST_ATTEST_COMMAND_AUDIT 12310 12311 generated by TPM2_GetCommandAuditDigest() 12312 12313 TPM_ST_ATTEST_TIME 12314 12315 generated by TPM2_GetTime() 12316 12317 TPM_ST_ATTEST_CREATION 12318 12319 generated by TPM2_CertifyCreation() 12320 12321 TPM_ST_ATTEST_NV 12322 12323 generated by TPM2_NV_Certify() 12324 12325 10.11.7 TPMU_ATTEST 12326 Table 116 Definition of TPMU_ATTEST Union <OUT> 12327 Parameter 12328 12329 Type 12330 12331 Selector 12332 12333 certify 12334 12335 TPMS_CERTIFY_INFO 12336 12337 TPM_ST_ATTEST_CERTIFY 12338 12339 creation 12340 12341 TPMS_CREATION_INFO 12342 12343 TPM_ST_ATTEST_CREATION 12344 12345 quote 12346 12347 TPMS_QUOTE_INFO 12348 12349 TPM_ST_ATTEST_QUOTE 12350 12351 commandAudit 12352 12353 TPMS_COMMAND_AUDIT_INFO 12354 12355 TPM_ST_ATTEST_COMMAND_AUDIT 12356 12357 sessionAudit 12358 12359 TPMS_SESSION_AUDIT_INFO 12360 12361 TPM_ST_ATTEST_SESSION_AUDIT 12362 12363 time 12364 12365 TPMS_TIME_ATTEST_INFO 12366 12367 TPM_ST_ATTEST_TIME 12368 12369 nv 12370 12371 TPMS_NV_CERTIFY_INFO 12372 12373 TPM_ST_ATTEST_NV 12374 12375 Page 102 12376 October 31, 2013 12377 12378 Published 12379 Copyright TCG 2006-2013 12380 12381 Family 2.0 12382 Level 00 Revision 00.99 12383 12384 Trusted Platform Module Library 12386 12387 Part 2: Structures 12388 12389 10.11.8 TPMS_ATTEST 12390 This structure is used on each TPM-generated signed structure. The signature is over this structure. 12391 When the structure is signed by a key in the Storage hierarchy, the values of clockInfo.resetCount, 12392 clockInfo.restartCount, and firmwareVersion are obfuscated with a per-key obfuscation value. 12393 Table 117 Definition of TPMS_ATTEST Structure <OUT> 12394 Parameter 12395 12396 Type 12397 12398 Description 12399 12400 magic 12401 12402 TPM_GENERATED 12403 12404 the indication that this structure was created by a TPM (always 12405 TPM_GENERATED_VALUE) 12406 12407 type 12408 12409 TPMI_ST_ATTEST 12410 12411 type of the attestation structure 12412 12413 qualifiedSigner 12414 12415 TPM2B_NAME 12416 12417 Qualified Name of the signing key 12418 12419 extraData 12420 12421 TPM2B_DATA 12422 12423 external information supplied by caller 12424 NOTE 12425 12426 A TPM2B_DATA structure provides room for a digest and a 12427 method indicator to indicate the components of the digest. 12428 The definition of this method indicator is outside the scope 12429 of this specification. 12430 12431 clockInfo 12432 12433 TPMS_CLOCK_INFO 12434 12435 Clock, resetCount, restartCount, and Safe 12436 12437 firmwareVersion 12438 12439 UINT64 12440 12441 TPM-vendor-specific field identifying the firmware on the TPM 12442 12443 [type]attested 12444 12445 TPMU_ATTEST 12446 12447 the type-specific attestation information 12448 12449 10.11.9 TPM2B_ATTEST 12450 This sized buffer to contain the signed structure. The attestationData is the signed portion of the structure. 12451 The size parameter is not signed. 12452 Table 118 Definition of TPM2B_ATTEST Structure <OUT> 12453 Parameter 12454 12455 Type 12456 12457 Description 12458 12459 size 12460 12461 UINT16 12462 12463 size of the attestationData structure 12464 12465 attestationData[size]{:sizeof(TPMS_ATTEST)} 12466 12467 BYTE 12468 12469 the signed structure 12470 12471 Family 2.0 12472 Level 00 Revision 00.99 12473 12474 Published 12475 Copyright TCG 2006-2013 12476 12477 Page 103 12478 October 31, 2013 12479 12480 Part 2: Structures 12482 12483 Trusted Platform Module Library 12484 12485 10.12 Authorization Structures 12486 The structures in this clause are used for all authorizations. One or more of these structures will be 12487 present in a command or response that has a tag of TPM_ST_SESSIONS. 12488 10.12.1 TPMS_AUTH_COMMAND 12489 This is the format used for each of the authorizations in the session area of a command. 12490 Table 119 Definition of TPMS_AUTH_COMMAND Structure <IN> 12491 Parameter 12492 12493 Type 12494 12495 Description 12496 12497 sessionHandle 12498 12499 TPMI_SH_AUTH_SESSION+ 12500 12501 the session handle 12502 12503 nonce 12504 12505 TPM2B_NONCE 12506 12507 the session nonce, may be the Empty Buffer 12508 12509 sessionAttributes 12510 12511 TPMA_SESSION 12512 12513 the session attributes 12514 12515 hmac 12516 12517 TPM2B_AUTH 12518 12519 either an HMAC, a password, or an EmptyAuth 12520 12521 10.12.2 TPMS_AUTH_RESPONSE 12522 This is the format for each of the authorizations in the session area of the response. If the TPM returns 12523 TPM_RC_SUCCESS, then the session area of the response contains the same number of authorizations 12524 as the command and the authorizations are in the same order. 12525 Table 120 Definition of TPMS_AUTH_RESPONSE Structure <OUT> 12526 Parameter 12527 12528 Type 12529 12530 Description 12531 12532 nonce 12533 12534 TPM2B_NONCE 12535 12536 the session nonce, may be the Empty Buffer 12537 12538 sessionAttributes 12539 12540 TPMA_SESSION 12541 12542 the session attributes 12543 12544 hmac 12545 12546 TPM2B_AUTH 12547 12548 either an HMAC, a password, or an EmptyAuth 12549 12550 Page 104 12551 October 31, 2013 12552 12553 Published 12554 Copyright TCG 2006-2013 12555 12556 Family 2.0 12557 Level 00 Revision 00.99 12558 12559 Trusted Platform Module Library 12561 12562 Part 2: Structures 12563 12564 11 Algorithm Parameters and Structures 12565 11.1 Symmetric 12566 11.1.1 Introduction 12567 This clause defines the parameters and structures for describing symmetric algorithms. 12568 11.1.2 TPMI_AES_KEY_BITS 12569 This interface type defines the supported sizes for an AES key. This type is used to allow the 12570 unmarshaling routine to generate the proper validation code for the supported key sizes. An 12571 implementation that supports different key sizes would have a different set of selections. 12572 When used in TPM2_StartAuthSession(), the mode parameter shall be TPM_ALG_CFB. 12573 NOTE 1 12574 12575 Key size is expressed in bits. 12576 12577 NOTE 2 12578 12579 The definition for AES_KEY_SIZES_BITS used in the reference implementation is found in Annex B 12580 12581 Table 121 Definition of {AES} (TPM_KEY_BITS) TPMI_AES_KEY_BITS Type 12582 Parameter 12583 12584 Description 12585 12586 $AES_KEY_SIZES_BITS 12587 12588 number of bits in the key 12589 12590 #TPM_RC_VALUE 12591 12592 error when key size is not supported 12593 12594 11.1.3 TPMI_SM4_KEY_BITS 12595 This interface type defines the supported sizes for an SM4 key. This type is used to allow the 12596 unmarshaling routine to generate the proper validation code for the supported key sizes. An 12597 implementation that supports different key sizes would have a different set of selections. 12598 NOTE 12599 12600 SM4 only supports a key size of 128 bits. 12601 12602 Table 122 Definition of {SM4} (TPM_KEY_BITS) TPMI_SM4_KEY_BITS Type 12603 Parameter 12604 12605 Description 12606 12607 $SM4_KEY_SIZES_BITS 12608 12609 number of bits in the key 12610 12611 #TPM_RC_VALUE 12612 12613 Family 2.0 12614 Level 00 Revision 00.99 12615 12616 Published 12617 Copyright TCG 2006-2013 12618 12619 Page 105 12620 October 31, 2013 12621 12622 Part 2: Structures 12624 12625 Trusted Platform Module Library 12626 12627 11.1.4 TPMU_SYM_KEY_BITS 12628 This union is used to collect the symmetric encryption key sizes. 12629 The xor entry is a hash algorithms selector and not a key size in bits. This overload is used in order to 12630 avoid an additional level of indirection with another union and another set of selectors. 12631 The xor entry is only selected in a TPMT_SYM_DEF, which is used to select the parameter encryption 12632 value. 12633 Table 123 Definition of TPMU_SYM_KEY_BITS Union 12634 Parameter 12635 12636 Type 12637 12638 Selector 12639 12640 aes 12641 12642 TPMI_AES_KEY_BITS 12643 12644 TPM_ALG_AES 12645 12646 SM4 12647 12648 TPMI_SM4_KEY_BITS 12649 12650 TPM_ALG_SM4 12651 12652 sym 12653 12654 TPM_KEY_BITS 12655 12656 xor 12657 12658 TPMI_ALG_HASH 12659 12660 Description 12661 12662 when selector may be any of the 12663 symmetric block ciphers 12664 12665 overload for using xor 12666 NOTE 12667 12668 null 12669 12670 12671 11.1.5 TPMU_SYM_MODE 12672 This union allows the mode value in a TPMT_SYM_DEF or TPMT_SYM_DEF_OBJECT to be empty. 12673 Table 124 Definition of TPMU_SYM_MODE Union 12674 Parameter 12675 12676 Type 12677 12678 Selector 12679 12680 Description 12681 12682 aes 12683 12684 TPMI_ALG_SYM_MODE 12685 12686 TPM_ALG_AES 12687 12688 NOTE 12689 12690 12691 SM4 12692 12693 TPMI_ALG_SYM_MODE 12694 12695 TPM_ALG_SM4 12696 12697 NOTE 12698 12699 sym 12700 12701 TPMI_ALG_SYM_MODE 12702 12703 when selector may be any of the 12704 symmetric block ciphers 12705 12706 no mode selector 12707 12708 null 12709 12710 TPM_ALG_NULL 12711 12712 no mode selector 12713 12714 Page 106 12715 October 31, 2013 12716 12717 Published 12718 Copyright TCG 2006-2013 12719 12720 Family 2.0 12721 Level 00 Revision 00.99 12722 12723 Trusted Platform Module Library 12725 12726 Part 2: Structures 12727 12728 11.1.6 TPMU_SYM_DETAILS 12729 This union allows additional parameters to be added for a symmetric cipher. Currently, no additional 12730 parameters are required for any of the symmetric algorithms. 12731 NOTE 12732 12733 The x character in the table title will suppress generation of this type as the parser is not, at this time, 12734 able to generate the proper values (a union of all empty data types). When an algorithm is added that 12735 requires additional parameterization, the Type column will contain a value and the x may be removed. 12736 12737 Table 125 xDefinition of TPMU_SYM_DETAILS Union 12738 Parameter 12739 12740 Type 12741 12742 Selector 12743 12744 aes 12745 12746 TPM_ALG_AES 12747 12748 SM4 12749 12750 Description 12751 12752 TPM_ALG_SM4 12753 12754 sym 12755 12756 when selector may be any of the 12757 symmetric block ciphers 12758 12759 xor 12760 12761 TPM_ALG_XOR 12762 12763 null 12764 12765 TPM_ALG_NULL 12766 12767 11.1.7 TPMT_SYM_DEF 12768 The TPMT_SYM_DEF structure is used to select an algorithm to be used for parameter encryption in 12769 those cases when different symmetric algorithms may be selected. 12770 Table 126 Definition of TPMT_SYM_DEF Structure 12771 Parameter 12772 12773 Type 12774 12775 Description 12776 12777 algorithm 12778 12779 +TPMI_ALG_SYM 12780 12781 indicates a symmetric algorithm 12782 12783 [algorithm]keyBits 12784 12785 TPMU_SYM_KEY_BITS 12786 12787 a supported key size 12788 12789 [algorithm]mode 12790 12791 TPMU_SYM_MODE 12792 12793 the mode for the key 12794 12795 //[algorithm]details 12796 12797 TPMU_SYM_DETAILS 12798 12799 contains additional algorithm details 12800 NOTE 12801 12802 This is commented out at this time as the parser 12803 may not produce the proper code for a union if 12804 none of the selectors produces any data. 12805 12806 11.1.8 TPMT_SYM_DEF_OBJECT 12807 This structure is used when different symmetric block cipher (not XOR) algorithms may be selected. 12808 Table 127 Definition of TPMT_SYM_DEF_OBJECT Structure 12809 Parameter 12810 12811 Type 12812 12813 Description 12814 12815 algorithm 12816 12817 +TPMI_ALG_SYM_OBJECT 12818 12819 selects a symmetric block cipher 12820 12821 [algorithm]keyBits 12822 12823 TPMU_SYM_KEY_BITS 12824 12825 the key size 12826 12827 [algorithm]mode 12828 12829 TPMU_SYM_MODE 12830 12831 default mode 12832 12833 //[algorithm]details 12834 12835 TPMU_SYM_DETAILS 12836 12837 contains the additional algorithm details, if any 12838 NOTE 12839 12840 Family 2.0 12841 Level 00 Revision 00.99 12842 12843 This is commented out at this time as the parser 12844 may not produce the proper code for a union if 12845 none of the selectors produces any data. 12846 12847 Published 12848 Copyright TCG 2006-2013 12849 12850 Page 107 12851 October 31, 2013 12852 12853 Part 2: Structures 12855 12856 Trusted Platform Module Library 12857 12858 11.1.9 TPM2B_SYM_KEY 12859 This structure is used to hold a symmetric key in the sensitive area of an asymmetric object. 12860 The number of bits in the key is in keyBits in the public area. When keyBits is not an even multiple of 8 12861 bits, the unused bits of buffer will be the most significant bits of buffer[0] and size will be rounded up to 12862 the number of octets required to hold all bits of the key. 12863 Table 128 Definition of TPM2B_SYM_KEY Structure 12864 Parameter 12865 12866 Type 12867 12868 Description 12869 12870 size 12871 12872 UINT16 12873 12874 size, in octets, of the buffer containing the key; may be 12875 zero 12876 12877 buffer [size] {:MAX_SYM_KEY_BYTES} 12878 12879 BYTE 12880 12881 the key 12882 12883 11.1.10 TPMS_SYMCIPHER_PARMS 12884 This structure contains the parameters for a symmetric block cipher object. 12885 Table 129 Definition of TPMS_SYMCIPHER_PARMS Structure 12886 Parameter 12887 12888 Type 12889 12890 Description 12891 12892 sym 12893 12894 TPMT_SYM_DEF_OBJECT 12895 12896 a symmetric block cipher 12897 12898 11.1.11 TPM2B_SENSITIVE_DATA 12899 This buffer holds the secret data of a data object. It can hold as much as 128 octets of data. 12900 MAX_SYM_DATA shall be 128. 12901 NOTE 12902 12903 A named value rather than a numeric is used to make coding clearer. A numeric value does not indicate 12904 the reason that it has the specific value that is has. 12905 12906 Table 130 Definition of TPM2B_SENSITIVE_DATA Structure 12907 Parameter 12908 12909 Type 12910 12911 size 12912 12913 UINT16 12914 12915 buffer[size]{: MAX_SYM_DATA} 12916 12917 BYTE 12918 12919 Page 108 12920 October 31, 2013 12921 12922 Description 12923 12924 the keyed hash private data structure 12925 12926 Published 12927 Copyright TCG 2006-2013 12928 12929 Family 2.0 12930 Level 00 Revision 00.99 12931 12932 Trusted Platform Module Library 12934 12935 Part 2: Structures 12936 12937 11.1.12 TPMS_SENSITIVE_CREATE 12938 This structure defines the values to be placed in the sensitive area of a created object. This structure is 12939 only used within a TPM2B_SENSITIVE_CREATE structure. 12940 NOTE 12941 12942 When sent to the TPM or unsealed, data is usually encrypted using parameter encryption. 12943 12944 If data.size is not zero, and the object is not a keyedHash, data.size must match the size indicated in the 12945 keySize of public.parameters. If the object is a keyedHash, data.size may be any value up to the 12946 maximum allowed in a TPM2B_SENSITIVE_DATA. 12947 For an asymmetric object, data shall be an Empty Buffer and sensitiveDataOrigin shall be SET. 12948 Table 131 Definition of TPMS_SENSITIVE_CREATE Structure <IN> 12949 Parameter 12950 12951 Type 12952 12953 Description 12954 12955 userAuth 12956 12957 TPM2B_AUTH 12958 12959 the USER auth secret value 12960 12961 data 12962 12963 TPM2B_SENSITIVE_DATA 12964 12965 data to be sealed 12966 12967 Family 2.0 12968 Level 00 Revision 00.99 12969 12970 Published 12971 Copyright TCG 2006-2013 12972 12973 Page 109 12974 October 31, 2013 12975 12976 Part 2: Structures 12978 12979 Trusted Platform Module Library 12980 12981 11.1.13 TPM2B_SENSITIVE_CREATE 12982 This structure contains the sensitive creation data in a sized buffer. This structure is defined so that both 12983 the userAuth and data values of the TPMS_SENSITIVE_CREATE may be passed as a single parameter 12984 for parameter encryption purposes. 12985 Table 132 Definition of TPM2B_SENSITIVE_CREATE Structure <IN, S> 12986 Parameter 12987 12988 Type 12989 12990 Description 12991 12992 size= 12993 12994 UINT16 12995 12996 size of sensitive in octets (may not be zero) 12997 NOTE 12998 12999 sensitive 13000 13001 TPMS_SENSITIVE_CREATE 13002 13003 The userAuth and data parameters in this buffer 13004 may both be zero length but the minimum size of 13005 this parameter will be the sum of the size fields of 13006 the 13007 two 13008 parameters 13009 of 13010 the 13011 TPMS_SENSITIVE_CREATE. 13012 13013 data to be sealed or a symmetric key value. 13014 13015 11.1.14 TPMS_SCHEME_SIGHASH 13016 This structure is the scheme data for schemes that only require a hash to complete the scheme definition. 13017 Table 133 Definition of TPMS_SCHEME_SIGHASH Structure 13018 Parameter 13019 13020 Type 13021 13022 Description 13023 13024 hashAlg 13025 13026 TPMI_ALG_HASH 13027 13028 the hash algorithm used to digest the message 13029 13030 11.1.15 TPMI_ALG_HASH_SCHEME 13031 This is the list of values that may appear in a keyedHash as the scheme parameter. 13032 Table 134 Definition of (TPM_ALG_ID) TPMI_ALG_KEYEDHASH_SCHEME Type 13033 Values 13034 13035 Comments 13036 13037 TPM_ALG_HMAC 13038 13039 the "signing" scheme 13040 13041 TPM_ALG_XOR 13042 13043 the "obfuscation" scheme 13044 13045 +TPM_ALG_NULL 13046 #TPM_RC_VALUE 13047 13048 11.1.16 HMAC_SIG_SCHEME 13049 Table 135 Definition of Types for HMAC_SIG_SCHEME 13050 Type 13051 13052 Name 13053 13054 TPMS_SCHEME_SIGHASH 13055 13056 TPMS_SCHEME_HMAC 13057 13058 Page 110 13059 October 31, 2013 13060 13061 Description 13062 13063 Published 13064 Copyright TCG 2006-2013 13065 13066 Family 2.0 13067 Level 00 Revision 00.99 13068 13069 Trusted Platform Module Library 13071 13072 Part 2: Structures 13073 13074 11.1.17 TPMS_SCHEME_XOR 13075 This structure is for the XOR encryption scheme. 13076 Table 136 Definition of TPMS_SCHEME_XOR Structure 13077 Parameter 13078 13079 Type 13080 13081 Description 13082 13083 hashAlg 13084 13085 +TPMI_ALG_HASH 13086 13087 the hash algorithm used to digest the message 13088 13089 kdf 13090 13091 TPMI_ALG_KDF 13092 13093 the key derivation function 13094 13095 11.1.18 TPMU_SCHEME_HMAC 13096 Table 137 Definition of TPMU_SCHEME_KEYEDHASH Union <IN/OUT, S> 13097 Parameter 13098 13099 Type 13100 13101 Selector 13102 13103 Description 13104 13105 hmac 13106 13107 TPMS_SCHEME_HMAC 13108 13109 TPM_ALG_HMAC 13110 13111 the "signing" scheme 13112 13113 xor 13114 13115 TPMS_SCHEME_XOR 13116 13117 TPM_ALG_XOR 13118 13119 the "obfuscation" scheme 13120 13121 null 13122 13123 TPM_ALG_NULL 13124 13125 11.1.19 TPMT_KEYEDHASH_SCHEME 13126 This structure is used for a hash signing object. 13127 Table 138 Definition of TPMT_KEYEDHASH_SCHEME Structure 13128 Parameter 13129 13130 Type 13131 13132 Description 13133 13134 scheme 13135 13136 +TPMI_ALG_KEYEDHASH_SCHEME 13137 13138 selects the scheme 13139 13140 [scheme]details 13141 13142 TPMU_SCHEME_KEYEDHASH 13143 13144 the scheme parameters 13145 13146 Family 2.0 13147 Level 00 Revision 00.99 13148 13149 Published 13150 Copyright TCG 2006-2013 13151 13152 Page 111 13153 October 31, 2013 13154 13155 Part 2: Structures 13157 13158 Trusted Platform Module Library 13159 13160 11.2 Asymmetric 13161 11.2.1 Signing Schemes 13162 11.2.1.1 13163 13164 Introduction 13165 13166 These structures are used to define the method in which the signature is to be created. These schemes 13167 would appear in an objects public area and in commands where the signing scheme is variable. 13168 Every scheme is required to indicate a hash that is used in digesting the message. 13169 11.2.1.2 13170 13171 RSA_SIG_SCHEMES 13172 13173 These are the RSA schemes that only need a hash algorithm as a scheme parameter. 13174 For the TPM_ALG_RSAPSS signing scheme, the same hash algorithm is used for digesting TPMgenerated data (an attestation structure) and in the KDF used for the masking operation. The salt size is 13175 always the largest salt value that will fit into the available space. 13176 Table 139 Definition of {RSA} Types for RSA_SIG_SCHEMES 13177 Type 13178 13179 Name 13180 13181 Description 13182 13183 TPMS_SCHEME_SIGHASH 13184 TPMS_SCHEME_RSASSA 13185 TPMS_SCHEME_SIGHASH 13186 TPMS_SCHEME_RSAPSS 13187 13188 11.2.1.3 13189 13190 ECC_SIG_SCHEMES 13191 13192 These are the ECC schemes that only need a hash algorithm as a controlling parameter. 13193 Table 140 Definition of {ECC} Types for ECC_SIG_SCHEMES 13194 Type 13195 13196 Name 13197 13198 Description 13199 13200 TPMS_SCHEME_SIGHASH 13201 TPMS_SCHEME_ECDSA 13202 TPMS_SCHEME_SIGHASH 13203 TPMS_SCHEME_SM2 13204 TPMS_SCHEME_SIGHASH 13205 TPMS_SCHEME_ECSCHNORR 13206 13207 11.2.1.4 TPMS_SCHEME_ECDAA 13208 Table 141 Definition of {ECC} TPMS_SCHEME_ECDAA Structure 13209 Parameter 13210 13211 Type 13212 13213 Description 13214 13215 hashAlg 13216 13217 TPMI_ALG_HASH 13218 13219 the hash algorithm used to digest the message 13220 13221 count 13222 13223 UINT16 13224 13225 the counter value that is used between TPM2_Commit() and the sign 13226 operation 13227 13228 Page 112 13229 October 31, 2013 13230 13231 Published 13232 Copyright TCG 2006-2013 13233 13234 Family 2.0 13235 Level 00 Revision 00.99 13236 13237 Trusted Platform Module Library 13239 11.2.1.5 13240 13241 Part 2: Structures 13242 13243 TPMU_SIG_SCHEME 13244 Table 142 Definition of TPMU_SIG_SCHEME Union <IN/OUT, S> 13245 13246 Parameter 13247 13248 Type 13249 13250 Selector 13251 13252 Description 13253 13254 rsassa 13255 13256 TPMS_SCHEME_RSASSA 13257 13258 TPM_ALG_RSASSA 13259 13260 the PKCS#1v1.5 scheme 13261 13262 rsapss 13263 13264 TPMS_SCHEME_RSAPSS 13265 13266 TPM_ALG_RSAPSS 13267 13268 the PKCS#1v2.1 PSS scheme 13269 13270 ecdsa 13271 13272 TPMS_SCHEME_ECDSA 13273 13274 TPM_ALG_ECDSA 13275 13276 the ECDSA scheme 13277 13278 sm2 13279 13280 TPMS_SCHEME_SM2 13281 13282 TPM_ALG_SM2 13283 13284 ECDSA from SM2 13285 13286 ecdaa 13287 13288 TPMS_SCHEME_ECDAA 13289 13290 TPM_ALG_ECDAA 13291 13292 the ECDAA scheme 13293 13294 ecSchnorr 13295 13296 TPMS_SCHEME_ECSCHNORR 13297 13298 TPM_ALG_ECSCHNORR 13299 13300 the EC Schnorr 13301 13302 hmac 13303 13304 TPMS_SCHEME_HMAC 13305 13306 TPM_ALG_HMAC 13307 13308 the HMAC scheme 13309 13310 any 13311 13312 TPMS_SCHEME_SIGHASH 13313 13314 null 13315 13316 11.2.1.6 13317 13318 selector that allows access to 13319 digest for any signing scheme 13320 TPM_ALG_NULL 13321 13322 no scheme or default 13323 13324 TPMT_SIG_SCHEME 13325 Table 143 Definition of TPMT_SIG_SCHEME Structure 13326 13327 Parameter 13328 13329 Type 13330 13331 Description 13332 13333 scheme 13334 13335 +TPMI_ALG_SIG_SCHEME 13336 13337 scheme selector 13338 13339 [scheme]details 13340 13341 TPMU_SIG_SCHEME 13342 13343 scheme parameters 13344 13345 Family 2.0 13346 Level 00 Revision 00.99 13347 13348 Published 13349 Copyright TCG 2006-2013 13350 13351 Page 113 13352 October 31, 2013 13353 13354 Part 2: Structures 13356 13357 Trusted Platform Module Library 13358 13359 11.2.2 Encryption Schemes 13360 11.2.2.1 13361 13362 Introduction 13363 13364 These structures are used to indicate the hash algorithm used for the encrypting process. These 13365 schemes would appear in an objects public area. 13366 11.2.2.2 13367 13368 TPMS_SCHEME_OAEP 13369 Table 144 Definition of {RSA} TPMS_SCHEME_OAEP Structure 13370 13371 Parameter 13372 13373 Type 13374 13375 Description 13376 13377 hashAlg 13378 13379 +TPMI_ALG_HASH 13380 13381 the hash algorithm used to digest the message 13382 13383 11.2.2.3 13384 13385 TPMS_SCHEME_ECDH 13386 13387 For ECDH, KDFe is used for the key derivation function that only a hash algorithm is needed to complete 13388 the definition. 13389 Table 145 Definition of {ECC} TPMS_SCHEME_ECDH Structure 13390 Parameter 13391 13392 Type 13393 13394 Description 13395 13396 hashAlg 13397 13398 +TPMI_ALG_HASH 13399 13400 the hash algorithm used in the KDF 13401 13402 11.2.3 Key Derivation Schemes 13403 11.2.3.1 13404 13405 Introduction 13406 13407 These structures are used to define the key derivation for symmetric secret sharing using asymmetric 13408 methods. A secret shareing scheme is required in any asymmetric key with the decrypt attribute SET. 13409 These schemes would appear in an objects public area and in commands where the secret sharing 13410 scheme is variable. 13411 Each scheme includes a symmetric algorithm and a KDF selection. 13412 11.2.3.2 13413 13414 TPMS_SCHEME_MGF1 13415 Table 146 Definition of TPMS_SCHEME_MGF1 Structure 13416 13417 Parameter 13418 13419 Type 13420 13421 Description 13422 13423 hashAlg 13424 13425 TPMI_ALG_HASH 13426 13427 the hash algorithm used in the KDF 13428 13429 11.2.3.3 13430 13431 TPMS_SCHEME_KDF1_SP800_56a 13432 Table 147 Definition of {ECC} TPMS_SCHEME_KDF1_SP800_56a Structure 13433 13434 Parameter 13435 13436 Type 13437 13438 Description 13439 13440 hashAlg 13441 13442 TPMI_ALG_HASH 13443 13444 the hash algorithm used in the KDF 13445 13446 Page 114 13447 October 31, 2013 13448 13449 Published 13450 Copyright TCG 2006-2013 13451 13452 Family 2.0 13453 Level 00 Revision 00.99 13454 13455 Trusted Platform Module Library 13457 11.2.3.4 13458 13459 Part 2: Structures 13460 13461 TPMS_SCHEME_KDF2 13462 Table 148 Definition of TPMS_SCHEME_KDF2 Structure 13463 13464 Parameter 13465 13466 Type 13467 13468 Description 13469 13470 hashAlg 13471 13472 TPMI_ALG_HASH 13473 13474 the hash algorithm used in the KDF 13475 13476 11.2.3.5 13477 13478 TPMS_SCHEME_KDF1_SP800_108 13479 Table 149 Definition of TPMS_SCHEME_KDF1_SP800_108 Structure 13480 13481 Parameter 13482 13483 Type 13484 13485 Description 13486 13487 hashAlg 13488 13489 TPMI_ALG_HASH 13490 13491 the hash algorithm used in the KDF 13492 13493 11.2.3.6 13494 13495 TPMU_KDF_SCHEME 13496 Table 150 Definition of TPMU_KDF_SCHEME Union <IN/OUT, S> 13497 13498 Parameter 13499 13500 Type 13501 13502 Selector 13503 13504 mgf1 13505 13506 TPMS_SCHEME_MGF1 13507 13508 TPM_ALG_MGF1 13509 13510 kdf1_SP800_56a 13511 13512 TPMS_SCHEME_KDF1_SP800_56a 13513 13514 TPM_ALG_KDF1_SP800_56a 13515 13516 kdf2 13517 13518 TPMS_SCHEME_KDF2 13519 13520 TPM_ALG_KDF2 13521 13522 kdf1_sp800_108 13523 13524 TPMS_SCHEME_KDF1_SP800_108 13525 13526 Description 13527 13528 TPM_ALG_KDF1_SP800_108 13529 13530 null 13531 13532 11.2.3.7 13533 13534 TPM_ALG_NULL 13535 13536 TPMT_KDF_SCHEME 13537 Table 151 Definition of TPMT_KDF_SCHEME Structure 13538 13539 Parameter 13540 13541 Type 13542 13543 Description 13544 13545 scheme 13546 13547 +TPMI_ALG_KDF 13548 13549 scheme selector 13550 13551 [scheme]details 13552 13553 TPMU_KDF_SCHEME 13554 13555 scheme parameters 13556 13557 Family 2.0 13558 Level 00 Revision 00.99 13559 13560 Published 13561 Copyright TCG 2006-2013 13562 13563 Page 115 13564 October 31, 2013 13565 13566 Part 2: Structures 13568 11.2.3.8 13569 13570 Trusted Platform Module Library 13571 13572 TPMI_ALG_ASYM_SCHEME 13573 13574 List of all of the scheme types for any asymmetric algorithm. This is used to define the 13575 TPMT_ASYM_SCHEME. 13576 Table 152 Definition of (TPM_ALG_ID) TPMI_ALG_ASYM_SCHEME Type <> 13577 Values 13578 13579 Comments 13580 13581 TPM_ALG_RSASSA 13582 13583 list of the allowed values 13584 13585 TPM_ALG_RSAPSS 13586 TPM_ALG_RSAES 13587 TPM_ALG_OAEP 13588 TPM_ALG_ECDSA 13589 TPM_ALG_SM2 13590 TPM_ALG_ECDAA 13591 TPM_ALG_ECDH 13592 +TPM_ALG_NULL 13593 #TPM_RC_VALUE 13594 13595 11.2.3.9 13596 13597 TPMU_ASYM_SCHEME 13598 13599 This union of all asymmetric schemes is used in each of the asymmetric scheme structures. The actual 13600 scheme structure is defined by the interface type used for the selector. 13601 EXAMPLE 13602 13603 The TPMT_RSA_SCHEME structure uses the TPMU_ASYM_SCHEME union but the selector type is 13604 TPMI_ALG_RSA_SCHEME. This means that the only elements of the union that can be selected for th e 13605 TPMT_RSA_SCHEME are those that are in TPMI_RSA_SCHEME. 13606 13607 Table 153 Definition of TPMU_ASYM_SCHEME Union 13608 Parameter 13609 13610 Type 13611 13612 Selector 13613 13614 Description 13615 13616 rsassa 13617 13618 TPMS_SCHEME_RSASSA 13619 13620 TPM_ALG_RSASSA 13621 13622 the PKCS#1v1.5 scheme 13623 13624 rsapss 13625 13626 TPMS_SCHEME_RSAPSS 13627 13628 TPM_ALG_RSAPSS 13629 13630 the PKCS#1v2.1 PSS scheme 13631 13632 oaep 13633 13634 TPMS_SCHEME_OAEP 13635 13636 TPM_ALG_OAEP 13637 13638 the PKSC#1v2.1 OAEP scheme 13639 13640 ecdsa 13641 13642 TPMS_SCHEME_ECDSA 13643 13644 TPM_ALG_ECDSA 13645 13646 an ECDSA scheme 13647 13648 sm2 13649 13650 TPMS_SCHEME_SM2 13651 13652 TPM_ALG_SM2 13653 13654 sign or key exchange from SM2 13655 13656 ecdaa 13657 13658 TPMS_SCHEME_ECDAA 13659 13660 TPM_ALG_ECDAA 13661 13662 an ECDAA scheme 13663 13664 ecSchnorr 13665 13666 TPMS_SCHEME_ECSCHNORR 13667 13668 TPM_ALG_ECSCHNORR elliptic curve Schnorr signature 13669 13670 ecdh 13671 TPMS_SCHEME_ECDH 13672 TPM_ALG_ECDH 13673 anySig 13674 13675 TPMS_SCHEME_SIGHASH 13676 13677 null 13678 13679 Page 116 13680 October 31, 2013 13681 13682 TPM_ALG_NULL 13683 13684 Published 13685 Copyright TCG 2006-2013 13686 13687 no scheme or default 13688 This selects the NULL Signature. 13689 13690 Family 2.0 13691 Level 00 Revision 00.99 13692 13693 Trusted Platform Module Library 13695 13696 Part 2: Structures 13697 13698 11.2.3.10 TPMT_ASYM_SCHEME 13699 This structure is defined to allow overlay of all of the schemes for any asymmetric object. This structure is 13700 not sent on the interface. 13701 Table 154 Definition of TPMT_ASYM_SCHEME Structure <> 13702 Parameter 13703 13704 Type 13705 13706 Description 13707 13708 scheme 13709 13710 +TPMI_ALG_ASYM_SCHEME 13711 13712 scheme selector 13713 13714 [scheme]details 13715 13716 TPMU_ASYM_SCHEME 13717 13718 scheme parameters 13719 13720 11.2.4 RSA 13721 11.2.4.1 13722 13723 TPMI_ALG_RSA_SCHEME 13724 13725 The list of values that may appear in the scheme parameter of a TPMS_RSA_PARMS structure. 13726 Table 155 Definition of (TPM_ALG_ID) {RSA} TPMI_ALG_RSA_SCHEME Type 13727 Values 13728 13729 Comments 13730 13731 TPM_ALG_RSASSA 13732 13733 list of the allowed values 13734 13735 TPM_ALG_RSAPSS 13736 TPM_ALG_RSAES 13737 TPM_ALG_OAEP 13738 +TPM_ALG_NULL 13739 #TPM_RC_VALUE 13740 13741 11.2.4.2 13742 13743 TPMT_RSA_SCHEME 13744 Table 156 Definition of {RSA} TPMT_RSA_SCHEME Structure 13745 13746 Parameter 13747 13748 Type 13749 13750 Description 13751 13752 scheme 13753 13754 +TPMI_ALG_RSA_SCHEME 13755 13756 scheme selector 13757 13758 [scheme]details 13759 13760 TPMU_ASYM_SCHEME 13761 13762 scheme parameters 13763 13764 Family 2.0 13765 Level 00 Revision 00.99 13766 13767 Published 13768 Copyright TCG 2006-2013 13769 13770 Page 117 13771 October 31, 2013 13772 13773 Part 2: Structures 13775 11.2.4.3 13776 13777 Trusted Platform Module Library 13778 13779 TPMI_ALG_RSA_DECRYPT 13780 13781 The list of values that are allowed in a decryption scheme selection as used in TPM2_RSA_Encrypt() and 13782 TPM2_RSA_Decrypt(). 13783 Table 157 Definition of (TPM_ALG_ID) {RSA} TPMI_ALG_RSA_DECRYPT Type 13784 Values 13785 13786 Comments 13787 13788 TPM_ALG_RSAES 13789 TPM_ALG_OAEP 13790 +TPM_ALG_NULL 13791 #TPM_RC_VALUE 13792 13793 11.2.4.4 13794 13795 TPMT_RSA_DECRYPT 13796 Table 158 Definition of {RSA} TPMT_RSA_DECRYPT Structure 13797 13798 Parameter 13799 13800 Type 13801 13802 Description 13803 13804 scheme 13805 13806 +TPMI_ALG_RSA_DECRYPT 13807 13808 scheme selector 13809 13810 [scheme]details 13811 13812 TPMU_ASYM_SCHEME 13813 13814 scheme parameters 13815 13816 11.2.4.5 13817 13818 TPM2B_PUBLIC_KEY_RSA 13819 13820 This sized buffer holds the largest RSA public key supported by the TPM. 13821 NOTE 13822 13823 The reference implementation only supports key sizes of 1,024 and 2,048 bits. 13824 13825 Table 159 Definition of {RSA} TPM2B_PUBLIC_KEY_RSA Structure 13826 Parameter 13827 13828 Type 13829 13830 Description 13831 13832 size 13833 13834 UINT16 13835 13836 size of the buffer 13837 The value of zero is only valid for create. 13838 13839 buffer[size] {: MAX_RSA_KEY_BYTES} 13840 13841 BYTE 13842 13843 Value 13844 13845 11.2.4.6 13846 13847 TPMI_RSA_KEY_BITS 13848 13849 This holds the value that is the maximum size allowed for an RSA key. 13850 NOTE 1 13851 13852 An implementation is allowed to provide limited support for smaller RSA key sizes. That is, a TPM may be 13853 able to accept a smaller RSA key size in TPM2_LoadExternal() when only the public area is loaded but 13854 not accept that smaller key size in any command that loads both the public and private portions of an RSA 13855 key. This would allow the TPM to validate signatures using the smaller key but would prevent the TPM 13856 from using the smaller key size for any other purpose. 13857 13858 NOTE 2 13859 13860 The definition for RSA_KEY_SIZES_BITS used in the reference implementation is found in Annex B 13861 13862 Page 118 13863 October 31, 2013 13864 13865 Published 13866 Copyright TCG 2006-2013 13867 13868 Family 2.0 13869 Level 00 Revision 00.99 13870 13871 Trusted Platform Module Library 13873 13874 Part 2: Structures 13875 13876 Table 160 Definition of {RSA} (TPM_KEY_BITS) TPMI_RSA_KEY_BITS Type 13877 Parameter 13878 13879 Description 13880 13881 $RSA_KEY_SIZES_BITS 13882 13883 the number of bits in the supported key 13884 13885 #TPM_RC_VALUE 13886 13887 error when key size is not supported 13888 13889 11.2.4.7 13890 13891 TPM2B_PRIVATE_KEY_RSA 13892 13893 This sized buffer holds the largest RSA prime number supported by the TPM. 13894 NOTE 13895 13896 All primes are required to have exactly half the number of significant bits as the public modulus , and the 13897 square of each prime is required to have the same number of significant bits as the public modulus. 13898 13899 Table 161 Definition of {RSA} TPM2B_PRIVATE_KEY_RSA Structure 13900 Parameter 13901 13902 Type 13903 13904 size 13905 13906 UINT16 13907 13908 buffer[size]{:MAX_RSA_KEY_BYTES/2} 13909 13910 BYTE 13911 13912 Family 2.0 13913 Level 00 Revision 00.99 13914 13915 Description 13916 13917 Published 13918 Copyright TCG 2006-2013 13919 13920 Page 119 13921 October 31, 2013 13922 13923 Part 2: Structures 13925 13926 Trusted Platform Module Library 13927 13928 11.2.5 ECC 13929 11.2.5.1 13930 13931 TPM2B_ECC_PARAMETER 13932 13933 This sized buffer holds the largest ECC parameter (coordinate) supported by the TPM. 13934 Table 162 Definition of {ECC} TPM2B_ECC_PARAMETER Structure 13935 Parameter 13936 13937 Type 13938 13939 Description 13940 13941 size 13942 13943 UINT16 13944 13945 size of buffer 13946 13947 buffer[size] {:MAX_ECC_KEY_BYTES} 13948 13949 BYTE 13950 13951 the parameter data 13952 13953 11.2.5.2 13954 13955 TPMS_ECC_POINT 13956 13957 This structure holds two ECC coordinates that, together, make up an ECC point. 13958 Table 163 Definition of {ECC} TPMS_ECC_POINT Structure 13959 Parameter 13960 13961 Type 13962 13963 Description 13964 13965 x 13966 13967 TPM2B_ECC_PARAMETER 13968 13969 X coordinate 13970 13971 y 13972 13973 TPM2B_ECC_PARAMETER 13974 13975 Y coordinate 13976 13977 11.2.5.3 13978 13979 TPM2B_ECC_POINT 13980 13981 This structure is defined to allow a point to be a single sized parameter so that it may be encrypted. 13982 NOTE 13983 13984 If the point is to be omitted, the X and Y coordinates need to be individual ly set to Empty Buffers. The 13985 minimum value for size will be four. It is checked indirectly by unmarshaling of the TPMS_ECC_POINT. If 13986 the type of point were BYTE, then size could have been zero. However, this would complicate the process 13987 of marshaling the structure. 13988 13989 Table 164 Definition of {ECC} TPM2B_ECC_POINT Structure 13990 Parameter 13991 13992 Type 13993 13994 Description 13995 13996 size= 13997 13998 UINT16 13999 14000 size of the remainder of this structure 14001 14002 point 14003 14004 TPMS_ECC_POINT 14005 14006 coordinates 14007 error returned if the unmarshaled size of point is 14008 not exactly equal to size 14009 14010 #TPM_RC_SIZE 14011 14012 Page 120 14013 October 31, 2013 14014 14015 Published 14016 Copyright TCG 2006-2013 14017 14018 Family 2.0 14019 Level 00 Revision 00.99 14020 14021 Trusted Platform Module Library 14023 11.2.5.4 14024 14025 Part 2: Structures 14026 14027 TPMI_ALG_ECC_SCHEME 14028 Table 165 Definition of (TPM_ALG_ID) {ECC} TPMI_ALG_ECC_SCHEME Type 14029 14030 Values 14031 14032 Comments 14033 14034 TPM_ALG_ECDSA 14035 14036 these are the selections allowed for an ECC key 14037 14038 TPM_ALG_SM2 14039 TPM_ALG_ECDAA 14040 TPM_ALG_ECSCHNORR 14041 TPM_ALG_ECDH 14042 +TPM_ALG_NULL 14043 #TPM_RC_SCHEME 14044 14045 11.2.5.5 14046 14047 TPMI_ECC_CURVE 14048 14049 The ECC curves implemented by the TPM. 14050 NOTE 14051 14052 The definition of ECC_CURVES used in the reference implementation is found in Annex B 14053 14054 Table 166 Definition of {ECC} (TPM_ECC_CURVE) TPMI_ECC_CURVE Type 14055 Parameter 14056 14057 Description 14058 14059 $ECC_CURVES 14060 14061 the list of implemented curves 14062 14063 #TPM_RC_CURVE 14064 14065 error when curve is not supported 14066 14067 11.2.5.6 14068 14069 TPMT_ECC_SCHEME 14070 14071 Table 167 Definition of (TPMT_SIG_SCHEME) {ECC} TPMT_ECC_SCHEME Structure 14072 Parameter 14073 14074 Type 14075 14076 Description 14077 14078 scheme 14079 14080 +TPMI_ALG_ECC_SCHEME 14081 14082 scheme selector 14083 14084 [scheme]details 14085 14086 TPMU_SIG_SCHEME 14087 14088 scheme parameters 14089 14090 Family 2.0 14091 Level 00 Revision 00.99 14092 14093 Published 14094 Copyright TCG 2006-2013 14095 14096 Page 121 14097 October 31, 2013 14098 14099 Part 2: Structures 14101 11.2.5.7 14102 14103 Trusted Platform Module Library 14104 14105 TPMS_ALGORITHM_DETAIL_ECC 14106 14107 This structure is used to report on the curve parameters of an ECC curve. It is returned by 14108 TPM2_ECC_Parameters(). 14109 Table 168 Definition of {ECC} TPMS_ALGORITHM_DETAIL_ECC Structure <OUT> 14110 Parameter 14111 14112 Type 14113 14114 Description 14115 14116 curveID 14117 14118 TPM_ECC_CURVE 14119 14120 identifier for the curve 14121 14122 keySize 14123 14124 UINT16 14125 14126 Size in bits of the key 14127 14128 kdf 14129 14130 TPMT_KDF_SCHEME 14131 14132 the default KDF and hash algorithm used in secret sharing 14133 operations 14134 14135 sign 14136 14137 TPMT_ECC_SCHEME+ 14138 14139 If not TPM_ALG_NULL, this is the mandatory signature 14140 scheme that is required to be used with this curve. 14141 14142 p 14143 14144 TPM2B_ECC_PARAMETER 14145 14146 Fp (the modulus) 14147 14148 a 14149 14150 TPM2B_ECC_PARAMETER 14151 14152 coefficient of the linear term in the curve equation 14153 14154 b 14155 14156 TPM2B_ECC_PARAMETER 14157 14158 constant term for curve equation 14159 14160 gX 14161 14162 TPM2B_ECC_PARAMETER 14163 14164 x coordinate of base point G 14165 14166 gY 14167 14168 TPM2B_ECC_PARAMETER 14169 14170 y coordinate of base point G 14171 14172 n 14173 14174 TPM2B_ECC_PARAMETER 14175 14176 order of G 14177 14178 h 14179 14180 TPM2B_ECC_PARAMETER 14181 14182 cofactor (a size of zero indicates a cofactor of 1) 14183 14184 11.3 Signatures 14185 11.3.1 TPMS_SIGNATURE_RSASSA 14186 Table 169 Definition of {RSA} TPMS_SIGNATURE_RSASSA Structure 14187 Parameter 14188 14189 Type 14190 14191 Description 14192 14193 hash 14194 14195 TPMI_ALG_HASH 14196 14197 the hash algorithm used to digest the message 14198 TPM_ALG_NULL is not allowed. 14199 14200 sig 14201 14202 TPM2B_PUBLIC_KEY_RSA 14203 14204 The signature is the size of a public key. 14205 14206 11.3.2 TPMS_SIGNATURE_RSAPSS 14207 When the TPM generates a PSS signature, the salt size is the largest size allowed by the key and hash 14208 combination. 14209 EXAMPLE 14210 14211 For a 2,048-bit public modulus key and SHA1 hash, the salt size is 256 20 2 = 234 octets. 14212 14213 NOTE 14214 14215 While this is significantly larger than required from a securit y perspective, it avoids issues of whether a 14216 particular size of salt value is sufficient. 14217 14218 Page 122 14219 October 31, 2013 14220 14221 Published 14222 Copyright TCG 2006-2013 14223 14224 Family 2.0 14225 Level 00 Revision 00.99 14226 14227 Trusted Platform Module Library 14229 14230 Part 2: Structures 14231 14232 Table 170 Definition of {RSA} TPMS_SIGNATURE_RSAPSS Structure 14233 Parameter 14234 14235 Type 14236 14237 Description 14238 14239 hash 14240 14241 TPMI_ALG_HASH 14242 14243 the hash algorithm used in the signature process 14244 TPM_ALG_NULL is not allowed. 14245 14246 sig 14247 14248 TPM2B_PUBLIC_KEY_RSA 14249 14250 The signature is the size of a public key. 14251 14252 11.3.3 TPMS_SIGNATURE_ECDSA 14253 Table 171 Definition of {ECC} TPMS_SIGNATURE_ECDSA Structure 14254 Parameter 14255 14256 Type 14257 14258 Description 14259 14260 hash 14261 14262 TPMI_ALG_HASH 14263 14264 the hash algorithm used in the signature process 14265 TPM_ALG_NULL is not allowed. 14266 14267 signatureR 14268 14269 TPM2B_ECC_PARAMETER 14270 14271 signatureS 14272 14273 TPM2B_ECC_PARAMETER 14274 14275 11.3.4 TPMU_SIGNATURE 14276 A TPMU_SIGNATURE_COMPOSITE is a union of the various signatures that is supported by a particular 14277 TPM implementation. The union allows substitution of any signature algorithm wherever a signature is 14278 required in a structure. Table 172 is an illustration of a TPMU_SIGNATURE for a TPM that implements 14279 both RSA and ECC signing. 14280 NOTE 1 14281 14282 All TPM are required to support a hash algorithm and the HMAC algorithm. 14283 14284 When a symmetric algorithm is used for signing, the signing algorithm is assumed to be an HMAC based 14285 on the indicated hash algorithm. The HMAC key will either be referenced as part of the usage or will be 14286 implied by context. 14287 NOTE 2 14288 14289 The table below is illustrative. It would be modified to reflect the signatures produced by the TPM. 14290 14291 Table 172 Definition of TPMU_SIGNATURE Union <IN/OUT, S> 14292 Parameter 14293 14294 Type 14295 14296 Selector 14297 14298 Description 14299 14300 rsassa 14301 14302 TPMS_SIGNATURE_RSASSA 14303 14304 TPM_ALG_RSASSA 14305 14306 a PKCS#1v1.5 signature 14307 14308 rsapss 14309 14310 TPMS_SIGNATURE_RSAPSS 14311 14312 TPM_ALG_RSAPSS 14313 14314 a PKCS#1v2.1PSS signature 14315 14316 ecdsa 14317 14318 TPMS_SIGNATURE_ECDSA 14319 14320 TPM_ALG_ECDSA 14321 14322 an ECDSA signature 14323 14324 sm2 14325 14326 TPMS_SIGNATURE_ECDSA 14327 14328 TPM_ALG_SM2 14329 14330 same format as ECDSA 14331 14332 ecdaa 14333 14334 TPMS_SIGNATURE_ECDSA 14335 14336 TPM_ALG_ECDAA 14337 14338 same format as ECDSA 14339 14340 ecschnorr 14341 14342 TPMS_SIGNATURE_ECDSA 14343 14344 TPM_ALG_ECSCHNORR 14345 14346 same format as ECDSA 14347 14348 hmac 14349 14350 TPMT_HA 14351 14352 TPM_ALG_HMAC 14353 14354 HMAC signature (required to 14355 be supported) 14356 14357 any 14358 14359 TPMS_SCHEME_SIGHASH 14360 14361 null 14362 14363 Family 2.0 14364 Level 00 Revision 00.99 14365 14366 Published 14367 Copyright TCG 2006-2013 14368 14369 the NULL signature 14370 14371 Page 123 14372 October 31, 2013 14373 14374 Part 2: Structures 14376 14377 Trusted Platform Module Library 14378 14379 11.3.5 TPMT_SIGNATURE 14380 Table 173 shows the basic algorithm-agile structure when a symmetric or asymmetric signature is 14381 indicated. The sigAlg parameter indicates the algorithm used for the signature. This structure is output 14382 from the attestation commands and is an input to TPM2_VerifySignature(), TPM2_PolicySigned(), and 14383 TPM2_FieldUpgradeStart(). 14384 Table 173 Definition of TPMT_SIGNATURE Structure 14385 Parameter 14386 14387 Type 14388 14389 Description 14390 14391 sigAlg 14392 14393 +TPMI_ALG_SIG_SCHEME 14394 14395 selector of the algorithm used to construct the signature 14396 14397 [sigAlg]signature 14398 14399 TPMU_SIGNATURE 14400 14401 This shall be the actual signature information. 14402 14403 11.4 Key/Secret Exchange 14404 11.4.1 Introduction 14405 The structures in this clause are used when a key or secret is being exchanged. The exchange may be in 14406 14407 14408 TPM2_StartAuthSession() where the secret is injected for salting the session, 14409 14410 14411 14412 TPM2_Duplicate(), TPM2_Import, or TPM2_Rewrap() where the secret is the symmetric encryption 14413 key for the outer wrapper of a duplication blob, or 14414 14415 14416 14417 TPM2_ActivateIdentity() or TPM2_CreateIdentity() where the secret is the symmetric encryption key 14418 for the credential blob. 14419 14420 Particulars are described in Part 1. 14421 11.4.2 TPMU_ENCRYPTED_SECRET 14422 This structure is used to hold either an ephemeral public point for ECDH, an OAEP-encrypted block for 14423 RSA, or a symmetrically encrypted value. This structure is defined for the limited purpose of determining 14424 the size of a TPM2B_ENCRYPTED_SECRET. 14425 The symmetrically encrypted value may use either CFB or XOR encryption. 14426 NOTE 14427 14428 Table 174 is illustrative. It would be modified depending on the algorithms supported in the TPM. 14429 14430 Table 174 Definition of TPMU_ENCRYPTED_SECRET Union <S> 14431 Parameter 14432 14433 Type 14434 14435 Selector 14436 14437 ecc[sizeof(TPMS_ECC_POINT)] 14438 14439 BYTE 14440 14441 TPM_ALG_ECC 14442 14443 rsa[MAX_RSA_KEY_BYTES] 14444 14445 BYTE 14446 14447 TPM_ALG_RSA 14448 14449 symmetric[sizeof(TPM2B_DIGEST)] 14450 14451 BYTE 14452 14453 TPM_ALG_SYMCIPHER 14454 14455 keyedHash[sizeof(TPM2B_DIGEST)] 14456 14457 BYTE 14458 14459 TPM_ALG_KEYEDHASH 14460 14461 Page 124 14462 October 31, 2013 14463 14464 Published 14465 Copyright TCG 2006-2013 14466 14467 Description 14468 14469 Any symmetrically encrypted 14470 secret value will be limited to 14471 be no larger than a digest. 14472 14473 Family 2.0 14474 Level 00 Revision 00.99 14475 14476 Trusted Platform Module Library 14478 14479 Part 2: Structures 14480 14481 11.4.3 TPM2B_ENCRYPTED_SECRET 14482 Table 175 Definition of TPM2B_ENCRYPTED_SECRET Structure 14483 Parameter 14484 14485 Type 14486 14487 Description 14488 14489 size 14490 14491 UINT16 14492 14493 size of the secret value 14494 14495 secret[size] {:sizeof(TPMU_ENCRYPTED_SECRET)} 14496 14497 BYTE 14498 14499 secret 14500 14501 Family 2.0 14502 Level 00 Revision 00.99 14503 14504 Published 14505 Copyright TCG 2006-2013 14506 14507 Page 125 14508 October 31, 2013 14509 14510 Part 2: Structures 14512 14513 Trusted Platform Module Library 14514 14515 12 Key/Object Complex 14516 12.1 Introduction 14517 An object description requires a TPM2B_PUBLIC structure and may require a TPMT_SENSITIVE 14518 structure. When the structure is stored off the TPM, the TPMT_SENSITIVE structure is encrypted within a 14519 TPM2B_PRIVATE structure. 14520 When the object requires two components for its description, those components are loaded as separate 14521 parameters in the TPM2_Load() command. When the TPM creates an object that requires both 14522 components, the TPM will return them as separate parameters from the TPM2_Create() operation. 14523 The TPM may produce multiple different TPM2B_PRIVATE structures for a single TPM2B_PUBLIC 14524 structure. Creation of a modified TPM2B_PRIVATE structure requires that the full structure be loaded with 14525 the TPM2_Load() command, modification of the TPMT_SENSITIVE data, and output of a new 14526 TPM2B_PRIVATE structure. 14527 12.2 Public Area Structures 14528 12.2.1 Description 14529 This clause defines the TPM2B_PUBLIC structure and the higher-level substructure that may be 14530 contained in a TPM2B_PUBLIC. The higher-level structures that are currently defined for inclusion in a 14531 TPM2B_PUBLIC are the 14532 14533 14534 structures for asymmetric keys, 14535 14536 14537 14538 structures for symmetric keys, and 14539 14540 14541 14542 structures for sealed data. 14543 14544 12.2.2 TPMI_ALG_PUBLIC 14545 Table 176 Definition of (TPM_ALG_ID) TPMI_ALG_PUBLIC Type 14546 Values 14547 14548 Comments 14549 14550 TPM_ALG_KEYEDHASH 14551 14552 required of all TPM 14553 14554 TPM_ALG_SYMCIPHER 14555 14556 required of all TPM 14557 14558 TPM_ALG_RSA 14559 14560 At least one asymmetric algorithm shall be implemented. 14561 14562 TPM_ALG_ECC 14563 14564 At least one asymmetric algorithm shall be implemented. 14565 14566 #TPM_RC_TYPE 14567 14568 response code when a public type is not supported 14569 14570 12.2.3 Type-Specific Parameters 14571 12.2.3.1 14572 14573 Description 14574 14575 The public area contains two fields (parameters and unique) that vary by object type. The parameters 14576 field varies according to the type of the object but the contents may be the same across multiple 14577 instances of a particular type. The unique field format also varies according to the type of the object and 14578 will also be unique for each instance. 14579 14580 Page 126 14581 October 31, 2013 14582 14583 Published 14584 Copyright TCG 2006-2013 14585 14586 Family 2.0 14587 Level 00 Revision 00.99 14588 14589 Trusted Platform Module Library 14591 14592 Part 2: Structures 14593 14594 For a symmetric key (type == TPM_ALG_SYMCIPHER), HMAC key (type == TPM_ALG_KEYEDHASH) 14595 or data object (also, type == TPM_ALG_KEYEDHASH), the contents of unique shall be computed from 14596 components of the sensitive area of the object as follows: 14597 14598 unique HnameAlg(seedValue || sensitive) 14599 14600 (8) 14601 14602 where 14603 14604 HnameAlg() 14605 14606 the hash algorithm used to compute the Name of the object 14607 14608 seedValue 14609 14610 the digest-sized obfuscation value in the sensitive area of a symmetric 14611 key 14612 or 14613 symmetric 14614 data 14615 object 14616 found 14617 in 14618 a 14619 TPMT_SENSITIVE.seedValue.buffer 14620 14621 sensitive 14622 14623 the 14624 secret 14625 key/data 14626 of 14627 TPMT_SENSITIVE.sensitive.any.buffer 14628 14629 12.2.3.2 14630 14631 the 14632 14633 object 14634 14635 in 14636 14637 the 14638 14639 TPMU_PUBLIC_ID 14640 Table 177 Definition of TPMU_PUBLIC_ID Union <IN/OUT, S> 14641 14642 Parameter 14643 14644 Type 14645 14646 Selector 14647 14648 keyedHash 14649 14650 TPM2B_DIGEST 14651 14652 TPM_ALG_KEYEDHASH 14653 14654 sym 14655 14656 TPM2B_DIGEST 14657 14658 TPM_ALG_SYMCIPHER 14659 14660 rsa 14661 14662 TPM2B_PUBLIC_KEY_RSA 14663 14664 TPM_ALG_RSA 14665 14666 ecc 14667 14668 TPMS_ECC_POINT 14669 14670 TPM_ALG_ECC 14671 14672 12.2.3.3 14673 14674 Description 14675 14676 TPMS_KEYEDHASH_PARMS 14677 14678 This structure describes the parameters that would appear in the public area of a KEYEDHASH object. 14679 Note 14680 14681 Although the names are the same, the types of the structures are not the same as for asymmetric 14682 parameter lists. 14683 14684 Table 178 Definition of TPMS_KEYEDHASH_PARMS Structure 14685 Parameter 14686 14687 Type 14688 14689 Description 14690 14691 scheme 14692 14693 TPMT_KEYEDHASH_SCHEME+ 14694 14695 Indicates the signing method used for a keyedHash signing 14696 object. This field also determines the size of the data field for a 14697 data object created with TPM2_Create(). This field shall not be set 14698 to TPM_ALG_NULL in a template if either sign or encrypt is SET. 14699 14700 12.2.3.4 14701 14702 TPMS_ASYM_PARMS 14703 14704 This structure contains the common public area parameters for an asymmetric key. The first two 14705 parameters of the parameter definition structures of an asymmetric key shall have the same two first 14706 components. 14707 NOTE 14708 14709 The sign parameter may have a different type in order to allow different schemes to be selected for each 14710 asymmetric type but the first parameter of each scheme definition shall be a TPM_ALG_ID for a valid 14711 signing scheme. 14712 14713 Family 2.0 14714 Level 00 Revision 00.99 14715 14716 Published 14717 Copyright TCG 2006-2013 14718 14719 Page 127 14720 October 31, 2013 14721 14722 Part 2: Structures 14724 14725 Trusted Platform Module Library 14726 Table 179 Definition of TPMS_ASYM_PARMS Structure <> 14727 14728 Parameter 14729 14730 Type 14731 14732 Description 14733 14734 symmetric 14735 14736 TPMT_SYM_DEF_OBJECT+ 14737 14738 the companion symmetric algorithm for a restricted 14739 decryption key and shall be set to a supported symmetric 14740 algorithm 14741 This field is optional for keys that are not decryption keys 14742 and shall be set to TPM_ALG_NULL if not used. 14743 14744 scheme 14745 14746 TPMT_ASYM_SCHEME+ 14747 14748 for a key with the sign attribute SET, a valid signing 14749 scheme for the key type 14750 for a key with the decrypt attribute SET, a valid key 14751 exchange protocol 14752 for a key with sign and decrypt attributes, shall be TPM_ALG_NULL 14753 14754 12.2.3.5 14755 14756 TPMS_RSA_PARMS 14757 14758 A TPM compatible with this specification and supporting RSA shall support numPrimes of two and an 14759 exponent of zero. Support for other values is optional. Use of other exponents in duplicated keys is not 14760 recommended because the resulting keys would not be interoperable with other TPMs. 14761 NOTE 1 14762 14763 Implementations are not required to check that exponent is the default exponent. They may fail to load the 14764 key if exponent is not zero. The reference implementation allows the values listed in the table. 14765 14766 Table 180 Definition of {RSA} TPMS_RSA_PARMS Structure 14767 Parameter 14768 14769 Type 14770 14771 Description 14772 14773 symmetric 14774 14775 TPMT_SYM_DEF_OBJECT+ 14776 14777 for a restricted decryption key, shall be set to a 14778 supported symmetric algorithm, key size, and mode. 14779 if the key is not a restricted decryption key, this field 14780 shall be set to TPM_ALG_NULL. 14781 14782 scheme 14783 14784 TPMT_RSA_SCHEME+ 14785 14786 14787 keyBits 14788 14789 TPMI_RSA_KEY_BITS 14790 14791 number of bits in the public modulus 14792 14793 exponent 14794 UINT32 14795 14796 the public exponent 14797 A prime number greater than 2. 14798 When zero, indicates that the exponent is the default 14799 16 14800 of 2 + 1 14801 14802 #TPM_RC_KEY_SIZE 14803 14804 #TPM_RC_VALUE 14805 14806 Page 128 14807 October 31, 2013 14808 14809 Published 14810 Copyright TCG 2006-2013 14811 14812 Family 2.0 14813 Level 00 Revision 00.99 14814 14815 Trusted Platform Module Library 14817 12.2.3.6 14818 14819 Part 2: Structures 14820 14821 TPMS_ECC_PARMS 14822 14823 This structure contains the parameters for prime modulus ECC. 14824 Table 181 Definition of {ECC} TPMS_ECC_PARMS Structure 14825 Parameter 14826 14827 Type 14828 14829 Description 14830 14831 symmetric 14832 14833 TPMT_SYM_DEF_OBJECT+ 14834 14835 for a restricted decryption key, shall be set to a supported 14836 symmetric algorithm, key size. and mode. 14837 if the key is not a restricted decryption key, this field shall be 14838 set to TPM_ALG_NULL. 14839 14840 scheme 14841 14842 TPMT_ECC_SCHEME+ 14843 14844 If the sign attribute of the key is SET, then this shall be a valid 14845 signing scheme. 14846 NOTE 14847 14848 If the sign parameter in curveID indicates a mandatory 14849 scheme, then this field shall have the same value. 14850 14851 curveID 14852 TPMI_ECC_CURVE 14853 14854 ECC curve ID 14855 14856 kdf 14857 14858 TPMT_KDF_SCHEME+ 14859 14860 14861 12.2.3.7 14862 14863 There are currently no commands where this parameter 14864 has effect and, in the reference code, this field needs to 14865 be set to TPM_ALG_NULL. 14866 14867 TPMU_PUBLIC_PARMS 14868 14869 Table 182 defines the possible parameter definition structures that may be contained in the public portion 14870 of a key. 14871 Table 182 Definition of TPMU_PUBLIC_PARMS Union <IN/OUT, S> 14872 Parameter 14873 14874 Type 14875 14876 (1) 14877 14878 Selector 14879 14880 Description 14881 14882 keyedHashDetail 14883 14884 TPMS_KEYEDHASH_PARMS 14885 14886 TPM_ALG_KEYEDHASH 14887 14888 sign | encrypt | neither 14889 14890 symDetail 14891 14892 TPMS_SYMCIPHER_PARMS 14893 14894 TPM_ALG_SYMCIPHER 14895 14896 a symmetric block cipher 14897 14898 rsaDetail 14899 14900 TPMS_RSA_PARMS 14901 14902 TPM_ALG_RSA 14903 14904 decrypt + sign 14905 14906 (2) 14907 14908 eccDetail 14909 14910 TPMS_ECC_PARMS 14911 14912 TPM_ALG_ECC 14913 14914 decrypt + sign 14915 14916 (2) 14917 14918 asymDetail 14919 14920 TPMS_ASYM_PARMS 14921 14922 common scheme structure 14923 for RSA and ECC keys 14924 14925 NOTES 14926 1) 14927 14928 Description column indicates which of TPMA_OBJECT.decrypt or TPMA_OBJECT.sign may be set. 14929 14930 2) 14931 14932 + indicates that both may be set but one shall be set. | indicates the optional settings. 14933 14934 Family 2.0 14935 Level 00 Revision 00.99 14936 14937 Published 14938 Copyright TCG 2006-2013 14939 14940 Page 129 14941 October 31, 2013 14942 14943 Part 2: Structures 14945 12.2.3.8 14946 14947 Trusted Platform Module Library 14948 14949 TPMT_PUBLIC_PARMS 14950 14951 This structure is used in TPM2_TestParms() to validate that a set of algorithm parameters is supported by 14952 the TPM. 14953 Table 183 Definition of TPMT_PUBLIC_PARMS Structure 14954 Parameter 14955 14956 Type 14957 14958 Description 14959 14960 type 14961 14962 TPMI_ALG_PUBLIC 14963 14964 the algorithm to be tested 14965 14966 [type]parameters 14967 14968 TPMU_PUBLIC_PARMS 14969 the algorithm details 14970 14971 12.2.4 TPMT_PUBLIC 14972 Table 184 defines the public area structure. The Name of the object is nameAlg concatenated with the 14973 digest of this structure using nameAlg. 14974 Table 184 Definition of TPMT_PUBLIC Structure 14975 Parameter 14976 14977 Type 14978 14979 Description 14980 14981 type 14982 14983 TPMI_ALG_PUBLIC 14984 14985 algorithm associated with this object 14986 14987 nameAlg 14988 14989 +TPMI_ALG_HASH 14990 14991 algorithm used for computing the Name of the object 14992 NOTE 14993 14994 The "+" indicates that the instance of a TPMT_PUBLIC may have 14995 a "+" to indicate that the nameAlg may be TPM_ALG_NULL. 14996 14997 objectAttributes 14998 14999 TPMA_OBJECT 15000 15001 attributes that, along with type, determine the manipulations of this 15002 object 15003 15004 authPolicy 15005 15006 TPM2B_DIGEST 15007 15008 optional policy for using this key 15009 The policy is computed using the nameAlg of the object. 15010 NOTE 15011 15012 Shall be the Empty Buffer if no authorization policy is present. 15013 15014 [type]parameters 15015 15016 TPMU_PUBLIC_PARMS 15017 15018 the algorithm or structure details 15019 15020 [type]unique 15021 15022 TPMU_PUBLIC_ID 15023 15024 Page 130 15025 October 31, 2013 15026 15027 the unique identifier of the structure 15028 For an asymmetric key, this would be the public key. 15029 15030 Published 15031 Copyright TCG 2006-2013 15032 15033 Family 2.0 15034 Level 00 Revision 00.99 15035 15036 Trusted Platform Module Library 15038 15039 Part 2: Structures 15040 15041 12.2.5 TPM2B_PUBLIC 15042 This sized buffer is used to embed a TPMT_PUBLIC in a command. 15043 Table 185 Definition of TPM2B_PUBLIC Structure 15044 Parameter 15045 15046 Type 15047 15048 Description 15049 15050 size= 15051 15052 UINT16 15053 15054 size of publicArea 15055 NOTE 15056 15057 publicArea 15058 15059 +TPMT_PUBLIC 15060 15061 The = will force the TPM to try to unmarshal a 15062 TPMT_PUBLIC and check that the unmarshaled size 15063 matches the value of size. If all the required fields of 15064 a TPMT_PUBLIC are not present, the TPM will return 15065 an error (generally TPM_RC_SIZE) when attempting 15066 to unmarshal the TPMT_PUBLIC. 15067 15068 the public area 15069 NOTE 15070 15071 The + indicates that the caller may specify that use 15072 of TPM_ALG_NULL is allowed for nameAlg. 15073 15074 12.3 Private Area Structures 15075 12.3.1 Introduction 15076 The structures in 12.3 define the contents and construction of the private portion of a TPM object. A 15077 TPM2B_PRIVATE along with a TPM2B_PUBLIC are needed to describe a TPM object. 15078 A TPM2B_PRIVATE area may be encrypted by different symmetric algorithms or, in some cases, not 15079 encrypted at all. 15080 12.3.2 Sensitive Data Structures 15081 12.3.2.1 15082 15083 Introduction 15084 15085 The structures in 12.3.2 define the presumptive internal representations of the sensitive areas of the 15086 various entities. A TPM may store the sensitive information in any desired format but when constructing a 15087 TPM_PRIVATE, the formats in this clause shall be used. 15088 12.3.2.2 15089 15090 TPM2B_PRIVATE_VENDOR_SPECIFIC 15091 15092 This structure is defined for coding purposes. For IO to the TPM, the sensitive portion of the key will be in 15093 a canonical form. For an RSA key, this will be one of the prime factors of the public modulus. After 15094 loading, it is typical that other values will be computed so that computations using the private key will not 15095 need to start with just one prime factor. This structure allows the vendor-specific structure to use the 15096 space of the 15097 The value for RSA_VENDOR_SPECIFIC is determined by the vendor. 15098 Table 186 Definition of {RSA} TPM2B_PRIVATE_VENDOR_SPECIFIC Structure<> 15099 Parameter 15100 15101 Type 15102 15103 size 15104 15105 UINT16 15106 15107 buffer[size]{:PRIVATE_VENDOR_SPECIFIC_BYTES} 15108 15109 BYTE 15110 15111 Family 2.0 15112 Level 00 Revision 00.99 15113 15114 Published 15115 Copyright TCG 2006-2013 15116 15117 Description 15118 15119 Page 131 15120 October 31, 2013 15121 15122 Part 2: Structures 15124 12.3.2.3 15125 15126 Trusted Platform Module Library 15127 15128 TPMU_SENSITIVE_COMPOSITE 15129 Table 187 Definition of TPMU_SENSITIVE_COMPOSITE Union <IN/OUT, S> 15130 15131 Parameter 15132 15133 Type 15134 15135 Selector 15136 15137 Description 15138 15139 rsa 15140 15141 TPM2B_PRIVATE_KEY_RSA 15142 15143 TPM_ALG_RSA 15144 15145 a prime factor of the public 15146 key 15147 15148 ecc 15149 15150 TPM2B_ECC_PARAMETER 15151 15152 TPM_ALG_ECC 15153 15154 the integer private key 15155 15156 bits 15157 15158 TPM2B_SENSITIVE_DATA 15159 15160 TPM_ALG_KEYEDHASH 15161 15162 the private data 15163 15164 sym 15165 15166 TPM2B_SYM_KEY 15167 15168 TPM_ALG_SYMCIPHER 15169 15170 the symmetric key 15171 15172 any 15173 15174 TPM2B_PRIVATE_VENDOR_SPECIFIC 15175 15176 12.3.2.4 15177 15178 vendor-specific size for key 15179 storage 15180 15181 TPMT_SENSITIVE 15182 Table 188 Definition of TPMT_SENSITIVE Structure 15183 15184 Parameter 15185 15186 Type 15187 15188 Description 15189 15190 sensitiveType 15191 15192 TPMI_ALG_PUBLIC 15193 15194 identifier for the sensitive area 15195 This shall be the same as the type parameter of the 15196 associated public area. 15197 15198 authValue 15199 15200 TPM2B_AUTH 15201 15202 user authorization data 15203 The authValue may be a zero-length string. 15204 This value shall not be larger than the size of the 15205 digest produced by the nameAlg of the object. 15206 15207 seedValue 15208 15209 TPM2B_DIGEST 15210 15211 for asymmetric key object, the optional protection 15212 seed; for other objects, the obfuscation value 15213 This value shall not be larger than the size of the 15214 digest produced by nameAlg of the object. 15215 15216 [sensitiveType]sensitive 15217 15218 TPMU_SENSITIVE_COMPOSITE 15219 15220 the type-specific private data 15221 15222 12.3.3 TPM2B_SENSITIVE 15223 The TPM2B_SENSITIVE structure is used as a parameter in TPM2_LoadExternal(). It is an unencrypted 15224 sensitive area but it may be encrypted using parameter encryption. 15225 NOTE 15226 15227 When this structure is unmarshaled, the size of the sensitiveType determines what type of value is 15228 unmarshaled. Each value of sensitiveType is associated with a TPM2B. It is the maximum size for each of 15229 the TPM2B values will determine if the unmarshal operation is successful . Since there is no selector for 15230 the any or vendor options for the union, the maximum input and output sizes for a TMP2B_SENSITIVE 15231 are not affected by the sizes of those parameters. 15232 15233 Table 189 Definition of TPM2B_SENSITIVE Structure <IN/OUT> 15234 Parameter 15235 15236 Type 15237 15238 Description 15239 15240 size 15241 15242 UINT16 15243 15244 size of the private structure 15245 15246 sensitiveArea 15247 15248 TPMT_SENSITIVE 15249 15250 an unencrypted sensitive area 15251 15252 Page 132 15253 October 31, 2013 15254 15255 Published 15256 Copyright TCG 2006-2013 15257 15258 Family 2.0 15259 Level 00 Revision 00.99 15260 15261 Trusted Platform Module Library 15263 15264 Part 2: Structures 15265 15266 12.3.4 Encryption 15267 A TPMS_SENSITIVE is the input to the encryption process. All TPMS_ENCRYPT structures are CFBencrypted using a key and Initialization Vector (IV) that are derived from a seed value. 15268 The method of generating the key and IV is described in Protected Storage subclause Symmetric 15269 Encryption. in Part 1. 15270 12.3.5 Integrity 15271 The integrity computation is used to ensure that a protected object is modified when stored in memory 15272 outside of the TPM. 15273 The method of protecting the integrity of the sensitive area is described in Protected Storage subclause 15274 Integrity in Part 1. 15275 12.3.6 _PRIVATE 15276 This structure is defined to size the contents of a TPM2B_PRIVATE. This structure is not directly 15277 marshaled or unmarshaled. 15278 For TPM2_Duplicate() and TPM2_Import(), the TPM2B_PRIVATE may contain multiply encrypted data 15279 and two integrity values. In some cases, the sensitive data is not encrypted and the integrity value is not 15280 present. 15281 For TPM2_Load() and TPM2_Create(), integrityInner is always present. 15282 If integrityInner is present, it and sensitive are encrypted as a single block. 15283 When an integrity value is not needed, it is not present and it is not represented by an Empty Buffer. 15284 Table 190 Definition of _PRIVATE Structure <> 15285 Parameter 15286 15287 Type 15288 15289 Description 15290 15291 integrityOuter 15292 15293 TPM2B_DIGEST 15294 15295 integrityInner 15296 15297 TPM2B_DIGEST 15298 15299 could also be a TPM2B_IV 15300 15301 sensitive 15302 15303 TPMT_SENSITIVE 15304 15305 the sensitive area 15306 15307 12.3.7 TPM2B_PRIVATE 15308 The TPM2B_PRIVATE structure is used as a parameter in multiple commands that create, load, and 15309 modify the sensitive area of an object. 15310 Table 191 Definition of TPM2B_PRIVATE Structure <IN/OUT, S> 15311 Parameter 15312 15313 Type 15314 15315 Description 15316 15317 size 15318 15319 UINT16 15320 15321 size of the private structure 15322 15323 buffer[size] {:sizeof(_PRIVATE)} 15324 15325 BYTE 15326 15327 an encrypted private area 15328 15329 Family 2.0 15330 Level 00 Revision 00.99 15331 15332 Published 15333 Copyright TCG 2006-2013 15334 15335 Page 133 15336 October 31, 2013 15337 15338 Part 2: Structures 15340 15341 Trusted Platform Module Library 15342 15343 12.4 Identity Object 15344 12.4.1 Description 15345 An identity object is used to convey credential protection value (CV) to a TPM that can load the object 15346 associated with the object. The CV is encrypted to a storage key on the target TPM, and if the credential 15347 integrity checks and the proper object is loaded in the TPM, then the TPM will return the CV. 15348 12.4.2 _ID_OBJECT 15349 This structure is used for sizing the TPM2_ID_OBJECT. 15350 Table 192 Definition of _ID_OBJECT Structure <> 15351 Parameter 15352 15353 Type 15354 15355 Description 15356 15357 integrityHMAC 15358 15359 TPM2B_DIGEST 15360 15361 encIdentity 15362 15363 TPM2B_DIGEST 15364 15365 credential protector information returned if name matches the 15366 referenced object 15367 All of the encIdentity is encrypted, including the size field. 15368 NOTE 15369 15370 The TPM is not required to check that the size is not larger 15371 than the digest of the nameAlg. However, if the size is 15372 larger, the ID object may not be usable on a TPM that has 15373 no digest larger than produced by nameAlg. 15374 15375 12.4.3 TPM2B_ID_OBJECT 15376 This structure is an output from TPM2_MakeCredential() and is an input to TPM2_ActivateCredential(). 15377 Table 193 Definition of TPM2B_ID_OBJECT Structure <IN/OUT> 15378 Parameter 15379 15380 Type 15381 15382 Description 15383 15384 size 15385 15386 UINT16 15387 15388 size of the credential structure 15389 15390 credential[size]{:sizeof(_ID_OBJECT)} 15391 15392 BYTE 15393 15394 an encrypted credential area 15395 15396 Page 134 15397 October 31, 2013 15398 15399 Published 15400 Copyright TCG 2006-2013 15401 15402 Family 2.0 15403 Level 00 Revision 00.99 15404 15405 Trusted Platform Module Library 15407 15408 Part 2: Structures 15409 15410 13 NV Storage Structures 15411 13.1 TPM_NV_INDEX 15412 A TPM_NV_INDEX is used to reference a defined location in NV memory. The format of the Index is 15413 changed from TPM 1.2 in order to include the Index in the reserved handle space. Handles in this range 15414 use the digest of the public area of the Index as the Name of the entity in authorization computations 15415 The 32-bit TPM 1.2 NV Index format is shown in Figure 4. In order to allow the Index to fit into the 24 bits 15416 available in the reserved handle space, the Index value format is changed as shown in Figure 5. 15417 3 3 2 2 2 2 2 2 2 15418 1 0 9 8 7 6 5 4 3 15419 15420 1 1 15421 6 5 15422 15423 T P U D reserved 15424 15425 0 15426 0 15427 15428 Purview 15429 15430 Index 15431 15432 Figure 4 TPM 1.2 TPM_NV_INDEX 15433 3 15434 1 15435 15436 2 2 15437 4 3 15438 15439 0 15440 0 15441 15442 TPM_HT_NV_INDEX 15443 15444 Index 15445 15446 Figure 5 TPM 2.0 TPM_NV_INDEX 15447 NOTE 15448 15449 This TPM_NV_INDEX format does not retain the Purview field and the D bit is not a part of an Index 15450 handle as in TPM 1.2. The TPMA_NV_PLATFORMCREATE attribute is a property of an Index that 15451 provides functionality similar to the D bit. 15452 15453 A valid Index handle will have an MSO of TPM_HT_NV_INDEX. 15454 NOTE 15455 15456 This structure is not used. It is defined here to indicate how the fields of the handle are assigned. The 15457 exemplary unmarshaling code unmarshals a TPM_HANDLE and validates that it is in the range for a 15458 TPM_NV_INDEX. 15459 15460 Table 194 Definition of (UINT32) TPM_NV_INDEX Bits <> 15461 Bit 15462 15463 Name 15464 15465 Definition 15466 15467 23:0 15468 15469 index 15470 15471 The index of the NV location 15472 15473 31:24 15474 15475 RH_NV 15476 15477 constant value of TPM_HT_NV_INDEX indicating the NV Index range 15478 15479 #TPM_RC_VALUE 15480 15481 response code returned if unmarshaling of this type fails because the handle 15482 value is incorrect 15483 15484 Family 2.0 15485 Level 00 Revision 00.99 15486 15487 Published 15488 Copyright TCG 2006-2013 15489 15490 Page 135 15491 October 31, 2013 15492 15493 Part 2: Structures 15495 15496 Trusted Platform Module Library 15497 Table 195 Options for space Field of TPM_NV_INDEX 15498 15499 Some prior versions of this specification contained a table here that assigned subsets of the index field to 15500 different entities. Since this assignment was a convention and not an architectural element of the TPM, 15501 the table was removed and the information is now contained in a registry document that is maintained by 15502 the TCG. 15503 13.2 TPMA_NV (NV Index Attributes) 15504 This structure allows the TPM to keep track of the data and permissions to manipulate an NV Index. 15505 The platform controls (TPMA_NV_PPWRITE and TPMA_NV_PPREAD) and owner controls 15506 (TPMA_NV_OWNERWRITE and TPMA_NV_OWNERREAD) give the platform and owner access to NV 15507 Indexes using platformAuth or ownerAuth rather than the authValue or authPolicy of the Index. 15508 If access to an NV Index is to be restricted based on PCR, then an appropriate authPolicy shall be 15509 provided. 15510 NOTE 15511 15512 platformAuth or ownerAuth can be provided in any type of authorization session or as a password. 15513 15514 If TPMA_NV_AUTHREAD is SET, then the Index may be read if the Index authValue is provided. If 15515 TPMA_NV_POLICYREAD is SET, then the Index may be read if the Index authPolicy is satisfied. 15516 At least one of TPMA_NV_PPREAD, 15517 TPMA_NV_POLICYREAD shall be SET. 15518 15519 TPMA_NV_OWNERREAD, 15520 15521 TPMA_NV_AUTHREAD, 15522 15523 or 15524 15525 If TPMA_NV_AUTHWRITE is SET, then the Index may be written if the Index authValue is provided. If 15526 TPMA_NV_POLICYWRITE is SET, then the Index may be written if the Index authPolicy is satisfied. 15527 At least one of TPMA_NV_PPWRITE, TPMA_NV_OWNERWRITE TPMA_NV_AUTHWRITE, or 15528 TPMA_NV_POLICYWRITE shall be SET. 15529 If TPMA_NV_WRITELOCKED is SET, then the Index may not be written. If TPMA_NV_WRITEDEFINE is 15530 SET, TPMA_NV_WRITELOCKED may not be CLEAR except by deleting and redefining the Index. If 15531 TPMA_NV_WRITEDEFINE is CLEAR, then TPMA_NV_WRITELOCK will be CLEAR on the next 15532 TPM2_Startup(TPM_SU_CLEAR). 15533 If TPMA_NV_READLOCKED is SET, then the Index may not be read. TPMA_NV_READLOCK will be 15534 CLEAR on the next TPM2_Startup(TPM_SU_CLEAR). 15535 NOTE 15536 15537 The TPM is expected to maintain indicators to indicate that the Index is temporarily locked. The state of 15538 these indicators is reported in the TPMA_NV_READLOCKED and TPMA_NV_WRITELOCKED attributes. 15539 15540 If TPMA_NV_EXTEND is SET, then writes to the Index will cause an update of the Index using the extend 15541 operation with the nameAlg used to create the digest. 15542 Only one of TPMA_NV_EXTEND, TPMA_NV_COUNTER, or TPMA_NV_BITS may be set. 15543 When 15544 the 15545 Index 15546 is 15547 created 15548 (TPM2_NV_DefineSpace()), 15549 TPMA_NV_WRITELOCKED, 15550 TPMA_NV_READLOCKED, TPMA_NV_WRITTEN shall all be CLEAR in the parameter that defines the 15551 attributes of the created Index. 15552 15553 Page 136 15554 October 31, 2013 15555 15556 Published 15557 Copyright TCG 2006-2013 15558 15559 Family 2.0 15560 Level 00 Revision 00.99 15561 15562 Trusted Platform Module Library 15564 15565 Part 2: Structures 15566 15567 Table 196 Definition of (UINT32) TPMA_NV Bits 15568 Bit 15569 15570 Name 15571 15572 Description 15573 15574 0 15575 15576 TPMA_NV_PPWRITE 15577 15578 SET (1): The Index data can be written if platformAuth is provided. 15579 CLEAR (0): Writing of the Index data cannot be authorized with 15580 platformAuth. 15581 15582 1 15583 15584 TPMA_NV_OWNERWRITE 15585 15586 SET (1): The Index data can be written if ownerAuth is provided. 15587 CLEAR (0): Writing of the Index data cannot be authorized with 15588 ownerAuth. 15589 15590 2 15591 15592 TPMA_NV_AUTHWRITE 15593 15594 SET (1): Authorizations to change the Index contents that require 15595 USER role may be provided with an HMAC session or password. 15596 CLEAR (0): Authorizations to change the Index contents that require 15597 USER role may not be provided with an HMAC session or password. 15598 15599 3 15600 15601 TPMA_NV_POLICYWRITE 15602 15603 SET (1): Authorizations to change the Index contents that require 15604 USER role may be provided with a policy session. 15605 CLEAR (0): Authorizations to change the Index contents that require 15606 USER role may not be provided with a policy session. 15607 NOTE 15608 15609 TPM2_NV_ChangeAuth() always requires that authorization be 15610 provided in a policy session. 15611 15612 4 15613 15614 TPMA_NV_COUNTER 15615 15616 SET (1): Index contains an 8-octet value that is to be used as a 15617 counter and can only be modified with TPM2_NV_Increment(). 15618 CLEAR (0): The Index is not a counter. 15619 15620 5 15621 15622 TPMA_NV_BITS 15623 15624 SET (1): Index contains an 8-octet value to be used as a bit field and 15625 can only be modified with TPM2_NV_SetBits(). 15626 CLEAR (0): The Index is not a bit field. 15627 15628 6 15629 15630 TPMA_NV_EXTEND 15631 15632 SET (1): Index contains a digest-sized value used like a PCR. The 15633 Index may only be modified using TPM2_NV_Extend. The extend will 15634 use the nameAlg of the Index. 15635 CLEAR (0): Index is not a PCR. 15636 15637 9:7 15638 15639 Reserved 15640 15641 shall be zero 15642 reserved for use in defining additional write controls 15643 15644 10 15645 15646 TPMA_NV_POLICY_DELETE 15647 15648 SET (1): Index may not be deleted unless the authPolicy is satisfied. 15649 CLEAR (0): Index may be deleted with proper platform or owner 15650 authorization. 15651 15652 11 15653 15654 TPMA_NV_WRITELOCKED 15655 15656 SET (1): Index cannot be written. 15657 CLEAR (0): Index can be written. 15658 15659 12 15660 15661 TPMA_NV_WRITEALL 15662 15663 SET (1): A partial write of the Index data is not allowed. The write 15664 size shall match the defined space size. 15665 CLEAR (0): Partial writes are allowed. This setting is required if 15666 TPMA_NV_BITS is SET. 15667 15668 13 15669 15670 TPMA_NV_WRITEDEFINE 15671 15672 SET (1): TPM2_NV_WriteLock() may be used to prevent further 15673 writes to this location. 15674 CLEAR (0): TPM2_NV_WriteLock() does not block subsequent 15675 writes. 15676 15677 14 15678 15679 TPMA_NV_WRITE_STCLEAR 15680 15681 SET (1): TPM2_NV_WriteLock() may be used to prevent further 15682 writes to this location until the next TPM Reset or TPM Restart. 15683 CLEAR (0): A write to this Index with a data size of zero does not 15684 change the write access. 15685 15686 Family 2.0 15687 Level 00 Revision 00.99 15688 15689 Published 15690 Copyright TCG 2006-2013 15691 15692 Page 137 15693 October 31, 2013 15694 15695 Part 2: Structures 15697 15698 Trusted Platform Module Library 15699 15700 Bit 15701 15702 Name 15703 15704 Description 15705 15706 15 15707 15708 TPMA_NV_GLOBALLOCK 15709 15710 SET (1): If TPM2_NV_GlobalWriteLock() is successful, then further 15711 writes to this location are not permitted until the next TPM Reset or 15712 TPM Restart. 15713 CLEAR (0): TPM2_NV_GlobalWriteLock() has no effect on the 15714 writing of the data at this Index. 15715 15716 16 15717 15718 TPMA_NV_PPREAD 15719 15720 SET (1): The Index data can be read if platformAuth is provided. 15721 CLEAR (0): Reading of the Index data cannot be authorized with 15722 platformAuth. 15723 15724 17 15725 15726 TPMA_NV_OWNERREAD 15727 15728 SET (1): The Index data can be read if ownerAuth is provided. 15729 CLEAR (0): Reading of the Index data cannot be authorized with 15730 ownerAuth. 15731 15732 18 15733 15734 TPMA_NV_AUTHREAD 15735 15736 SET (1): The Index data may be read if the authValue is provided. 15737 CLEAR (0): Reading of the Index data cannot be authorized with the 15738 Index authValue. 15739 15740 19 15741 15742 TPMA_NV_POLICYREAD 15743 15744 SET (1): The Index data may be read if the authPolicy is satisfied. 15745 CLEAR (0): Reading of the Index data cannot be authorized with the 15746 Index authPolicy. 15747 15748 Reserved 15749 15750 shall be zero 15751 reserved for use in defining additional read controls 15752 15753 25 15754 15755 TPMA_NV_NO_DA 15756 15757 SET (1): Authorization failures of the Index do not affect the DA logic 15758 and authorization of the Index is not blocked when the TPM is in 15759 Lockout mode. 15760 CLEAR (0): Authorization failures of the Index will increment the 15761 authorization failure counter and authorizations of this Index are not 15762 allowed when the TPM is in Lockout mode. 15763 15764 26 15765 15766 TPMA_NV_ORDERLY 15767 15768 SET (1): NV Index state is only required to be saved when the TPM 15769 performs an orderly shutdown (TPM2_Shutdown()). Only an Index 15770 with TPMA_NV_COUNTER SET may have this setting. 15771 CLEAR (0): NV Index state is required to be persistent after the 15772 command to update the Index completes successfully (that is, the NV 15773 update is synchronous with the update command). 15774 15775 27 15776 15777 TPMA_NV_CLEAR_STCLEAR 15778 15779 SET (1): TPMA_NV_WRITTEN for the Index is CLEAR by TPM 15780 Reset or TPM Restart. 15781 CLEAR (0): TPMA_NV_WRITTEN is not changed by TPM Restart. 15782 15783 24:20 15784 15785 NOTE 15786 15787 This attribute may only be SET if TPMA_NV_COUNTER is not 15788 SET. 15789 15790 NOTE 15791 15792 If the TPMA_NV_ORDERLY is SET, TPMA_NV_WRITTEN will 15793 be CLEAR by TPM Reset. 15794 15795 28 15796 15797 TPMA_NV_READLOCKED 15798 15799 SET (1): Reads of the Index are blocked until the next TPM Reset or 15800 TPM Restart. 15801 CLEAR (0): Reads of the Index are allowed if proper authorization is 15802 provided. 15803 15804 29 15805 15806 TPMA_NV_WRITTEN 15807 15808 SET (1): Index has been written. 15809 CLEAR (0): Index has not been written. 15810 15811 30 15812 15813 TPMA_NV_PLATFORMCREATE 15814 15815 SET (1): This Index may be undefined with platformAuth but not with 15816 ownerAuth. 15817 CLEAR (0): This Index may be undefined using ownerAuth but not 15818 with platformAuth. 15819 The TPM will validate that this attribute is SET when the Index is 15820 defined using platformAuth and will validate that this attribute is 15821 CLEAR when the Index is defined using ownerAuth. 15822 15823 Page 138 15824 October 31, 2013 15825 15826 Published 15827 Copyright TCG 2006-2013 15828 15829 Family 2.0 15830 Level 00 Revision 00.99 15831 15832 Trusted Platform Module Library 15834 15835 Part 2: Structures 15836 15837 Bit 15838 15839 Name 15840 15841 Description 15842 15843 31 15844 15845 TPMA_NV_READ_STCLEAR 15846 15847 SET (1): TPM2_NV_ReadLock() may be used to SET 15848 TPMA_NV_READLOCKED for this Index. 15849 CLEAR (0): TPM2_NV_ReadLock() has no effect on this Index. 15850 15851 13.3 TPMS_NV_PUBLIC 15852 This structure describes an NV Index. 15853 Table 197 Definition of TPMS_NV_PUBLIC Structure 15854 Name 15855 15856 Type 15857 15858 Description 15859 15860 nvIndex 15861 15862 TPMI_RH_NV_INDEX 15863 15864 the handle of the data area 15865 15866 nameAlg 15867 15868 TPMI_ALG_HASH 15869 15870 hash algorithm used to compute the name of the 15871 Index and used for the authPolicy 15872 15873 attributes 15874 15875 TPMA_NV 15876 15877 the Index attributes 15878 15879 authPolicy 15880 15881 TPM2B_DIGEST 15882 15883 the access policy for the Index 15884 15885 dataSize{:MAX_NV_INDEX_SIZE} 15886 15887 UINT16 15888 15889 the size of the data area 15890 The 15891 maximum 15892 size is implementationdependent. The minimum maximum size is 15893 platform-specific. 15894 15895 #TPM_RC_SIZE 15896 15897 response code returned when the requested size 15898 is too large for the implementation 15899 15900 13.4 TPM2B_NV_PUBLIC 15901 This structure is used when a TPMS_NV_PUBLIC is sent on the TPM interface. 15902 Table 198 Definition of TPM2B_NV_PUBLIC Structure 15903 Name 15904 15905 Type 15906 15907 Description 15908 15909 size= 15910 15911 UINT16 15912 15913 size of nvPublic 15914 15915 nvPublic 15916 15917 TPMS_NV_PUBLIC 15918 15919 the public area 15920 15921 Family 2.0 15922 Level 00 Revision 00.99 15923 15924 Published 15925 Copyright TCG 2006-2013 15926 15927 Page 139 15928 October 31, 2013 15929 15930 Part 2: Structures 15932 15933 Trusted Platform Module Library 15934 15935 14 Context Data 15936 14.1 Introduction 15937 This clause defines the contents of the 15938 TPM2_ContextLoad() command parameters. 15939 15940 TPM2_ContextSave() 15941 15942 response 15943 15944 parameters 15945 15946 and 15947 15948 If the parameters provided by the caller in TPM2_ContextLoad() do not match the values returned by the 15949 TPM when the context was saved, the integrity check of the TPM2B_CONTEXT will fail and the object or 15950 session will not be loaded. 15951 14.2 TPM2B_CONTEXT_SENSITIVE 15952 This structure holds the object or session context data. When saved, the full structure is encrypted. 15953 Table 199 Definition of TPM2B_CONTEXT_SENSITIVE Structure <IN/OUT> 15954 Parameter 15955 15956 Type 15957 15958 size 15959 15960 Description 15961 15962 UINT16 15963 15964 buffer[size]{:MAX_CONTEXT_SIZE} 15965 BYTE 15966 15967 the sensitive data 15968 15969 14.3 TPMS_CONTEXT_DATA 15970 This structure holds the integrity value and the encrypted data for a context. 15971 Table 200 Definition of TPMS_CONTEXT_DATA Structure <IN/OUT, S> 15972 Parameter 15973 15974 Type 15975 15976 Description 15977 15978 integrity 15979 15980 TPM2B_DIGEST 15981 15982 the integrity value 15983 15984 encrypted 15985 15986 TPM2B_CONTEXT_SENSITIVE 15987 15988 the sensitive area 15989 15990 14.4 TPM2B_CONTEXT_DATA 15991 This structure is used in a TPMS_CONTEXT. 15992 Table 201 Definition of TPM2B_CONTEXT_DATA Structure <IN/OUT> 15993 Parameter 15994 15995 Type 15996 15997 size 15998 15999 Description 16000 16001 UINT16 16002 16003 buffer[size] {:sizeof(TPMS_CONTEXT_DATA)} 16004 BYTE 16005 16006 Page 140 16007 October 31, 2013 16008 16009 Published 16010 Copyright TCG 2006-2013 16011 16012 Family 2.0 16013 Level 00 Revision 00.99 16014 16015 Trusted Platform Module Library 16017 16018 Part 2: Structures 16019 16020 14.5 TPMS_CONTEXT 16021 This structure is used in TPM2_ContextLoad() and TPM2_ContextSave(). If the values of the 16022 TPMS_CONTEXT structure in TPM2_ContextLoad() are not the same as the values when the context 16023 was saved (TPM2_ContextSave()), then the TPM shall not load the context. 16024 Saved object contexts shall not be loaded as long as the associated hierarchy is disabled. 16025 Saved object contexts are invalidated when the Primary Seed of their hierarchy changes. Objects in the 16026 Endorsement hierarchy are invalidated when either the EPS or SPS is changed. 16027 When an object has the stClear attribute, it shall not be possible to reload the context or any descendant 16028 object after a TPM Reset or TPM Restart. 16029 NOTE 1 16030 16031 The reference implementation prevents reloads after TPM Restart by including the curre nt value of a 16032 clearCount in the saved object context. When an object is loaded, this value is compared with the current 16033 value of the clearCount if the object has the stClear attribute. If the values are not the same, then the 16034 object cannot be loaded. 16035 16036 A sequence value is contained within the integrity-protected part of the saved context. The sequence 16037 value is repeated in the sequence parameter of the TPMS_CONTEXT of the context. The sequence 16038 parameter, along with other values, is used in the generation the protection values of the context. 16039 If the integrity value of the context is valid, but the sequence value of the decrypted context does not 16040 match the value in the sequence parameter, then TPM shall enter the failure mode because this is 16041 indicative of a specific type of attack on the context values. 16042 NOTE 2 16043 16044 If the integrity value is correct, but the decryption fails and produces the wrong value for sequence, this 16045 implies that either the TPM is faulty or an external entity is able to forge an integrity val ue for the context 16046 but they have insufficient information to know what the encryption key of the context. Since the TPM 16047 generated the valid context, then there is no reason for the sequence value in the context to be decrypted 16048 incorrectly other than the TPM is faulty or the TPM is under attack. In either case, it is appropriate for the 16049 TPM to enter failure more. 16050 16051 Table 202 Definition of TPMS_CONTEXT Structure 16052 Name 16053 16054 Type 16055 16056 Description 16057 16058 sequence 16059 16060 UINT64 16061 16062 the sequence number of the context 16063 NOTE 16064 16065 Transient object contexts and 16066 contexts used different counters. 16067 16068 session 16069 16070 savedHandle 16071 16072 TPMI_DH_CONTEXT 16073 16074 the handle of the session, object or sequence 16075 16076 hierarchy 16077 16078 TPMI_RH_HIERARCHY+ 16079 16080 the hierarchy of the context 16081 16082 contextBlob 16083 16084 TPM2B_CONTEXT_DATA 16085 16086 the context data and integrity HMAC 16087 16088 Family 2.0 16089 Level 00 Revision 00.99 16090 16091 Published 16092 Copyright TCG 2006-2013 16093 16094 Page 141 16095 October 31, 2013 16096 16097 Part 2: Structures 16099 16100 Trusted Platform Module Library 16101 16102 14.6 Parameters of TPMS_CONTEXT 16103 14.6.1 sequence 16104 The sequence parameter is used to differentiate the contexts and to allow the TPM to create a different 16105 encryption key for each context. Objects and sessions use different sequence counters. The sequence 16106 counter for objects (transient and sequence) is incremented when an object context is saved, and the 16107 sequence counter for sessions increments when a session is created or when it is loaded 16108 (TPM2_ContextLoad()). The session sequence number is the contextID counter. 16109 For a session, the sequence number also allows the TRM to find the older contexts so that they may be 16110 refreshed if the contextID are too widely separated. 16111 If an input value for sequence is larger than the value used in any saved context, the TPM shall return an 16112 error (TPM_RC_VALUE) and do no additional processing of the context. 16113 If the context is a session context and the input value for sequence is less than the current value of 16114 contextID minus the maximum range for sessions, the TPM shall return an error (TPM_RC_VALUE) and 16115 do no additional processing of the context. 16116 14.6.2 savedHandle 16117 For a session, this is the handle that was assigned to the session when it was saved. For a transient 16118 object, the handle will have one of the values shown in Table 203. 16119 If the handle type for savedHandle is TPM_HT_TRANSIENT, then the low order bits are used to 16120 differentiate static objects from sequence objects. 16121 If an input value for handle is outside of the range of values used by the TPM, the TPM shall return an 16122 error (TPM_RC_VALUE) and do no additional processing of the context. 16123 Table 203 Context Handle Values 16124 Value 16125 16126 Description 16127 16128 0x02xxxxxx 16129 16130 an HMAC session context 16131 16132 0x03xxxxxx 16133 16134 a policy session context 16135 16136 0x80000000 16137 16138 an ordinary transient object 16139 16140 0x80000001 16141 16142 a sequence object 16143 16144 0x80000002 16145 16146 a transient object with the stClear attribute SET 16147 16148 Page 142 16149 October 31, 2013 16150 16151 Published 16152 Copyright TCG 2006-2013 16153 16154 Family 2.0 16155 Level 00 Revision 00.99 16156 16157 Trusted Platform Module Library 16159 16160 Part 2: Structures 16161 16162 14.6.3 hierarchy 16163 This is the hierarchy (TPMI_RH_HIERARCHY) for the saved context and determines the proof value used 16164 in the construction of the encryption and integrity values for the context. For session and sequence 16165 contexts, the hierarchy is TPM_RC_NULL. The hierarchy for a transient object may be TPM_RH_NULL 16166 but it is not required. 16167 14.7 Context Protection 16168 14.7.1 Context Integrity 16169 The integrity of the context blob is protected by an HMAC. The integrity value is constructed such that 16170 changes to the component values will invalidate the context and prevent it from being loaded. 16171 Previously saved contexts for objects in the Platform hierarchy shall not be loadable after the PPS is 16172 changed. 16173 Previously saved contexts for objects in the Storage hierarchy shall not be loadable after the SPS is 16174 changed. 16175 Previously saved contexts for objects in the Endorsement hierarchy shall not be loadable after either the 16176 EPS or SPS is changed. 16177 Previously saved sessions shall not be loadable after the SPS changes. 16178 Previously saved contexts for objects that have their stClear attribute SET shall not be loadable after a 16179 TPM Restart. If a Storage Key has its stClear attribute SET, the descendants of this key shall not be 16180 loadable after TPM Restart. 16181 Previously saved contexts for a session and objects shall not be loadable after a TPM Reset. 16182 A saved context shall not be loaded if its HMAC is not valid. The equation for computing the HMAC for a 16183 context is found in Context Integrity Protection in Part 1. 16184 14.7.2 Context Confidentiality 16185 The context data of sessions and objects shall be protected by symmetric encryption using CFB. The 16186 method for computing the IV and encryption key is found in Context Confidentiality Protection in Part 1. 16187 16188 Family 2.0 16189 Level 00 Revision 00.99 16190 16191 Published 16192 Copyright TCG 2006-2013 16193 16194 Page 143 16195 October 31, 2013 16196 16197 Part 2: Structures 16199 16200 Trusted Platform Module Library 16201 16202 15 Creation Data 16203 15.1 TPMS_CREATION_DATA 16204 This structure provides information relating to the creation environment for the object. The creation data 16205 includes the parent Name, parent Qualified Name, and the digest of selected PCR. These values 16206 represent the environment in which the object was created. Creation data allows a relying party to 16207 determine if an object was created when some appropriate protections were present. 16208 When the object is created, the structure shown in Table 204 is generated and a ticket is computed over 16209 this data. 16210 If 16211 the 16212 parent 16213 is 16214 a 16215 permanent 16216 handle 16217 (TPM_RH_OWNER, 16218 TPM_RH_PLATFORM, 16219 TPM_RH_ENDORSEMENT, or TPM_RH_NULL), then parentName and parentQualifiedName will be set 16220 to the parent handle value and parentNameAlg will be TPM_ALG_NULL. 16221 Table 204 Definition of TPMS_CREATION_DATA Structure <OUT> 16222 Parameter 16223 16224 Type 16225 16226 Description 16227 16228 pcrSelect 16229 16230 TPML_PCR_SELECTION 16231 16232 list indicating the PCR included in pcrDigest 16233 16234 pcrDigest 16235 16236 TPM2B_DIGEST 16237 16238 digest of the selected PCR using nameAlg of the object for 16239 which this structure is being created 16240 pcrDigest.size shall be zero if the pcrSelect list is empty. 16241 16242 locality 16243 16244 TPMA_LOCALITY 16245 16246 the locality at which the object was created 16247 16248 parentNameAlg 16249 16250 TPM_ALG_ID 16251 16252 nameAlg of the parent 16253 16254 parentName 16255 16256 TPM2B_NAME 16257 16258 Name of the parent at time of creation 16259 The size will match digest size associated with parentNameAlg 16260 unless it is TPM_ALG_NULL, in which case the size will be 4 16261 and parentName will be the hierarchy handle. 16262 16263 parentQualifiedName 16264 16265 TPM2B_NAME 16266 16267 Qualified Name of the parent at the time of creation 16268 Size is the same as parentName. 16269 16270 outsideInfo 16271 16272 TPM2B_DATA 16273 16274 association with additional information added by the key 16275 creator 16276 This will be the contents of the outsideInfo parameter in 16277 TPM2_Create() or TPM2_CreatePrimary(). 16278 16279 15.2 TPM2B_CREATION_DATA 16280 This structure is created by TPM2_Create() and TPM2_CreatePrimary(). It is never entered into the TPM 16281 and never has a size of zero. 16282 Table 205 Definition of TPM2B_CREATION_DATA Structure <OUT> 16283 Parameter 16284 16285 Type 16286 16287 Description 16288 16289 size= 16290 16291 UINT16 16292 16293 size of the creation data 16294 16295 creationData 16296 16297 TPMS_CREATION_DATA 16298 16299 1.1.1.1.1 16300 Page 144 16301 October 31, 2013 16302 16303 Published 16304 Copyright TCG 2006-2013 16305 16306 Family 2.0 16307 Level 00 Revision 00.99 16308 16309 Trusted Platform Module Library 16311 16312 Part 2: Structures 16313 16314 Annex A 16315 (informative) 16316 Algorithm Constants 16317 A.1 16318 16319 Introduction 16320 16321 This annex contains constants that are defined by algorithms. 16322 16323 A.2 16324 A.2.1 16325 16326 Allowed Hash Algorithms 16327 SHA1 16328 Table 206 Defines for SHA1 Hash Values 16329 16330 Name 16331 16332 Value 16333 16334 SHA1_DIGEST_SIZE 16335 16336 20 16337 16338 SHA1_BLOCK_SIZE 16339 16340 64 16341 16342 SHA1_DER_SIZE 16343 16344 Description 16345 16346 15 16347 16348 SHA1_DER 16349 16350 Values are in octets. 16351 16352 {0x30,0x21,0x30,0x09,0x06,0x05,0x2B,0x0E,0x03,0x02,0x1A,0x05,0x00,0x04,0x14} 16353 16354 A.2.2 16355 16356 SHA256 16357 Table 207 Defines for SHA256 Hash Values 16358 16359 Name 16360 16361 Value 16362 16363 SHA256_DIGEST_SIZE 16364 16365 32 16366 16367 SHA256_BLOCK_SIZE 16368 16369 64 16370 16371 SHA256_DER_SIZE 16372 16373 Description 16374 16375 19 16376 16377 SHA256_DER 16378 16379 16380 Values are in octets. 16381 16382 {0x30,0x31,0x30,0x0d,0x06,0x09,0x60,0x86,0x48,0x01,0x65,0x03,0x04,0x02,0x01,0x05,0x00,0x04,0x20} 16383 16384 A.2.3 16385 SHA384 16386 Table 208 Defines for SHA384 Hash Values 16387 16388 Name 16389 16390 Value 16391 16392 SHA384_DIGEST_SIZE 16393 16394 48 16395 16396 SHA384_BLOCK_SIZE 16397 16398 128 16399 16400 SHA384_DER_SIZE 16401 16402 Description 16403 16404 19 16405 16406 SHA384_DER 16407 16408 Family 2.0 16409 Level 00 Revision 00.99 16410 16411 Values are in octets. 16412 16413 {0x30,0x41,0x30,0x0d,0x06,0x09,0x60,0x86,0x48,0x01,0x65,0x03,0x04,0x02,0x02,0x05,0x00,0x04,0x30} 16414 16415 Published 16416 Copyright TCG 2006-2013 16417 16418 Page 145 16419 October 31, 2013 16420 16421 Part 2: Structures 16423 A.2.4 16424 16425 Trusted Platform Module Library 16426 16427 SHA512 16428 Table 209 Defines for SHA512 Hash Values 16429 16430 Name 16431 16432 Value 16433 16434 SHA512_DIGEST_SIZE 16435 16436 64 16437 16438 SHA512_BLOCK_SIZE 16439 16440 128 16441 16442 SHA512_DER_SIZE 16443 16444 Description 16445 16446 19 16447 16448 SHA512_DER 16449 16450 16451 Values are in octets. 16452 16453 {0x30,0x51,0x30,0x0d,0x06,0x09,0x60,0x86,0x48,0x01,0x65,0x03,0x04,0x02,0x03,0x05,0x00,0x04,0x40} 16454 16455 A.2.5 16456 SM3_256 16457 Table 210 Defines for SM3_256 Hash Values 16458 16459 Name 16460 16461 Value 16462 16463 Description 16464 16465 SM3_256_DIGEST_SIZE 16466 16467 32 16468 16469 Values are in octets. 16470 16471 SM3_256_BLOCK_SIZE 16472 16473 64 16474 16475 ?? 16476 16477 SM3_256_DER_SIZE 16478 16479 18 16480 16481 SM3_256_DER 16482 16483 16484 {0x30,0x30,0x30,0x0c,0x06,0x08,0x2a,0x81,0x1c,0x81,0x45,0x01,0x83,0x11,0x05,0x00,0x04,0x20} 16485 16486 A.3 16487 Unknown 16488 16489 Architectural Limits 16490 Table 211 Defines for Architectural Limits Values 16491 16492 Name 16493 MAX_SESSION_NUMBER 16494 16495 Page 146 16496 October 31, 2013 16497 16498 Value 16499 3 16500 16501 Description 16502 the maximum number of authorization sessions that may be in a 16503 command 16504 This value may be increased if new commands require more than 16505 two authorization handles. 16506 16507 Published 16508 Copyright TCG 2006-2013 16509 16510 Family 2.0 16511 Level 00 Revision 00.99 16512 16513 Trusted Platform Module Library 16515 16516 Part 2: Structures 16517 16518 Annex B 16519 (informative) 16520 Implementation Definitions 16521 B.1 16522 16523 Introduction 16524 16525 This annex contains some of the tables that are used to define the desired implementation for the 16526 automated tools. 16527 NOTE 16528 16529 B.2 16530 16531 The reference implementation assumes that stdint.h is used. 16532 16533 Logic Values 16534 16535 The values in this clause are used to see the generation of the subsequent tables. These values should 16536 not be changed. 16537 Table 212 Defines for Logic Values 16538 Name 16539 16540 Value 16541 16542 YES 16543 16544 1 16545 16546 NO 16547 16548 0 16549 16550 TRUE 16551 16552 1 16553 16554 FALSE 16555 16556 0 16557 16558 SET 16559 16560 1 16561 16562 CLEAR 16563 16564 Description 16565 16566 0 16567 16568 B.3 16569 16570 Processor Values 16571 16572 These values are used to control generation of octet-swapping routines. The canonical octet ordering for 16573 the TPM input/output buffer is big endian with the most significant octet of any datum at the lowest 16574 address. 16575 NOTE 16576 16577 The setting for the exemplar is for the x86 family of processor. 16578 16579 Table 213 Defines for Processor Values 16580 Name 16581 16582 Value 16583 16584 Description 16585 16586 BIG_ENDIAN_TPM 16587 16588 NO 16589 16590 set to YES or NO according to the processor 16591 16592 LITTLE_ENDIAN_TPM 16593 16594 YES 16595 16596 set to YES or NO according to the processor 16597 NOTE 16598 16599 NO_AUTO_ALIGN 16600 16601 NO 16602 16603 set to YES if the processor does not allow unaligned accesses 16604 NOTE 16605 16606 Family 2.0 16607 Level 00 Revision 00.99 16608 16609 BIG_ENDIAN and LITTLE_ENDIAN shall be set to opposite values. 16610 16611 If LITTLE_ENDIAN is YES, then the setting of this value has no effect. 16612 16613 Published 16614 Copyright TCG 2006-2013 16615 16616 Page 147 16617 October 31, 2013 16618 16619 Part 2: Structures 16621 16622 B.4 16623 16624 Trusted Platform Module Library 16625 16626 Implemented Algorithms 16627 16628 Table 214 is used to indicate the algorithms that are implemented in a TPM. The selections in the Value 16629 column may be changed to reflect the implementation. The values shown are illustrative. 16630 The "Implemented" column contains a "Y", "YES", or blank to indicate that the command is present in the 16631 implementation, an "N" or "NO" to indicate that the command is not implemented. 16632 The leading and trailing _ characters are to avoid name space collisions with some crypto libraries. 16633 16634 NOTE 16635 16636 Table 214 Defines for Implemented Algorithms 16637 Algorithm Name 16638 16639 Implemented 16640 16641 RSA 16642 16643 YES 16644 16645 SHA1 16646 16647 YES 16648 16649 HMAC 16650 16651 YES 16652 16653 AES 16654 16655 YES 16656 16657 MGF1 16658 16659 YES 16660 16661 XOR 16662 16663 YES 16664 16665 KEYEDHASH 16666 16667 YES 16668 16669 SHA256 16670 16671 YES 16672 16673 SHA384 16674 16675 NO 16676 16677 SHA512 16678 16679 NO 16680 16681 SM3_256 16682 16683 YES 16684 16685 SM4 16686 16687 Comments 16688 16689 YES 16690 16691 REQUIRED, do not change this value 16692 16693 REQUIRED, do not change this value 16694 16695 RSASSA 16696 16697 (YES * RSA) 16698 16699 requires RSA 16700 16701 RSAES 16702 16703 (YES * RSA) 16704 16705 requires RSA 16706 16707 RSAPSS 16708 16709 (YES * RSA) 16710 16711 requires RSA 16712 16713 OAEP 16714 16715 (YES * RSA) 16716 16717 requires RSA 16718 16719 ECC 16720 16721 YES 16722 16723 ECDH 16724 16725 (YES * ECC) 16726 16727 requires ECC 16728 16729 ECDSA 16730 16731 (YES * ECC) 16732 16733 requires ECC 16734 16735 ECDAA 16736 16737 (YES * ECC) 16738 16739 requires ECC 16740 16741 SM2 16742 16743 (YES * ECC) 16744 16745 requires ECC 16746 16747 ECSCHNORR 16748 16749 (YES * ECC) 16750 16751 requires ECC 16752 16753 ECMQV 16754 16755 (NO * ECC) 16756 16757 requires ECC 16758 16759 SYMCIPHER 16760 KDF1_SP800_56a 16761 16762 YES 16763 16764 REQUIRED, at least one symmetric algorithm shall be implemented 16765 16766 (YES * ECC) 16767 16768 KDF2 16769 16770 NO 16771 16772 KDF1_SP800_108 16773 16774 YES 16775 16776 CTR 16777 16778 YES 16779 16780 OFB 16781 16782 YES 16783 16784 CBC 16785 16786 YES 16787 16788 CFB 16789 16790 YES 16791 16792 ECB 16793 16794 requires ECC 16795 16796 YES 16797 16798 B.5 16799 16800 REQUIRED, do not change this value 16801 16802 Implemented Commands 16803 16804 Page 148 16805 October 31, 2013 16806 16807 Published 16808 Copyright TCG 2006-2013 16809 16810 Family 2.0 16811 Level 00 Revision 00.99 16812 16813 Trusted Platform Module Library 16815 16816 Part 2: Structures 16817 16818 This table is used to indicate which of the commands are implemented. In the reference implementation, 16819 this table determines which commands can be called and drives the generation of various commanddependent switch statements. 16820 The "Implemented or Dependent" column contains a "Y", "YES", or blank to indicate that the command is 16821 present in the implementation; an "N" or "NO" to indicate that the command is not implemented; and an 16822 algorithm value if implementation of the command is dependent on a setting in Table 214. Linkage to 16823 Table 214 is not required and is provide as a convenience. 16824 To indicate that the command is implemented, only "Y", "N", blank, or a value from Table 214 is allowed. 16825 Table 215 Defines for Implemented Commands 16826 Name 16827 ActivateCredential 16828 16829 Implemented 16830 or Dependent 16831 16832 Comments 16833 16834 YES 16835 16836 Certify 16837 16838 Y 16839 16840 CertifyCreation 16841 16842 Y 16843 16844 ChangeEPS 16845 16846 Y 16847 16848 ChangePPS 16849 16850 Y 16851 16852 Clear 16853 16854 Y 16855 16856 ClearControl 16857 16858 Y 16859 16860 ClockRateAdjust 16861 16862 Y 16863 16864 ClockSet 16865 16866 Y 16867 16868 Commit 16869 16870 ECC 16871 16872 ContextLoad 16873 16874 Y 16875 16876 Context 16877 16878 ContextSave 16879 16880 Y 16881 16882 Context 16883 16884 Create 16885 16886 Y 16887 16888 CreatePrimary 16889 16890 Y 16891 16892 DictionaryAttackLockReset 16893 16894 Y 16895 16896 DictionaryAttackParameters 16897 16898 Y 16899 16900 Duplicate 16901 16902 Y 16903 16904 ECC_Parameters 16905 16906 ECC 16907 16908 ECDH_KeyGen 16909 16910 ECC 16911 16912 ECDH_ZGen 16913 16914 ECC 16915 16916 EncryptDecrypt 16917 16918 Y 16919 16920 EventSequenceComplete 16921 16922 Y 16923 16924 EvictControl 16925 16926 Y 16927 16928 FieldUpgradeData 16929 16930 N 16931 16932 FieldUpgradeStart 16933 16934 N 16935 16936 FirmwareRead 16937 16938 N 16939 16940 FlushContext 16941 16942 Y 16943 16944 GetCapability 16945 16946 Y 16947 16948 GetCommandAuditDigest 16949 16950 Y 16951 16952 GetRandom 16953 16954 Y 16955 16956 GetSessionAuditDigest 16957 16958 Y 16959 16960 Family 2.0 16961 Level 00 Revision 00.99 16962 16963 Context 16964 16965 Published 16966 Copyright TCG 2006-2013 16967 16968 Page 149 16969 October 31, 2013 16970 16971 Part 2: Structures 16973 16974 Name 16975 16976 Trusted Platform Module Library 16977 Implemented 16978 or Dependent 16979 16980 Comments 16981 16982 GetTestResult 16983 16984 Y 16985 16986 GetTime 16987 16988 Y 16989 16990 Hash 16991 16992 Y 16993 16994 HashSequenceStart 16995 16996 Y 16997 16998 HierarchyChangeAuth 16999 17000 Y 17001 17002 HierarchyControl 17003 17004 Y 17005 17006 HMAC 17007 17008 Y 17009 17010 HMAC_Start 17011 17012 Y 17013 17014 Import 17015 17016 Y 17017 17018 IncrementalSelfTest 17019 17020 Y 17021 17022 Load 17023 17024 Y 17025 17026 LoadExternal 17027 17028 Y 17029 17030 MakeCredential 17031 17032 Y 17033 17034 NV_Certify 17035 17036 Y 17037 17038 NV_ChangeAuth 17039 17040 Y 17041 17042 NV_DefineSpace 17043 17044 Y 17045 17046 NV_Extend 17047 17048 Y 17049 17050 NV_GlobalWriteLock 17051 17052 Y 17053 17054 NV_Increment 17055 17056 Y 17057 17058 NV_Read 17059 17060 Y 17061 17062 NV_ReadLock 17063 17064 Y 17065 17066 NV_ReadPublic 17067 17068 Y 17069 17070 NV_SetBits 17071 17072 Y 17073 17074 NV_UndefineSpace 17075 17076 Y 17077 17078 NV_UndefineSpaceSpecial 17079 17080 Y 17081 17082 NV_Write 17083 17084 Y 17085 17086 NV_WriteLock 17087 17088 Y 17089 17090 ObjectChangeAuth 17091 17092 Y 17093 17094 PCR_Allocate 17095 17096 Y 17097 17098 PCR_Event 17099 17100 Y 17101 17102 PCR_Extend 17103 17104 Y 17105 17106 PCR_Read 17107 17108 Y 17109 17110 PCR 17111 17112 PCR_Reset 17113 17114 Y 17115 17116 PCR 17117 17118 PCR_SetAuthPolicy 17119 17120 Y 17121 17122 PCR_SetAuthValue 17123 17124 Y 17125 17126 PolicyAuthorize 17127 17128 Y 17129 17130 Policy 17131 17132 PolicyAuthValue 17133 17134 Y 17135 17136 Policy 17137 17138 PolicyCommandCode 17139 17140 Y 17141 17142 Policy 17143 17144 PolicyCounterTimer 17145 17146 Y 17147 17148 Policy 17149 17150 PolicyCpHash 17151 17152 Y 17153 17154 Policy 17155 17156 Page 150 17157 October 31, 2013 17158 17159 NV 17160 17161 PCR 17162 17163 Published 17164 Copyright TCG 2006-2013 17165 17166 Family 2.0 17167 Level 00 Revision 00.99 17168 17169 Trusted Platform Module Library 17171 17172 Part 2: Structures 17173 Implemented 17174 or Dependent 17175 17176 Name 17177 17178 Comments 17179 17180 PolicyDuplicationSelect 17181 17182 Y 17183 17184 Policy 17185 17186 PolicyGetDigest 17187 17188 Y 17189 17190 Policy 17191 17192 PolicyLocality 17193 17194 Y 17195 17196 Policy 17197 17198 PolicyNameHash 17199 17200 Y 17201 17202 Policy 17203 17204 PolicyNV 17205 17206 Y 17207 17208 Policy 17209 17210 PolicyOR 17211 17212 Y 17213 17214 Policy 17215 17216 PolicyPassword 17217 17218 Y 17219 17220 Policy 17221 17222 PolicyPCR 17223 17224 Y 17225 17226 Policy 17227 17228 PolicyPhysicalPresence 17229 17230 Y 17231 17232 Policy 17233 17234 PolicyRestart 17235 17236 Y 17237 17238 PolicySecret 17239 17240 Y 17241 17242 Policy 17243 17244 PolicySigned 17245 17246 Y 17247 17248 Policy 17249 17250 PolicyTicket 17251 17252 Y 17253 17254 Policy 17255 17256 PP_Commands 17257 17258 Y 17259 17260 Quote 17261 17262 Y 17263 17264 ReadClock 17265 17266 Y 17267 17268 ReadPublic 17269 17270 Y 17271 17272 Rewrap 17273 17274 Y 17275 17276 RSA_Decrypt 17277 17278 RSA 17279 17280 RSA_Encrypt 17281 17282 RSA 17283 17284 SelfTest 17285 17286 Y 17287 17288 SequenceComplete 17289 17290 Y 17291 17292 SequenceUpdate 17293 17294 Y 17295 17296 SetAlgorithmSet 17297 17298 Y 17299 17300 SetCommandCodeAuditStatus 17301 17302 Y 17303 17304 SetPrimaryPolicy 17305 17306 Y 17307 17308 Shutdown 17309 17310 Y 17311 17312 Sign 17313 17314 Y 17315 17316 StartAuthSession 17317 17318 Y 17319 17320 Startup 17321 17322 Y 17323 17324 StirRandom 17325 17326 Y 17327 17328 TestParms 17329 17330 Y 17331 17332 Unseal 17333 17334 Y 17335 17336 VerifySignature 17337 17338 Y 17339 17340 ZGen_2Phase 17341 17342 Y 17343 17344 EC_Ephemeral 17345 17346 Y 17347 17348 PolicyNvWritten 17349 17350 Y 17351 17352 B.6 17353 17354 Algorithm Constants 17355 17356 Family 2.0 17357 Level 00 Revision 00.99 17358 17359 Published 17360 Copyright TCG 2006-2013 17361 17362 Page 151 17363 October 31, 2013 17364 17365 Part 2: Structures 17367 B.6.1 17368 17369 Trusted Platform Module Library 17370 17371 RSA 17372 Table 216 Defines for RSA Algorithm Constants 17373 17374 Name 17375 17376 Value 17377 17378 Comments 17379 17380 RSA_KEY_SIZES_BITS 17381 17382 {1024, 2048} 17383 17384 braces because this is a 17385 list value 17386 17387 MAX_RSA_KEY_BITS 17388 17389 2048 17390 17391 MAX_RSA_KEY_BYTES 17392 17393 ((MAX_RSA_KEY_BITS + 7) / 8) 17394 17395 B.6.2 17396 17397 ECC 17398 Table 217 Defines for ECC Algorithm Constants 17399 17400 Name 17401 17402 Value 17403 17404 ECC_CURVES 17405 17406 {TPM_ECC_NIST_P256, TPM_ECC_BN_P256, TPM_ECC_SM2_P256} 17407 17408 ECC_KEY_SIZES_BITS 17409 17410 {256} 17411 17412 MAX_ECC_KEY_BITS 17413 17414 256 17415 17416 MAX_ECC_KEY_BYTES 17417 17418 ((MAX_ECC_KEY_BITS + 7) / 8) 17419 17420 B.6.3 17421 17422 Comments 17423 17424 this is a list value with 17425 length of one 17426 17427 AES 17428 Table 218 Defines for AES Algorithm Constants 17429 17430 Name 17431 17432 Value 17433 17434 AES_KEY_SIZES_BITS 17435 17436 {128} 17437 17438 MAX_AES_KEY_BITS 17439 17440 128 17441 17442 MAX_AES_BLOCK_SIZE_BYTES 17443 17444 16 17445 17446 MAX_AES_KEY_BYTES 17447 17448 ((MAX_AES_KEY_BITS + 7) / 8) 17449 17450 B.6.4 17451 17452 Comments 17453 17454 SM4 17455 Table 219 Defines for SM4 Algorithm Constants 17456 17457 Name 17458 17459 Value 17460 17461 SM4_KEY_SIZES_BITS 17462 17463 {128} 17464 17465 MAX_SM4_KEY_BITS 17466 17467 128 17468 17469 MAX_SM4_BLOCK_SIZE_BYTES 17470 17471 16 17472 17473 MAX_SM4_KEY_BYTES 17474 17475 ((MAX_SM4_KEY_BITS + 7) / 8) 17476 17477 Page 152 17478 October 31, 2013 17479 17480 Comments 17481 17482 Published 17483 Copyright TCG 2006-2013 17484 17485 Family 2.0 17486 Level 00 Revision 00.99 17487 17488 Trusted Platform Module Library 17490 B.6.5 17491 17492 Part 2: Structures 17493 17494 Symmetric 17495 17496 The definitions in this table are derived from the implemented symmetric algorithms. 17497 Table 220 Defines for Symmetric Algorithm Constants 17498 Name 17499 17500 Value 17501 17502 MAX_SYM_KEY_BITS 17503 17504 MAX_AES_KEY_BITS 17505 17506 MAX_SYM_KEY_BYTES 17507 17508 MAX_AES_KEY_BYTES 17509 17510 MAX_SYM_BLOCK_SIZE 17511 17512 MAX_AES_BLOCK_SIZE_BYTES 17513 17514 Family 2.0 17515 Level 00 Revision 00.99 17516 17517 Comments 17518 17519 Published 17520 Copyright TCG 2006-2013 17521 17522 Page 153 17523 October 31, 2013 17524 17525 Part 2: Structures 17527 17528 B.7 17529 17530 Trusted Platform Module Library 17531 17532 Implementation Specific Values 17533 17534 The values listed in Table 221 are defined for a specific TPM implementation. The numbers in the Value 17535 column may be changed to reflect the implementation. The values shown are illustrative. 17536 Table 221 Defines for Implementation Values 17537 Name 17538 17539 Value 17540 17541 Description 17542 17543 FIELD_UPGRADE_IMPLEMENTED 17544 17545 NO 17546 17547 temporary define 17548 17549 BSIZE 17550 17551 UINT16 17552 17553 size used for internal storage of 17554 the size field of a TPM2B 17555 This is the definition used for 17556 the reference design. 17557 Compilation with this value 17558 changed may cause warnings 17559 about conversions. 17560 17561 BUFFER_ALIGNMENT 17562 17563 4 17564 17565 sets the size granularity for the 17566 buffers in a TPM2B structure 17567 TPMxB buffers will be assigned 17568 a space that is a multiple of this 17569 value. This does not set the size 17570 limits for IO. Those are set by 17571 the canonical form of the 17572 TPMxB 17573 17574 IMPLEMENTATION_PCR 17575 17576 24 17577 17578 the number of PCR in the TPM 17579 17580 PLATFORM_PCR 17581 17582 24 17583 17584 the number of PCR required by 17585 the relevant platform 17586 specification 17587 17588 DRTM_PCR 17589 17590 17 17591 17592 the DRTM PCR 17593 17594 HCRTM_PCR 17595 17596 0 17597 17598 the PCR that will receive the HCRTM value at TPM2_Startup 17599 17600 NUM_LOCALITIES 17601 17602 5 17603 17604 the number of localities 17605 supported by the TPM 17606 This is expected to be either 5 17607 for a PC, or 1 for just about 17608 everything else. 17609 17610 MAX_HANDLE_NUM 17611 17612 3 17613 17614 the maximum number of 17615 handles in the handle area 17616 This should be produced by the 17617 Part 3 parser but is here for 17618 now. 17619 17620 MAX_ACTIVE_SESSIONS 17621 17622 64 17623 17624 the number of simultaneously 17625 active sessions that are 17626 supported by the TPM 17627 implementation 17628 17629 CONTEXT_SLOT 17630 17631 UINT16 17632 17633 the type of an entry in the array 17634 of saved contexts 17635 17636 CONTEXT_COUNTER 17637 17638 UINT64 17639 17640 the type of the saved session 17641 counter 17642 17643 MAX_LOADED_SESSIONS 17644 17645 3 17646 17647 the number of sessions that the 17648 TPM may have in memory 17649 17650 MAX_SESSION_NUM 17651 17652 3 17653 17654 this is the current maximum 17655 value 17656 17657 Page 154 17658 October 31, 2013 17659 17660 Published 17661 Copyright TCG 2006-2013 17662 17663 Family 2.0 17664 Level 00 Revision 00.99 17665 17666 Trusted Platform Module Library 17668 17669 Part 2: Structures 17670 17671 Name 17672 17673 Value 17674 17675 Description 17676 17677 MAX_LOADED_OBJECTS 17678 17679 3 17680 17681 the number of simultaneously 17682 loaded objects that are 17683 supported by the TPM; this 17684 number does not include the 17685 objects that may be placed in 17686 NV memory by 17687 TPM2_EvictControl(). 17688 17689 MIN_EVICT_OBJECTS 17690 17691 2 17692 17693 the minimum number of evict 17694 objects supported by the TPM 17695 17696 PCR_SELECT_MIN 17697 17698 ((PLATFORM_PCR+7)/8) 17699 17700 PCR_SELECT_MAX 17701 17702 ((IMPLEMENTATION_PCR+7)/8) 17703 17704 NUM_POLICY_PCR_GROUP 17705 17706 1 17707 17708 number of PCR groups that 17709 have individual policies 17710 17711 NUM_AUTHVALUE_PCR_GROUP 17712 17713 1 17714 17715 number of PCR groups that 17716 have individual authorization 17717 values 17718 17719 MAX_CONTEXT_SIZE 17720 17721 4000 17722 17723 This may be larger than 17724 necessary 17725 17726 MAX_DIGEST_BUFFER 17727 17728 1024 17729 17730 MAX_NV_INDEX_SIZE 17731 17732 2048 17733 17734 maximum data size allowed in 17735 an NV Index 17736 17737 MAX_NV_BUFFER_SIZE 17738 17739 1024 17740 17741 maximum data size in one NV 17742 read or write command 17743 17744 MAX_CAP_BUFFER 17745 17746 1024 17747 17748 NV_MEMORY_SIZE 17749 17750 16384 17751 17752 NUM_STATIC_PCR 17753 17754 16 17755 17756 MAX_ALG_LIST_SIZE 17757 17758 64 17759 17760 number of algorithms that can 17761 be in a list 17762 17763 TIMER_PRESCALE 17764 17765 100000 17766 17767 nominal value for the pre-scale 17768 value of Clock (the number of 17769 cycles of the TPM's oscillator for 17770 each increment of Clock) 17771 17772 PRIMARY_SEED_SIZE 17773 17774 32 17775 17776 size of the Primary Seed in 17777 octets 17778 17779 CONTEXT_ENCRYPT_ALG 17780 17781 TPM_ALG_AES 17782 17783 context encryption algorithm 17784 17785 CONTEXT_ENCRYPT_KEY_BITS 17786 17787 MAX_SYM_KEY_BITS 17788 17789 context encryption key size in 17790 bits 17791 17792 CONTEXT_ENCRYPT_KEY_BYTES 17793 17794 ((CONTEXT_ENCRYPT_KEY_BITS+7)/8) 17795 17796 CONTEXT_INTEGRITY_HASH_ALG 17797 17798 TPM_ALG_SHA256 17799 17800 context integrity hash algorithm 17801 17802 CONTEXT_INTEGRITY_HASH_SIZE 17803 17804 SHA256_DIGEST_SIZE 17805 17806 number of byes in the context 17807 integrity digest 17808 17809 PROOF_SIZE 17810 17811 CONTEXT_INTEGRITY_HASH_SIZE 17812 17813 size of proof value in octets 17814 This size of the proof should be 17815 consistent with the digest size 17816 used for context integrity. 17817 17818 NV_CLOCK_UPDATE_INTERVAL 17819 17820 12 17821 17822 the update interval expressed 17823 as a power of 2 seconds 17824 17825 size of NV memory in octets 17826 17827 A value of 12 is 4,096 seconds 17828 (~68 minutes). 17829 17830 Family 2.0 17831 Level 00 Revision 00.99 17832 17833 Published 17834 Copyright TCG 2006-2013 17835 17836 Page 155 17837 October 31, 2013 17838 17839 Part 2: Structures 17841 17842 Trusted Platform Module Library 17843 17844 Name 17845 17846 Value 17847 17848 Description 17849 17850 NUM_POLICY_PCR 17851 17852 1 17853 17854 number of PCR that allow 17855 policy/auth 17856 17857 MAX_COMMAND_SIZE 17858 17859 4096 17860 17861 maximum size of a command 17862 17863 MAX_RESPONSE_SIZE 17864 17865 4096 17866 17867 maximum size of a response 17868 17869 ORDERLY_BITS 17870 17871 8 17872 17873 number between 1 and 32 17874 inclusive 17875 17876 MAX_ORDERLY_COUNT 17877 17878 ((1 << ORDERLY_BITS) - 1) 17879 17880 maximum count of orderly 17881 counter before NV is updated 17882 This must be of the form 2N 1 17883 where 1 N 32. 17884 17885 ALG_ID_FIRST 17886 17887 TPM_ALG_FIRST 17888 17889 used by GetCapability() 17890 processing to bound the 17891 algorithm search 17892 17893 ALG_ID_LAST 17894 17895 TPM_ALG_LAST 17896 17897 used by GetCapability() 17898 processing to bound the 17899 algorithm search 17900 17901 MAX_SYM_DATA 17902 17903 128 17904 17905 this is the maximum number of 17906 octets that may be in a sealed 17907 blob. 17908 17909 MAX_RNG_ENTROPY_SIZE 17910 17911 64 17912 17913 RAM_INDEX_SPACE 17914 17915 512 17916 17917 RSA_DEFAULT_PUBLIC_EXPONENT 17918 17919 0x00010001 17920 17921 216 + 1 17922 17923 ENABLE_PCR_NO_INCREMENT 17924 17925 YES 17926 17927 17928 CRT_FORMAT_RSA 17929 17930 YES 17931 17932 PRIVATE_VENDOR_SPECIFIC_BYTES 17933 17934 ((MAX_RSA_KEY_BYTES/2) * (3 + CRT_FORMAT_RSA * 2)) 17935 17936 Page 156 17937 October 31, 2013 17938 17939 Published 17940 Copyright TCG 2006-2013 17941 17942 Family 2.0 17943 Level 00 Revision 00.99 17944 17945 17947