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 Family 2.0 2622 Level 00 Revision 00.99 2623 2624 Published 2625 Copyright TCG 2006-2013 2626 2627 Page 17 2628 October 31, 2013 2629 2630 Part 2: Structures 2632 2633 6 2634 2635 Trusted Platform Module Library 2636 2637 Constants 2638 2639 6.1 2640 2641 TPM_SPEC (Specification Version Values) 2642 2643 These values are readable with TPM2_GetCapability(). 2644 NOTE 2645 2646 This table will require editing when the specification is updated. 2647 2648 Table 5 Definition of (UINT32) TPM_SPEC Constants <> 2649 Name 2650 2651 Value 2652 2653 Comments 2654 ASCII 2.0 with null terminator 2655 2656 TPM_SPEC_FAMILY 2657 2658 0x322E3000 2659 2660 TPM_SPEC_LEVEL 2661 2662 00 2663 2664 the level number for the specification 2665 2666 TPM_SPEC_VERSION 2667 2668 99 2669 2670 the version number of the spec (00.99 * 100) 2671 2672 TPM_SPEC_YEAR 2673 2674 2013 2675 2676 the year of the version 2677 2678 TPM_SPEC_DAY_OF_YEAR 2679 2680 304 2681 2682 the day of the year (October 31, 2013) 2683 2684 6.2 2685 2686 TPM_GENERATED 2687 2688 This constant value differentiates TPM-generated structures from non-TPM structures. 2689 Table 6 Definition of (UINT32) TPM_GENERATED Constants <O> 2690 Name 2691 2692 Value 2693 2694 Comments 2695 2696 TPM_GENERATED_VALUE 2697 2698 0xff544347 2699 2700 0xFF TCG (FF 54 43 4716) 2701 2702 Page 18 2703 October 31, 2013 2704 2705 Published 2706 Copyright TCG 2006-2013 2707 2708 Family 2.0 2709 Level 00 Revision 00.99 2710 2711 Trusted Platform Module Library 2713 6.3 2714 2715 Part 2: Structures 2716 2717 TPM_ALG_ID 2718 2719 The TCG maintains a registry of all algorithms that have an assigned algorithm ID. That registry is the 2720 definitive list of algorithms that may be supported by a TPM. 2721 NOTE 2722 2723 Inclusion of an algorithm does NOT indicate that the necessary claims of the algorithm are av ailable 2724 under RAND terms from a TCG member. 2725 2726 Table 7 is a copy of the TPM_ALG_ID constants table in the TCG registry as of the date of publication of 2727 this specification. Table 7 is provided for illustrative purposes only. 2728 {{Note for TCG Admin: Table 7 and the text in the paragraph above should be updated to reflect the final 2729 decisions by the TCG Board of Directors about inclusion of the table and the contents of the table. The 2730 desired approach is to leave the text as is and, immediately before publication of this specification for 2731 TCG admin to verify that Table 7 is the same as the algorithm registry table published by the TCG.}} 2732 An algorithm ID is often used like a tag to determine the type of a structure in a context-sensitive way. 2733 The values for TPM_ALG_ID shall be in the range of 00 0016 7F FF16. Other structure tags will be in the 2734 range 80 0016 FF FF16. 2735 NOTE 2736 2737 In TPM 1.2, these were defined as 32-bit constants. This specification limits the future size of the 2738 algorithm ID to 16 bits. The TPM_ALGORITHM_ID data type will continue to be a 32-bit number. 2739 2740 An algorithm shall not be assigned a value in the range 00 C116 00 C616 in order to prevent any overlap 2741 with the command structure tags used in TPM 1.2. 2742 The implementation of some algorithms is dependent on the presence of other algorithms. When there is 2743 a dependency, the algorithm that is required is listed in column labeled "D" (dependent) in Table 7. 2744 EXAMPLE 2745 2746 Implementation of TPM_ALG_RSASSA requires that the RSA algorithm be implemented. 2747 2748 TPM_ALG_KEYEDHASH and TPM_ALG_NULL are required of all TPM implementations. 2749 Table 7 Definition of (UINT16) TPM_ALG_ID Constants <IN/OUT, S> 2750 Algorithm Name 2751 2752 Value 2753 2754 Type 2755 2756 a 2757 2758 D 2759 2760 Comments 2761 2762 TPM_ALG_ERROR 2763 2764 0x0000 2765 2766 should not occur 2767 2768 TPM_ALG_FIRST 2769 2770 0x0001 2771 2772 TPM_ALG_RSA 2773 2774 0x0001 2775 2776 AO 2777 2778 the RSA algorithm 2779 2780 TPM_ALG_SHA 2781 2782 0x0004 2783 2784 H 2785 2786 the SHA1 algorithm 2787 2788 TPM_ALG_SHA1 2789 2790 0x0004 2791 2792 H 2793 2794 redefinition for documentation consistency 2795 OID 30 21 30 09 06 05 2B 0E 03 02 1A 05 00 04 14 16 2796 2797 TPM_ALG_HMAC 2798 2799 0x0005 2800 2801 HX 2802 2803 the RFC 2104 Hash Message Authentication Code 2804 (HMAC) algorithm 2805 2806 TPM_ALG_AES 2807 2808 0x0006 2809 2810 S 2811 2812 the AES algorithm with a key size of 128 bits for TPM 2813 1.2 2814 the AES algorithm with multiple sizes of key for TPM 2815 2.0 2816 2817 TPM_ALG_MGF1 2818 2819 0x0007 2820 2821 HM 2822 2823 the mask-generation function defined in IEEE Std 2824 1363-2000 2825 2826 TPM_ALG_KEYEDHASH 2827 2828 0x0008 2829 2830 HEXO 2831 2832 an encryption or signing algorithm using a keyed hash, 2833 defined by TCG in the TPM 2.0 specification 2834 may also refer to a data object that is neither signing 2835 nor encrypting 2836 2837 TPM_ALG_XOR 2838 2839 0x000A 2840 2841 HS 2842 2843 marker value 2844 2845 the XOR obfuscation algorithm 2846 NOTE 2847 2848 Family 2.0 2849 Level 00 Revision 00.99 2850 2851 The implementation of XOR obfuscation in TPM 2852 2.0 is not the same as the XOR encryption 2853 method in TPM 1.2. 2854 2855 Published 2856 Copyright TCG 2006-2013 2857 2858 Page 19 2859 October 31, 2013 2860 2861 Part 2: Structures 2863 Algorithm Name 2864 2865 Trusted Platform Module Library 2866 a 2867 2868 Value 2869 2870 Type 2871 2872 TPM_ALG_SHA256 2873 2874 0x000B 2875 2876 H 2877 2878 D 2879 2880 Comments 2881 the SHA 256 algorithm 2882 OID 30 31 30 0d 06 09 60 86 48 01 65 03 04 02 01 05 2883 00 04 2016 2884 2885 TPM_ALG_SHA384 2886 2887 0x000C 2888 2889 H 2890 2891 the SHA 384 algorithm 2892 OID 30 41 30 0d 06 09 60 86 48 01 65 03 04 02 02 05 2893 00 04 3016 2894 2895 TPM_ALG_SHA512 2896 2897 0x000D 2898 2899 H 2900 2901 the SHA 512 algorithm 2902 OID 30 51 30 0d 06 09 60 86 48 01 65 03 04 02 03 05 2903 00 04 4016 2904 2905 TPM_ALG_NULL 2906 2907 0x0010 2908 2909 TPM_ALG_SM3_256 2910 2911 0x0012 2912 2913 H 2914 2915 hash algorithm standardized by OSCCA 2916 Block size is 512 bits. 2917 Output size is 256 bits. 2918 2919 TPM_ALG_SM4 2920 2921 0x0013 2922 2923 S 2924 2925 symmetric algorithm standardized by OSCCA 2926 Key and block size are 128 bits. 2927 2928 TPM_ALG_RSASSA 2929 2930 0x0014 2931 2932 AX 2933 2934 RSA a signature algorithm according to PKCS#1v2.1, 8.2 2935 2936 TPM_ALG_RSAES 2937 2938 0x0015 2939 2940 AE 2941 2942 RSA a padding algorithm according to PKCS#1v2.1, 7.2 2943 2944 TPM_ALG_RSAPSS 2945 2946 0x0016 2947 2948 AX 2949 2950 RSA signature algorithm (RSSASSA-PSS) according to 2951 PKCS#1v2.1, 8.1 2952 2953 TPM_ALG_OAEP 2954 2955 0x0017 2956 2957 AE 2958 2959 RSA padding algorithm 2960 PKCS#1v2.1, 7.1 2961 2962 TPM_ALG_ECDSA 2963 2964 0x0018 2965 2966 AX 2967 2968 ECC signature algorithm using elliptic curve cryptography 2969 (ECC) 2970 2971 TPM_ALG_ECDH 2972 2973 0x0019 2974 2975 AM 2976 2977 ECC secret sharing using ECC from SP800-56A 2978 Based on context, this can be either One-Pass DiffieHellman, C(1, 1, ECC CDH) defined in 6.2.2.2 or Full 2979 Unified Model C(2, 2, ECC CDH) defined in 6.1.1.2 2980 2981 TPM_ALG_ECDAA 2982 2983 0x001A 2984 2985 AX 2986 2987 ECC elliptic-curve based, anonymous signing scheme 2988 2989 TPM_ALG_SM2 2990 2991 0x001B 2992 2993 AXE 2994 2995 Null algorithm 2996 2997 (RSAES_OAEP) 2998 2999 according 3000 3001 to 3002 3003 ECC depending on context, either an elliptic-curve based, 3004 signature algorithm or a key exchange protocol 3005 NOTE 3006 3007 This would be one of the algorithms specified in 3008 CM/T 0002 2012. 3009 3010 TPM_ALG_ECSCHNORR 3011 3012 0x001C 3013 3014 AX 3015 3016 ECC elliptic-curve-based Schnorr signature 3017 3018 TPM_ALG_ECMQV 3019 3020 0x001D 3021 3022 AE 3023 3024 ECC two-phase elliptic-curve key exchange -- C(2, 2, ECC 3025 MQV) from SP800-56A 3026 3027 TPM_ALG_KDF1_SP800_56a 3028 3029 0x0020 3030 3031 HM 3032 3033 ECC key derivation alternative #1 from SP800-56A 3034 3035 TPM_ALG_KDF2 3036 3037 0x0021 3038 3039 HM 3040 3041 key derivation function from IEEE Std 1363a-2004 3042 3043 TPM_ALG_KDF1_SP800_108 3044 3045 0x0022 3046 3047 HM 3048 3049 a key derivation method according to SP 800-108, "5.1 3050 KDF in Counter Mode 3051 3052 TPM_ALG_ECC 3053 3054 0x0023 3055 3056 AO 3057 3058 prime field ECC 3059 3060 TPM_ALG_SYMCIPHER 3061 3062 0x0025 3063 3064 O 3065 3066 TPM_ALG_CTR 3067 3068 0x0040 3069 3070 SE 3071 3072 Counter mode if implemented, all symmetric block 3073 ciphers (S type) implemented shall be capable of using 3074 this mode. 3075 3076 TPM_ALG_OFB 3077 3078 0x0041 3079 3080 SE 3081 3082 Output Feedback mode if implemented, all 3083 symmetric block ciphers (S type) implemented shall be 3084 capable of using this mode. 3085 3086 TPM_ALG_CBC 3087 3088 0x0042 3089 3090 SE 3091 3092 Cipher Block Chaining mode if implemented, all 3093 symmetric block ciphers (S type) implemented shall be 3094 capable of using this mode. 3095 3096 Page 20 3097 October 31, 2013 3098 3099 the object type for a symmetric block cipher 3100 3101 Published 3102 Copyright TCG 2006-2013 3103 3104 Family 2.0 3105 Level 00 Revision 00.99 3106 3107 Trusted Platform Module Library 3109 3110 Part 2: Structures 3111 a 3112 3113 Algorithm Name 3114 3115 Value 3116 3117 Type 3118 3119 TPM_ALG_CFB 3120 3121 0x0043 3122 3123 SE 3124 3125 D 3126 3127 Comments 3128 Cipher Feedback mode if implemented, all 3129 symmetric block ciphers (S type) implemented shall be 3130 capable of using this mode. 3131 3132 TPM_ALG_ECB 3133 3134 0x0044 3135 3136 SE 3137 3138 Electronic Codebook mode if implemented, all 3139 symmetric block ciphers (S type) implemented shall be 3140 capable of using this mode. 3141 NOTE 3142 3143 This mode is not recommended for uses unless 3144 the key is frequently rotated such as in video 3145 codecs. 3146 3147 TPM_ALG_LAST 3148 3149 0x0044 3150 3151 marker value 3152 3153 reserved 3154 3155 0x00C1 3156 3157 0x00C1 0x00C6 are reserved 3158 3159 reserved 3160 3161 0x00C2 3162 3163 reserved 3164 3165 0x00C3 3166 3167 reserved 3168 3169 0x00C4 3170 3171 reserved 3172 3173 0x00C5 3174 3175 reserved 3176 3177 0x00C6 3178 3179 NOTE a Column Indicates the algorithm type and use of the algorithm inside of the TPM. The values are: 3180 A asymmetric algorithm with a public and private key 3181 S symmetric algorithm with only a private key 3182 H hash algorithm that compresses input data to a digest value 3183 X signing algorithm 3184 E an encryption algorithm 3185 M a method such as a mask generation function 3186 O an object type 3187 3188 Family 2.0 3189 Level 00 Revision 00.99 3190 3191 Published 3192 Copyright TCG 2006-2013 3193 3194 Page 21 3195 October 31, 2013 3196 3197 Part 2: Structures 3199 6.4 3200 3201 Trusted Platform Module Library 3202 3203 TPM_ECC_CURVE 3204 3205 The TCG maintains a registry of all curves that have an assigned curve identifier. That registry is the 3206 definitive list of curves that may be supported by a TPM. 3207 Table 8 is a copy of the TPM_ECC_CURVE constants table in the TCG registry as of the date of 3208 publication of this specification. Table 8 is provided for illustrative purposes only. 3209 {{Note for TCG Admin: Table 8 and the text in the paragraph above should be updated to reflect the final 3210 decisions by the TCG Board of Directors about inclusion of the table and the contents of the table. The 3211 desired approach is to leave the text as is and, immediately before publication of this specification for 3212 TCG admin to verify that Table 8 is the same as the curve registry table published by the TCG.}} 3213 Table 8 Definition of (UINT16) {ECC} TPM_ECC_CURVE Constants <IN/OUT, S> 3214 Name 3215 3216 Value 3217 3218 Comments 3219 3220 TPM_ECC_NONE 3221 3222 0x0000 3223 3224 TPM_ECC_NIST_P192 3225 3226 0x0001 3227 3228 TPM_ECC_NIST_P224 3229 3230 0x0002 3231 3232 TPM_ECC_NIST_P256 3233 3234 0x0003 3235 3236 TPM_ECC_NIST_P384 3237 3238 0x0004 3239 3240 TPM_ECC_NIST_P521 3241 3242 0x0005 3243 3244 TPM_ECC_BN_P256 3245 3246 0x0010 3247 3248 curve to support ECDAA 3249 3250 TPM_ECC_BN_P638 3251 3252 0x0011 3253 3254 curve to support ECDAA 3255 3256 TPM_ECC_SM2_P256 3257 3258 0x0020 3259 3260 #TPM_RC_CURVE 3261 3262 6.5 3263 6.5.1 3264 3265 TPM_CC (Command Codes) 3266 Format 3267 3268 A command is a 32-bit structure with fields assigned as shown in Figure 1. 3269 3 3 2 2 3270 1 0 9 8 3271 3272 Res V 3273 3274 1 1 3275 6 5 3276 3277 Reserved 3278 3279 0 3280 0 3281 3282 Command Index 3283 3284 Figure 1 Command Format 3285 Table 9 TPM Command Format Fields Description 3286 Bit 3287 15:0 3288 3289 Name 3290 3291 Definition 3292 3293 Command Index 3294 3295 the index of the command 3296 3297 28:16 Reserved 3298 29 3299 3300 V 3301 3302 31:30 Res 3303 3304 Page 22 3305 October 31, 2013 3306 3307 shall be zero 3308 SET(1): the command is vendor specific 3309 CLEAR(0): the command is not vendor specific 3310 shall be zero 3311 3312 Published 3313 Copyright TCG 2006-2013 3314 3315 Family 2.0 3316 Level 00 Revision 00.99 3317 3318 Trusted Platform Module Library 3320 6.5.2 3321 3322 Part 2: Structures 3323 3324 Description 3325 3326 Table 10 provides the legend for the interpretation of the column data in Table 11. 3327 Table 10 Legend for Command Code Tables 3328 Column 3329 3330 Allowed 3331 Values 3332 3333 Comments 3334 3335 Name 3336 3337 Command 3338 Code Name 3339 3340 Name of the command 3341 3342 Command Code 3343 3344 Numeric value 3345 3346 the numeric value for the commandCode 3347 3348 NV Write 3349 3350 blank, Y, O 3351 3352 indicates whether the command may cause an NV write operation 3353 If this column contains a Y, then successful completion of the 3354 command is expected to cause modification of the NV memory 3355 because of the command actions. 3356 If the column contains an O, then the command may cause a 3357 modification to NV associated with an orderly shutdown. That is, the 3358 command may modify the orderly save state of NV, in which case, an 3359 NV write will be necessary. 3360 NOTE 1 3361 3362 Any command may be delayed in order for the TPM to complete 3363 NV actions due to a previous command or because of an 3364 asynchronous update of Clock. 3365 3366 NOTE 2 3367 3368 Any command with an authorization value may cause an NV write 3369 on an authorization failure but the command does not complete 3370 successfully. 3371 3372 If the entry is blank, then writing to NV is not allowed in the command 3373 actions. 3374 Physical Presence 3375 3376 blank, Y 3377 3378 indicates whether the platformAuth for this command may require 3379 confirmation through a physical presence indication 3380 3381 Encrypted 3382 3383 blank, 2, 4 3384 3385 A numeric value that indicates the number of octets in the size field of 3386 the first parameter of a command 3387 Blank indicates that no size field is present and no parameter 3388 encryption is allowed. 3389 3390 Encrypt 3391 3392 blank, 2, 4 3393 3394 A numeric value that indicates the number of octets in the size field of 3395 the first parameter of a response 3396 Blank indicates that no size field is present and no parameter 3397 encryption is allowed. 3398 3399 Family 2.0 3400 Level 00 Revision 00.99 3401 3402 Published 3403 Copyright TCG 2006-2013 3404 3405 Page 23 3406 October 31, 2013 3407 3408 Part 2: Structures 3410 6.5.3 3411 3412 Trusted Platform Module Library 3413 3414 TPM_CC Listing 3415 3416 Table 11 lists the command codes and their attributes. The only normative column in this table is the 3417 column indicating the command code assigned to a specific command (the "Command Code" column). 3418 For all other columns, the command and response tables in Part 3 are definitive. 3419 3420 Encrypt 3421 3422 Encrypted 3423 3424 Physical Presence 3425 3426 NV Write 3427 3428 Table 11 Definition of (UINT32) TPM_CC Constants (Numeric Order) <IN/OUT, S> 3429 3430 Name 3431 3432 Command 3433 Code 3434 3435 TPM_CC_FIRST 3436 3437 0x0000011F 3438 3439 Compile variable. May decrease 3440 based on implementation. 3441 3442 TPM_CC_PP_FIRST 3443 3444 0x0000011F 3445 3446 Compile variable. Would decrease 3447 if new PP commands are added 3448 3449 TPM_CC_NV_UndefineSpaceSpecial 3450 3451 0x0000011F 3452 3453 Y 3454 3455 Y 3456 3457 TPM_CC_EvictControl 3458 3459 0x00000120 3460 3461 Y 3462 3463 Y 3464 3465 TPM_CC_HierarchyControl 3466 3467 0x00000121 3468 3469 Y 3470 3471 Y 3472 3473 TPM_CC_NV_UndefineSpace 3474 3475 0x00000122 3476 3477 Y 3478 3479 Y 3480 3481 TPM_CC_ChangeEPS 3482 3483 0x00000124 3484 3485 Y 3486 3487 Y 3488 3489 TPM_CC_ChangePPS 3490 3491 0x00000125 3492 3493 Y 3494 3495 Y 3496 3497 TPM_CC_Clear 3498 3499 0x00000126 3500 3501 Y 3502 3503 Y 3504 3505 TPM_CC_ClearControl 3506 3507 0x00000127 3508 3509 Y 3510 3511 Y 3512 3513 TPM_CC_ClockSet 3514 3515 0x00000128 3516 3517 Y 3518 3519 Y 3520 3521 TPM_CC_HierarchyChangeAuth 3522 3523 0x00000129 3524 3525 Y 3526 3527 Y 3528 3529 2 3530 3531 TPM_CC_NV_DefineSpace 3532 3533 0x0000012A 3534 3535 Y 3536 3537 Y 3538 3539 2 3540 3541 TPM_CC_PCR_Allocate 3542 3543 0x0000012B 3544 3545 Y 3546 3547 Y 3548 3549 TPM_CC_PCR_SetAuthPolicy 3550 3551 0x0000012C 3552 3553 Y 3554 3555 Y 3556 3557 TPM_CC_PP_Commands 3558 3559 0x0000012D 3560 3561 Y 3562 3563 Y 3564 3565 TPM_CC_SetPrimaryPolicy 3566 3567 0x0000012E 3568 3569 Y 3570 3571 Y 3572 3573 2 3574 3575 TPM_CC_FieldUpgradeStart 3576 3577 0x0000012F 3578 3579 O 3580 3581 Y 3582 3583 2 3584 3585 TPM_CC_ClockRateAdjust 3586 3587 0x00000130 3588 3589 O 3590 3591 Y 3592 3593 TPM_CC_CreatePrimary 3594 3595 0x00000131 3596 3597 TPM_CC_NV_GlobalWriteLock 3598 3599 0x00000132 3600 3601 TPM_CC_PP_LAST 3602 3603 0x00000132 3604 3605 TPM_CC_GetCommandAuditDigest 3606 3607 0x00000133 3608 3609 Y 3610 3611 TPM_CC_NV_Increment 3612 3613 0x00000134 3614 3615 Y 3616 3617 Page 24 3618 October 31, 2013 3619 3620 Y 3621 O 3622 3623 Comments 3624 3625 2 3626 3627 2 3628 3629 2 3630 3631 Y 3632 Compile variable 3633 2 3634 3635 Published 3636 Copyright TCG 2006-2013 3637 3638 Family 2.0 3639 Level 00 Revision 00.99 3640 3641 Command 3643 Code 3644 3645 TPM_CC_NV_SetBits 3646 3647 0x00000135 3648 3649 Y 3650 3651 TPM_CC_NV_Extend 3652 3653 0x00000136 3654 3655 Y 3656 3657 TPM_CC_NV_Write 3658 3659 0x00000137 3660 3661 Y 3662 3663 TPM_CC_NV_WriteLock 3664 3665 0x00000138 3666 3667 Y 3668 3669 TPM_CC_DictionaryAttackLockReset 3670 3671 0x00000139 3672 3673 O 3674 3675 TPM_CC_DictionaryAttackParameters 3676 3677 0x0000013A 3678 3679 Y 3680 3681 TPM_CC_NV_ChangeAuth 3682 3683 0x0000013B 3684 3685 Y 3686 3687 2 3688 3689 TPM_CC_PCR_Event 3690 3691 0x0000013C 3692 3693 O 3694 3695 2 3696 3697 TPM_CC_PCR_Reset 3698 3699 0x0000013D 3700 3701 O 3702 3703 TPM_CC_SequenceComplete 3704 3705 0x0000013E 3706 3707 O 3708 3709 TPM_CC_SetAlgorithmSet 3710 3711 0x0000013F 3712 3713 Y 3714 3715 TPM_CC_SetCommandCodeAuditStatus 3716 3717 0x00000140 3718 3719 Y 3720 3721 TPM_CC_FieldUpgradeData 3722 3723 0x00000141 3724 3725 O 3726 3727 TPM_CC_IncrementalSelfTest 3728 3729 0x00000142 3730 3731 O 3732 3733 TPM_CC_SelfTest 3734 3735 0x00000143 3736 3737 O 3738 3739 TPM_CC_Startup 3740 3741 0x00000144 3742 3743 Y 3744 3745 TPM_CC_Shutdown 3746 3747 0x00000145 3748 3749 Y 3750 3751 TPM_CC_StirRandom 3752 3753 0x00000146 3754 3755 Y 3756 3757 TPM_CC_ActivateCredential 3758 3759 0x00000147 3760 3761 TPM_CC_Certify 3762 3763 0x00000148 3764 3765 TPM_CC_PolicyNV 3766 3767 0x00000149 3768 3769 TPM_CC_CertifyCreation 3770 3771 0x0000014A 3772 3773 TPM_CC_Duplicate 3774 3775 0x0000014B 3776 3777 TPM_CC_GetTime 3778 3779 0x0000014C 3780 3781 O 3782 3783 2 3784 3785 TPM_CC_GetSessionAuditDigest 3786 3787 0x0000014D 3788 3789 O 3790 3791 2 3792 3793 TPM_CC_NV_Read 3794 3795 0x0000014E 3796 3797 TPM_CC_NV_ReadLock 3798 3799 0x0000014F 3800 3801 TPM_CC_ObjectChangeAuth 3802 3803 0x00000150 3804 3805 2 3806 3807 TPM_CC_PolicySecret 3808 3809 0x00000151 3810 3811 2 3812 3813 TPM_CC_Rewrap 3814 3815 0x00000152 3816 3817 2 3818 3819 Family 2.0 3820 Level 00 Revision 00.99 3821 3822 Encrypt 3823 3824 Name 3825 3826 NV Write 3827 3828 Encrypted 3829 3830 Part 2: Structures 3831 3832 Physical Presence 3833 3834 Trusted Platform Module Library 3835 3836 2 3837 3838 PCR 3839 PCR 3840 3841 2 3842 3843 2 3844 3845 2 3846 3847 2 3848 2 3849 3850 O 3851 3852 2 3853 3854 2 3855 3856 2 3857 3858 2 3859 O 3860 3861 Comments 3862 3863 Policy 3864 3865 2 3866 3867 2 3868 3869 2 3870 3871 2 3872 3873 2 3874 O 3875 3876 Published 3877 Copyright TCG 2006-2013 3878 3879 2 3880 Policy 3881 2 3882 3883 Page 25 3884 October 31, 2013 3885 3886 Trusted Platform Module Library 3888 3889 Command 3890 Code 3891 3892 Encrypt 3893 3894 TPM_CC_Create 3895 3896 0x00000153 3897 3898 2 3899 3900 2 3901 3902 TPM_CC_ECDH_ZGen 3903 3904 0x00000154 3905 3906 2 3907 3908 2 3909 3910 TPM_CC_HMAC 3911 3912 0x00000155 3913 3914 2 3915 3916 2 3917 3918 TPM_CC_Import 3919 3920 0x00000156 3921 3922 2 3923 3924 2 3925 3926 TPM_CC_Load 3927 3928 0x00000157 3929 3930 2 3931 3932 2 3933 3934 TPM_CC_Quote 3935 3936 0x00000158 3937 3938 2 3939 3940 2 3941 3942 TPM_CC_RSA_Decrypt 3943 3944 0x00000159 3945 3946 TPM_CC_HMAC_Start 3947 3948 0x0000015B 3949 3950 2 3951 3952 TPM_CC_SequenceUpdate 3953 3954 0x0000015C 3955 3956 2 3957 3958 TPM_CC_Sign 3959 3960 0x0000015D 3961 3962 2 3963 3964 TPM_CC_Unseal 3965 3966 0x0000015E 3967 3968 TPM_CC_PolicySigned 3969 3970 0x00000160 3971 3972 TPM_CC_ContextLoad 3973 3974 0x00000161 3975 3976 O 3977 3978 Context 3979 3980 TPM_CC_ContextSave 3981 3982 0x00000162 3983 3984 O 3985 3986 Context 3987 3988 TPM_CC_ECDH_KeyGen 3989 3990 0x00000163 3991 3992 2 3993 3994 TPM_CC_EncryptDecrypt 3995 3996 0x00000164 3997 3998 2 3999 4000 TPM_CC_FlushContext 4001 4002 0x00000165 4003 4004 TPM_CC_LoadExternal 4005 4006 0x00000167 4007 4008 2 4009 4010 2 4011 4012 TPM_CC_MakeCredential 4013 4014 0x00000168 4015 4016 2 4017 4018 2 4019 4020 TPM_CC_NV_ReadPublic 4021 4022 0x00000169 4023 4024 TPM_CC_PolicyAuthorize 4025 4026 0x0000016A 4027 4028 TPM_CC_PolicyAuthValue 4029 4030 0x0000016B 4031 4032 Policy 4033 4034 TPM_CC_PolicyCommandCode 4035 4036 0x0000016C 4037 4038 Policy 4039 4040 TPM_CC_PolicyCounterTimer 4041 4042 0x0000016D 4043 4044 2 4045 4046 Policy 4047 4048 TPM_CC_PolicyCpHash 4049 4050 0x0000016E 4051 4052 2 4053 4054 Policy 4055 4056 TPM_CC_PolicyLocality 4057 4058 0x0000016F 4059 4060 TPM_CC_PolicyNameHash 4061 4062 0x00000170 4063 4064 TPM_CC_PolicyOR 4065 4066 0x00000171 4067 4068 TPM_CC_PolicyTicket 4069 4070 0x00000172 4071 4072 TPM_CC_ReadPublic 4073 4074 0x00000173 4075 4076 Page 26 4077 October 31, 2013 4078 4079 NV Write 4080 4081 Name 4082 4083 Encrypted 4084 4085 Physical Presence 4086 4087 Part 2: Structures 4088 4089 O 4090 4091 Comments 4092 4093 2 4094 2 4095 4096 2 4097 2 4098 4099 Policy 4100 4101 O 4102 4103 Context 4104 4105 NV 4106 2 4107 4108 Policy 4109 4110 Policy 4111 2 4112 4113 Policy 4114 Policy 4115 4116 2 4117 4118 Published 4119 Copyright TCG 2006-2013 4120 4121 Policy 4122 2 4123 4124 Family 2.0 4125 Level 00 Revision 00.99 4126 4127 Encrypt 4129 4130 2 4131 4132 NV Write 4133 4134 Encrypted 4135 4136 Part 2: Structures 4137 4138 Physical Presence 4139 4140 Trusted Platform Module Library 4141 4142 2 4143 4144 2 4145 4146 2 4147 4148 Name 4149 4150 Command 4151 Code 4152 4153 TPM_CC_RSA_Encrypt 4154 4155 0x00000174 4156 4157 TPM_CC_StartAuthSession 4158 4159 0x00000176 4160 4161 TPM_CC_VerifySignature 4162 4163 0x00000177 4164 4165 TPM_CC_ECC_Parameters 4166 4167 0x00000178 4168 4169 TPM_CC_FirmwareRead 4170 4171 0x00000179 4172 4173 TPM_CC_GetCapability 4174 4175 0x0000017A 4176 4177 TPM_CC_GetRandom 4178 4179 0x0000017B 4180 4181 TPM_CC_GetTestResult 4182 4183 0x0000017C 4184 4185 TPM_CC_Hash 4186 4187 0x0000017D 4188 4189 TPM_CC_PCR_Read 4190 4191 0x0000017E 4192 4193 PCR 4194 4195 TPM_CC_PolicyPCR 4196 4197 0x0000017F 4198 4199 Policy 4200 4201 TPM_CC_PolicyRestart 4202 4203 0x00000180 4204 4205 TPM_CC_ReadClock 4206 4207 0x00000181 4208 4209 TPM_CC_PCR_Extend 4210 4211 0x00000182 4212 4213 O 4214 4215 2 4216 4217 TPM_CC_PCR_SetAuthValue 4218 4219 0x00000183 4220 4221 N 4222 4223 2 4224 4225 TPM_CC_NV_Certify 4226 4227 0x00000184 4228 4229 O 4230 4231 TPM_CC_EventSequenceComplete 4232 4233 0x00000185 4234 4235 O 4236 4237 TPM_CC_HashSequenceStart 4238 4239 0x00000186 4240 4241 TPM_CC_PolicyPhysicalPresence 4242 4243 0x00000187 4244 4245 Policy 4246 4247 TPM_CC_PolicyDuplicationSelect 4248 4249 0x00000188 4250 4251 Policy 4252 4253 TPM_CC_PolicyGetDigest 4254 4255 0x00000189 4256 4257 Policy 4258 4259 TPM_CC_TestParms 4260 4261 0x0000018A 4262 4263 TPM_CC_Commit 4264 4265 0x0000018B 4266 4267 TPM_CC_PolicyPassword 4268 4269 0x0000018C 4270 4271 TPM_CC_ZGen_2Phase 4272 4273 0x0000018D 4274 4275 TPM_CC_EC_Ephemeral 4276 4277 0x0000018E 4278 4279 TPM_CC_PolicyNvWritten 4280 4281 0x0000018F 4282 4283 Policy 4284 4285 TPM_CC_LAST 4286 4287 0x0000018F 4288 4289 Compile variable. May increase 4290 based on implementation. 4291 4292 O 4293 4294 Comments 4295 4296 2 4297 4298 2 4299 4300 2 4301 4302 O 4303 4304 2 4305 4306 2 4307 4308 2 4309 Policy 4310 4311 2 4312 4313 2 4314 4315 NOTE 4316 4317 #TPM_RC_COMMAND_CODE 4318 4319 Family 2.0 4320 Level 00 Revision 00.99 4321 4322 Published 4323 Copyright TCG 2006-2013 4324 4325 This is not a FMT1 code 4326 and a parameter indicator 4327 value may not be added to 4328 4329 Page 27 4330 October 31, 2013 4331 4332 Encrypt 4334 4335 Encrypted 4336 4337 Command 4338 Code 4339 4340 Name 4341 4342 Physical Presence 4343 4344 Trusted Platform Module Library 4345 4346 NV Write 4347 4348 Part 2: Structures 4349 4350 Comments 4351 this value. 4352 4353 6.6 4354 4355 TPM_RC (Response Codes) 4356 4357 6.6.1 4358 4359 Description 4360 4361 Each return from the TPM has a 32-bit response code. The TPM will always set the upper 20 bits (31:12) 4362 of the response code to 0 00 0016 and the low-order 12 bits (11:00) will contain the response code. 4363 When a command succeeds, the TPM shall return TPM_RC_SUCCESS (0 0016) and will update any 4364 authorization-session nonce associated with the command. 4365 When a command fails to complete for any reason, the TPM shall return 4366 4367 4368 a TPM_ST (UINT16) with a value of TPM_TAG_RSP_COMMAND or TPM_ST_NO_SESSIONS, 4369 followed by 4370 4371 4372 4373 a UINT32 (responseSize) with a value of 10, followed by 4374 4375 4376 4377 a UINT32 containing a response code with a value other than TPM_RC_SUCCESS. 4378 4379 Commands defined in this specification will use a tag of either TPM_ST_NO_SESSIONS or 4380 TPM_ST_SESSIONS. Error responses will use a tag value of TPM_ST_NO_SESSIONS and the 4381 response code will be as defined in this specification. Commands that use tags defined in the TPM 1.2 4382 specification will use TPM_TAG_RSP_COMMAND in an error and a response code defined in TPM 1.2. 4383 If the tag of the command is not a recognized command tag, the TPM error response will differ depending 4384 on TPM 1.2 compatibility. If the TPM supports 1.2 compatibility, the TPM shall return a tag of 4385 TPM_TAG_RSP_COMMAND and an appropriate TPM 1.2 response code (TPM_BADTAG = 4386 00 00 00 1E16). If the TPM does not have compatibility with TPM 1.2, the TPM shall return 4387 TPM_ST_NO_SESSION and a response code of TPM_RC_TAG. 4388 When a command fails, the TPM shall not update the authorization-session nonces associated with the 4389 command and will not close the authorization sessions used by the command. Audit digests will not be 4390 updated on an error. Unless noted in the command actions, a command that returns an error shall leave 4391 the state of the TPM as if the command had not been attempted. The exception to this principle is that a 4392 failure due to an authorization failure may update the dictionary-attack protection values. 4393 4394 Page 28 4395 October 31, 2013 4396 4397 Published 4398 Copyright TCG 2006-2013 4399 4400 Family 2.0 4401 Level 00 Revision 00.99 4402 4403 Trusted Platform Module Library 4405 6.6.2 4406 4407 Part 2: Structures 4408 4409 Response Code Formats 4410 4411 The response codes for this specification are defined such that there is no overlap between the response 4412 codes used for this specification and those assigned in previous TPM specifications. 4413 The formats defined in this clause only apply when the tag for the response is TPM_ST_NO_SESSIONS. 4414 The response codes use two different format groups. One group contains the TPM 1.2 compatible 4415 response codes and the response codes for this specification that are not related to command 4416 parameters. The second group contains the errors that may be associated with a command parameter, 4417 handle, or session. 4418 Figure 2 shows the format for the response codes when bit 7 is zero. 4419 1 4420 1 4421 4422 1 4423 0 4424 4425 0 4426 9 4427 4428 0 4429 8 4430 4431 0 4432 7 4433 4434 S 4435 4436 bit 4437 4438 T 4439 4440 r 4441 4442 V 4443 4444 0 4445 6 4446 4447 0 4448 5 4449 4450 F 4451 4452 0 4453 4 4454 4455 0 4456 3 4457 4458 0 4459 2 4460 4461 0 4462 1 4463 4464 0 4465 0 4466 4467 E 4468 4469 Figure 2 Format-Zero Response Codes 4470 4471 Family 2.0 4472 Level 00 Revision 00.99 4473 4474 Published 4475 Copyright TCG 2006-2013 4476 4477 Page 29 4478 October 31, 2013 4479 4480 Part 2: Structures 4482 4483 Trusted Platform Module Library 4484 4485 The field definitions are: 4486 Table 12 Format-Zero Response Codes 4487 Bit 4488 4489 Name 4490 4491 Definition 4492 4493 06:00 4494 4495 E 4496 4497 the error number 4498 The interpretation of this field is dependent on the setting of the G and S fields. 4499 4500 07 4501 4502 F 4503 4504 format selector 4505 CLEAR when the format is as defined in this Table 12 or when the response code is 4506 TPM_RC_BAD_TAG. 4507 4508 08 4509 4510 V 4511 4512 version 4513 SET (1): The error number is defined in this specification and is returned when the response tag 4514 is TPM_ST_NO_SESSIONS. 4515 CLEAR (0): The error number is defined by a previous TPM specification. The error number is 4516 returned when the response tag is TPM_TAG_RSP_COMMAND. 4517 NOTE 4518 4519 09 4520 4521 In any error number returned by a TPM, the F (bit 7) and V (bit 8) attributes shall be CLEAR 4522 when the response tag is TPM_TAG_RSP_COMMAND value used in TPM 1.2. 4523 4524 Reserved shall be zero. 4525 4526 10 4527 4528 T 4529 4530 TCG/Vendor indicator 4531 SET (1): The response code is defined by the TPM vendor. 4532 CLEAR (0): The response code is defined by the TCG (a value in this specification). 4533 NOTE 4534 4535 11 4536 4537 S 4538 4539 This attribute does not indicate a vendor-specific code unless the F attribute (bit[07]) is CLEAR. 4540 4541 severity 4542 SET (1): The response code is a warning and the command was not necessarily in error. This 4543 command indicates that the TPM is busy or that the resources of the TPM have to be adjusted in 4544 order to allow the command to execute. 4545 CLEAR (0): The response code indicates that the command had an error that would prevent it 4546 from running. 4547 4548 When the format bit (bit 7) is SET, then the error occurred during the unmarshaling or validation of an 4549 input parameter to the TPM. Figure 3 shows the format for the response codes when bit 7 is one. 4550 bit 4551 4552 1 4553 1 4554 4555 1 4556 0 4557 4558 0 4559 9 4560 4561 N 4562 4563 0 4564 8 4565 4566 0 4567 7 4568 4569 0 4570 6 4571 4572 1 4573 4574 0 4575 5 4576 4577 P 4578 4579 0 4580 4 4581 4582 0 4583 3 4584 4585 0 4586 2 4587 4588 0 4589 1 4590 4591 0 4592 0 4593 4594 E 4595 4596 Figure 3 Format-One Response Codes 4597 There are 64 errors with this format. The errors can be associated with a parameter, handle, or session. 4598 The error number for this format is in bits[05:00]. When an error is associated with a parameter, 0 40 16 is 4599 added and N is set to the parameter number. 4600 For an error associated with a handle, a parameter number (1 to 7) is added to the N field. For an error 4601 associated with a session, a value of 8 plus the session number (1 to 7) is added to the N field. In other 4602 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 4603 will indicate a session error. 4604 NOTE 4605 4606 If an implementation is not able to designate the handle, session, or parameter in error, then P and N will 4607 be zero. 4608 4609 Page 30 4610 October 31, 2013 4611 4612 Published 4613 Copyright TCG 2006-2013 4614 4615 Family 2.0 4616 Level 00 Revision 00.99 4617 4618 Trusted Platform Module Library 4620 4621 Part 2: Structures 4622 4623 The field definitions are: 4624 Table 13 Format-One Response Codes 4625 Bit 4626 4627 Name Definition 4628 4629 05:00 4630 4631 E 4632 4633 the error number 4634 The error number is independent of the other settings. 4635 4636 06 4637 4638 P 4639 4640 SET (1): The error is associated with a parameter. 4641 CLEAR (0): The error is associated with a handle or a session. 4642 4643 07 4644 4645 F 4646 4647 the response code format selector 4648 This field shall be SET for the format in this table. 4649 4650 11:08 4651 4652 N 4653 4654 the number of the handle, session, or parameter in error 4655 If P is SET, then this field is the parameter in error. If P is CLEAR, then this field indicates the 4656 handle or session in error. Handles use values of N between 0000 2 and 01112. Sessions use 4657 values between 10002 and 11112. 4658 4659 The groupings of response codes are determined by bits 08, 07, and 06 of the response code as 4660 summarized in Table 14. 4661 Table 14 Response Code Groupings 4662 Bit 4663 0 4664 8 4665 4666 0 4667 7 4668 4669 0 4670 6 4671 4672 Definition 4673 4674 0 4675 4676 0 4677 4678 x 4679 4680 a response code defined by TPM 1.2 4681 NOTE 4682 4683 An x in a column indicates that this may be either 0 or 1 and not affect the grouping of the response 4684 code. 4685 4686 1 4687 4688 0 4689 4690 x 4691 4692 a response code defined by this specification with no handle, session, or parameter number modifier 4693 4694 x 4695 4696 1 4697 4698 0 4699 4700 a response code defined by this specification with either a handle or session number modifier 4701 4702 x 4703 4704 1 4705 4706 1 4707 4708 a response code defined by this specification with a parameter number modifier 4709 4710 Family 2.0 4711 Level 00 Revision 00.99 4712 4713 Published 4714 Copyright TCG 2006-2013 4715 4716 Page 31 4717 October 31, 2013 4718 4719 Part 2: Structures 4721 6.6.3 4722 4723 Trusted Platform Module Library 4724 4725 TPM_RC Values 4726 4727 In general, response codes defined in Part 2 will be unmarshaling errors and will have the F (format) bit 4728 SET. Codes that are unique to Part 3 will have the F bit CLEAR but the V (version) attribute will be SET to 4729 indicate that it is a TPM 2.0 response code. 4730 NOTE 4731 4732 The constant RC_VER1 is used to indicate that the V attribute is SET and the constant RC_ FMT1 is used 4733 to indicate that the F attribute is SET and that the return code is variable based on handle, session, and 4734 parameter modifiers. 4735 4736 Table 15 Definition of (UINT32) TPM_RC Constants (Actions) <OUT> 4737 Name 4738 4739 Value 4740 4741 Description 4742 4743 TPM_RC_SUCCESS 4744 4745 0x000 4746 4747 TPM_RC_BAD_TAG 4748 4749 0x01E 4750 4751 defined for compatibility with TPM 1.2 4752 4753 RC_VER1 4754 4755 0x100 4756 4757 set for all format 0 response codes 4758 4759 TPM_RC_INITIALIZE 4760 4761 RC_VER1 + 0x000 4762 4763 TPM not initialized 4764 commands not being accepted because of a TPM 4765 failure 4766 4767 TPM_RC_FAILURE 4768 4769 RC_VER1 + 0x001 4770 4771 NOTE 4772 4773 TPM_RC_SEQUENCE 4774 4775 RC_VER1 + 0x003 4776 4777 improper use of a sequence handle 4778 4779 TPM_RC_PRIVATE 4780 4781 RC_VER1 + 0x00B 4782 4783 TPM_RC_HMAC 4784 4785 RC_VER1 + 0x019 4786 4787 TPM_RC_DISABLED 4788 4789 RC_VER1 + 0x020 4790 4791 TPM_RC_EXCLUSIVE 4792 4793 RC_VER1 + 0x021 4794 4795 command failed because audit sequence required 4796 exclusivity 4797 4798 TPM_RC_AUTH_TYPE 4799 4800 RC_VER1 + 0x024 4801 4802 authorization handle is not correct for command 4803 4804 TPM_RC_AUTH_MISSING 4805 4806 RC_VER1 + 0x025 4807 4808 command requires an authorization session for 4809 handle and it is not present. 4810 4811 TPM_RC_POLICY 4812 4813 RC_VER1 + 0x026 4814 4815 policy Failure In Math Operation or an invalid 4816 authPolicy value 4817 4818 TPM_RC_PCR 4819 4820 RC_VER1 + 0x027 4821 4822 PCR check fail 4823 4824 TPM_RC_PCR_CHANGED 4825 4826 RC_VER1 + 0x028 4827 4828 PCR have changed since checked. 4829 4830 TPM_RC_UPGRADE 4831 4832 RC_VER1 + 0x02D 4833 4834 for 4835 all 4836 commands 4837 other 4838 than 4839 TPM2_FieldUpgradeData(), this code indicates 4840 that the TPM is in field upgrade mode; for 4841 TPM2_FieldUpgradeData(), this code indicates 4842 that the TPM is not in field upgrade mode 4843 4844 TPM_RC_TOO_MANY_CONTEXTS 4845 4846 RC_VER1 + 0x02E 4847 4848 context ID counter is at maximum. 4849 4850 TPM_RC_AUTH_UNAVAILABLE 4851 4852 RC_VER1 + 0x02F 4853 4854 authValue or authPolicy is not available for 4855 selected entity. 4856 4857 TPM_RC_REBOOT 4858 4859 RC_VER1 + 0x030 4860 4861 a _TPM_Init and Startup(CLEAR) is required 4862 before the TPM can resume operation. 4863 4864 RC_VER1 + 0x031 4865 4866 the protection algorithms (hash and symmetric) are 4867 not reasonably balanced. The digest size of the 4868 hash must be larger than the key size of the 4869 symmetric algorithm. 4870 4871 TPM_RC_UNBALANCED 4872 4873 Page 32 4874 October 31, 2013 4875 4876 This 4877 may 4878 be 4879 returned 4880 by 4881 TPM2_GetTestResult() as the testResult 4882 parameter. 4883 4884 Published 4885 Copyright TCG 2006-2013 4886 4887 Family 2.0 4888 Level 00 Revision 00.99 4889 4890 Trusted Platform Module Library 4892 Name 4893 4894 Part 2: Structures 4895 Value 4896 4897 Description 4898 4899 TPM_RC_COMMAND_SIZE 4900 4901 RC_VER1 + 0x042 4902 4903 command commandSize value is inconsistent with 4904 contents of the command buffer; either the size is 4905 not the same as the octets loaded by the hardware 4906 interface layer or the value is not large enough to 4907 hold a command header 4908 4909 TPM_RC_COMMAND_CODE 4910 4911 RC_VER1 + 0x043 4912 4913 command code not supported 4914 4915 TPM_RC_AUTHSIZE 4916 4917 RC_VER1 + 0x044 4918 4919 the value of authorizationSize is out of range or the 4920 number of octets in the Authorization Area is 4921 greater than required 4922 4923 TPM_RC_AUTH_CONTEXT 4924 4925 RC_VER1 + 0x045 4926 4927 use of an authorization session with a context 4928 command 4929 4930 TPM_RC_NV_RANGE 4931 4932 RC_VER1 + 0x046 4933 4934 NV offset+size is out of range. 4935 4936 TPM_RC_NV_SIZE 4937 4938 RC_VER1 + 0x047 4939 4940 Requested allocation size is larger than allowed. 4941 4942 TPM_RC_NV_LOCKED 4943 4944 RC_VER1 + 0x048 4945 4946 NV access locked. 4947 4948 TPM_RC_NV_AUTHORIZATION 4949 4950 RC_VER1 + 0x049 4951 4952 NV access authorization fails in command actions 4953 (this failure does not affect lockout.action) 4954 4955 TPM_RC_NV_UNINITIALIZED 4956 4957 RC_VER1 + 0x04A 4958 4959 an NV Index is used before being initialized or the 4960 state saved by TPM2_Shutdown(STATE) could not 4961 be restored 4962 4963 TPM_RC_NV_SPACE 4964 4965 RC_VER1 + 0x04B 4966 4967 insufficient space for NV allocation 4968 4969 TPM_RC_NV_DEFINED 4970 4971 RC_VER1 + 0x04C 4972 4973 NV Index or persistend object already defined 4974 4975 TPM_RC_BAD_CONTEXT 4976 4977 RC_VER1 + 0x050 4978 4979 context in TPM2_ContextLoad() is not valid 4980 4981 TPM_RC_CPHASH 4982 4983 RC_VER1 + 0x051 4984 4985 cpHash value already set or not correct for use 4986 4987 TPM_RC_PARENT 4988 4989 RC_VER1 + 0x052 4990 4991 handle for parent is not a valid parent 4992 4993 TPM_RC_NEEDS_TEST 4994 4995 RC_VER1 + 0x053 4996 4997 some function needs testing. 4998 4999 RC_VER1 + 0x054 5000 5001 returned when an internal function cannot process 5002 a request due to an unspecified problem. This 5003 code is usually related to invalid parameters that 5004 are not properly filtered by the input unmarshaling 5005 code. 5006 5007 TPM_RC_SENSITIVE 5008 5009 RC_VER1 + 0x055 5010 5011 the sensitive area did not unmarshal correctly after 5012 decryption this code is used in lieu of the other 5013 unmarshaling errors so that an attacker cannot 5014 determine where the unmarshaling error occurred 5015 5016 RC_MAX_FM0 5017 5018 RC_VER1 + 0x07F 5019 5020 largest version 1 code that is not a warning 5021 5022 TPM_RC_NO_RESULT 5023 5024 New Subsection 5025 5026 RC_FMT1 5027 5028 0x080 5029 5030 This bit is SET in all format 1 response codes 5031 The codes in this group may have a value added to 5032 them to indicate the handle, session, or parameter 5033 to which they apply. 5034 5035 TPM_RC_ASYMMETRIC 5036 5037 RC_FMT1 + 0x001 5038 5039 asymmetric algorithm not supported or not correct 5040 5041 TPM_RC_ATTRIBUTES 5042 5043 RC_FMT1 + 0x002 5044 5045 inconsistent attributes 5046 5047 TPM_RC_HASH 5048 5049 RC_FMT1 + 0x003 5050 5051 hash algrithm not supported or not appropriate 5052 5053 TPM_RC_VALUE 5054 5055 RC_FMT1 + 0x004 5056 5057 value is out of range or is not correct for the 5058 context 5059 5060 TPM_RC_HIERARCHY 5061 5062 RC_FMT1 + 0x005 5063 5064 hierarchy is not enabled or is not correct for the 5065 use 5066 5067 Family 2.0 5068 Level 00 Revision 00.99 5069 5070 Published 5071 Copyright TCG 2006-2013 5072 5073 Page 33 5074 October 31, 2013 5075 5076 Part 2: Structures 5078 5079 Trusted Platform Module Library 5080 5081 Name 5082 5083 Value 5084 5085 Description 5086 5087 TPM_RC_KEY_SIZE 5088 5089 RC_FMT1 + 0x007 5090 5091 key size is not supported 5092 5093 TPM_RC_MGF 5094 5095 RC_FMT1 + 0x008 5096 5097 mask generation function not supported 5098 5099 TPM_RC_MODE 5100 5101 RC_FMT1 + 0x009 5102 5103 mode of operation not supported 5104 5105 TPM_RC_TYPE 5106 5107 RC_FMT1 + 0x00A 5108 5109 the type of the value is not appropriate for the use 5110 5111 TPM_RC_HANDLE 5112 5113 RC_FMT1 + 0x00B 5114 5115 the handle is not correct for the use 5116 5117 TPM_RC_KDF 5118 5119 RC_FMT1 + 0x00C 5120 5121 unsupported key derivation function or function not 5122 appropriate for use 5123 5124 TPM_RC_RANGE 5125 5126 RC_FMT1 + 0x00D 5127 5128 value was out of allowed range. 5129 5130 TPM_RC_AUTH_FAIL 5131 5132 RC_FMT1 + 0x00E 5133 5134 the authorization HMAC check failed and DA 5135 counter incremented 5136 5137 TPM_RC_NONCE 5138 5139 RC_FMT1 + 0x00F 5140 5141 invalid nonce size 5142 5143 TPM_RC_PP 5144 5145 RC_FMT1 + 0x010 5146 5147 authorization requires assertion of PP 5148 5149 TPM_RC_SCHEME 5150 5151 RC_FMT1 + 0x012 5152 5153 unsupported or incompatible scheme 5154 5155 TPM_RC_SIZE 5156 5157 RC_FMT1 + 0x015 5158 5159 structure is the wrong size 5160 5161 TPM_RC_SYMMETRIC 5162 5163 RC_FMT1 + 0x016 5164 5165 unsupported symmetric algorithm or key size, or 5166 not appropriate for instance 5167 5168 TPM_RC_TAG 5169 5170 RC_FMT1 + 0x017 5171 5172 incorrect structure tag 5173 5174 TPM_RC_SELECTOR 5175 5176 RC_FMT1 + 0x018 5177 5178 union selector is incorrect 5179 5180 TPM_RC_INSUFFICIENT 5181 5182 RC_FMT1 + 0x01A 5183 5184 the TPM was unable to unmarshal a value 5185 because there were not enough octets in the input 5186 buffer 5187 5188 TPM_RC_SIGNATURE 5189 5190 RC_FMT1 + 0x01B 5191 5192 the signature is not valid 5193 5194 TPM_RC_KEY 5195 5196 RC_FMT1 + 0x01C 5197 5198 key fields are not compatible with the selected use 5199 5200 TPM_RC_POLICY_FAIL 5201 5202 RC_FMT1 + 0x01D 5203 5204 a policy check failed 5205 5206 TPM_RC_INTEGRITY 5207 5208 RC_FMT1 + 0x01F 5209 5210 integrity check failed 5211 5212 TPM_RC_TICKET 5213 5214 RC_FMT1 + 0x020 5215 5216 invalid ticket 5217 5218 TPM_RC_RESERVED_BITS 5219 5220 RC_FMT1 + 0x021 5221 5222 reserved bits not set to zero as required 5223 5224 TPM_RC_BAD_AUTH 5225 5226 RC_FMT1 + 0x022 5227 5228 authroization failure without DA implications 5229 5230 TPM_RC_EXPIRED 5231 5232 RC_FMT1 + 0x023 5233 5234 the policy has expired 5235 5236 TPM_RC_POLICY_CC 5237 5238 RC_FMT1 + 0x024 5239 5240 the commandCode in the policy is not the 5241 commandCode of the command or the command 5242 code in a policy command references a command 5243 that is not implemented 5244 5245 TPM_RC_BINDING 5246 5247 RC_FMT1 + 0x025 5248 5249 public and sensitive portions of an object are not 5250 cryptographically bound 5251 5252 TPM_RC_CURVE 5253 5254 RC_FMT1 + 0x026 5255 5256 curve not supported 5257 5258 TPM_RC_ECC_POINT 5259 5260 RC_FMT1 + 0x027 5261 5262 point is not on the required curve. 5263 5264 New Subsection 5265 RC_WARN 5266 5267 0x900 5268 5269 set for warning response codes 5270 5271 TPM_RC_CONTEXT_GAP 5272 5273 RC_WARN + 0x001 5274 5275 gap for context ID is too large 5276 5277 TPM_RC_OBJECT_MEMORY 5278 5279 RC_WARN + 0x002 5280 5281 out of memory for object contexts 5282 5283 Page 34 5284 October 31, 2013 5285 5286 Published 5287 Copyright TCG 2006-2013 5288 5289 Family 2.0 5290 Level 00 Revision 00.99 5291 5292 Trusted Platform Module Library 5294 5295 Part 2: Structures 5296 5297 Name 5298 5299 Value 5300 5301 Description 5302 5303 TPM_RC_SESSION_MEMORY 5304 5305 RC_WARN + 0x003 5306 5307 out of memory for session contexts 5308 5309 TPM_RC_MEMORY 5310 5311 RC_WARN + 0x004 5312 5313 out of shared object/session memory or need 5314 space for internal operations 5315 5316 TPM_RC_SESSION_HANDLES 5317 5318 RC_WARN + 0x005 5319 5320 out of session handles a session must be flushed 5321 before a new session may be created 5322 out of object handles the handle space for 5323 objects is depleted and a reboot is required 5324 NOTE 5325 5326 TPM_RC_LOCALITY 5327 5328 TPM_RC_YIELDED 5329 5330 This cannot occur 5331 implementation. 5332 5333 NOTE 5334 5335 TPM_RC_OBJECT_HANDLES 5336 5337 There is no reason why an implementation 5338 would implement a design that would deplete 5339 handle space. Platform specifications are 5340 encouraged to forbid it. 5341 5342 RC_WARN + 0x006 5343 5344 RC_WARN + 0x007 5345 5346 RC_WARN + 0x008 5347 5348 on 5349 5350 the 5351 5352 reference 5353 5354 bad locality 5355 the TPM has suspended operation on the 5356 command; forward progress was made and the 5357 command may be retried. 5358 See Part 1, Multi-tasking. 5359 NOTE 5360 5361 This cannot occur 5362 implementation. 5363 5364 on 5365 5366 the 5367 5368 reference 5369 5370 TPM_RC_CANCELED 5371 5372 RC_WARN + 0x009 5373 5374 the command was canceled 5375 5376 TPM_RC_TESTING 5377 5378 RC_WARN + 0x00A 5379 5380 TPM is performing self-tests 5381 5382 TPM_RC_REFERENCE_H0 5383 5384 RC_WARN + 0x010 5385 5386 the 1 handle in the handle area references a 5387 transient object or session that is not loaded 5388 5389 TPM_RC_REFERENCE_H1 5390 5391 RC_WARN + 0x011 5392 5393 the 2 handle in the handle area references a 5394 transient object or session that is not loaded 5395 5396 TPM_RC_REFERENCE_H2 5397 5398 RC_WARN + 0x012 5399 5400 the 3 handle in the handle area references a 5401 transient object or session that is not loaded 5402 5403 TPM_RC_REFERENCE_H3 5404 5405 RC_WARN + 0x013 5406 5407 the 4 handle in the handle area references a 5408 transient object or session that is not loaded 5409 5410 TPM_RC_REFERENCE_H4 5411 5412 RC_WARN + 0x014 5413 5414 the 5 handle in the handle area references a 5415 transient object or session that is not loaded 5416 5417 TPM_RC_REFERENCE_H5 5418 5419 RC_WARN + 0x015 5420 5421 the 6 handle in the handle area references a 5422 transient object or session that is not loaded 5423 5424 TPM_RC_REFERENCE_H6 5425 5426 RC_WARN + 0x016 5427 5428 the 7 handle in the handle area references a 5429 transient object or session that is not loaded 5430 5431 TPM_RC_REFERENCE_S0 5432 5433 RC_WARN + 0x018 5434 5435 the 1 authorization session handle references a 5436 session that is not loaded 5437 5438 TPM_RC_REFERENCE_S1 5439 5440 RC_WARN + 0x019 5441 5442 the 2 authorization session handle references a 5443 session that is not loaded 5444 5445 TPM_RC_REFERENCE_S2 5446 5447 RC_WARN + 0x01A 5448 5449 the 3 authorization session handle references a 5450 session that is not loaded 5451 5452 TPM_RC_REFERENCE_S3 5453 5454 RC_WARN + 0x01B 5455 5456 the 4th authorization session handle references a 5457 session that is not loaded 5458 5459 TPM_RC_REFERENCE_S4 5460 5461 RC_WARN + 0x01C 5462 5463 the 5 session handle references a session that is 5464 not loaded 5465 5466 TPM_RC_REFERENCE_S5 5467 5468 RC_WARN + 0x01D 5469 5470 the 6 session handle references a session that is 5471 not loaded 5472 5473 st 5474 5475 nd 5476 5477 rd 5478 5479 th 5480 5481 th 5482 5483 th 5484 5485 th 5486 5487 st 5488 5489 nd 5490 5491 rd 5492 5493 th 5494 5495 th 5496 5497 Family 2.0 5498 Level 00 Revision 00.99 5499 5500 Published 5501 Copyright TCG 2006-2013 5502 5503 Page 35 5504 October 31, 2013 5505 5506 Part 2: Structures 5508 5509 Trusted Platform Module Library 5510 5511 Name 5512 5513 Value 5514 5515 Description 5516 5517 TPM_RC_REFERENCE_S6 5518 5519 RC_WARN + 0x01E 5520 5521 the 7 authorization session handle references a 5522 session that is not loaded 5523 5524 TPM_RC_NV_RATE 5525 5526 RC_WARN + 0x020 5527 5528 the TPM is rate-limiting accesses to prevent 5529 wearout of NV 5530 5531 TPM_RC_LOCKOUT 5532 5533 RC_WARN + 0x021 5534 5535 authorizations for objects subject to DA protection 5536 are not allowed at this time because the TPM is in 5537 DA lockout mode 5538 5539 TPM_RC_RETRY 5540 5541 RC_WARN + 0x022 5542 5543 the TPM was not able to start the command 5544 5545 TPM_RC_NV_UNAVAILABLE 5546 5547 RC_WARN + 0x023 5548 5549 the command may require writing of NV and NV is 5550 not current accessible 5551 5552 TPM_RC_NOT_USED 5553 5554 RC_WARN + 0x7F 5555 5556 this value is reserved and shall not be returned by 5557 the TPM 5558 5559 th 5560 5561 Additional Defines 5562 TPM_RC_H 5563 5564 0x000 5565 5566 add to a handle-related error 5567 5568 TPM_RC_P 5569 5570 0x040 5571 5572 add to a parameter-related error 5573 5574 TPM_RC_S 5575 5576 0x800 5577 5578 add to a session-related error 5579 5580 TPM_RC_1 5581 5582 0x100 5583 5584 add to a parameter-, handle-, or session-related 5585 error 5586 5587 TPM_RC_2 5588 5589 0x200 5590 5591 add to a parameter-, handle-, or session-related 5592 error 5593 5594 TPM_RC_3 5595 5596 0x300 5597 5598 add to a parameter-, handle-, or session-related 5599 error 5600 5601 TPM_RC_4 5602 5603 0x400 5604 5605 add to a parameter-, handle-, or session-related 5606 error 5607 5608 TPM_RC_5 5609 5610 0x500 5611 5612 add to a parameter-, handle-, or session-related 5613 error 5614 5615 TPM_RC_6 5616 5617 0x600 5618 5619 add to a parameter-, handle-, or session-related 5620 error 5621 5622 TPM_RC_7 5623 5624 0x700 5625 5626 add to a parameter-, handle-, or session-related 5627 error 5628 5629 TPM_RC_8 5630 5631 0x800 5632 5633 add to a parameter-related error 5634 5635 TPM_RC_9 5636 5637 0x900 5638 5639 add to a parameter-related error 5640 5641 TPM_RC_A 5642 5643 0xA00 5644 5645 add to a parameter-related error 5646 5647 TPM_RC_B 5648 5649 0xB00 5650 5651 add to a parameter-related error 5652 5653 TPM_RC_C 5654 5655 0xC00 5656 5657 add to a parameter-related error 5658 5659 TPM_RC_D 5660 5661 0xD00 5662 5663 add to a parameter-related error 5664 5665 TPM_RC_E 5666 5667 0xE00 5668 5669 add to a parameter-related error 5670 5671 TPM_RC_F 5672 5673 0xF00 5674 5675 add to a parameter-related error 5676 5677 TPM_RC_N_MASK 5678 5679 0xF00 5680 5681 number mask 5682 5683 Page 36 5684 October 31, 2013 5685 5686 Published 5687 Copyright TCG 2006-2013 5688 5689 Family 2.0 5690 Level 00 Revision 00.99 5691 5692 Trusted Platform Module Library 5694 6.7 5695 5696 Part 2: Structures 5697 5698 TPM_CLOCK_ADJUST 5699 5700 A TPM_CLOCK_ADJUST value is used to change the rate at which the TPM internal oscillator is divided. 5701 A change to the divider will change the rate at which Clock and Time change. 5702 NOTE 5703 5704 The recommended adjustments are approximately 1% for a course adjustment, 0.1% for a medium 5705 adjustment, and the minimum possible on the implementation for the fine adjustment (e.g., one count of 5706 the pre-scalar if possible). 5707 5708 Table 16 Definition of (INT8) TPM_CLOCK_ADJUST Constants <IN> 5709 Name 5710 5711 Value 5712 5713 Comments 5714 5715 TPM_CLOCK_COARSE_SLOWER 5716 5717 -3 5718 5719 Slow the Clock update rate by one coarse adjustment step. 5720 5721 TPM_CLOCK_MEDIUM_SLOWER 5722 5723 -2 5724 5725 Slow the Clock update rate by one medium adjustment step. 5726 5727 TPM_CLOCK_FINE_SLOWER 5728 5729 -1 5730 5731 Slow the Clock update rate by one fine adjustment step. 5732 5733 TPM_CLOCK_NO_CHANGE 5734 5735 0 5736 5737 No change to the Clock update rate. 5738 5739 TPM_CLOCK_FINE_FASTER 5740 5741 1 5742 5743 Speed the Clock update rate by one fine adjustment step. 5744 5745 TPM_CLOCK_MEDIUM_FASTER 5746 5747 2 5748 5749 Speed the Clock update rate by one medium adjustment step. 5750 5751 TPM_CLOCK_COARSE_FASTER 5752 5753 3 5754 5755 Speed the Clock update rate by one coarse adjustment step. 5756 5757 #TPM_RC_VALUE 5758 5759 6.8 5760 5761 TPM_EO (EA Arithmetic Operands) 5762 Table 17 Definition of (UINT16) TPM_EO Constants <IN/OUT> 5763 5764 Operation Name 5765 5766 Value 5767 5768 Comments 5769 5770 TPM_EO_EQ 5771 5772 0x0000 5773 5774 A=B 5775 5776 TPM_EO_NEQ 5777 5778 0x0001 5779 5780 AB 5781 5782 TPM_EO_SIGNED_GT 5783 5784 0x0002 5785 5786 A > B signed 5787 5788 TPM_EO_UNSIGNED_GT 5789 5790 0x0003 5791 5792 A > B unsigned 5793 5794 TPM_EO_SIGNED_LT 5795 5796 0x0004 5797 5798 A < B signed 5799 5800 TPM_EO_UNSIGNED_LT 5801 5802 0x0005 5803 5804 A < B unsigned 5805 5806 TPM_EO_SIGNED_GE 5807 5808 0x0006 5809 5810 A B signed 5811 5812 TPM_EO_UNSIGNED_GE 5813 5814 0x0007 5815 5816 A B unsigned 5817 5818 TPM_EO_SIGNED_LE 5819 5820 0x0008 5821 5822 A B signed 5823 5824 TPM_EO_UNSIGNED_LE 5825 5826 0x0009 5827 5828 A B unsigned 5829 5830 TPM_EO_BITSET 5831 5832 0x000A 5833 5834 All bits SET in B are SET in A. ((A&B)=B) 5835 5836 TPM_EO_BITCLEAR 5837 5838 0x000B 5839 5840 All bits SET in B are CLEAR in A. ((A&B)=0) 5841 5842 #TPM_RC_VALUE 5843 5844 Family 2.0 5845 Level 00 Revision 00.99 5846 5847 Response code returned when unmarshaling of this type fails 5848 5849 Published 5850 Copyright TCG 2006-2013 5851 5852 Page 37 5853 October 31, 2013 5854 5855 Part 2: Structures 5857 5858 6.9 5859 5860 Trusted Platform Module Library 5861 5862 TPM_ST (Structure Tags) 5863 5864 Structure tags are used to disambiguate structures. They are 16-bit values with the most significant bit 5865 SET so that they do not overlap TPM_ALG_ID values. A single exception is made for the value 5866 associated with TPM_ST_RSP_COMMAND (0x00C4), which has the same value as the 5867 TPM_TAG_RSP_COMMAND tag from earlier versions of this specification. This value is used when the 5868 TPM is compatible with a previous TPM specification and the TPM cannot determine which family of 5869 response code to return because the command tag is not valid. 5870 Many of the structures defined in this document have parameters that are unions of other structures. That 5871 is, a parameter may be one of several structures. The parameter will have a selector value that indicates 5872 which of the options is actually present. 5873 In order to allow the marshaling and unmarshaling code to determine which of the possible structures is 5874 allowed, each selector will have a unique interface type and will constrain the number of possible tag 5875 values. 5876 Table 18 defines the structure tags values. The definition of many structures is context-sensitive using an 5877 algorithm ID. In cases where an algorithm ID is not a meaningful way to designate the structure, the 5878 values in this table are used. 5879 Table 18 Definition of (UINT16) TPM_ST Constants <IN/OUT, S> 5880 Name 5881 TPM_ST_RSP_COMMAND 5882 5883 Value 5884 5885 Comments 5886 5887 0x00C4 5888 5889 tag value for a response; used when there is an error 5890 in the tag. This is also the value returned from a TPM 5891 1.2 when an error occurs. This value is used in this 5892 specification because an error in the command tag 5893 may prevent determination of the family. When this tag 5894 is used in the response, the response code will be 5895 TPM_RC_BAD_TAG (0 1E16), which has the same 5896 numeric value as the TPM 1.2 response code for 5897 TPM_BADTAG. 5898 NOTE 5899 5900 In a previously published version of this 5901 specification, 5902 TPM_RC_BAD_TAG 5903 was 5904 incorrectly assigned a value of 0x030 instead of 5905 30 (0x01e). Some implementations my return the 5906 old value instead of the new value. 5907 5908 TPM_ST_NULL 5909 5910 0X8000 5911 5912 no structure type specified 5913 5914 TPM_ST_NO_SESSIONS 5915 5916 0x8001 5917 5918 tag value for a command/response for a command 5919 defined in this specification; indicating that the 5920 command/response has no attached sessions and no 5921 authorizationSize/parameterSize value is present 5922 If the responseCode from the TPM is not 5923 TPM_RC_SUCCESS, then the response tag shall 5924 have this value. 5925 5926 TPM_ST_SESSIONS 5927 5928 0x8002 5929 5930 tag value for a command/response for a command 5931 defined in this specification; indicating that the 5932 command/response has one or more attached 5933 sessions and the authorizationSize/parameterSize 5934 field is present 5935 5936 Page 38 5937 October 31, 2013 5938 5939 Published 5940 Copyright TCG 2006-2013 5941 5942 Family 2.0 5943 Level 00 Revision 00.99 5944 5945 Trusted Platform Module Library 5947 Name 5948 reserved 5949 5950 Part 2: Structures 5951 Value 5952 5953 Comments 5954 5955 0x8003 5956 5957 When used between application software and the TPM 5958 resource manager, this tag indicates that the 5959 command has no sessions and the handles are using 5960 the Name format rather than the 32-bit handle format. 5961 NOTE 1 5962 5963 The response to application software will have a 5964 tag of TPM_ST_NO_SESSIONS. 5965 5966 Between the TRM and TPM, this tag would occur in a 5967 response from a TPM that overlaps the tag parameter 5968 of a request with the tag parameter of a response, 5969 when the response has no associated sessions. 5970 NOTE 2 5971 5972 reserved 5973 5974 0x8004 5975 5976 This tag is not used by all TPM or TRM 5977 implementations. 5978 5979 When used between application software and the TPM 5980 resource manager, this tag indicates that the 5981 command has sessions and the handles are using the 5982 Name format rather than the 32-bit handle format. 5983 NOTE 1 5984 5985 If the command completes successfully, the 5986 response to application software will have a tag 5987 of TPM_ST_SESSIONS. 5988 5989 Between the TRM and TPM, would occur in a 5990 response from a TPM that overlaps the tag parameter 5991 of a request with the tag parameter of a response, 5992 when the response has authorization sessions. 5993 NOTE 2 5994 5995 This tag is not used by all TPM or TRM 5996 implementations. 5997 5998 TPM_ST_ATTEST_NV 5999 6000 0x8014 6001 6002 tag for an attestation structure 6003 6004 TPM_ST_ATTEST_COMMAND_AUDIT 6005 6006 0x8015 6007 6008 tag for an attestation structure 6009 6010 TPM_ST_ATTEST_SESSION_AUDIT 6011 6012 0x8016 6013 6014 tag for an attestation structure 6015 6016 TPM_ST_ATTEST_CERTIFY 6017 6018 0x8017 6019 6020 tag for an attestation structure 6021 6022 TPM_ST_ATTEST_QUOTE 6023 6024 0x8018 6025 6026 tag for an attestation structure 6027 6028 TPM_ST_ATTEST_TIME 6029 6030 0x8019 6031 6032 tag for an attestation structure 6033 6034 TPM_ST_ATTEST_CREATION 6035 6036 0x801A 6037 6038 tag for an attestation structure 6039 6040 reserved 6041 6042 0x801B 6043 6044 do not use 6045 NOTE 6046 6047 This 6048 was 6049 previously 6050 assigned 6051 to 6052 TPM_ST_ATTEST_NV. The tag is changed 6053 because the structure has changed 6054 6055 TPM_ST_CREATION 6056 6057 0x8021 6058 6059 tag for a ticket type 6060 6061 TPM_ST_VERIFIED 6062 6063 0x8022 6064 6065 tag for a ticket type 6066 6067 TPM_ST_AUTH_SECRET 6068 6069 0x8023 6070 6071 tag for a ticket type 6072 6073 TPM_ST_HASHCHECK 6074 6075 0x8024 6076 6077 tag for a ticket type 6078 6079 TPM_ST_AUTH_SIGNED 6080 6081 0x8025 6082 6083 tag for a ticket type 6084 6085 TPM_ST_FU_MANIFEST 6086 6087 0x8029 6088 6089 tag for a structure describing a Field Upgrade Policy 6090 6091 Family 2.0 6092 Level 00 Revision 00.99 6093 6094 Published 6095 Copyright TCG 2006-2013 6096 6097 Page 39 6098 October 31, 2013 6099 6100 Part 2: Structures 6102 6103 Trusted Platform Module Library 6104 6105 6.10 TPM_SU (Startup Type) 6106 These values are used in TPM2_Startup() to indicate the shutdown and startup mode. The defined 6107 startup sequences are: 6108 a) TPM Reset Two cases: 6109 1) Shutdown(CLEAR) followed by Startup(CLEAR) 6110 2) Startup(CLEAR) with no Shutdown() 6111 b) TPM Restart Shutdown(STATE) followed by Startup(CLEAR) 6112 c) TPM Resume Shutdown(STATE) followed by Startup(STATE) 6113 TPM_SU values of 80 0016 and above are reserved for internal use of the TPM and may not be assigned 6114 values. 6115 NOTE 6116 6117 In the reference code, a value of FF FF 16 indicates that the startup state has not been set. If this was 6118 defined in this table to be, say, TPM_SU_NONE, then TPM_SU_NONE would be a valid input value but 6119 the caller is not allowed to indicate the that the startup type is TPM_SU_NONE so the reserved value is 6120 defined in the implementation as required for internal TPM uses. 6121 6122 Table 19 Definition of (UINT16) TPM_SU Constants <IN> 6123 Name 6124 6125 Value 6126 6127 Description 6128 6129 TPM_SU_CLEAR 6130 6131 0x0000 6132 6133 on TPM2_Shutdown(), indicates that the TPM should prepare 6134 for loss of power and save state required for an orderly startup 6135 (TPM Reset). 6136 on TPM2_Startup(), indicates that the TPM should start from 6137 perform TPM Reset or TPM Restart 6138 6139 TPM_SU_STATE 6140 6141 0x0001 6142 6143 on TPM2_Shutdown(), indicates that the TPM should prepare 6144 for loss of power and save state required for an orderly startup 6145 (TPM Restart or TPM Resume) 6146 on TPM2_Startup(), indicates that the TPM should restore the 6147 state saved by TPM2_Shutdown(TPM_SU_STATE) 6148 6149 #TPM_RC_VALUE 6150 6151 response code when incorrect value is used 6152 6153 6.11 TPM_SE (Session Type) 6154 This type is used in TPM2_StartAuthSession() to indicate the type of the session to be created. 6155 Table 20 Definition of (UINT8) TPM_SE Constants <IN> 6156 Name 6157 6158 Value 6159 6160 TPM_SE_HMAC 6161 6162 0x00 6163 6164 TPM_SE_POLICY 6165 6166 0x01 6167 6168 TPM_SE_TRIAL 6169 6170 0x03 6171 6172 #TPM_RC_VALUE 6173 6174 Page 40 6175 October 31, 2013 6176 6177 Description 6178 6179 The policy session is being used to compute the policyHash and 6180 not for command authorization. 6181 This setting modifies some policy commands and prevents 6182 session from being used to authorize a command. 6183 response code when incorrect value is used 6184 6185 Published 6186 Copyright TCG 2006-2013 6187 6188 Family 2.0 6189 Level 00 Revision 00.99 6190 6191 Trusted Platform Module Library 6193 6194 Part 2: Structures 6195 6196 6.12 TPM_CAP (Capabilities) 6197 The TPM_CAP values are used in TPM2_GetCapability() to select the type of the value to be returned. 6198 The format of the response varies according to the type of the value. 6199 Table 21 Definition of (UINT32) TPM_CAP Constants 6200 Capability Name 6201 6202 Value 6203 6204 Property Type 6205 6206 Return Type 6207 6208 TPM_CAP_FIRST 6209 6210 0x00000000 6211 6212 TPM_CAP_ALGS 6213 6214 0x00000000 TPM_ALG_ID 6215 6216 TPM_CAP_HANDLES 6217 6218 0x00000001 TPM_HANDLE 6219 6220 TPML_HANDLE 6221 6222 TPM_CAP_COMMANDS 6223 6224 0x00000002 TPM_CC 6225 6226 TPML_CCA 6227 6228 TPM_CAP_PP_COMMANDS 6229 6230 0x00000003 TPM_CC 6231 6232 TPML_CC 6233 6234 TPM_CAP_AUDIT_COMMANDS 6235 6236 0x00000004 TPM_CC 6237 6238 TPML_CC 6239 6240 TPM_CAP_PCRS 6241 6242 0x00000005 reserved 6243 6244 TPML_PCR_SELECTION 6245 6246 TPM_CAP_TPM_PROPERTIES 6247 6248 0x00000006 TPM_PT 6249 6250 TPML_TAGGED_TPM_PROPERTY 6251 6252 TPM_CAP_PCR_PROPERTIES 6253 6254 0x00000007 TPM_PT_PCR 6255 6256 (1) 6257 6258 TPM_CAP_ECC_CURVES 6259 6260 0x00000008 TPM_ECC_CURVE 6261 6262 TPM_CAP_LAST 6263 6264 TPML_ALG_PROPERTY 6265 6266 TPML_TAGGED_PCR_PROPERTY 6267 (1) 6268 6269 0x00000008 6270 6271 TPM_CAP_VENDOR_PROPERTY 0x00000100 manufacturer specific 6272 6273 TPML_ECC_CURVE 6274 6275 manufacturer-specific values 6276 6277 #TPM_RC_VALUE 6278 NOTES: 6279 (1) The TPM_ALG_ID or TPM_ECC_CURVE is cast to a UINT32 6280 6281 6.13 TPM_PT (Property Tag) 6282 The TPM_PT constants are used in TPM2_GetCapability(capability = TPM_CAP_TPM_PROPERTIES) to 6283 indicate the property being selected or returned. 6284 The values in the fixed group (PT_FIXED) are not changeable through programmatic means other than a 6285 firmware update. The values in the variable group (PT_VAR) may be changed with TPM commands but 6286 should be persistent over power cycles and only changed when indicated by the detailed actions code. 6287 Table 22 Definition of (UINT32) TPM_PT Constants <IN/OUT, S> 6288 Capability Name 6289 6290 Value 6291 6292 Comments 6293 6294 TPM_PT_NONE 6295 6296 0x00000000 6297 6298 indicates no property type 6299 6300 PT_GROUP 6301 6302 0x00000100 6303 6304 The number of properties in each group. 6305 NOTE The first group with any properties is group 1 6306 (PT_GROUP * 1). Group 0 is reserved. 6307 6308 PT_FIXED 6309 6310 PT_GROUP * 1 the 6311 group 6312 of 6313 fixed 6314 properties 6315 returned 6316 as 6317 TPMS_TAGGED_PROPERTY 6318 The values in this group are only changed due to a 6319 firmware change in the TPM. 6320 6321 TPM_PT_FAMILY_INDICATOR 6322 6323 PT_FIXED + 0 a 4-octet character string containing the TPM Family value 6324 (TPM_SPEC_FAMILY) 6325 6326 Family 2.0 6327 Level 00 Revision 00.99 6328 6329 Published 6330 Copyright TCG 2006-2013 6331 6332 Page 41 6333 October 31, 2013 6334 6335 Part 2: Structures 6337 6338 Capability Name 6339 TPM_PT_LEVEL 6340 6341 Trusted Platform Module Library 6342 6343 Value 6344 6345 Comments 6346 6347 PT_FIXED + 1 the level of the specification 6348 NOTE 1 6349 6350 TPM_PT_REVISION 6351 6352 For this specification, the level is zero. 6353 6354 NOTE 2 6355 6356 The level is on the title page of the specification. 6357 6358 PT_FIXED + 2 the specification Revision times 100 6359 EXAMPLE Revision 01.01 would have a value of 101. 6360 NOTE 6361 6362 TPM_PT_DAY_OF_YEAR 6363 6364 The Revision value is on the title page of the 6365 specification. 6366 6367 PT_FIXED + 3 the specification day of year using TCG calendar 6368 EXAMPLE November 15, 2010, has a day of year value of 319 6369 (00 00 01 3F16). 6370 NOTE 6371 6372 TPM_PT_YEAR 6373 6374 The specification date is on the title page of the 6375 specification. 6376 6377 PT_FIXED + 4 the specification year using the CE 6378 EXAMPLE The year 2010 has a value of 00 00 07 DA16. 6379 NOTE 6380 6381 The specification date is on the title page of the 6382 specification. 6383 6384 TPM_PT_MANUFACTURER 6385 6386 PT_FIXED + 5 the vendor ID unique to each TPM manufacturer 6387 6388 TPM_PT_VENDOR_STRING_1 6389 6390 PT_FIXED + 6 the first four characters of the vendor ID string 6391 NOTE 6392 6393 When the vendor string is fewer than 16 octets, the 6394 additional property values do not have to be present. 6395 A vendor string of 4 octets can be represented in one 6396 32-bit value and no null terminating character is 6397 required. 6398 6399 TPM_PT_VENDOR_STRING_2 6400 6401 PT_FIXED + 7 the second four characters of the vendor ID string 6402 6403 TPM_PT_VENDOR_STRING_3 6404 6405 PT_FIXED + 8 the third four characters of the vendor ID string 6406 6407 TPM_PT_VENDOR_STRING_4 6408 6409 PT_FIXED + 9 the fourth four characters of the vendor ID sting 6410 6411 TPM_PT_VENDOR_TPM_TYPE 6412 6413 PT_FIXED + 10 vendor-defined value indicating the TPM model 6414 6415 TPM_PT_FIRMWARE_VERSION_1 6416 6417 PT_FIXED + 11 the most-significant 32 bits of a vendor-specific value 6418 indicating the version of the firmware 6419 6420 TPM_PT_FIRMWARE_VERSION_2 6421 6422 PT_FIXED + 12 the least-significant 32 bits of a vendor-specific value 6423 indicating the version of the firmware 6424 6425 TPM_PT_INPUT_BUFFER 6426 6427 PT_FIXED + 13 the maximum size of 6428 TPM2B_MAX_BUFFER) 6429 6430 TPM_PT_HR_TRANSIENT_MIN 6431 6432 PT_FIXED + 14 the minimum number of transient objects that can be held 6433 in TPM RAM 6434 NOTE 6435 6436 TPM_PT_HR_PERSISTENT_MIN 6437 6438 parameter 6439 6440 (typically, 6441 6442 a 6443 6444 This minimum shall be no less than the minimum 6445 value required by the platform-specific specification 6446 to which the TPM is built. 6447 6448 PT_FIXED + 15 the minimum number of persistent objects that can be 6449 held in TPM NV memory 6450 NOTE 6451 6452 TPM_PT_HR_LOADED_MIN 6453 6454 a 6455 6456 This minimum shall be no less than the minimum 6457 value required by the platform-specific specification 6458 to which the TPM is built. 6459 6460 PT_FIXED + 16 the minimum number of authorization sessions that can 6461 be held in TPM RAM 6462 NOTE 6463 6464 Page 42 6465 October 31, 2013 6466 6467 This minimum shall be no less than the minimum 6468 value required by the platform-specific specification 6469 to which the TPM is built. 6470 6471 Published 6472 6473 Family 2.0 6474 6475 Copyright TCG 2006-2013 6476 6477 Level 00 Revision 00.99 6478 6479 Trusted Platform Module Library 6481 Capability Name 6482 TPM_PT_ACTIVE_SESSIONS_MAX 6483 6484 Part 2: Structures 6485 Value 6486 6487 Comments 6488 6489 PT_FIXED + 17 the number of authorization sessions that may be active at 6490 a time 6491 A session is active when it has a context associated with 6492 its handle. The context may either be in TPM RAM or be 6493 context saved. 6494 NOTE 6495 6496 This value shall be no less than the minimum value 6497 required by the platform-specific specification to 6498 which the TPM is built. 6499 6500 TPM_PT_PCR_COUNT 6501 6502 PT_FIXED + 18 the number of PCR implemented 6503 NOTE This number is determined by the defined 6504 attributes, not the number of PCR that are populated. 6505 6506 TPM_PT_PCR_SELECT_MIN 6507 6508 PT_FIXED + 19 the 6509 minimum 6510 number 6511 of 6512 TPMS_PCR_SELECT.sizeOfSelect 6513 NOTE 6514 6515 TPM_PT_CONTEXT_GAP_MAX 6516 6517 octets 6518 6519 in 6520 6521 a 6522 6523 This value is not determined by the number of PCR 6524 implemented but by the number of PCR required by 6525 the platform-specific specification with which the TPM 6526 is compliant. 6527 6528 PT_FIXED + 20 the maximum allowed difference (unsigned) between the 6529 contextID values of two saved session contexts 6530 16 6531 6532 This value shall be at least 2 -1 (65535). 6533 PT_FIXED + 21 skipped 6534 TPM_PT_NV_COUNTERS_MAX 6535 6536 PT_FIXED + 22 the maximum number of NV Indexes that are allowed to 6537 have the TPMA_NV_COUNTER attribute SET 6538 NOTE 6539 6540 It is allowed for this value to be larger than the 6541 number of NV Indexes that can be defined. This 6542 would be indicative of a TPM implementation that did 6543 not use different implementation technology for 6544 different NV Index types. 6545 6546 TPM_PT_NV_INDEX_MAX 6547 6548 PT_FIXED + 23 the maximum size of an NV Index data area 6549 6550 TPM_PT_MEMORY 6551 6552 PT_FIXED + 24 a TPMA_MEMORY indicating the memory management 6553 method for the TPM 6554 6555 TPM_PT_CLOCK_UPDATE 6556 6557 PT_FIXED + 25 interval, in milliseconds, between updates to the copy of 6558 TPMS_CLOCK_INFO.clock in NV 6559 6560 TPM_PT_CONTEXT_HASH 6561 6562 PT_FIXED + 26 the algorithm used for the integrity HMAC on saved 6563 contexts 6564 and 6565 for 6566 hashing 6567 the 6568 fuData 6569 of 6570 TPM2_FirmwareRead() 6571 6572 TPM_PT_CONTEXT_SYM 6573 6574 PT_FIXED + 27 the algorithm used for encryption of saved contexts 6575 6576 TPM_PT_CONTEXT_SYM_SIZE 6577 6578 PT_FIXED + 28 the size of the key used for encryption of saved contexts 6579 6580 TPM_PT_ORDERLY_COUNT 6581 6582 PT_FIXED + 29 the modulus - 1 of the count for NV update of an orderly 6583 counter 6584 The returned value is MAX_ORDERLY_COUNT. 6585 N 6586 This will have a value of 2 1 where 1 N 32 6587 NOTE 6588 6589 An orderly counter is an NV Index with 6590 TPMA_NV_COUNTER and TPMA_NV_ORDERLY 6591 both SET. 6592 6593 TPM_PT_MAX_COMMAND_SIZE 6594 6595 PT_FIXED + 30 the maximum value for commandSize in a command 6596 6597 TPM_PT_MAX_RESPONSE_SIZE 6598 6599 PT_FIXED + 31 the maximum value for responseSize in a response 6600 6601 TPM_PT_MAX_DIGEST 6602 6603 PT_FIXED + 32 the maximum size of a digest that can be produced by the 6604 TPM 6605 6606 TPM_PT_MAX_OBJECT_CONTEXT 6607 6608 PT_FIXED + 33 the maximum size of an object context that will be 6609 returned by TPM2_ContextSave 6610 6611 Family 2.0 6612 Level 00 Revision 00.99 6613 6614 Published 6615 Copyright TCG 2006-2013 6616 6617 Page 43 6618 October 31, 2013 6619 6620 Part 2: Structures 6622 6623 Capability Name 6624 6625 Trusted Platform Module Library 6626 6627 Value 6628 6629 Comments 6630 6631 TPM_PT_MAX_SESSION_CONTEXT PT_FIXED + 34 the maximum size of a session context that will be 6632 returned by TPM2_ContextSave 6633 TPM_PT_PS_FAMILY_INDICATOR 6634 6635 PT_FIXED + 35 platform-specific family (a TPM_PS value)(see Table 24) 6636 NOTE 6637 6638 The platform-specific values for the TPM_PT_PS 6639 parameters are in the relevant platform-specific 6640 specification. In the reference implementation, all of 6641 these values are 0. 6642 6643 TPM_PT_PS_LEVEL 6644 6645 PT_FIXED + 36 the level of the platform-specific specification 6646 6647 TPM_PT_PS_REVISION 6648 6649 PT_FIXED + 37 the specification Revision times 100 for the platformspecific specification 6650 6651 TPM_PT_PS_DAY_OF_YEAR 6652 6653 PT_FIXED + 38 the platform-specific specification day of year using TCG 6654 calendar 6655 6656 TPM_PT_PS_YEAR 6657 6658 PT_FIXED + 39 the platform-specific specification year using the CE 6659 6660 TPM_PT_SPLIT_MAX 6661 6662 PT_FIXED + 40 the number of split signing operations supported by the 6663 TPM 6664 6665 TPM_PT_TOTAL_COMMANDS 6666 6667 PT_FIXED + 41 total number of commands implemented in the TPM 6668 6669 TPM_PT_LIBRARY_COMMANDS 6670 6671 PT_FIXED + 42 number of commands from the TPM library that are 6672 implemented 6673 6674 TPM_PT_VENDOR_COMMANDS 6675 6676 PT_FIXED + 43 number of vendor commands that are implemented 6677 6678 TPM_PT_NV_BUFFER_MAX 6679 6680 PT_FIXED + 44 the maximum data size in one NV write command 6681 6682 PT_VAR 6683 6684 PT_GROUP * 2 the group of variable properties returned as 6685 TPMS_TAGGED_PROPERTY 6686 The properties in this group change because of a 6687 Protected Capability other than a firmware update. The 6688 values are not necessarily persistent across all power 6689 transitions. 6690 6691 TPM_PT_PERMANENT 6692 6693 PT_VAR + 0 6694 6695 TPMA_PERMANENT 6696 6697 TPM_PT_STARTUP_CLEAR 6698 6699 PT_VAR + 1 6700 6701 TPMA_STARTUP_CLEAR 6702 6703 TPM_PT_HR_NV_INDEX 6704 6705 PT_VAR + 2 6706 6707 the number of NV Indexes currently defined 6708 6709 TPM_PT_HR_LOADED 6710 6711 PT_VAR + 3 6712 6713 the number of authorization sessions currently loaded into 6714 TPM RAM 6715 6716 TPM_PT_HR_LOADED_AVAIL 6717 6718 PT_VAR + 4 6719 6720 the number of additional authorization sessions, of any 6721 type, that could be loaded into TPM RAM 6722 This value is an estimate. If this value is at least 1, then at 6723 least one authorization session of any type may be 6724 loaded. Any command that changes the RAM memory 6725 allocation can make this estimate invalid. 6726 NOTE 6727 6728 TPM_PT_HR_ACTIVE 6729 6730 Page 44 6731 October 31, 2013 6732 6733 PT_VAR + 5 6734 6735 A valid implementation may return 1 even if more 6736 than one authorization session would fit into RAM. 6737 6738 the number of active authorization sessions currently 6739 being tracked by the TPM 6740 This is the sum of the loaded and saved sessions. 6741 6742 Published 6743 Copyright TCG 2006-2013 6744 6745 Family 2.0 6746 Level 00 Revision 00.99 6747 6748 Trusted Platform Module Library 6750 Capability Name 6751 TPM_PT_HR_ACTIVE_AVAIL 6752 6753 Part 2: Structures 6754 Value 6755 6756 Comments 6757 6758 PT_VAR + 6 6759 6760 the number of additional authorization sessions, of any 6761 type, that could be created 6762 This value is an estimate. If this value is at least 1, then at 6763 least one authorization session of any type may be 6764 created. Any command that changes the RAM memory 6765 allocation can make this estimate invalid. 6766 NOTE 6767 6768 TPM_PT_HR_TRANSIENT_AVAIL 6769 6770 PT_VAR + 7 6771 6772 A valid implementation may return 1 even if more 6773 than one authorization session could be created. 6774 6775 estimate of the number of additional transient objects that 6776 could be loaded into TPM RAM 6777 This value is an estimate. If this value is at least 1, then at 6778 least one object of any type may be loaded. Any 6779 command that changes the memory allocation can make 6780 this estimate invalid. 6781 NOTE 6782 6783 A valid implementation may return 1 even if more 6784 than one transient object would fit into RAM. 6785 6786 TPM_PT_HR_PERSISTENT 6787 6788 PT_VAR + 8 6789 6790 the number of persistent objects currently loaded into 6791 TPM NV memory 6792 6793 TPM_PT_HR_PERSISTENT_AVAIL 6794 6795 PT_VAR + 9 6796 6797 the number of additional persistent objects that could be 6798 loaded into NV memory 6799 This value is an estimate. If this value is at least 1, then at 6800 least one object of any type may be made persistent. Any 6801 command that changes the NV memory allocation can 6802 make this estimate invalid. 6803 NOTE 6804 6805 A valid implementation may return 1 even if more 6806 than one persistent object would fit into NV memory. 6807 6808 TPM_PT_NV_COUNTERS 6809 6810 PT_VAR + 10 6811 6812 the number of defined NV Indexes that have NV 6813 TPMA_NV_COUNTER attribute SET 6814 6815 TPM_PT_NV_COUNTERS_AVAIL 6816 6817 PT_VAR + 11 6818 6819 the number of additional NV Indexes that can be defined 6820 with 6821 their 6822 TPMA_NV_COUNTER 6823 and 6824 TPMA_NV_ORDERLY attribute SET 6825 This value is an estimate. If this value is at least 1, then at 6826 least one NV Index may be created with the 6827 TPMA_NV_COUNTER 6828 and 6829 TPMA_NV_ORDERLY 6830 attributes SET. Any command that changes the NV 6831 memory allocation can make this estimate invalid. 6832 NOTE A valid implementation may return 1 even if more 6833 than one NV counter could be defined. 6834 6835 TPM_PT_ALGORITHM_SET 6836 6837 PT_VAR + 12 6838 6839 code that limits the algorithms that may be used with the 6840 TPM 6841 6842 TPM_PT_LOADED_CURVES 6843 6844 PT_VAR + 13 6845 6846 the number of loaded ECC curves 6847 6848 TPM_PT_LOCKOUT_COUNTER 6849 6850 PT_VAR + 14 6851 6852 the current value of the lockout counter (failedTries) 6853 6854 TPM_PT_MAX_AUTH_FAIL 6855 6856 PT_VAR + 15 6857 6858 the number of authorization failures before DA lockout is 6859 invoked 6860 6861 TPM_PT_LOCKOUT_INTERVAL 6862 6863 PT_VAR + 16 6864 6865 the number of seconds before the value reported by 6866 TPM_PT_LOCKOUT_COUNTER is decremented 6867 6868 TPM_PT_LOCKOUT_RECOVERY 6869 6870 PT_VAR + 17 6871 6872 the number of seconds after a lockoutAuth failure before 6873 use of lockoutAuth may be attempted again 6874 6875 TPM_PT_NV_WRITE_RECOVERY 6876 6877 PT_VAR + 18 6878 6879 number of milliseconds before the TPM will accept 6880 another command that will modify NV 6881 This value is an approximation and may go up or down 6882 over time. 6883 6884 Family 2.0 6885 Level 00 Revision 00.99 6886 6887 Published 6888 Copyright TCG 2006-2013 6889 6890 Page 45 6891 October 31, 2013 6892 6893 Part 2: Structures 6895 6896 Capability Name 6897 6898 Trusted Platform Module Library 6899 6900 Value 6901 6902 Comments 6903 6904 TPM_PT_AUDIT_COUNTER_0 6905 6906 PT_VAR + 19 6907 6908 the high-order 32 bits of the command audit counter 6909 6910 TPM_PT_AUDIT_COUNTER_1 6911 6912 PT_VAR + 20 6913 6914 the low-order 32 bits of the command audit counter 6915 6916 Page 46 6917 October 31, 2013 6918 6919 Published 6920 Copyright TCG 2006-2013 6921 6922 Family 2.0 6923 Level 00 Revision 00.99 6924 6925 Trusted Platform Module Library 6927 6928 Part 2: Structures 6929 6930 6.14 TPM_PT_PCR (PCR Property Tag) 6931 The TPM_PT_PCR constants are used in TPM2_GetCapability() to indicate the property being selected 6932 or returned. The PCR properties can be read when capability == TPM_CAP_PCR_PROPERTIES. 6933 Table 23 Definition of (UINT32) TPM_PT_PCR Constants <IN/OUT, S> 6934 Capability Name 6935 6936 Value 6937 6938 Comments 6939 6940 TPM_PT_PCR_FIRST 6941 6942 0x00000000 6943 6944 bottom of the range of TPM_PT_PCR properties 6945 6946 TPM_PT_PCR_SAVE 6947 6948 0x00000000 6949 6950 a SET bit in the TPMS_PCR_SELECT indicates that the PCR is 6951 saved and restored by TPM_SU_STATE 6952 6953 TPM_PT_PCR_EXTEND_L0 6954 6955 0x00000001 6956 6957 a SET bit in the TPMS_PCR_SELECT indicates that the PCR 6958 may be extended from locality 0 6959 This property is only present if a locality other than 0 is 6960 implemented. 6961 6962 TPM_PT_PCR_RESET_L0 6963 6964 0x00000002 6965 6966 a SET bit in the TPMS_PCR_SELECT indicates that the PCR 6967 may be reset by TPM2_PCR_Reset() from locality 0 6968 6969 TPM_PT_PCR_EXTEND_L1 6970 6971 0x00000003 6972 6973 a SET bit in the TPMS_PCR_SELECT indicates that the PCR 6974 may be extended from locality 1 6975 This property is only present if locality 1 is implemented. 6976 6977 TPM_PT_PCR_RESET_L1 6978 6979 0x00000004 6980 6981 a SET bit in the TPMS_PCR_SELECT indicates that the PCR 6982 may be reset by TPM2_PCR_Reset() from locality 1 6983 This property is only present if locality 1 is implemented. 6984 6985 TPM_PT_PCR_EXTEND_L2 6986 6987 0x00000005 6988 6989 a SET bit in the TPMS_PCR_SELECT indicates that the PCR 6990 may be extended from locality 2 6991 This property is only present if localities 1 and 2 are 6992 implemented. 6993 6994 TPM_PT_PCR_RESET_L2 6995 6996 0x00000006 6997 6998 a SET bit in the TPMS_PCR_SELECT indicates that the PCR 6999 may be reset by TPM2_PCR_Reset() from locality 2 7000 This property is only present if localities 1 and 2 are 7001 implemented. 7002 7003 TPM_PT_PCR_EXTEND_L3 7004 7005 0x00000007 7006 7007 a SET bit in the TPMS_PCR_SELECT indicates that the PCR 7008 may be extended from locality 3 7009 This property is only present if localities 1, 2, and 3 are 7010 implemented. 7011 7012 TPM_PT_PCR_RESET_L3 7013 7014 0x00000008 7015 7016 a SET bit in the TPMS_PCR_SELECT indicates that the PCR 7017 may be reset by TPM2_PCR_Reset() from locality 3 7018 This property is only present if localities 1, 2, and 3 are 7019 implemented. 7020 7021 TPM_PT_PCR_EXTEND_L4 7022 7023 0x00000009 7024 7025 a SET bit in the TPMS_PCR_SELECT indicates that the PCR 7026 may be extended from locality 4 7027 This property is only present if localities 1, 2, 3, and 4 are 7028 implemented. 7029 7030 TPM_PT_PCR_RESET_L4 7031 7032 0x0000000A 7033 7034 a SET bit in the TPMS_PCR_SELECT indicates that the PCR 7035 may be reset by TPM2_PCR_Reset() from locality 4 7036 This property is only present if localities 1, 2, 3, and 4 are 7037 implemented. 7038 7039 Family 2.0 7040 Level 00 Revision 00.99 7041 7042 Published 7043 Copyright TCG 2006-2013 7044 7045 Page 47 7046 October 31, 2013 7047 7048 Part 2: Structures 7050 7051 Capability Name 7052 reserved 7053 7054 Trusted Platform Module Library 7055 7056 Value 7057 7058 Comments 7059 7060 0x0000000B the values in this range are reserved 7061 0x00000010 They correspond to values that may be used to describe 7062 attributes associated with the extended localities (32255).synthesize additional software localities. The meaning of 7063 these properties need not be the same as the meaning for the 7064 Extend and Reset properties above. 7065 7066 TPM_PT_PCR_NO_INCREMENT 7067 7068 0x00000011 7069 7070 a SET bit in the TPMS_PCR_SELECT indicates that 7071 modifications to this PCR (reset or Extend) will not increment 7072 the pcrUpdateCounter 7073 7074 TPM_PT_PCR_DRTM_RESET 7075 7076 0x00000012 7077 7078 a SET bit in the TPMS_PCR_SELECT indicates that the PCR is 7079 reset by a DRTM event 7080 These PCR are reset to -1 on TPM2_Startup() and reset to 0 on 7081 a _TPM_Hash_End event following a _TPM_Hash_Start event. 7082 7083 TPM_PT_PCR_POLICY 7084 7085 0x00000013 7086 7087 a SET bit in the TPMS_PCR_SELECT indicates that the PCR is 7088 controlled by policy 7089 This property is only present if the TPM supports policy control 7090 of a PCR. 7091 7092 TPM_PT_PCR_AUTH 7093 7094 0x00000014 7095 7096 a SET bit in the TPMS_PCR_SELECT indicates that the PCR is 7097 controlled by an authorization value 7098 This property is only present if the TPM supports authorization 7099 control of a PCR. 7100 7101 reserved 7102 7103 0x00000015 7104 7105 reserved for the next (2 ) TPM_PT_PCR_POLICY set 7106 7107 reserved 7108 7109 0x00000016 7110 7111 reserved for the next (2 ) TPM_PT_PCR_AUTH set 7112 7113 reserved 7114 7115 nd 7116 nd 7117 7118 nd 7119 7120 th 7121 7122 0x00000017 reserved for the 2 through 255 TPM_PT_PCR_POLICY and 7123 0x00000210 TPM_PT_PCR_AUTH values 7124 th 7125 7126 and 7127 7128 highest 7129 7130 allowed, 7131 7132 th 7133 7134 and 7135 7136 highest 7137 7138 allowed, 7139 7140 reserved 7141 7142 0x00000211 7143 7144 reserved 7145 to 7146 the 7147 256 , 7148 TPM_PT_PCR_POLICY set 7149 7150 reserved 7151 7152 0x00000212 7153 7154 reserved 7155 to 7156 the 7157 256 , 7158 TPM_PT_PCR_AUTH set 7159 7160 reserved 7161 7162 0x00000213 7163 7164 new PCR property values may be assigned starting with this 7165 value 7166 7167 TPM_PT_PCR_LAST 7168 7169 0x00000014 7170 7171 top of the range of TPM_PT_PCR properties of the 7172 implementation 7173 If the TPM receives a request for a PCR property with a value 7174 larger than this, the TPM will return a zero length list and set the 7175 moreData parameter to NO. 7176 NOTE 7177 7178 Page 48 7179 October 31, 2013 7180 7181 This is an implementation-specific value. The value shown 7182 reflects the reference code implementation. 7183 7184 Published 7185 Copyright TCG 2006-2013 7186 7187 Family 2.0 7188 Level 00 Revision 00.99 7189 7190 Trusted Platform Module Library 7192 7193 Part 2: Structures 7194 7195 6.15 TPM_PS (Platform Specific) 7196 The platform values in Table 24 are used for the TPM_PT_PS_FAMILY_INDICATOR. 7197 NOTE 7198 7199 Values below six (6) have the same values as the purview assignments in TPM 1.2. 7200 7201 Table 24 Definition of (UINT32) TPM_PS Constants <OUT> 7202 Capability Name 7203 7204 Value 7205 7206 Comments 7207 7208 TPM_PS_MAIN 7209 7210 0x00000000 7211 7212 not platform specific 7213 7214 TPM_PS_PC 7215 7216 0x00000001 7217 7218 PC Client 7219 7220 TPM_PS_PDA 7221 7222 0x00000002 7223 7224 PDA (includes all mobile devices that are not specifically cell 7225 phones) 7226 7227 TPM_PS_CELL_PHONE 7228 7229 0x00000003 7230 7231 Cell Phone 7232 7233 TPM_PS_SERVER 7234 7235 0x00000004 7236 7237 Server WG 7238 7239 TPM_PS_PERIPHERAL 7240 7241 0x00000005 7242 7243 Peripheral WG 7244 7245 TPM_PS_TSS 7246 7247 0x00000006 7248 7249 TSS WG 7250 7251 TPM_PS_STORAGE 7252 7253 0x00000007 7254 7255 Storage WG 7256 7257 TPM_PS_AUTHENTICATION 7258 7259 0x00000008 7260 7261 Authentication WG 7262 7263 TPM_PS_EMBEDDED 7264 7265 0x00000009 7266 7267 Embedded WG 7268 7269 TPM_PS_HARDCOPY 7270 7271 0x0000000A 7272 7273 Hardcopy WG 7274 7275 TPM_PS_INFRASTRUCTURE 7276 7277 0x0000000B 7278 7279 Infrastructure WG 7280 7281 TPM_PS_VIRTUALIZATION 7282 7283 0x0000000C Virtualization WG 7284 7285 TPM_PS_TNC 7286 7287 0x0000000D Trusted Network Connect WG 7288 7289 TPM_PS_MULTI_TENANT 7290 7291 0x0000000E 7292 7293 Multi-tenant WG 7294 7295 TPM_PS_TC 7296 7297 0x0000000F 7298 7299 Technical Committee 7300 7301 Family 2.0 7302 Level 00 Revision 00.99 7303 7304 Published 7305 Copyright TCG 2006-2013 7306 7307 Page 49 7308 October 31, 2013 7309 7310 Part 2: Structures 7312 7313 7 7314 7315 Trusted Platform Module Library 7316 7317 Handles 7318 7319 7.1 7320 7321 Introduction 7322 7323 Handles are 32-bit values used to reference shielded locations of various types within the TPM. 7324 Table 25 Definition of Types for Handles 7325 Type 7326 7327 Name 7328 7329 Description 7330 7331 UINT32 7332 7333 TPM_HANDLE 7334 7335 Handles may refer to objects (keys or data blobs), authorization sessions (HMAC and policy), NV 7336 Indexes, permanent TPM locations, and PCR. 7337 7.2 7338 7339 TPM_HT (Handle Types) 7340 7341 The 32-bit handle space is divided into 256 regions of equal size with 2 7342 ranges represents a handle type. 7343 7344 24 7345 7346 values in each. Each of these 7347 7348 The type of the entity is indicated by the MSO of its handle. The values for the MSO and the entity 7349 referenced are shown in Table 26. 7350 Table 26 Definition of (UINT8) TPM_HT Constants <S> 7351 Name 7352 7353 Value 7354 7355 Comments 7356 7357 TPM_HT_PCR 7358 7359 0x00 7360 7361 PCR consecutive numbers, starting at 0, that reference the PCR 7362 registers 7363 A platform-specific specification will set the minimum number of PCR 7364 and an implementation may have more. 7365 7366 TPM_HT_NV_INDEX 7367 7368 0x01 7369 7370 NV Index assigned by the caller 7371 7372 TPM_HT_HMAC_SESSION 7373 7374 0x02 7375 7376 HMAC Authorization Session assigned by the TPM when the 7377 session is created 7378 7379 TPM_HT_LOADED_SESSION 7380 7381 0x02 7382 7383 Loaded Authorization Session used only in the context of 7384 TPM2_GetCapability 7385 This type references both loaded HMAC and loaded policy 7386 authorization sessions. 7387 7388 TPM_HT_POLICY_SESSION 7389 7390 0x03 7391 7392 Policy Authorization Session assigned by the TPM when the 7393 session is created 7394 7395 TPM_HT_ACTIVE_SESSION 7396 7397 0x03 7398 7399 Active Authorization Session used only in the context of 7400 TPM2_GetCapability 7401 This type references saved authorization session contexts for which 7402 the TPM is maintaining tracking information. 7403 7404 TPM_HT_PERMANENT 7405 7406 0x40 7407 7408 Permanent Values assigned by this specification in Table 27 7409 7410 TPM_HT_TRANSIENT 7411 7412 0x80 7413 7414 Transient Objects assigned by the TPM when an object is loaded 7415 into transient-object memory or when a persistent object is converted 7416 to a transient object 7417 7418 TPM_HT_PERSISTENT 7419 7420 0x81 7421 7422 Persistent Objects assigned by the TPM when a loaded transient 7423 object is made persistent 7424 7425 Page 50 7426 October 31, 2013 7427 7428 Published 7429 Copyright TCG 2006-2013 7430 7431 Family 2.0 7432 Level 00 Revision 00.99 7433 7434 Trusted Platform Module Library 7436 7437 Part 2: Structures 7438 7439 When a transient object is loaded, the TPM shall assign a handle with an MSO of TPM_HT_TRANSIENT. 7440 The object may be assigned a different handle each time it is loaded. The TPM shall ensure that handles 7441 assigned to transient objects are unique and assigned to only one transient object at a time. 7442 EXAMPLE 7443 7444 If a TPM is only able to hold 4 transient objects in internal memory, it might choose to assign handles to 7445 those objects with the values 80 00 00 0016 80 00 00 0316. 7446 7447 When a transient object is converted to a persistent object (TPM2_EvictControl()), the TPM shall validate 7448 that the handle provided by the caller has an MSO of TPM_HT_PERSISTENT and that the handle is not 7449 already assigned to a persistent object. 7450 A handle is assigned to a session when the session is started. The handle shall have an MSO equal to 7451 TPM_HT_SESSION and remain associated with that session until the session is closed or flushed. The 7452 TPM shall ensure that a session handle is only associated with one session at a time. When the session 7453 is loaded into the TPM using TPM2_LoadContext(), it will have the same handle each time it is loaded. 7454 EXAMPLE 7455 7456 7.3 7457 7458 If a TPM is only able to track 64 active sessions at a time, it could number those sessions using the 7459 values xx 00 01 0016 xx 00 01 3F 16 where xx is either 02 16 or 03 16 depending on the session type. 7460 7461 Persistent Handle Sub-ranges 7462 7463 Persistent handles are assigned by the caller of TPM2_EvictControl(). ownerAuth or platformAuth is 7464 required to authorize allocation of space for a persistent object. These entities are given separate ranges 7465 of persistent handles so that they do not have to allocate from a common range of handles. 7466 NOTE 7467 7468 While this namespace allocation of the handle ranges could have been handled by convention, TPM 7469 enforcement is used to prevent errors by the OS or malicious software from affecting the platforms use of 7470 the NV memory. 7471 7472 The Owner is allocated persistent handles in the range of 81 00 00 0016 to 81 7F FF FF16 inclusive and 7473 the TPM will return an error if ownerAuth is used to attempt to assign a persistent handle outside of this 7474 range. 7475 7476 Family 2.0 7477 Level 00 Revision 00.99 7478 7479 Published 7480 Copyright TCG 2006-2013 7481 7482 Page 51 7483 October 31, 2013 7484 7485 Part 2: Structures 7487 7.4 7488 7489 Trusted Platform Module Library 7490 7491 TPM_RH (Permanent Handles) 7492 7493 Table 27 lists the architecturally defined handles that cannot be changed. The handles include 7494 authorization handles, and special handles. 7495 Table 27 Definition of (UINT32) TPM_RH Constants <IN, S> 7496 Name 7497 7498 Value 7499 7500 Type 7501 7502 TPM_RH_FIRST 7503 7504 0x40000000 7505 7506 R 7507 7508 TPM_RH_SRK 7509 7510 0x40000000 7511 7512 R 7513 7514 TPM_RH_OWNER 7515 7516 0x40000001 7517 7518 K, A, P 7519 7520 TPM_RH_REVOKE 7521 7522 0x40000002 7523 7524 R 7525 7526 not used 7527 7528 1 7529 7530 TPM_RH_TRANSPORT 7531 7532 0x40000003 7533 7534 R 7535 7536 not used 7537 7538 1 7539 7540 TPM_RH_OPERATOR 7541 7542 0x40000004 7543 7544 R 7545 7546 not used 7547 7548 1 7549 7550 TPM_RH_ADMIN 7551 7552 0x40000005 7553 7554 R 7555 7556 not used 7557 7558 1 7559 7560 TPM_RH_EK 7561 7562 0x40000006 7563 7564 R 7565 7566 not used 7567 7568 1 7569 7570 TPM_RH_NULL 7571 7572 0x40000007 7573 7574 K, A, P 7575 7576 a handle associated with the null hierarchy, an EmptyAuth 7577 authValue, and an Empty Policy authPolicy. 7578 7579 TPM_RH_UNASSIGNED 7580 7581 0x40000008 7582 7583 R 7584 7585 value reserved to the TPM to indicate a handle location that 7586 has not been initialized or assigned 7587 7588 TPM_RS_PW 7589 7590 0x40000009 7591 7592 S 7593 7594 authorization value 7595 authorization session 7596 7597 TPM_RH_LOCKOUT 7598 7599 0x4000000A 7600 7601 A 7602 7603 references the authorization associated with the dictionary 7604 attack lockout reset 7605 7606 TPM_RH_ENDORSEMENT 7607 7608 0x4000000B 7609 7610 K, A, P 7611 7612 references the Endorsement Primary 7613 endorsementAuth, and endorsementPolicy 7614 7615 TPM_RH_PLATFORM 7616 7617 0x4000000C 7618 7619 K, A, P 7620 7621 references the Platform Primary Seed (PPS), platformAuth, 7622 and platformPolicy 7623 7624 TPM_RH_PLATFORM_NV 7625 7626 0x4000000D 7627 7628 C 7629 7630 for phEnableNV 7631 7632 R 7633 7634 the top of the reserved handle area 7635 This is set to allow TPM2_GetCapability() to know where to 7636 stop. It may vary as implementations add to the permanent 7637 handle area. 7638 7639 TPM_RH_LAST 7640 7641 0x4000000D 7642 7643 Comments 7644 7645 not used 7646 7647 1 7648 7649 handle references the Storage Primary Seed (SPS), the 7650 ownerAuth, and the ownerPolicy 7651 7652 used 7653 7654 to 7655 7656 indicate 7657 7658 a 7659 7660 password 7661 7662 Seed 7663 7664 (EPS), 7665 7666 Type definitions: 7667 R a reserved value 7668 K a Primary Seed 7669 A an authorization value 7670 P a policy value 7671 S a session handle 7672 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 7673 in any command defined in this version of the specification. 7674 7675 Page 52 7676 October 31, 2013 7677 7678 Published 7679 Copyright TCG 2006-2013 7680 7681 Family 2.0 7682 Level 00 Revision 00.99 7683 7684 Trusted Platform Module Library 7686 7.5 7687 7688 Part 2: Structures 7689 7690 TPM_HC (Handle Value Constants) 7691 7692 The definitions in Table 28 are used to define many of the interface data types. However, the values of 7693 these constants, other than PCR_FIRST, are informative and may be changed by an implementation as 7694 long as the values stay within the prescribed ranges for the handle type. 7695 NOTE 7696 7697 PCR0 is architecturally defined to have a handle value of 0. 7698 7699 For the reference implementation, the handle range for sessions starts at the lowest allowed value for a 7700 session handle. The highest value for a session handle is determined by how many active sessions are 7701 allowed by the implementation. The MSO of the session handle will be set according to the session type. 7702 A similar approach is used for transient objects with the first assigned handle at the bottom of the range 7703 defined by TPM_HT_TRANSIENT and the top of the range determined by the implementation-dependent 7704 value of MAX_LOADED_OBJECTS. 7705 The first assigned handle for evict objects is also at the bottom of the allowed range defined by 7706 TPM_HT_PERSISTENT and the top of the range determined by the implementation-dependent value of 7707 MAX_EVICT_OBJECTS. 7708 NOTE 7709 7710 The values in Table 28 are intended to facilitate the process of making the handle larger than 32 bits in 7711 the future. It is intended that HR_MASK and HR_SHIFT are the only values that need change to resize 7712 the handle space. 7713 7714 Family 2.0 7715 Level 00 Revision 00.99 7716 7717 Published 7718 Copyright TCG 2006-2013 7719 7720 Page 53 7721 October 31, 2013 7722 7723 Part 2: Structures 7725 7726 Trusted Platform Module Library 7727 7728 Table 28 Definition of (TPM_HANDLE) TPM_HC Constants <IN, S> 7729 Name 7730 7731 Value 7732 7733 Comments 7734 7735 HR_HANDLE_MASK 7736 7737 0x00FFFFFF 7738 7739 to mask off the HR 7740 7741 HR_RANGE_MASK 7742 7743 0xFF000000 7744 7745 to mask off the variable 7746 part 7747 7748 HR_SHIFT 7749 7750 24 7751 7752 HR_PCR 7753 7754 (TPM_HT_PCR << HR_SHIFT) 7755 7756 HR_HMAC_SESSION 7757 7758 (TPM_HT_HMAC_SESSION << HR_SHIFT) 7759 7760 HR_POLICY_SESSION 7761 7762 (TPM_HT_POLICY_SESSION << HR_SHIFT) 7763 7764 HR_TRANSIENT 7765 7766 (TPM_HT_TRANSIENT << HR_SHIFT) 7767 7768 HR_PERSISTENT 7769 7770 (TPM_HT_PERSISTENT << HR_SHIFT) 7771 7772 HR_NV_INDEX 7773 7774 (TPM_HT_NV_INDEX << HR_SHIFT) 7775 7776 HR_PERMANENT 7777 7778 (TPM_HT_PERMANENT << HR_SHIFT) 7779 7780 PCR_FIRST 7781 7782 (HR_PCR + 0) 7783 7784 first PCR 7785 7786 PCR_LAST 7787 7788 (PCR_FIRST + IMPLEMENTATION_PCR-1) 7789 7790 last PCR 7791 7792 HMAC_SESSION_FIRST 7793 7794 (HR_HMAC_SESSION + 0) 7795 7796 first HMAC session 7797 7798 HMAC_SESSION_LAST 7799 7800 (HMAC_SESSION_FIRST+MAX_ACTIVE_SESSIONS-1) 7801 7802 last HMAC session 7803 7804 LOADED_SESSION_FIRST HMAC_SESSION_FIRST 7805 7806 used in GetCapability 7807 7808 LOADED_SESSION_LAST 7809 7810 HMAC_SESSION_LAST 7811 7812 used in GetCapability 7813 7814 POLICY_SESSION_FIRST 7815 7816 (HR_POLICY_SESSION + 0) 7817 7818 first policy session 7819 7820 POLICY_SESSION_LAST 7821 7822 (POLICY_SESSION_FIRST + MAX_ACTIVE_SESSIONS-1) last policy session 7823 7824 TRANSIENT_FIRST 7825 7826 (HR_TRANSIENT + 0) 7827 7828 first transient object 7829 7830 ACTIVE_SESSION_FIRST 7831 7832 POLICY_SESSION_FIRST 7833 7834 used in GetCapability 7835 7836 ACTIVE_SESSION_LAST 7837 7838 POLICY_SESSION_LAST 7839 7840 used in GetCapability 7841 7842 TRANSIENT_LAST 7843 7844 (TRANSIENT_FIRST+MAX_LOADED_OBJECTS-1) 7845 7846 last transient object 7847 7848 PERSISTENT_FIRST 7849 7850 (HR_PERSISTENT + 0) 7851 7852 first persistent object 7853 7854 PERSISTENT_LAST 7855 7856 (PERSISTENT_FIRST + 0x00FFFFFF) 7857 7858 last persistent object 7859 7860 PLATFORM_PERSISTENT 7861 7862 (PERSISTENT_FIRST + 0x00800000) 7863 7864 first platform persistent 7865 object 7866 7867 NV_INDEX_FIRST 7868 7869 (HR_NV_INDEX + 0) 7870 7871 first allowed NV Index 7872 7873 NV_INDEX_LAST 7874 7875 (NV_INDEX_FIRST + 0x00FFFFFF) 7876 7877 last allowed NV Index 7878 7879 PERMANENT_FIRST 7880 7881 TPM_RH_FIRST 7882 7883 PERMANENT_LAST 7884 7885 TPM_RH_LAST 7886 7887 Page 54 7888 October 31, 2013 7889 7890 Published 7891 Copyright TCG 2006-2013 7892 7893 Family 2.0 7894 Level 00 Revision 00.99 7895 7896 Trusted Platform Module Library 7898 7899 Part 2: Structures 7900 7901 Attribute Structures 7902 7903 8 7904 8.1 7905 7906 Description 7907 7908 Attributes are expressed as bit fields of varying size. An attribute field structure may be 1, 2, or 4 octets in 7909 length. 7910 The bit numbers for an attribute structure are assigned with the number 0 assigned to the least-significant 7911 bit of the structure and the highest number assigned to the most-significant bit of the structure. 7912 The least significant bit is determined by treating the attribute structure as an integer. The least-significant 7913 bit would be the bit that is set when the value of the integer is 1. 7914 When any reserved bit in an attribute is SET, the TPM shall return TPM_RC_RESERVED_BITS. This 7915 response code is not shown in the tables for attributes. 7916 8.2 7917 7918 TPMA_ALGORITHM 7919 7920 This structure defines the attributes of an algorithm. 7921 Each algorithm has a fundamental attribute: asymmetric, symmetric, or hash. In some cases (e.g., 7922 TPM_ALG_RSA or TPM_ALG_AES), this is the only attribute. 7923 A mode, method, or scheme may have an associated asymmetric, symmetric, or hash algorithm. 7924 Table 29 Definition of (UINT32) TPMA_ALGORITHM Bits 7925 Bit 7926 7927 Name 7928 7929 Definition 7930 7931 0 7932 7933 asymmetric 7934 7935 SET (1): an asymmetric algorithm with public and private portions 7936 CLEAR (0): not an asymmetric algorithm 7937 7938 1 7939 7940 symmetric 7941 7942 SET (1): a symmetric block cipher 7943 CLEAR (0): not a symmetric block cipher 7944 7945 2 7946 7947 hash 7948 7949 SET (1): a hash algorithm 7950 CLEAR (0): not a hash algorithm 7951 7952 3 7953 7954 object 7955 7956 SET (1): an algorithm that may be used as an object type 7957 CLEAR (0): an algorithm that is not used as an object type 7958 7959 7:4 7960 7961 Reserved 7962 7963 8 7964 7965 signing 7966 7967 SET (1): a signing algorithm. The setting of asymmetric, symmetric, and hash 7968 will indicate the type of signing algorithm. 7969 CLEAR (0): not a signing algorithm 7970 7971 9 7972 7973 encrypting 7974 7975 SET (1): an encryption/decryption algorithm. The setting of asymmetric, 7976 symmetric, and hash will indicate the type of encryption/decryption algorithm. 7977 CLEAR (0): not an encryption/decryption algorithm 7978 7979 10 7980 7981 method 7982 7983 SET (1): a method such as a key derivative function (KDF) 7984 CLEAR (0): not a method 7985 7986 31:11 Reserved 7987 7988 8.3 7989 8.3.1 7990 7991 TPMA_OBJECT (Object Attributes) 7992 Introduction 7993 7994 Family 2.0 7995 Level 00 Revision 00.99 7996 7997 Published 7998 Copyright TCG 2006-2013 7999 8000 Page 55 8001 October 31, 2013 8002 8003 Part 2: Structures 8005 8006 Trusted Platform Module Library 8007 8008 This attribute structure indicates an objects use, its authorization types, and it relationship to other 8009 objects. 8010 The state of the attributes is determined when the object is created and they are never changed by the 8011 TPM. Additionally, the setting of these structures is reflected in the integrity value of the private area of an 8012 object in order to allow the TPM to detect modifications of the Protected Object when stored off the TPM. 8013 8.3.2 8014 8015 Structure Definition 8016 Table 30 Definition of (UINT32) TPMA_OBJECT Bits 8017 8018 Bit 8019 8020 Name 8021 8022 Definition 8023 8024 0 8025 8026 Reserved 8027 8028 shall be zero 8029 8030 1 8031 8032 fixedTPM 8033 8034 SET (1): The hierarchy of the object, as indicated by its Qualified Name, may 8035 not change. 8036 CLEAR (0): The hierarchy of the object may change as a result of this object or 8037 an ancestor key being duplicated for use in another hierarchy. 8038 8039 2 8040 8041 stClear 8042 8043 SET (1): Previously saved contexts of this object may not be loaded after 8044 Startup(CLEAR). 8045 CLEAR (0): Saved contexts of this object may be used after a 8046 Shutdown(STATE) and subsequent Startup(). 8047 8048 3 8049 8050 Reserved 8051 8052 shall be zero 8053 8054 4 8055 8056 fixedParent 8057 8058 SET (1): The parent of the object may not change. 8059 CLEAR (0): The parent of the object may change as the result of a 8060 TPM2_Duplicate() of the object. 8061 8062 5 8063 8064 sensitiveDataOrigin 8065 8066 SET (1): Indicates that, when the object was created with TPM2_Create() or 8067 TPM2_CreatePrimary(), the TPM generated all of the sensitive data other than 8068 the authValue. 8069 CLEAR (0): A portion of the sensitive data, other than the authValue, was 8070 provided by the caller. 8071 8072 6 8073 8074 userWithAuth 8075 8076 SET (1): Approval of USER role actions with this object may be with an HMAC 8077 session or with a password using the authValue of the object or a policy 8078 session. 8079 CLEAR (0): Approval of USER role actions with this object may only be done 8080 with a policy session. 8081 8082 7 8083 8084 adminWithPolicy 8085 8086 SET (1): Approval of ADMIN role actions with this object may only be done with 8087 a policy session. 8088 CLEAR (0): Approval of ADMIN role actions with this object may be with an 8089 HMAC session or with a password using the authValue of the object or a policy 8090 session. 8091 8092 9:8 8093 8094 Reserved 8095 8096 shall be zero 8097 8098 10 8099 8100 noDA 8101 8102 SET (1): The object is not subject to dictionary attack protections. 8103 CLEAR (0): The object is subject to dictionary attack protections. 8104 8105 11 8106 8107 encryptedDuplication 8108 8109 SET (1): If the object is duplicated, then symmetricAlg shall not be 8110 TPM_ALG_NULL and newParentHandle shall not be TPM_RH_NULL. 8111 CLEAR (0): The object may be duplicated without an inner wrapper on the 8112 private portion of the object and the new parent may be TPM_RH_NULL. 8113 8114 15:12 Reserved 8115 16 8116 8117 restricted 8118 8119 Page 56 8120 October 31, 2013 8121 8122 shall be zero 8123 SET (1): Key usage is restricted to manipulate structures of known format; the 8124 parent of this key shall have restricted SET. 8125 CLEAR (0): Key usage is not restricted to use on special formats. 8126 8127 Published 8128 Copyright TCG 2006-2013 8129 8130 Family 2.0 8131 Level 00 Revision 00.99 8132 8133 Trusted Platform Module Library 8135 8136 Part 2: Structures 8137 8138 Bit 8139 8140 Name 8141 8142 Definition 8143 8144 17 8145 8146 decrypt 8147 8148 SET (1): The private portion of the key may be used to decrypt. 8149 CLEAR (0): The private portion of the key may not be used to decrypt. 8150 8151 18 8152 8153 sign 8154 8155 SET (1): The private portion of the key may be used to sign. 8156 CLEAR (0): The private portion of the key may not be used to sign. 8157 8158 31:19 Reserved 8159 8160 8.3.3 8161 8.3.3.1 8162 8163 shall be zero 8164 8165 Attribute Descriptions 8166 Introduction 8167 8168 The following remaining paragraphs in this clause describe the use and settings for each of the 8169 TPMA_OBJECT attributes. The description includes checks that are performed on the objectAttributes 8170 when an object is created, when it is loaded, and when it is imported. In these descriptions: 8171 Creation 8172 8173 indicates 8174 settings 8175 for 8176 TPM2_CreatePrimary() 8177 8178 the 8179 8180 template 8181 8182 parameter 8183 8184 in 8185 8186 TPM2_Create() 8187 8188 or 8189 8190 Load 8191 8192 8193 8194 indicates settings for the inPublic parameter in TPM2_Load() 8195 8196 Import 8197 8198 8199 8200 indicates settings for the objectPublic parameter in TPM2_Import() 8201 8202 External 8203 8204 8205 8206 indicates settings that apply to the inPublic parameter in TPM2_LoadExternal() if both the 8207 public and sensitive portions of the object are loaded 8208 8209 NOTE 8210 8211 For TPM2_LoadExternal() when only the public portion of the object is loaded, the only attribute checks 8212 are the checks in the validation code following Table 30 and the reserved attributes check. 8213 8214 For any consistency error of attributes in TPMA_OBJECT, the TPM shall return TPM_RC_ATTRIBUTES. 8215 8.3.3.2 8216 8217 Bit[1] fixedTPM 8218 8219 When SET, the object cannot be duplicated for use on a different TPM, either directly or indirectly and the 8220 Qualified Name of the object cannot change. When CLEAR, the objects Qualified Name may change if 8221 the object or an ancestor is duplicated. 8222 NOTE 8223 8224 This attribute is the logical inverse of the migratable attribute in 1.2. That is, when this attribute is C LEAR, 8225 it is the equivalent to a 1.2 object with migratable SET. 8226 8227 Creation 8228 8229 If fixedTPM is SET in the object's parent, then fixedTPM and fixedParent shall both be 8230 set to the same value in template. If fixedTPM is CLEAR in the parent, this attribute shall 8231 also be CLEAR in template. 8232 NOTE 8233 8234 For a Primary Object, the parent is considered to have fixedTPM SET. 8235 8236 Load 8237 8238 8239 8240 If fixedTPM is SET in the object's parent, then fixedTPM and fixedParent shall both be 8241 set to the same value. If fixedTPM is CLEAR in the parent, this attribute shall also be 8242 CLEAR. 8243 8244 Import 8245 8246 8247 8248 shall be CLEAR 8249 8250 External 8251 8252 8253 8254 shall be CLEAR if both the public and sensitive portions are loaded or if fixedParent is 8255 CLEAR, otherwise may be SET or CLEAR 8256 8257 Family 2.0 8258 Level 00 Revision 00.99 8259 8260 Published 8261 Copyright TCG 2006-2013 8262 8263 Page 57 8264 October 31, 2013 8265 8266 Part 2: Structures 8268 8.3.3.3 8269 8270 Trusted Platform Module Library 8271 8272 Bit[2] stClear 8273 8274 If this attribute is SET, then saved contexts of this object will be invalidated on 8275 TPM2_Startup(TPM_SU_CLEAR). If the attribute is CLEAR, then the TPM shall not invalidate the saved 8276 context if the TPM received TPM2_Shutdown(TPM_SU_STATE). If the saved state is valid when checked 8277 at the next TPM2_Startup(), then the TPM shall continue to be able to use the saved contexts. 8278 Creation 8279 8280 may be SET or CLEAR in template 8281 8282 Load 8283 8284 8285 8286 may be SET or CLEAR 8287 8288 Import 8289 8290 8291 8292 may be SET or CLEAR 8293 8294 External 8295 8296 8297 8298 may be SET or CLEAR 8299 8300 8.3.3.4 8301 8302 Bit[4] fixedParent 8303 8304 If this attribute is SET, the objects parent may not be changed. That is, this object may not be the object 8305 of a TPM2_Duplicate(). If this attribute is CLEAR, then this object may be the object of a 8306 TPM2_Duplicate(). 8307 Creation 8308 8309 may be SET or CLEAR in template 8310 8311 Load 8312 8313 8314 8315 may be SET or CLEAR 8316 8317 Import 8318 8319 8320 8321 shall be CLEAR 8322 8323 External 8324 8325 8326 8327 shall be CLEAR if both the public and sensitive portions are loaded; otherwise it may be 8328 SET or CLEAR 8329 8330 8.3.3.5 8331 8332 Bit[5] sensitiveDataOrigin 8333 8334 This attribute is SET for any key that was generated by TPM in TPM2_Create() or 8335 TPM2_CreatePrimary(). If CLEAR, it indicates that the sensitive part of the object (other than the 8336 obfuscation value) was provided by the caller. 8337 NOTE 1 8338 8339 If the fixedTPM attribute is SET, then this attribute is authoritative and accurately reflects the source of 8340 the sensitive area data. If the fixedTPM attribute is CLEAR, then validation of this attribute requires 8341 evaluation of the properties of the ancestor keys. 8342 8343 Creation 8344 8345 If inSensitive.sensitive.data.size is zero, then this attribute shall be SET in the template; 8346 otherwise, it shall be CLEAR in the template. 8347 8348 NOTE 2 8349 8350 The inSensitive.sensitive.data.size parameter is required to be zero for an asymmetric key so 8351 sensitiveDataOrigin is required to be SET. 8352 8353 NOTE 3 8354 8355 The inSensitive.sensitive.data.size parameter may not be zero for a data object so sensitiveDataOrigin is 8356 required to be CLEAR. A data object has type = TPM_ALG_KEYEDHASH and its sign and decrypt 8357 attributes are CLEAR. 8358 8359 Load 8360 8361 8362 8363 may be SET or CLEAR 8364 8365 Import 8366 8367 8368 8369 may be SET or CLEAR 8370 8371 External 8372 8373 8374 8375 may be SET or CLEAR 8376 8377 Page 58 8378 October 31, 2013 8379 8380 Published 8381 Copyright TCG 2006-2013 8382 8383 Family 2.0 8384 Level 00 Revision 00.99 8385 8386 Trusted Platform Module Library 8388 8.3.3.6 8389 8390 Part 2: Structures 8391 8392 Bit[6] userWithAuth 8393 8394 If SET, authorization for operations that require USER role authorization may be given if the caller 8395 provides proof of knowledge of the authValue of the object with an HMAC authorization session or a 8396 password. 8397 If this attribute is CLEAR, then then HMAC or password authorizations may not be used for USER role 8398 authorizations. 8399 NOTE 1 8400 8401 Regardless of the setting of this attribute, authorizations for operations th at require USER role 8402 authorizations may be provided with a policy session that satisfies the object's authPolicy. 8403 8404 NOTE 2 8405 8406 Regardless of the setting of this attribute, the authValue may be referenced in a policy session or used to 8407 provide the bind value in TPM2_StartAuthSession(). However, if userWithAuth is CLEAR, then the object 8408 may be used as the bind object in TPM2_StartAuthSession() but the session cannot be used to authorize 8409 actions on the object. If this were allowed, then the userWithAuth control could be circumvented simply by 8410 using the object as the bind object. 8411 8412 Creation 8413 8414 may be SET or CLEAR in template 8415 8416 Load 8417 8418 8419 8420 may be SET or CLEAR 8421 8422 Import 8423 8424 8425 8426 may be SET or CLEAR 8427 8428 External 8429 8430 8431 8432 may be SET or CLEAR 8433 8434 8.3.3.7 8435 8436 Bit[7] adminWithPolicy 8437 8438 If CLEAR, authorization for operations that require ADMIN role may be given if the caller provides proof of 8439 knowledge of the authValue of the object with an HMAC authorization session or a password. 8440 If this attribute is SET, then then HMAC or password authorizations may not be used for ADMIN role 8441 authorizations. 8442 NOTE 1 8443 8444 Regardless of the setting of this attribute, operations that require ADMIN role authorization may be 8445 provided by a policy session that satisfies the object's authPolicy. 8446 8447 NOTE 2 8448 8449 This attribute is similar to userWithAuth but the logic is a bit different. When userWithAuth is CLEAR, the 8450 authValue may not be used for USER mode authorizations. When adminWithPolicy is CLEAR, it means 8451 that the authValue may be used for ADMIN role. Policy may always be used regardless of t he setting of 8452 userWithAuth or adminWithPolicy. 8453 8454 Actions that always require policy (TPM2_Duplicate()) are not affected by the setting of this attribute. 8455 Creation 8456 8457 may be SET or CLEAR in template 8458 8459 Load 8460 8461 8462 8463 may be SET or CLEAR 8464 8465 Import 8466 8467 8468 8469 may be SET or CLEAR 8470 8471 External 8472 8473 8474 8475 may be SET or CLEAR 8476 8477 8.3.3.8 8478 8479 Bit[10] noDA 8480 8481 If SET, then authorization failures for the object do not affect the dictionary attack protection logic and 8482 authorization of the object is not blocked if the TPM is in lockout. 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 Family 2.0 8506 Level 00 Revision 00.99 8507 8508 Published 8509 Copyright TCG 2006-2013 8510 8511 Page 59 8512 October 31, 2013 8513 8514 Part 2: Structures 8516 8.3.3.9 8517 8518 Trusted Platform Module Library 8519 8520 Bit[11] encryptedDuplication 8521 8522 If SET, then when the object is duplicated, the sensitive portion of the object is required to be encrypted 8523 with an inner wrapper and the new parent shall be an asymmetric key and not TPM_RH_NULL 8524 NOTE 1 8525 8526 Enforcement of these requirements in TPM2_Duplicate() is by not allowing symmetricAlg to be 8527 TPM_ALG_NULL and newParentHandle may not be TPM_RH_NULL. 8528 8529 This attribute shall not be SET in any object that has fixedTPM SET. 8530 NOTE 2 8531 8532 This requirement means that encryptedDuplication may not be SET if the object cannot be directly or 8533 indirectly duplicated. 8534 8535 If an object's parent has fixedTPM SET, and the object is duplicable (fixedParent == CLEAR), then 8536 encryptedDuplication may be SET or CLEAR in the object. 8537 NOTE 3 8538 8539 This allows the object at the boundary between duplicable and non -duplicable objects to have either 8540 setting. 8541 8542 If an object's parent has fixedTPM CLEAR, then the object is required to have the same setting of 8543 encryptedDuplication as its parent. 8544 NOTE 4 8545 8546 This requirement forces all 8547 encryptedDuplication setting. 8548 8549 duplicable 8550 8551 objects 8552 8553 in 8554 8555 a 8556 8557 duplication 8558 8559 group 8560 8561 to 8562 8563 have 8564 8565 the 8566 8567 same 8568 8569 Creation 8570 8571 shall be CLEAR if fixedTPM is SET. If fixedTPM is CLEAR, then this attribute shall have 8572 the same value as its parent unless fixedTPM is SET in the object's parent, in which 8573 case, it may be SET or CLEAR. 8574 8575 Load 8576 8577 8578 8579 shall be CLEAR if fixedTPM is SET. If fixedTPM is CLEAR, then this attribute shall have 8580 the same value as its parent, unless fixedTPM is SET the parent, in which case, it may 8581 be SET or CLEAR. 8582 8583 Import 8584 8585 8586 8587 if fixedTPM is SET in the object's new parent, then this attribute may be SET or CLEAR, 8588 otherwise, it shall have the same setting as the new parent. 8589 8590 External 8591 8592 8593 8594 may be SET or CLEAR. 8595 8596 8.3.3.10 8597 8598 Bit[16] restricted 8599 8600 This this attribute modifies the decrypt and sign attributes of an object. 8601 NOTE 8602 8603 A key with this object CLEAR may not be a parent for another object. 8604 8605 Creation 8606 8607 shall be CLEAR in template if neither sign nor decrypt is SET in template. 8608 8609 Load 8610 8611 8612 8613 shall be CLEAR if neither sign nor decrypt is SET in the object 8614 8615 Import 8616 8617 8618 8619 may be SET or CLEAR 8620 8621 External 8622 8623 8624 8625 shall be CLEAR 8626 8627 Page 60 8628 October 31, 2013 8629 8630 Published 8631 Copyright TCG 2006-2013 8632 8633 Family 2.0 8634 Level 00 Revision 00.99 8635 8636 Trusted Platform Module Library 8638 8.3.3.11 8639 8640 Part 2: Structures 8641 8642 Bit[17] decrypt 8643 8644 When SET, the private portion of this key can be used to decrypt an external blob. If restricted is SET, 8645 then the TPM will return an error if the external decrypted blob is not formatted as appropriate for the 8646 command. 8647 NOTE 1 8648 8649 Since TPM-generated keys and sealed data will contain a hash and a structure tag, the TPM can ensure 8650 that it is not being used to improperly decrypt and return sensitive data that should not be returned. The 8651 only type of data that may be returned after decryption is a Sealed Data Object (a keyedHash object with 8652 decrypt and sign CLEAR). 8653 8654 When restricted is CLEAR, there are no restrictions on the use of the private portion of the key for 8655 decryption and the key may be used to decrypt and return any structure encrypted by the public portion of 8656 the key. 8657 NOTE 2 8658 8659 A key with this attribute SET may be a parent for another object if restricted is SET and sign is CLEAR. 8660 8661 If decrypt is SET on an object with type set to TPM_ALG_KEYEDHASH, it indicates that the object is an 8662 XOR encryption key. 8663 Creation 8664 8665 may be SET or CLEAR in template 8666 8667 Load 8668 8669 8670 8671 may be SET or CLEAR 8672 8673 Import 8674 8675 8676 8677 may be SET or CLEAR 8678 8679 External 8680 8681 8682 8683 may be SET or CLEAR 8684 8685 8.3.3.12 8686 8687 Bit[18] sign 8688 8689 When this attribute is SET, the private portion of this key may be used to sign a digest. If restricted is 8690 SET, then the key may only be used to sign a digest that was computed by the TPM. A restricted signing 8691 key may be used to sign a TPM-generated digest. If a structure is generated by the TPM, it will begin with 8692 TPM_GENERATED_VALUE and the TPM may sign the digest of that structure. If the data is externally 8693 supplied and has TPM_GENERATED_VALUE as its first octets, then the TPM will not sign a digest of 8694 that data with a restricted signing key. 8695 If restricted is CLEAR, then the key may be used to sign any digest, whether generated by the TPM or 8696 externally provided. 8697 NOTE 1 8698 8699 Some asymmetric algorithms may not support both sign and decrypt being SET in the same key. 8700 8701 If sign is SET on an object with type set to TPM_ALG_KEYEDHASH, it indicates that the object is an 8702 HMAC key. 8703 NOTE 2 8704 8705 A key with this attribute SET may not be a parent for another object. 8706 8707 Creation 8708 8709 shall not be SET if decrypt and restricted are both SET 8710 8711 Load 8712 8713 8714 8715 shall not be SET if decrypt and restricted are both SET 8716 8717 Import 8718 8719 8720 8721 shall not be SET if decrypt and restricted are both SET 8722 8723 External 8724 8725 8726 8727 shall not be SET if decrypt and restricted are both SET 8728 8729 Family 2.0 8730 Level 00 Revision 00.99 8731 8732 Published 8733 Copyright TCG 2006-2013 8734 8735 Page 61 8736 October 31, 2013 8737 8738 Part 2: Structures 8740 8.4 8741 8742 Trusted Platform Module Library 8743 8744 TPMA_SESSION (Session Attributes) 8745 8746 This octet in each session is used to identify the session type, indicate its relationship to any handles in 8747 the command, and indicate its use in parameter encryption. 8748 Table 31 Definition of (UINT8) TPMA_SESSION Bits <IN/OUT> 8749 Bit 8750 8751 Name 8752 8753 Meaning 8754 8755 0 8756 8757 continueSession 8758 8759 SET (1): In a command, this setting indicates that the session is to remain active 8760 after successful completion of the command. In a response, it indicates that the 8761 session is still active. If SET in the command, this attribute shall be SET in the 8762 response. 8763 CLEAR (0): In a command, this setting indicates that the TPM should close the 8764 session and flush any related context when the command completes successfully. In 8765 a response, it indicates that the session is closed and the context is no longer active. 8766 This attribute has no meaning for a password authorization and the TPM will allow 8767 any setting of the attribute in the command and SET the attribute in the response. 8768 This attribute will only be CLEAR in one response for a logical session. If the attribute 8769 is CLEAR, the context associated with the session is no longer in use and the space 8770 is available. A session created after another session is ended may have the same 8771 handle but logically is not the same session. 8772 This attribute has no effect if the command does not complete successfully. 8773 8774 1 8775 8776 auditExclusive 8777 8778 SET (1): In a command, this setting indicates that the command should only be 8779 executed if the session is exclusive at the start of the command. In a response, it 8780 indicates that the session is exclusive. This setting is only allowed if the audit 8781 attribute is SET. 8782 CLEAR (0): If audit is CLEAR, then this field is reserved but the error is 8783 TPM_RC_ATTRIBUTES rather than TPM_RC_RESERVED_BITS. 8784 See "Exclusive Audit Session" clause in Part 1. 8785 8786 2 8787 8788 auditReset 8789 8790 SET (1): In a command, this setting indicates that the audit digest of the session 8791 should be initialized and the exclusive status of the session SET. 8792 CLEAR (0): If audit is CLEAR, then this field is reserved but the error is 8793 TPM_RC_ATTRIBUTES rather than TPM_RC_RESERVED_BITS. This setting is 8794 always used for a response. 8795 8796 4:3 8797 8798 Reserved 8799 8800 shall be CLEAR 8801 8802 decrypt 8803 8804 SET (1): In a command, this setting indicates that the first parameter in the command 8805 is symmetrically encrypted using the parameter encryption scheme described in Part 8806 1. The TPM will decrypt the parameter after performing any HMAC computations and 8807 before unmarshaling the parameter. In a response, the attribute is copied from the 8808 request but has no effect on the response. 8809 CLEAR (0): Session not used for encryption. 8810 8811 5 8812 8813 For a password authorization, this attribute will be CLEAR in both the command and 8814 response. 8815 This attribute may only be SET in one session per command. 8816 This attribute may be SET in a session that is not associated with a command 8817 handle. Such a session is provided for purposes of encrypting a parameter and not 8818 for authorization. 8819 This attribute may be SET in combination with any other session attributes. 8820 This attribute may only be SET if the first parameter of the command is a sized buffer 8821 (TPM2B_). 8822 8823 Page 62 8824 October 31, 2013 8825 8826 Published 8827 Copyright TCG 2006-2013 8828 8829 Family 2.0 8830 Level 00 Revision 00.99 8831 8832 Trusted Platform Module Library 8834 8835 Part 2: Structures 8836 8837 Bit 8838 8839 Name 8840 8841 Meaning 8842 8843 6 8844 8845 encrypt 8846 8847 SET (1): In a command, this setting indicates that the TPM should use this session to 8848 encrypt the first parameter in the response. In a response, it indicates that the 8849 attribute was set in the command and that the TPM used the session to encrypt the 8850 first parameter in the response using the parameter encryption scheme described in 8851 Part 1 of this specification. 8852 CLEAR (0): Session not used for encryption. 8853 For a password authorization, this attribute will be CLEAR in both the command and 8854 response. 8855 This attribute may only be SET in one session per command. 8856 This attribute may be SET in a session that is not associated with a command 8857 handle. Such a session is provided for purposes of encrypting a parameter and not 8858 for authorization. 8859 This attribute may only be SET if the first parameter of a response is a sized buffer 8860 (TPM2B_). 8861 8862 7 8863 8864 SET (1): In a command or response, this setting indicates that the session is for audit 8865 and that auditExclusive and auditReset have meaning. This session may also be 8866 used for authorization, encryption, or decryption. The encrypted and encrypt fields 8867 may be SET or CLEAR. 8868 CLEAR (0): Session is not used for audit. 8869 8870 audit 8871 8872 This attribute may only be SET in one session per command or response. If SET in 8873 the command, then this attribute will be SET in the response. 8874 8875 8.5 8876 8877 TPMA_LOCALITY (Locality Attribute) 8878 8879 In a TPMS_CREATION_DATA structure, this structure is used to indicate the locality of the command that 8880 created the object. No more than one of the locality attributes shall be set in the creation data. 8881 When used in TPM2_PolicyLocality(), this structure indicates which localities are approved by the policy. 8882 When a policy is started, all localities are allowed. If TPM2_PolicyLocality() is executed, it indicates that 8883 the command may only be executed at specific localities. More than one locality may be selected. 8884 EXAMPLE 1 8885 8886 TPM_LOC_TWO would indicate that only locality 2 is authorized. 8887 8888 EXAMPLE 2 8889 8890 TPM_LOC_ONE + TPM_LOC_TWO would indicate that locality 1 or 2 is authorized. 8891 8892 EXAMPLE 3 8893 8894 TPM_LOC_FOUR + TPM_LOC_THREE would indicate that localities 3 or 4 are authorized. 8895 8896 EXAMPLE 4 8897 8898 A value of 21 16 would represent a locality of 33. 8899 8900 NOTE 8901 8902 Locality values of 5 through 31 are not selectable. 8903 8904 Family 2.0 8905 Level 00 Revision 00.99 8906 8907 Published 8908 Copyright TCG 2006-2013 8909 8910 Page 63 8911 October 31, 2013 8912 8913 Part 2: Structures 8915 8916 Trusted Platform Module Library 8917 8918 If Extended is non-zero, then an extended locality is indicated and the TPMA_LOCALITY contains an 8919 integer value. 8920 Table 32 Definition of (UINT8) TPMA_LOCALITY Bits <IN/OUT> 8921 Bit 8922 8923 Name 8924 8925 Definition 8926 8927 0 8928 8929 TPM_LOC_ZERO 8930 8931 1 8932 8933 TPM_LOC_ONE 8934 8935 2 8936 8937 TPM_LOC_TWO 8938 8939 3 8940 8941 TPM_LOC_THREE 8942 8943 4 8944 8945 TPM_LOC_FOUR 8946 8947 7:5 8948 8949 8.6 8950 8951 Extended 8952 8953 If any of these bits is set, an extended locality is indicated 8954 8955 TPMA_PERMANENT 8956 8957 The attributes in this structure are persistent and are not changed as a result of _TPM_Init or any 8958 TPM2_Startup(). Some of the attributes in this structure may change as the result of specific Protected 8959 Capabilities. 8960 This 8961 structure 8962 may 8963 be 8964 read 8965 using 8966 TPM2_GetCapability(capability 8967 = 8968 TPM_CAP_TPM_PROPERTIES, property = TPM_PT_PERMANENT). 8969 Table 33 Definition of (UINT32) TPMA_PERMANENT Bits <OUT> 8970 Bit 8971 8972 Parameter 8973 8974 Description 8975 8976 0 8977 8978 ownerAuthSet 8979 8980 SET (1): TPM2_HierarchyChangeAuth() with ownerAuth has been executed since 8981 the last TPM2_Clear(). 8982 CLEAR (0): ownerAuth has not been changed since TPM2_Clear(). 8983 8984 1 8985 8986 endorsementAuthSet 8987 8988 SET (1): TPM2_HierarchyChangeAuth() with endorsementAuth has been executed 8989 since the last TPM2_Clear(). 8990 CLEAR (0): endorsementAuth has not been changed since TPM2_Clear(). 8991 8992 2 8993 8994 lockoutAuthSet 8995 8996 SET (1): TPM2_HierarchyChangeAuth() with lockoutAuth has been executed since 8997 the last TPM2_Clear(). 8998 CLEAR (0): lockoutAuth has not been changed since TPM2_Clear(). 8999 9000 7:3 9001 8 9002 9003 Reserved 9004 disableClear 9005 9006 SET (1): TPM2_Clear() is disabled. 9007 CLEAR (0): TPM2_Clear() is enabled. 9008 NOTE 9009 9010 See TPM2_ClearControl in Part 3 of this specification for details on changing 9011 this attribute. 9012 9013 9 9014 9015 inLockout 9016 9017 SET (1): The TPM is in lockout and commands that require authorization with other 9018 than platformAuth will not succeed. 9019 9020 10 9021 9022 tpmGeneratedEPS 9023 9024 SET (1): The EPS was created by the TPM. 9025 CLEAR (0): The EPS was created outside of the TPM using a manufacturerspecific process. 9026 9027 31:11 Reserved 9028 9029 Page 64 9030 October 31, 2013 9031 9032 Published 9033 Copyright TCG 2006-2013 9034 9035 Family 2.0 9036 Level 00 Revision 00.99 9037 9038 Trusted Platform Module Library 9040 8.7 9041 9042 Part 2: Structures 9043 9044 TPMA_STARTUP_CLEAR 9045 9046 These attributes are set to their default state on reset on each TPM Reset or TPM Restart. The attributes 9047 are preserved on TPM Resume. 9048 On each TPM2_Startup(TPM_SU_CLEAR), the TPM will set these attributes to their indicated defaults. 9049 This structure may be read using TPM2_GetCapability(capability = TPM_CAP_TPM_PROPERTIES, 9050 property = TPM_PT_STARTUP_CLEAR). 9051 Some of attributes may be changed as the result of specific Protected Capabilities. 9052 Table 34 Definition of (UINT32) TPMA_STARTUP_CLEAR Bits <OUT> 9053 Bit 9054 0 9055 9056 Parameter 9057 9058 Description 9059 9060 phEnable 9061 9062 SET (1): (default) The platform hierarchy is enabled and platformAuth or 9063 platformPolicy may be used for authorization. 9064 CLEAR (0): platformAuth and platformPolicy may not be used for authorizations, 9065 and objects in the platform hierarchy, including NV Indexes and persistent objects, 9066 cannot be used. 9067 NOTE 9068 9069 1 9070 9071 shEnable 9072 9073 SET (1): (default) The Storage hierarchy is enabled and ownerAuth or ownerPolicy 9074 may be used for authorization. 9075 CLEAR (0): ownerAuth and ownerPolicy may not be used for authorizations, and 9076 objects in the Storage hierarchy, including NV Indexes and persistent objects, 9077 cannot be used. 9078 NOTE 9079 9080 2 9081 9082 ehEnable 9083 9084 phEnableNV 9085 9086 See TPM2_HierarchyControl in Part 3 of this specification for details on 9087 changing this attribute. 9088 9089 SET (1): (default) The EPS hierarchy is enabled and endorsementAuth may be 9090 used to authorize commands. 9091 CLEAR (0): endorsementAuth and endorsementPolicy may not be used for 9092 authorizations, and objects in the endorsement hierarchy, including persistent 9093 objects, cannot be used. 9094 NOTE 9095 9096 3 9097 9098 See TPM2_HierarchyControl in Part 3 of this specification for details on 9099 changing this attribute. 9100 9101 See TPM2_HierarchyControl in Part 3 of this specification for details on 9102 changing this attribute. 9103 9104 SET (1): (default) NV indices that have TPMA_PLATFORM_CREATE SET may be 9105 read or written. The platform can create define and undefine indices. 9106 CLEAR (0): NV indices that have TPMA_PLATFORM_CREATE SET may not be 9107 read or written (TPM_RC_HANDLE). The platform cannot 9108 define 9109 (TPM_RC_HIERARCHY) or undefined (TPM_RC_HANDLE) indices. 9110 NOTE 9111 See TPM2_HierarchyControl in Part 3 of this specification for details on changing 9112 this attribute. 9113 NOTE 9114 read refers to these commands: TPM2_NV_Read, TPM2_NV_ReadPublic, TPM_NV_Certify, 9115 TPM2_PolicyNV 9116 write refers to thse commands: TPM2_NV_Write, TPM2_NV_Increment, TPM2_NV_Extend, 9117 TPM2_NV_SetBits 9118 NOTE The TPM must query the index TPMA_PLATFORM_CREATE attribute to determine 9119 whether phEnableNV is applicable. Since the TPM will return TPM_RC_HANDLE if the index 9120 does not exist, it also returns this error code if the index is disabled. Otherwise, the TPM 9121 would leak the existence of an index even when disabled. 9122 9123 30:4 Reserved 9124 9125 Family 2.0 9126 Level 00 Revision 00.99 9127 9128 shall be zero 9129 9130 Published 9131 Copyright TCG 2006-2013 9132 9133 Page 65 9134 October 31, 2013 9135 9136 Part 2: Structures 9138 9139 Trusted Platform Module Library 9140 9141 Bit 9142 9143 Parameter 9144 9145 Description 9146 9147 31 9148 9149 orderly 9150 9151 SET (1): The TPM received a TPM2_Shutdown() and a matching TPM2_Startup(). 9152 CLEAR (0): TPM2_Startup(TPM_SU_CLEAR) was not preceded by a 9153 TPM2_Shutdown() of any type. 9154 NOTE 9155 9156 8.8 9157 9158 A shutdown is orderly if the TPM receives a TPM2_Shutdown() of any type 9159 followed by a TPM2_Startup() of any type. However, the TPM will return an error if 9160 TPM2_Startup(TPM_SU_STATE) 9161 was 9162 not 9163 preceded 9164 by 9165 TPM2_State_Save(TPM_SU_STATE). 9166 9167 TPMA_MEMORY 9168 9169 This structure of this attribute is used to report the memory management method used by the TPM for 9170 transient 9171 objects 9172 and 9173 authorization 9174 sessions. 9175 This 9176 structure 9177 may be 9178 read 9179 using 9180 TPM2_GetCapability(capability = TPM_CAP_TPM_PROPERTIES, property = TPM_PT_MEMORY). 9181 If the RAM memory is shared, then context save of a session may make it possible to load an additional 9182 transient object. 9183 Table 35 Definition of (UINT32) TPMA_MEMORY Bits <Out> 9184 Bit 9185 9186 Name 9187 9188 Definition 9189 9190 0 9191 9192 sharedRAM 9193 9194 SET (1): indicates that the RAM memory used for authorization session 9195 contexts is shared with the memory used for transient objects 9196 CLEAR (0): indicates that the memory used for authorization sessions is not 9197 shared with memory used for transient objects 9198 9199 1 9200 9201 sharedNV 9202 9203 SET (1): indicates that the NV memory used for persistent objects is shared 9204 with the NV memory used for NV Index values 9205 CLEAR (0): indicates that the persistent objects and NV Index values are 9206 allocated from separate sections of NV 9207 9208 2 9209 9210 objectCopiedToRam 9211 9212 SET (1): indicates that the TPM copies persistent objects to a transient-object 9213 slot in RAM when the persistent object is referenced in a command. The TRM 9214 is required to make sure that an object slot is available. 9215 CLEAR (0): indicates that the TPM does not use transient-object slots when 9216 persistent objects are referenced 9217 9218 31:3 9219 9220 Reserved 9221 9222 shall be zero 9223 9224 Page 66 9225 October 31, 2013 9226 9227 Published 9228 Copyright TCG 2006-2013 9229 9230 Family 2.0 9231 Level 00 Revision 00.99 9232 9233 Trusted Platform Module Library 9235 8.9 9236 9237 Part 2: Structures 9238 9239 TPMA_CC (Command Code Attributes) 9240 9241 8.9.1 9242 9243 Introduction 9244 9245 This structure defines the attributes of a command from a context management perspective. The fields of 9246 the structure indicate to the TPM Resource Manager (TRM) the number of resources required by a 9247 command and how the command affects the TPMs resources. 9248 This structure is only used in a list returned by the TPM in response to TPM2_GetCapability(capability = 9249 TPM_CAP_COMMANDS). 9250 For a command to the TPM, only the commandIndex field and V attribute are allowed to be non-zero. 9251 8.9.2 9252 9253 Structure Definition 9254 Table 36 Definition of (TPM_CC) TPMA_CC Bits <OUT> 9255 9256 Bit 9257 15:0 9258 9259 Name 9260 9261 Definition 9262 9263 commandIndex 9264 9265 indicates the command being selected 9266 9267 21:16 Reserved 9268 9269 shall be zero 9270 9271 22 9272 9273 nv 9274 9275 SET (1): indicates that the command may write to NV 9276 CLEAR (0): indicates that the command does not write to NV 9277 9278 23 9279 9280 extensive 9281 9282 SET (1): This command could flush any number of loaded contexts. 9283 CLEAR (0): no additional changes other than indicated by the flushed attribute 9284 9285 24 9286 9287 flushed 9288 9289 SET (1): The context associated with any transient handle in the command will 9290 be flushed when this command completes. 9291 CLEAR (0): No context is flushed as a side effect of this command. 9292 9293 27:25 cHandles 9294 9295 indicates the number of the handles in the handle area for this command 9296 9297 28 9298 9299 rHandle 9300 9301 SET (1): indicates the presence of the handle area in the input 9302 9303 29 9304 9305 V 9306 9307 SET (1): indicates that the command is vendor-specific 9308 CLEAR (0): indicates that the command is defined in a version of this 9309 specification 9310 9311 31:30 Res 9312 9313 8.9.3 9314 8.9.3.1 9315 9316 allocated for software; shall be zero 9317 9318 Field Descriptions 9319 Bits[15:0] commandIndex 9320 9321 This is the command index of the command in the set of commands. The two sets are defined by the V 9322 attribute. If V is zero, then the commandIndex shall be in the set of commands defined in a version of this 9323 specification. If V is one, then the meaning of commandIndex is as determined by the TPM vendor. 9324 8.9.3.2 9325 9326 Bit[22] nv 9327 9328 If this attribute is SET, then the TPM may perform an NV write as part of the command actions. This write 9329 is independent of any write that may occur as a result of dictionary attack protection. If this attribute is 9330 CLEAR, then the TPM shall not perform an NV write as part of the command actions. 9331 8.9.3.3 9332 9333 Bit[23] extensive 9334 9335 Family 2.0 9336 Level 00 Revision 00.99 9337 9338 Published 9339 Copyright TCG 2006-2013 9340 9341 Page 67 9342 October 31, 2013 9343 9344 Part 2: Structures 9346 9347 Trusted Platform Module Library 9348 9349 If this attribute is SET, then the TPM may flush many transient objects as a side effect of this command. 9350 In Part 3, a command that has this attribute is indicated by using a {E} decoration in the Description 9351 column of the commandCode parameter. 9352 EXAMPLE 9353 9354 See TPM2_Clear in Part 3. 9355 9356 NOTE 9357 9358 The {E} decoration may be combined with other decorations such as {NV} in which case the decoration 9359 would be {NV E}. 9360 9361 8.9.3.4 9362 9363 Bit[24] flushed 9364 9365 If this attribute is SET, then the TPM will flush transient objects as a side effect of this command. Any 9366 transient objects listed in the handle area of the command will be flushed from TPM memory. Handles 9367 associated with persistent objects, sessions, PCR, or other fixed TPM resources are not flushed. 9368 NOTE 9369 9370 The TRM is expected to use this value to determine how many objects are loaded into transient TPM 9371 memory. 9372 9373 NOTE 9374 9375 The {F} decoration may be combined with other decorations such as {NV} in which case the decoration 9376 would be {NV F}. 9377 9378 If this attribute is SET for a command, and the handle of the command is associated with a hierarchy 9379 (TPM_RH_PLATFORM, TPM_RH_OWNER, or TPM_RH_ENDORSEMENT), all loaded objects in the 9380 indicated hierarchy are flushed. 9381 The TRM is expected to know the behaviour of TPM2_ContextSave(), and sessions are flushed when 9382 context saved, but objects are not. The flushed attribute for that command shall be CLEAR. 9383 In Part 3, a command that has this attribute is indicated by using a {F} decoration in the Description 9384 column of the commandCode parameter. 9385 EXAMPLE 9386 9387 8.9.3.5 9388 9389 See TPM2_SequenceComplete in Part 3. 9390 9391 Bits[27:25] cHandles 9392 9393 This field indicates the number of handles in the handle area of the command. This number allows the 9394 TRM to enumerate the handles in the handle area and find the position of the authorizations (if any). 9395 8.9.3.6 9396 9397 Bit[28] rHandle 9398 9399 If this attribute is SET, then the response to this command has a handle area. This area will contain no 9400 more than one handle. This field is necessary to allow the TRM to locate the parameterSize field in the 9401 response, which is then used to locate the authorizations. 9402 NOTE 9403 9404 The TRM is expected to virtualize the handle value for any returned handle. 9405 9406 Page 68 9407 October 31, 2013 9408 9409 Published 9410 Copyright TCG 2006-2013 9411 9412 Family 2.0 9413 Level 00 Revision 00.99 9414 9415 Trusted Platform Module Library 9417 9418 Part 2: Structures 9419 9420 A TPM command is only allowed to have one handle in the session area. 9421 8.9.3.7 9422 9423 Bit[29] V 9424 9425 When this attribute is SET, it indicates that the command operation is defined by the TPM vendor. When 9426 CLEAR, it indicates that the command is defined by a version of this specification. 9427 8.9.3.8 9428 9429 Bits[31:30] Res 9430 9431 This field is reserved for system software. This field is required to be zero for a command to the TPM. 9432 9433 Family 2.0 9434 Level 00 Revision 00.99 9435 9436 Published 9437 Copyright TCG 2006-2013 9438 9439 Page 69 9440 October 31, 2013 9441 9442 Part 2: Structures 9444 9445 9 9446 9447 Trusted Platform Module Library 9448 9449 Interface Types 9450 9451 9.1 9452 9453 Introduction 9454 9455 This clause contains definitions for interface types. An interface type is type checked when it is 9456 unmarshaled. These types are based on an underlying type that is indicated in the table title by the value 9457 in parentheses. When an interface type is used, the base type is unmarshaled and then checked to see if 9458 it has one of the allowed values. 9459 9.2 9460 9461 TPMI_YES_NO 9462 9463 This interface type is used in place of a Boolean type in order to eliminate ambiguity in the handling of a 9464 octet that conveys a single bit of information. This type only has two allowed values, YES (1) and NO (0). 9465 NOTE 9466 9467 This list is not used as input to the TPM. 9468 9469 Table 37 Definition of (BYTE) TPMI_YES_NO Type 9470 Value 9471 9472 Description 9473 9474 NO 9475 9476 a value of 0 9477 9478 YES 9479 9480 a value of 1 9481 9482 #TPM_RC_VALUE 9483 9484 9.3 9485 9486 TPMI_DH_OBJECT 9487 9488 The TPMI_DH_OBJECT interface type is a handle that references a loaded object. The handles in this 9489 set are used to refer to either transient or persistent object. The range of these values would change 9490 according to the TPM implementation. 9491 NOTE 9492 9493 These interface types should not be used by system software to qualify the keys produced by the TPM. 9494 The value returned by the TPM shall be used to reference the object. 9495 9496 Table 38 Definition of (TPM_HANDLE) TPMI_DH_OBJECT Type 9497 Values 9498 9499 Comments 9500 9501 {TRANSIENT_FIRST:TRANSIENT_LAST} 9502 9503 allowed range for transient objects 9504 9505 {PERSISTENT_FIRST:PERSISTENT_LAST} 9506 9507 allowed range for persistent objects 9508 9509 +TPM_RH_NULL 9510 9511 the conditional value 9512 9513 #TPM_RC_VALUE 9514 9515 Page 70 9516 October 31, 2013 9517 9518 Published 9519 Copyright TCG 2006-2013 9520 9521 Family 2.0 9522 Level 00 Revision 00.99 9523 9524 Trusted Platform Module Library 9526 9.4 9527 9528 Part 2: Structures 9529 9530 TPMI_DH_PERSISTENT 9531 9532 The TPMI_DH_PERSISTENT interface type is a handle that references a location for a transient object. 9533 This type is used in TPM2_EvictControl() to indicate the handle to be assigned to the persistent object. 9534 Table 39 Definition of (TPM_HANDLE) TPMI_DH_PERSISTENT Type 9535 Values 9536 9537 Comments 9538 9539 {PERSISTENT_FIRST:PERSISTENT_LAST} 9540 9541 allowed range for persistent objects 9542 9543 #TPM_RC_VALUE 9544 9545 9.5 9546 9547 TPMI_DH_ENTITY 9548 9549 The TPMI_DH_ENTITY interface type is TPM-defined values that are used to indicate that the handle 9550 refers to an authValue. The range of these values would change according to the TPM implementation. 9551 Table 40 Definition of (TPM_HANDLE) TPMI_DH_ENTITY Type <IN> 9552 Values 9553 9554 Comments 9555 9556 TPM_RH_OWNER 9557 TPM_RH_ENDORSEMENT 9558 TPM_RH_PLATFORM 9559 TPM_RH_LOCKOUT 9560 {TRANSIENT_FIRST : TRANSIENT_LAST} 9561 9562 range of object handles 9563 9564 {PERSISTENT_FIRST : PERSISTENT_LAST} 9565 {NV_INDEX_FIRST : NV_INDEX_LAST} 9566 {PCR_FIRST : PCR_LAST} 9567 +TPM_RH_NULL 9568 9569 conditional value 9570 9571 #TPM_RC_VALUE 9572 9573 Family 2.0 9574 Level 00 Revision 00.99 9575 9576 Published 9577 Copyright TCG 2006-2013 9578 9579 Page 71 9580 October 31, 2013 9581 9582 Part 2: Structures 9584 9.6 9585 9586 Trusted Platform Module Library 9587 9588 TPMI_DH_PCR 9589 9590 This interface type consists of the handles that may be used as PCR references. The upper end of this 9591 range of values would change according to the TPM implementation. 9592 NOTE 1 9593 9594 Typically, the 0 th PCR will have a handle value of zero. 9595 9596 NOTE 2 9597 9598 The handle range for PCR is defined to be the same as the handle range for PCR in previous versions of 9599 TPM specifications. 9600 9601 Table 41 Definition of (TPM_HANDLE) TPMI_DH_PCR Type <IN> 9602 Values 9603 9604 Comments 9605 9606 {PCR_FIRST:PCR_LAST} 9607 +TPM_RH_NULL 9608 9609 conditional value 9610 9611 #TPM_RC_VALUE 9612 9613 9.7 9614 9615 TPMI_SH_AUTH_SESSION 9616 9617 The TPMI_SH_AUTH_SESSION interface type is TPM-defined values that are used to indicate that the 9618 handle refers to an authorization session. 9619 Table 42 Definition of (TPM_HANDLE) TPMI_SH_AUTH_SESSION Type <IN/OUT> 9620 Values 9621 9622 Comments 9623 9624 {HMAC_SESSION_FIRST : HMAC_SESSION_LAST} 9625 9626 range of HMAC authorization session handles 9627 9628 {POLICY_SESSION_FIRST: POLICY_SESSION_LAST} 9629 9630 range of policy authorization session handles 9631 9632 +TPM_RS_PW 9633 9634 a password authorization 9635 9636 #TPM_RC_VALUE 9637 9638 error returned if the handle is out of range 9639 9640 9.8 9641 9642 TPMI_SH_HMAC 9643 9644 This interface type is used for an authorization handle when the authorization session uses an HMAC. 9645 Table 43 Definition of (TPM_HANDLE) TPMI_SH_HMAC Type <IN/OUT> 9646 Values 9647 9648 Comments 9649 9650 {HMAC_SESSION_FIRST: HMAC_SESSION_LAST} 9651 9652 range of HMAC authorization session handles 9653 9654 #TPM_RC_VALUE 9655 9656 error returned if the handle is out of range 9657 9658 9.9 9659 9660 TPMI_SH_POLICY 9661 9662 This interface type is used for a policy handle when it appears in a policy command. 9663 Table 44 Definition of (TPM_HANDLE) TPMI_SH_POLICY Type <IN/OUT> 9664 Values 9665 9666 Comments 9667 9668 {POLICY_SESSION_FIRST: POLICY_SESSION_LAST} 9669 9670 range of policy authorization session handles 9671 9672 #TPM_RC_VALUE 9673 9674 error returned if the handle is out of range 9675 9676 Page 72 9677 October 31, 2013 9678 9679 Published 9680 Copyright TCG 2006-2013 9681 9682 Family 2.0 9683 Level 00 Revision 00.99 9684 9685 Trusted Platform Module Library 9687 9688 Part 2: Structures 9689 9690 9.10 TPMI_DH_CONTEXT 9691 This type defines the handle values that may be used in TPM2_ContextSave() or TPM2_Flush(). 9692 Table 45 Definition of (TPM_HANDLE) TPMI_DH_CONTEXT Type 9693 Values 9694 9695 Comments 9696 9697 {HMAC_SESSION_FIRST : HMAC_SESSION_LAST} 9698 {POLICY_SESSION_FIRST:POLICY_SESSION_LAST} 9699 {TRANSIENT_FIRST:TRANSIENT_LAST} 9700 #TPM_RC_VALUE 9701 9702 9.11 TPMI_RH_HIERARCHY 9703 The TPMI_RH_HIERARCHY interface type is used as the type of a handle in a command when the 9704 handle is required to be one of the hierarchy selectors. 9705 Table 46 Definition of (TPM_HANDLE) TPMI_RH_HIERARCHY Type 9706 Values 9707 9708 Comments 9709 9710 TPM_RH_OWNER 9711 9712 Storage hierarchy 9713 9714 TPM_RH_PLATFORM 9715 9716 Platform hierarchy 9717 9718 TPM_RH_ENDORSEMENT 9719 9720 Endorsement hierarchy 9721 9722 +TPM_RH_NULL 9723 9724 no hierarchy 9725 9726 #TPM_RC_VALUE 9727 9728 response code returned when the unmarshaling of this type fails 9729 9730 9.12 TPMI_RH_ENABLES 9731 The TPMI_RH_ENABLES interface type is used as the type of a handle in a command when the handle 9732 is required to be one of the hierarchy or NV enables. 9733 Table 47 Definition of (TPM_HANDLE) TPMI_RH_ENABLES 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_PLATFORM_NV 9751 9752 Platform NV 9753 9754 +TPM_RH_NULL 9755 9756 no hierarchy 9757 9758 #TPM_RC_VALUE 9759 9760 response code returned when the unmarshaling of this type fails 9761 9762 Family 2.0 9763 Level 00 Revision 00.99 9764 9765 Published 9766 Copyright TCG 2006-2013 9767 9768 Page 73 9769 October 31, 2013 9770 9771 Part 2: Structures 9773 9774 Trusted Platform Module Library 9775 9776 9.13 TPMI_RH_HIERARCHY_AUTH 9777 This interface type is used as the type of a handle in a command when the handle is required to be one of 9778 the hierarchy selectors or the Lockout Authorization. 9779 Table 48 Definition of (TPM_HANDLE) TPMI_RH_HIERARCHY_AUTH Type <IN> 9780 Values 9781 9782 Comments 9783 9784 TPM_RH_OWNER 9785 9786 Storage hierarchy 9787 9788 TPM_RH_PLATFORM 9789 9790 Platform hierarchy 9791 9792 TPM_RH_ENDORSEMENT 9793 9794 Endorsement hierarchy 9795 9796 TPM_RH_LOCKOUT 9797 9798 Lockout Authorization 9799 9800 #TPM_RC_VALUE 9801 9802 response code returned when the unmarshaling of this type fails 9803 9804 9.14 TPMI_RH_PLATFORM 9805 The TPMI_RH_PLATFORM interface type is used as the type of a handle in a command when the only 9806 allowed handle is TPM_RH_PLATFORM indicating that platformAuth is required. 9807 Table 49 Definition of (TPM_HANDLE) TPMI_RH_PLATFORM Type <IN> 9808 Values 9809 9810 Comments 9811 9812 TPM_RH_PLATFORM 9813 9814 Platform hierarchy 9815 9816 #TPM_RC_VALUE 9817 9818 response code returned when the unmarshaling of this type fails 9819 9820 9.15 TPMI_RH_OWNER 9821 This interface type is used as the type of a handle in a command when the only allowed handle is 9822 TPM_RH_OWNER indicating that ownerAuth is required. 9823 Table 50 Definition of (TPM_HANDLE) TPMI_RH_OWNER Type <IN> 9824 Values 9825 9826 Comments 9827 9828 TPM_RH_OWNER 9829 9830 Owner hierarchy 9831 9832 +TPM_RH_NULL 9833 9834 may allow the null handle 9835 9836 #TPM_RC_VALUE 9837 9838 response code returned when the unmarshaling of this type fails 9839 9840 Page 74 9841 October 31, 2013 9842 9843 Published 9844 Copyright TCG 2006-2013 9845 9846 Family 2.0 9847 Level 00 Revision 00.99 9848 9849 Trusted Platform Module Library 9851 9852 Part 2: Structures 9853 9854 9.16 TPMI_RH_ENDORSEMENT 9855 This interface type is used as the type of a handle in a command when the only allowed handle is 9856 TPM_RH_ENDORSEMENT indicating that endorsementAuth is required. 9857 Table 51 Definition of (TPM_HANDLE) TPMI_RH_ENDORSEMENT Type <IN> 9858 Values 9859 9860 Comments 9861 9862 TPM_RH_ENDORSEMENT 9863 9864 Endorsement hierarchy 9865 9866 +TPM_RH_NULL 9867 9868 may allow the null handle 9869 9870 #TPM_RC_VALUE 9871 9872 response code returned when the unmarshaling of this type fails 9873 9874 9.17 TPMI_RH_PROVISION 9875 The TPMI_RH_PROVISION interface type is used as the type of the handle in a command when the only 9876 allowed handles are either TPM_RH_OWNER or TPM_RH_PLATFORM indicating that either 9877 platformAuth or ownerAuth are allowed. 9878 In most cases, either platformAuth or ownerAuth may be used to authorize the commands used for 9879 management of the resources of the TPM and this interface type will be used. 9880 Table 52 Definition of (TPM_HANDLE) TPMI_RH_PROVISION Type <IN> 9881 Value 9882 9883 Comments 9884 9885 TPM_RH_OWNER 9886 9887 handle for ownerAuth 9888 9889 TPM_RH_PLATFORM 9890 9891 handle for platformAuth 9892 9893 #TPM_RC_VALUE 9894 9895 response code returned when the unmarshaling of this type fails 9896 9897 9.18 TPMI_RH_CLEAR 9898 The TPMI_RH_CLEAR interface type is used as the type of the handle in a command when the only 9899 allowed handles are either TPM_RH_LOCKOUT or TPM_RH_PLATFORM indicating that either 9900 platformAuth or lockoutAuth are allowed. 9901 This interface type is normally used for performing or controlling TPM2_Clear(). 9902 Table 53 Definition of (TPM_HANDLE) TPMI_RH_CLEAR Type <IN> 9903 Value 9904 9905 Comments 9906 9907 TPM_RH_LOCKOUT 9908 9909 handle for lockoutAuth 9910 9911 TPM_RH_PLATFORM 9912 9913 handle for platformAuth 9914 9915 #TPM_RC_VALUE 9916 9917 response code returned when the unmarshaling of this type fails 9918 9919 Family 2.0 9920 Level 00 Revision 00.99 9921 9922 Published 9923 Copyright TCG 2006-2013 9924 9925 Page 75 9926 October 31, 2013 9927 9928 Part 2: Structures 9930 9931 Trusted Platform Module Library 9932 9933 9.19 TPMI_RH_NV_AUTH 9934 This interface type is used to identify the source of the authorization for access to an NV location. The 9935 handle value of a TPMI_RH_NV_AUTH shall indicate that the authorization value is either platformAuth, 9936 ownerAuth, or the authValue. This type is used in the commands that access an NV Index (commands of 9937 the form TPM2_NV_xxx) other than TPM2_NV_DefineSpace() and TPM2_NV_UndefineSpace(). 9938 Table 54 Definition of (TPM_HANDLE) TPMI_RH_NV_AUTH Type <IN> 9939 Value 9940 9941 Comments 9942 9943 TPM_RH_PLATFORM 9944 9945 platformAuth is allowed 9946 9947 TPM_RH_OWNER 9948 9949 ownerAuth is allowed 9950 9951 {NV_INDEX_FIRST:NV_INDEX_LAST} 9952 9953 range for NV locations 9954 9955 #TPM_RC_VALUE 9956 9957 response code returned when unmarshaling of this type fails 9958 9959 9.20 TPMI_RH_LOCKOUT 9960 The TPMI_RH_LOCKOUT interface type is used as the type of a handle in a command when the only 9961 allowed handle is TPM_RH_LOCKOUT indicating that lockoutAuth is required. 9962 Table 55 Definition of (TPM_HANDLE) TPMI_RH_LOCKOUT Type <IN> 9963 Value 9964 9965 Comments 9966 9967 TPM_RH_LOCKOUT 9968 #TPM_RC_VALUE 9969 9970 response code returned when the unmarshaling of this type fails 9971 9972 9.21 TPMI_RH_NV_INDEX 9973 This interface type is used to identify an NV location. This type is used in the NV commands. 9974 Table 56 Definition of (TPM_HANDLE) TPMI_RH_NV_INDEX Type <IN/OUT> 9975 Value 9976 9977 Comments 9978 9979 {NV_INDEX_FIRST:NV_INDEX_LAST} 9980 9981 Range of NV Indexes 9982 9983 #TPM_RC_VALUE 9984 9985 error returned if the handle is out of range 9986 9987 Page 76 9988 October 31, 2013 9989 9990 Published 9991 Copyright TCG 2006-2013 9992 9993 Family 2.0 9994 Level 00 Revision 00.99 9995 9996 Trusted Platform Module Library 9998 9999 Part 2: Structures 10000 10001 9.22 TPMI_ALG_HASH 10002 A TPMI_ALG_HASH is an interface type of all the hash algorithms implemented on a specific TPM. Table 10003 57 is a list of the hash algorithms that have an algorithm ID assigned by the TCG and does not indicate 10004 the algorithms that will be accepted by a TPM. 10005 NOTE 10006 10007 An implementation would modify this table according to the implemented algorithms, changing the values 10008 that are accepted as hash algorithms. 10009 10010 Table 57 Definition of (TPM_ALG_ID) TPMI_ALG_HASH Type 10011 Values 10012 10013 Comments 10014 10015 TPM_ALG_SHA1 10016 10017 example 10018 10019 TPM_ALG_SHA256 10020 10021 example 10022 10023 TPM_ALG_SM3_256 10024 10025 example 10026 10027 TPM_ALG_SHA384 10028 10029 example 10030 10031 TPM_ALG_SHA512 10032 10033 example 10034 10035 +TPM_ALG_NULL 10036 #TPM_RC_HASH 10037 10038 9.23 TPMI_ALG_ASYM (Asymmetric Algorithms) 10039 A TPMI_ALG_ASYM is an interface type of all the asymmetric algorithms implemented on a specific TPM. 10040 Table 58 lists each of the asymmetric algorithms that have an algorithm ID assigned by the TCG. 10041 Table 58 Definition of (TPM_ALG_ID) TPMI_ALG_ASYM Type 10042 Values 10043 10044 Comments 10045 10046 TPM_ALG_RSA 10047 TPM_ALG_ECC 10048 +TPM_ALG_NULL 10049 #TPM_RC_ASYMMETRIC 10050 10051 Family 2.0 10052 Level 00 Revision 00.99 10053 10054 Published 10055 Copyright TCG 2006-2013 10056 10057 Page 77 10058 October 31, 2013 10059 10060 Part 2: Structures 10062 10063 Trusted Platform Module Library 10064 10065 9.24 TPMI_ALG_SYM (Symmetric Algorithms) 10066 A TPMI_ALG_SYM is an interface type of all the symmetric algorithms that have an algorithm ID assigned 10067 by the TCG and are implemented on the TPM. 10068 The list in the table below is illustrative and will change according to the implementation. The validation 10069 code will only accept the subset of algorithms implemented on a TPM. 10070 NOTE 10071 10072 The validation code produced by an example script will produce a CASE statement with a case for each of 10073 the values in the Values column. The case for a value is delimited by a #ifdef/#endif pair so that if the 10074 algorithm is not implemented on the TPM, then the case for the algorithm is not generated, and use of the 10075 algorithm will cause a TPM error (TPM_RC_SYMMETRIC). 10076 10077 Table 59 Definition of (TPM_ALG_ID) TPMI_ALG_SYM Type 10078 Values 10079 10080 Comments 10081 10082 TPM_ALG_AES 10083 10084 example 10085 10086 TPM_ALG_SM4 10087 10088 example 10089 10090 TPM_ALG_XOR 10091 10092 example 10093 10094 +TPM_ALG_NULL 10095 10096 required to be present in all versions of this table 10097 10098 #TPM_RC_SYMMETRIC 10099 10100 9.25 TPMI_ALG_SYM_OBJECT 10101 A TPMI_ALG_SYM_OBJECT is an interface type of all the TCG-defined symmetric algorithms that may 10102 be used as companion symmetric encryption algorithm for an asymmetric object. All algorithms in this list 10103 shall be block ciphers usable in Cipher Feedback (CFB). 10104 Table 60 is illustrative. It would be modified to indicate the algorithms of the TPM. 10105 NOTE 10106 10107 TPM_ALG_XOR is not allowed in this list. 10108 10109 Table 60 Definition of (TPM_ALG_ID) TPMI_ALG_SYM_OBJECT Type 10110 Values 10111 10112 Comments 10113 10114 TPM_ALG_AES 10115 10116 example 10117 10118 TPM_ALG_SM4 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 Page 78 10129 October 31, 2013 10130 10131 Published 10132 Copyright TCG 2006-2013 10133 10134 Family 2.0 10135 Level 00 Revision 00.99 10136 10137 Trusted Platform Module Library 10139 10140 Part 2: Structures 10141 10142 9.26 TPMI_ALG_SYM_MODE 10143 A TPMI_ALG_SYM_MODE is an interface type of all the TCG-defined block-cipher modes of operation. 10144 This version of the table is not expected to be the table checked by the validation code. Rather, the table 10145 would be replaced by one containing the algorithms implemented on the TPM and that the values in that 10146 table would be checked by the input validation code. 10147 Table 61 Definition of (TPM_ALG_ID) TPMI_ALG_SYM_MODE Type 10148 Values 10149 10150 Comments 10151 10152 TPM_ALG_CTR 10153 10154 IV will be determined by use. 10155 If the outside provides the nonce and initial counter, then the caller can 10156 know what IV to provide for chaining. 10157 10158 TPM_ALG_OFB 10159 10160 XOR last cipher text block with last plaintext to create IV for next block 10161 10162 TPM_ALG_CBC 10163 10164 IV will be determined by use. 10165 indefinite chaining using previous output block as IV for next block 10166 10167 TPM_ALG_CFB 10168 10169 shall be implemented in all TPM compliant with this specification 10170 IV will be determined by use. 10171 indefinite chaining using previous cipher text as IV 10172 10173 TPM_ALG_ECB 10174 10175 no IV or chaining value required 10176 10177 +TPM_ALG_NULL 10178 #TPM_RC_MODE 10179 10180 9.27 TPMI_ALG_KDF (Key and Mask Generation Functions) 10181 A TPMI_ALG_KDF is an interface type of all the key derivation functions implemented on a specific TPM. 10182 Table 62 is exemplary and would change based on the algorithms implemented in a TPM. 10183 Table 62 Definition of (TPM_ALG_ID) TPMI_ALG_KDF Type 10184 Values 10185 10186 Comments 10187 10188 TPM_ALG_MGF1 10189 TPM_ALG_KDF1_SP800_108 10190 TPM_ALG_KDF1_SP800_56a 10191 TPM_ALG_KDF2 10192 +TPM_ALG_NULL 10193 #TPM_RC_KDF 10194 10195 Family 2.0 10196 Level 00 Revision 00.99 10197 10198 Published 10199 Copyright TCG 2006-2013 10200 10201 Page 79 10202 October 31, 2013 10203 10204 Part 2: Structures 10206 10207 Trusted Platform Module Library 10208 10209 9.28 TPMI_ALG_SIG_SCHEME 10210 This is the definition of the interface type for a signature scheme. This table would change according to 10211 the algorithms implemented on the TPM. 10212 Table 63 Definition of (TPM_ALG_ID) TPMI_ALG_SIG_SCHEME Type 10213 Values 10214 10215 Comments 10216 10217 TPM_ALG_RSASSA 10218 10219 requires that RSA be implemented 10220 10221 TPM_ALG_RSAPSS 10222 10223 requires that RSA be implemented 10224 10225 TPM_ALG_ECDSA 10226 10227 requires that ECC be implemented 10228 10229 TPM_ALG_ECDAA 10230 10231 requires that ECC and ECDAA be implemented 10232 10233 TPM_ALG_ECSCHNORR 10234 TPM_ALG_SM2 10235 10236 requires that ECC be implemented 10237 10238 TPM_ALG_HMAC 10239 10240 present on all TPM 10241 10242 +TPM_ALG_NULL 10243 #TPM_RC_SCHEME 10244 10245 response code when a signature scheme is not correct 10246 10247 9.29 TPMI_ECC_KEY_EXCHANGE 10248 This is the definition of the interface type for an ECC key exchange scheme. This table would change 10249 according to the algorithms implemented on the TPM. 10250 Table 64 Definition of (TPM_ALG_ID) TPMI_ECC_KEY_EXCHANGE Type 10251 Values 10252 10253 Comments 10254 10255 TPM_ALG_ECDH 10256 10257 used for single and two phase key exchange 10258 10259 TPM_ALG_ECMQV 10260 TPM_ALG_SM2 10261 10262 requires that ECC be implemented 10263 10264 +TPM_ALG_NULL 10265 #TPM_RC_SCHEME 10266 10267 response code when a key exchange scheme is not correct 10268 10269 9.30 TPMI_ST_COMMAND_TAG 10270 This interface type is used for the command tags. 10271 The response code for a bad command tag has the same value as the TPM 1.2 response code 10272 (TPM_BAD_TAG). This value is used in case the software is not compatible with this specification and an 10273 unexpected response code might have unexpected side effects. 10274 Table 65 Definition of (TPM_ST) TPMI_ST_COMMAND_TAG Type 10275 Values 10276 10277 Comments 10278 10279 TPM_ST_NO_SESSIONS 10280 TPM_ST_SESSIONS 10281 #TPM_RC_BAD_TAG 10282 10283 Page 80 10284 October 31, 2013 10285 10286 Published 10287 Copyright TCG 2006-2013 10288 10289 Family 2.0 10290 Level 00 Revision 00.99 10291 10292 Trusted Platform Module Library 10294 10295 Part 2: Structures 10296 10297 10 Structure Definitions 10298 10.1 TPMS_ALGORITHM_DESCRIPTION 10299 This structure is a return value for a TPM2_GetCapability() that reads the installed algorithms. 10300 Table 66 Definition of TPMS_ALGORITHM_DESCRIPTION Structure <OUT> 10301 Parameter 10302 10303 Type 10304 10305 Description 10306 10307 alg 10308 10309 TPM_ALG_ID 10310 10311 an algorithm 10312 10313 attributes 10314 10315 TPMA_ALGORITHM 10316 10317 the attributes of the algorithm 10318 10319 10.2 Hash/Digest Structures 10320 10.2.1 TPMU_HA (Hash) 10321 A TPMU_HA is a union of all the hash algorithms implemented on a TPM. Table 67 is exemplary and 10322 would change based on the algorithms implemented in a TPM. 10323 NOTE 10324 10325 If processed by an automated tool, each entry of the table should be qualified (with #ifdef/#endif) so that if 10326 the hash algorithm is not implemented on the TPM, the parameter associated with that hash is not 10327 present. This will keep the union from being larger than the largest digest of a hash implemented on that 10328 TPM. 10329 10330 Table 67 Definition of TPMU_HA Union <IN/OUT, S> 10331 Parameter 10332 10333 Type 10334 10335 Selector 10336 10337 sha1 [SHA1_DIGEST_SIZE] 10338 10339 BYTE 10340 10341 TPM_ALG_SHA1 10342 10343 sha256 [SHA256_DIGEST_SIZE] 10344 10345 BYTE 10346 10347 TPM_ALG_SHA256 10348 10349 sm3_256 [SM3_256_DIGEST_SIZE] 10350 10351 BYTE 10352 10353 TPM_ALG_SM3_256 10354 10355 sha384 [SHA384_DIGEST_SIZE] 10356 10357 BYTE 10358 10359 TPM_ALG_SHA384 10360 10361 sha512 [SHA512_DIGEST_SIZE] 10362 10363 BYTE 10364 10365 TPM_ALG_SHA512 10366 10367 null 10368 10369 Family 2.0 10370 Level 00 Revision 00.99 10371 10372 Description 10373 10374 TPM_ALG_NULL 10375 10376 Published 10377 Copyright TCG 2006-2013 10378 10379 Page 81 10380 October 31, 2013 10381 10382 Part 2: Structures 10384 10385 Trusted Platform Module Library 10386 10387 10.2.2 TPMT_HA 10388 Table 68 shows the basic hash-agile structure used in this specification. To handle hash agility, this 10389 structure uses the hashAlg parameter to indicate the algorithm used to compute the digest and, by 10390 implication, the size of the digest. 10391 When transmitted, only the number of octets indicated by hashAlg is sent. 10392 NOTE 10393 10394 In the exemplary code, when a TPMT_HA is allocated, the digest field is large enough to support the 10395 largest hash algorithm in the TPMU_HA union. 10396 10397 Table 68 Definition of TPMT_HA Structure <IN/OUT> 10398 Parameter 10399 10400 Type 10401 10402 Description 10403 10404 hashAlg 10405 10406 +TPMI_ALG_HASH 10407 10408 selector of the hash contained in the digest that implies the 10409 size of the digest 10410 NOTE 10411 10412 [hashAlg] digest 10413 10414 TPMU_HA 10415 10416 The leading + on the type indicates that this structure 10417 should pass an indication to the unmarshaling function for 10418 TPMI_ALG_HASH so that TPM_ALG_NULL will be 10419 allowed if a use of a TPMT_HA allows TPM_ALG_NULL. 10420 10421 the digest data 10422 10423 10.3 Sized Buffers 10424 10.3.1 Introduction 10425 The TPM2B_ prefix is used for a structure that has a size field followed by a data buffer with the 10426 indicated number of octets. The size field is 16 bits. 10427 When the type of the second parameter in a TPM2B_ structure is BYTE, the TPM shall unmarshal the 10428 indicated number of octets, which may be zero. 10429 When the type of the second parameter in the TPM2B_ structure is not BYTE, the value of the size field 10430 shall either be zero indicating that no structure is to be unmarshaled; or it shall be identical to the number 10431 of octets unmarshaled for the second parameter. 10432 NOTE 1 10433 10434 If the TPM2B_ defines a structure and not an array of octets, then the structure is self-describing and the 10435 TPM will be able to determine how many octets are in the structure when it is unmarshaled. If that number 10436 of octets is not equal to the size parameter, then it is an error. 10437 10438 NOTE 2 10439 10440 The reason that a structure may be put into a TPM2B_ is that the parts of the structure may be handled 10441 as separate opaque blocks by the application/system software. Rather than require that all of the 10442 structures in a command or response be marshaled or unmarshaled sequentially, the size field allows the 10443 structure to be manipulated as an opaque block. Placing a structure in a TPM2B_ also makes it possible 10444 to use parameter encryption on the structure. 10445 10446 If a TPM2B_ is encrypted, the TPM will encrypt/decrypt the data field of the TPM2B_ but not the size 10447 parameter. The TPM will encrypt/decrypt the number of octets indicated by the size field. 10448 NOTE 3 10449 10450 In the reference implementation, a TPM2B type is defined that is a 16-bit size field followed by a single 10451 byte of data. The TPM2B_ is then defined as a union that contains a TPM2B (union member b) and the 10452 structure in the definition table (union member t). This union is used for internally generated structures 10453 so that there is a way to define a structure of the correct size (forced by the t member) while giving a way 10454 to pass the structure generically as a b. Most function calls use the 't' member so that the compiler will 10455 generate a warning if there is a type error (a TPM2B_ of the wrong type). Having the type checked helps 10456 avoid many issues with buffer overflow caused by a too small buffer being passed to a function. 10457 10458 Page 82 10459 October 31, 2013 10460 10461 Published 10462 Copyright TCG 2006-2013 10463 10464 Family 2.0 10465 Level 00 Revision 00.99 10466 10467 Trusted Platform Module Library 10469 10470 Part 2: Structures 10471 10472 10.3.2 TPM2B_DIGEST 10473 This structure is used for a sized buffer that cannot be larger than the largest digest produced by any 10474 hash algorithm implemented on the TPM. 10475 As with all sized buffers, the size is checked to see if it is within the prescribed range. If not, the response 10476 code is TPM_RC_SIZE. 10477 NOTE 10478 10479 For any structure, like the one below, that contains an implied size check, it is implied that TPM_RC_SIZE 10480 is a possible response code and the response code will not be listed in the table. 10481 10482 Table 69 Definition of TPM2B_DIGEST Structure 10483 Parameter 10484 10485 Type 10486 10487 Description 10488 10489 size 10490 10491 UINT16 10492 10493 size in octets of the buffer field; may be 0 10494 10495 buffer[size]{:sizeof(TPMU_HA)} 10496 10497 BYTE 10498 10499 the buffer area that can be no larger than a digest 10500 10501 10.3.3 TPM2B_DATA 10502 This structure is used for a data buffer that is required to be no larger than the size of the Name of an 10503 object. This size limit includes the algorithm ID of the hash and the hash data. 10504 Table 70 Definition of TPM2B_DATA Structure 10505 Parameter 10506 10507 Type 10508 10509 Description 10510 10511 size 10512 10513 UINT16 10514 10515 size in octets of the buffer field; may be 0 10516 10517 buffer[size]{:sizeof(TPMT_HA)} 10518 10519 BYTE 10520 10521 the buffer area that contains the algorithm ID and the 10522 digest 10523 10524 10.3.4 TPM2B_NONCE 10525 Table 71 Definition of Types for TPM2B_NONCE 10526 Type 10527 10528 Name 10529 10530 Description 10531 10532 TPM2B_DIGEST 10533 10534 TPM2B_NONCE 10535 10536 size limited to the same as the digest structure 10537 10538 10.3.5 TPM2B_AUTH 10539 This structure is used for an authorization value and limits an authValue to being no larger than the 10540 largest digest produced by a TPM. In order to ensure consistency within an object, the authValue may be 10541 no larger than the size of the digest produced by the objects nameAlg. This ensures that any TPM that 10542 can load the object will be able to handle the authValue of the object. 10543 Table 72 Definition of Types for TPM2B_AUTH 10544 Type 10545 10546 Name 10547 10548 Description 10549 10550 TPM2B_DIGEST 10551 10552 TPM2B_AUTH 10553 10554 size limited to the same as the digest structure 10555 10556 Family 2.0 10557 Level 00 Revision 00.99 10558 10559 Published 10560 Copyright TCG 2006-2013 10561 10562 Page 83 10563 October 31, 2013 10564 10565 Part 2: Structures 10567 10568 Trusted Platform Module Library 10569 10570 10.3.6 TPM2B_OPERAND 10571 This type is a sized buffer that can hold an operand for a comparison with an NV Index location. The 10572 maximum size of the operand is implementation dependent but a TPM is required to support an operand 10573 size that is at least as big as the digest produced by any of the hash algorithms implemented on the TPM. 10574 Table 73 Definition of Types for TPM2B_OPERAND 10575 Type 10576 10577 Name 10578 10579 Description 10580 10581 TPM2B_DIGEST 10582 10583 TPM2B_OPERAND 10584 10585 size limited to the same as the digest structure 10586 10587 10.3.7 TPM2B_EVENT 10588 This type is a sized buffer that can hold event data. 10589 Table 74 Definition of TPM2B_EVENT Structure 10590 Parameter 10591 10592 Type 10593 10594 Description 10595 10596 size 10597 10598 UINT16 10599 10600 size of the operand buffer 10601 10602 buffer [size] {:1024} 10603 10604 BYTE 10605 10606 the operand 10607 10608 10.3.8 TPM2B_MAX_BUFFER 10609 This type is a sized buffer that can hold a maximally sized buffer for commands that use a large data 10610 buffer 10611 such 10612 as 10613 TPM2_PCR_Event(), 10614 TPM2_Hash(), 10615 TPM2_SequenceUpdate(), 10616 or 10617 TPM2_FieldUpgradeData(). 10618 NOTE 10619 10620 The above list is not comprehensive and other commands may use this buffer type. 10621 10622 Table 75 Definition of TPM2B_MAX_BUFFER Structure 10623 Parameter 10624 10625 Type 10626 10627 Description 10628 10629 size 10630 10631 UINT16 10632 10633 size of the buffer 10634 10635 buffer [size] {:MAX_DIGEST_BUFFER} 10636 10637 BYTE 10638 10639 the operand 10640 NOTE 10641 MAX_DIGEST_BUFFER 10642 is 10643 TPMdependent but is required to be at least 1,024. 10644 10645 10.3.9 TPM2B_MAX_NV_BUFFER 10646 This type is a sized buffer that can hold a maximally sized buffer for NV data commands such as 10647 TPM2_NV_Read(), TPM2_NV_Write(), and TPM2_NV_Certify(). 10648 Table 76 Definition of TPM2B_MAX_NV_BUFFER Structure 10649 Parameter 10650 10651 Type 10652 10653 Description 10654 10655 size 10656 10657 UINT16 10658 10659 size of the buffer 10660 10661 buffer [size] {:MAX_NV_BUFFER_SIZE} 10662 10663 BYTE 10664 10665 the operand 10666 NOTE 10667 MAX_NV_BUFFER_SIZE 10668 dependent 10669 10670 Page 84 10671 October 31, 2013 10672 10673 Published 10674 Copyright TCG 2006-2013 10675 10676 is 10677 10678 TPM- 10679 10680 Family 2.0 10681 Level 00 Revision 00.99 10682 10683 Trusted Platform Module Library 10685 10686 Part 2: Structures 10687 10688 10.3.10 TPM2B_TIMEOUT 10689 This TPM-dependent structure is used to provide the timeout value for an authorization. 10690 Table 77 Definition of TPM2B_TIMEOUT Structure <IN/OUT> 10691 Parameter 10692 10693 Type 10694 10695 Description 10696 10697 size 10698 10699 UINT16 10700 10701 size of the timeout value 10702 This value is fixed for a TPM implementation. 10703 10704 buffer [size] {:sizeof(UINT64)} 10705 10706 BYTE 10707 10708 the timeout value 10709 10710 10.3.11 TPM2B_IV 10711 This structure is used for passing an initial value for a symmetric block cipher to or from the TPM. The 10712 size is set to be the largest block size of any implemented symmetric cipher implemented on the TPM. 10713 Table 78 Definition of TPM2B_IV Structure <IN/OUT> 10714 Parameter 10715 10716 Type 10717 10718 Description 10719 10720 size 10721 10722 UINT16 10723 10724 size of the timeout value 10725 This value is fixed for a TPM implementation. 10726 10727 buffer [size] {:MAX_SYM_BLOCK_SIZE} 10728 10729 BYTE 10730 10731 the timeout value 10732 10733 10.4 Names 10734 10.4.1 Introduction 10735 The Name of an entity is used in place of the handle in authorization computations. The substitution 10736 occurs in cpHash and policyHash computations. 10737 For an entity that is defined by a public area (objects and NV Indexes), the Name is the hash of the public 10738 structure that defines the entity. The hash is done using the nameAlg of the entity. 10739 NOTE 10740 10741 For an object, a TPMT_PUBLIC defines the entity. For an NV Index, a TPMS_NV_PUBLIC defines the 10742 entity. 10743 10744 For entities not defined by a public area, the Name is the handle that is used to refer to the entity. 10745 10.4.2 TPMU_NAME 10746 Table 79 Definition of TPMU_NAME Union <> 10747 Parameter 10748 10749 Type 10750 10751 digest 10752 10753 TPMT_HA 10754 10755 when the Name is a digest 10756 10757 handle 10758 10759 TPM_HANDLE 10760 10761 when the Name is a handle 10762 10763 Family 2.0 10764 Level 00 Revision 00.99 10765 10766 Selector 10767 10768 Description 10769 10770 Published 10771 Copyright TCG 2006-2013 10772 10773 Page 85 10774 October 31, 2013 10775 10776 Part 2: Structures 10778 10779 Trusted Platform Module Library 10780 10781 10.4.3 TPM2B_NAME 10782 This buffer holds a Name for any entity type. 10783 The type of Name in the structure is determined by context and the size parameter. If size is four, then 10784 the Name is a handle. If size is zero, then no Name is present. Otherwise, the size shall be the size of a 10785 TPM_ALG_ID plus the size of the digest produced by the indicated hash algorithm. 10786 Table 80 Definition of TPM2B_NAME Structure 10787 Parameter 10788 10789 Type 10790 10791 Description 10792 10793 size 10794 10795 UINT16 10796 10797 size of the Name structure 10798 10799 name[size]{:sizeof(TPMU_NAME)} 10800 10801 BYTE 10802 10803 the Name structure 10804 10805 10.5 PCR Structures 10806 10.5.1 TPMS_PCR_SELECT 10807 This structure provides a standard method of specifying a list of PCR. 10808 PCR numbering starts at zero. 10809 PcrSelect is an array of octets. The octet containing the bit corresponding to a specific PCR is found by 10810 dividing the PCR number by 8. 10811 EXAMPLE 1 10812 10813 The bit in pcrSelect corresponding to PCR 19 is in pcrSelect [2] (19/8 = 2). 10814 10815 The least significant bit in a octet is bit number 0. The bit in the octet associated with a PCR is the 10816 remainder after division by 8. 10817 EXAMPLE 2 10818 10819 The bit in pcrSelect [2] corresponding to PCR 19 is bit 3 (19 mod 8). If sizeofSelect is 3, then the 10820 pcrSelect array that would specify PCR 19 and no other PCR is 00 00 08 16. 10821 10822 Each bit in pcrSelect indicates whether the corresponding PCR is selected (1) or not (0). If the pcrSelect 10823 is all zero bits, then no PCR is selected. 10824 SizeofSelect indicates the number of octets in pcrSelect. The allowable values for sizeofSelect is 10825 determined by the number of PCR required by the applicable platform-specific specification and the 10826 number of PCR implemented in the TPM. The minimum value for sizeofSelect is: 10827 PCR_SELECT_MIN (PLATFORM_PCR + 7) / 8 10828 10829 (1) 10830 10831 where 10832 PLATFORM_PCR 10833 10834 the number of PCR required by the platform-specific specification 10835 10836 The maximum value for sizeofSelect is: 10837 PCR_SELECT_MAX (IMPLEMENTATION_PCR + 7) / 8 10838 10839 (2) 10840 10841 where 10842 IMPLEMENTATION_PCR 10843 10844 Page 86 10845 October 31, 2013 10846 10847 the number of PCR implemented on the TPM 10848 10849 Published 10850 Copyright TCG 2006-2013 10851 10852 Family 2.0 10853 Level 00 Revision 00.99 10854 10855 Trusted Platform Module Library 10857 10858 Part 2: Structures 10859 10860 If the TPM implements more PCR than there are bits in pcrSelect, the additional PCR are not selected. 10861 EXAMPLE 3 10862 10863 If the applicable platform-specific specification requires that the TPM have a minimum of 24 PCR but the 10864 TPM implements 32, then a PCR select of 3 octets would imply that PCR 24-31 are not selected. 10865 10866 Table 81 Definition of TPMS_PCR_SELECT Structure 10867 Parameter 10868 10869 Type 10870 10871 Description 10872 10873 sizeofSelect {PCR_SELECT_MIN:} 10874 10875 UINT8 10876 10877 the size in octets of the pcrSelect array 10878 10879 pcrSelect [sizeofSelect] {:PCR_SELECT_MAX} 10880 10881 BYTE 10882 10883 the bit map of selected PCR 10884 10885 #TPM_RC_VALUE 10886 10887 10.5.2 TPMS_PCR_SELECTION 10888 Table 82 Definition of TPMS_PCR_SELECTION Structure 10889 Parameter 10890 10891 Type 10892 10893 Description 10894 10895 hash 10896 10897 TPMI_ALG_HASH 10898 10899 the hash algorithm associated with the 10900 selection 10901 10902 sizeofSelect {PCR_SELECT_MIN:} 10903 10904 UINT8 10905 10906 the size in octets of the pcrSelect array 10907 10908 pcrSelect [sizeofSelect] {:PCR_SELECT_MAX} 10909 10910 BYTE 10911 10912 the bit map of selected PCR 10913 10914 #TPM_RC_VALUE 10915 10916 10.6 Tickets 10917 10.6.1 Introduction 10918 Tickets are evidence that the TPM has previously processed some information. A ticket is an HMAC over 10919 the data using a secret key known only to the TPM. A ticket is a way to expand the state memory of the 10920 TPM. A ticket is only usable by the TPM that produced it. 10921 The formulations for tickets shown in this clause are to be used by a TPM that is compliant with this 10922 specification. 10923 The method of creating the ticket data is: 10924 10925 HMACcontexAlg(proof, (ticketType || param { || param {})) 10926 10927 (3) 10928 10929 where 10930 10931 HMACcontexAlg() 10932 10933 an HMAC using the hash used for context integrity 10934 10935 proof 10936 10937 a TPM secret value (depends on hierarchy) 10938 10939 ticketType 10940 10941 a value to differentiate the tickets 10942 10943 param 10944 10945 one or more values that were checked by the TPM 10946 10947 Family 2.0 10948 Level 00 Revision 00.99 10949 10950 Published 10951 Copyright TCG 2006-2013 10952 10953 Page 87 10954 October 31, 2013 10955 10956 Part 2: Structures 10958 10959 Trusted Platform Module Library 10960 10961 The proof value used for each hierarchy is shown in Table 83. 10962 Table 83 Values for proof Used in Tickets 10963 Hierarchy 10964 10965 proof 10966 10967 Description 10968 10969 None 10970 10971 Empty Buffer 10972 10973 Platform 10974 10975 phProof 10976 10977 a value that changes with each change of the PPS 10978 10979 Owner 10980 10981 shProof 10982 10983 a value that changes with each change of the SPS 10984 10985 Endorsement 10986 10987 ehProof 10988 10989 a value that changes with each change of either the EPS or SPS 10990 10991 The format for a ticket is shown in Table 84. This is a template for the tickets shown in the remainder of 10992 this clause. 10993 Table 84 General Format of a Ticket 10994 Parameter 10995 10996 Type 10997 10998 Description 10999 11000 tag 11001 11002 TPM_ST 11003 11004 structure tag indicating the type of the ticket 11005 11006 hierarchy 11007 11008 TPMI_RH_HIERARCHY+ 11009 11010 the hierarchy of the proof value 11011 11012 digest 11013 11014 TPM2B_DIGEST 11015 11016 the HMAC over the ticket-specific data 11017 11018 10.6.2 A NULL Ticket 11019 When a command requires a ticket and no ticket is available, the caller is required to provide a structure 11020 with a ticket tag that is correct for the context. The hierarchy shall be set to TPM_RH_NULL, and digest 11021 shall be the Empty Buffer (a buffer with a size field of zero). This construct is the NULL Ticket. When a 11022 response indicates that a ticket is returned, the TPM may return a NULL Ticket. 11023 NOTE 11024 11025 Because each use of a ticket requires that the structure tag for the ticket be appropriate for the use, t here 11026 is no single representation of a NULL Ticket that will work in all circumstances. Minimally, a NULL ticket 11027 will have a structure type that is appropriate for the context. 11028 11029 Page 88 11030 October 31, 2013 11031 11032 Published 11033 Copyright TCG 2006-2013 11034 11035 Family 2.0 11036 Level 00 Revision 00.99 11037 11038 Trusted Platform Module Library 11040 11041 Part 2: Structures 11042 11043 10.6.3 TPMT_TK_CREATION 11044 This ticket is produced by TPM2_Create() or TPM2_CreatePrimary(). It is used to bind the creation data 11045 to the object to which it applies. The ticket is computed by 11046 11047 HMACcontextAlg(proof, (TPM_ST_CREATION || name || HnameAlg(TPMS_CREATION_DATA))) 11048 11049 (4) 11050 11051 where 11052 11053 HMACcontextAlg() 11054 11055 an HMAC using the context integrity hash algorithm 11056 11057 proof 11058 11059 a TPM secret value associated with the hierarchy associated with name 11060 11061 TPM_ST_CREATION 11062 11063 a value used to ensure that the ticket is properly used 11064 11065 name 11066 11067 the Name of the object to which the creation data is to be associated 11068 11069 HnameAlg() 11070 11071 hash using the nameAlg of the created object 11072 11073 TPMS_CREATION_DATA the creation data structure associated with name 11074 Table 85 Definition of TPMT_TK_CREATION Structure 11075 Parameter 11076 11077 Type 11078 11079 Description 11080 11081 tag {TPM_ST_CREATION} 11082 11083 TPM_ST 11084 11085 ticket structure tag 11086 error returned when tag is not TPM_ST_CREATION 11087 11088 #TPM_RC_TAG 11089 hierarchy 11090 11091 TPMI_RH_HIERARCHY+ 11092 11093 the hierarchy containing name 11094 11095 digest 11096 11097 TPM2B_DIGEST 11098 11099 This shall be the HMAC produced using a proof value 11100 of hierarchy. 11101 11102 EXAMPLE 11103 11104 A NULL Creation Ticket is the tuple <TPM_ST_CREATION, TPM_RH_NULL, 0x0000>. 11105 11106 Family 2.0 11107 Level 00 Revision 00.99 11108 11109 Published 11110 Copyright TCG 2006-2013 11111 11112 Page 89 11113 October 31, 2013 11114 11115 Part 2: Structures 11117 11118 Trusted Platform Module Library 11119 11120 10.6.4 TPMT_TK_VERIFIED 11121 This ticket is produced by TPM2_VerifySignature(). This formulation is used for multiple ticket uses. The 11122 ticket provides evidence that the TPM has validated that a digest was signed by a key with the Name of 11123 keyName. The ticket is computed by 11124 11125 HMACcontextAlg(proof, (TPM_ST_VERIFIED || digest || keyName)) 11126 11127 (5) 11128 11129 where 11130 11131 HMACcontextAlg() 11132 11133 an HMAC using the context integrity hash 11134 11135 proof 11136 11137 a TPM secret value associated with the hierarchy associated with 11138 11139 TPM_ST_VERIFIED 11140 11141 a value used to ensure that the ticket is properly used 11142 11143 digest 11144 11145 the signed digest 11146 11147 keyName 11148 11149 Name of the key that signed digest 11150 11151 keyName 11152 11153 Table 86 Definition of TPMT_TK_VERIFIED Structure 11154 Parameter 11155 11156 Type 11157 11158 Description 11159 11160 tag {TPM_ST_VERIFIED} 11161 11162 TPM_ST 11163 11164 ticket structure tag 11165 error returned when tag is not TPM_ST_VERIFIED 11166 11167 #TPM_RC_TAG 11168 hierarchy 11169 11170 TPMI_RH_HIERARCHY+ 11171 11172 the hierarchy containing keyName 11173 11174 digest 11175 11176 TPM2B_DIGEST 11177 11178 This shall be the HMAC produced using a proof value 11179 of hierarchy. 11180 11181 EXAMPLE 11182 11183 A NULL Verified Ticket is the tuple <TPM_ST_VERIFIED, TPM_RH_NULL, 0x0000>. 11184 11185 Page 90 11186 October 31, 2013 11187 11188 Published 11189 Copyright TCG 2006-2013 11190 11191 Family 2.0 11192 Level 00 Revision 00.99 11193 11194 Trusted Platform Module Library 11196 11197 Part 2: Structures 11198 11199 10.6.5 TPMT_TK_AUTH 11200 This ticket is produced by TPM2_PolicySigned() and TPM2_PolicySecret() when the authorization has an 11201 expiration time. The ticket is computed by 11202 11203 HMACcontextAlg(proof, (TPM_ST_AUTH_xxx || timeout || cpHash || policyRef || keyName)) 11204 11205 (6) 11206 11207 where 11208 11209 HMACcontextAlg() 11210 11211 an HMAC using the context integrity hash 11212 11213 proof 11214 11215 a TPM secret value associated with the hierarchy of the key associated 11216 with keyName 11217 11218 TPM_ST_AUTH_xxx 11219 11220 either TPM_ST_AUTH_SIGNED or TPM_ST_AUTH_SECRET; used to 11221 ensure that the ticket is properly used 11222 11223 timeout 11224 11225 implementation-specific value indicating when the authorization expires 11226 11227 cpHash 11228 11229 optional hash of the authorized command 11230 11231 policyRef 11232 11233 optional reference to a policy value 11234 11235 keyName 11236 11237 Name of the key that signed the authorization 11238 Table 87 Definition of TPMT_TK_AUTH Structure 11239 11240 Parameter 11241 11242 Type 11243 11244 Description 11245 11246 tag {TPM_ST_AUTH_SIGNED, TPM_ST_AUTH_SECRET} TPM_ST 11247 11248 ticket structure tag 11249 11250 #TPM_RC_TAG 11251 11252 error returned when tag is 11253 not TPM_ST_AUTH 11254 11255 hierarchy 11256 11257 TPMI_RH_HIERARCHY+ 11258 11259 the hierarchy of the object 11260 used to produce the ticket 11261 11262 digest 11263 11264 TPM2B_DIGEST 11265 11266 This shall be the HMAC 11267 produced using a proof 11268 value of hierarchy. 11269 11270 EXAMPLE 11271 11272 A NULL Auth Ticket is the tuple <TPM_ST_AUTH_SIGNED, TPM_RH_NULL, 0x0000> or the tuple 11273 <TPM_ST_AUTH_SIGNED, TPM_RH_NULL, 0x0000> 11274 11275 Family 2.0 11276 Level 00 Revision 00.99 11277 11278 Published 11279 Copyright TCG 2006-2013 11280 11281 Page 91 11282 October 31, 2013 11283 11284 Part 2: Structures 11286 11287 Trusted Platform Module Library 11288 11289 10.6.6 TPMT_TK_HASHCHECK 11290 This ticket is produced by TPM2_SequenceComplete() when the message that was digested did not start 11291 with TPM_GENERATED_VALUE. The ticket is computed by 11292 11293 HMACcontexAlg(proof, (TPM_ST_HASHCHECK || digest)) 11294 11295 (7) 11296 11297 where 11298 11299 HMACcontexAlg () 11300 11301 an HMAC using the context integrity hash 11302 11303 proof 11304 11305 a TPM secret value associated with the hierarchy indicated by the 11306 command 11307 11308 TPM_ST_HASHCHECK 11309 11310 a value used to ensure that the ticket is properly used 11311 11312 digest 11313 11314 the digest of the data 11315 Table 88 Definition of TPMT_TK_HASHCHECK Structure 11316 11317 Parameter 11318 11319 Type 11320 11321 Description 11322 11323 tag {TPM_ST_HASHCHECK} 11324 11325 TPM_ST 11326 11327 ticket structure tag 11328 11329 #TPM_RC_TAG 11330 11331 error returned when is not TPM_ST_HASHCHECK 11332 11333 hierarchy 11334 11335 TPMI_RH_HIERARCHY+ 11336 11337 the hierarchy 11338 11339 digest 11340 11341 TPM2B_DIGEST 11342 11343 This shall be the HMAC produced using a proof value 11344 of hierarchy. 11345 11346 10.7 Property Structures 11347 10.7.1 TPMS_ALG_PROPERTY 11348 This structure is used to report the properties of an algorithm identifier. It is returned in response to a 11349 TPM2_GetCapability() with capability = TPM_CAP_ALG. 11350 Table 89 Definition of TPMS_ALG_PROPERTY Structure <OUT> 11351 Parameter 11352 11353 Type 11354 11355 Description 11356 11357 alg 11358 11359 TPM_ALG_ID 11360 11361 an algorithm identifier 11362 11363 algProperties 11364 11365 TPMA_ALGORITHM 11366 11367 the attributes of the algorithm 11368 11369 10.7.2 TPMS_TAGGED_PROPERTY 11370 This structure is used to report the properties that are UINT32 values. It is returned in response to a 11371 TPM2_GetCapability(). 11372 Table 90 Definition of TPMS_TAGGED_PROPERTY Structure <OUT> 11373 Parameter 11374 11375 Type 11376 11377 Description 11378 11379 property 11380 11381 TPM_PT 11382 11383 a property identifier 11384 11385 value 11386 11387 UINT32 11388 11389 the value of the property 11390 11391 Page 92 11392 October 31, 2013 11393 11394 Published 11395 Copyright TCG 2006-2013 11396 11397 Family 2.0 11398 Level 00 Revision 00.99 11399 11400 Trusted Platform Module Library 11402 11403 Part 2: Structures 11404 11405 10.7.3 TPMS_TAGGED_PCR_SELECT 11406 This structure is used in TPM2_GetCapability() to return the attributes of the PCR. 11407 Table 91 Definition of TPMS_TAGGED_PCR_SELECT Structure <OUT> 11408 Parameter 11409 11410 Type 11411 11412 Description 11413 11414 tag 11415 11416 TPM_PT 11417 11418 the property identifier 11419 11420 sizeofSelect {PCR_SELECT_MIN:} 11421 11422 UINT8 11423 11424 the size in octets of the pcrSelect array 11425 11426 pcrSelect [sizeofSelect] {:PCR_SELECT_MAX} 11427 11428 BYTE 11429 11430 the bit map of PCR with the identified property 11431 11432 10.8 Lists 11433 10.8.1 TPML_CC 11434 A list of command codes may be input to the TPM or returned by the TPM depending on the command. 11435 Table 92 Definition of TPML_CC Structure 11436 Parameter 11437 11438 Type 11439 11440 Description 11441 11442 count 11443 11444 UINT32 11445 11446 number of commands in the commandCode list; 11447 may be 0 11448 11449 commandCodes[count]{:MAX_CAP_CC} 11450 11451 TPM_CC 11452 11453 a list of command codes 11454 The maximum only applies to a command code 11455 list in a command. The response size is limited 11456 only by the size of the parameter buffer. 11457 11458 #TPM_RC_SIZE 11459 11460 Family 2.0 11461 Level 00 Revision 00.99 11462 11463 response code when count is greater than the 11464 maximum allowed list size 11465 11466 Published 11467 Copyright TCG 2006-2013 11468 11469 Page 93 11470 October 31, 2013 11471 11472 Part 2: Structures 11474 11475 Trusted Platform Module Library 11476 11477 10.8.2 TPML_CCA 11478 This list is only used in TPM2_GetCapability(capability = TPM_CAP_COMMANDS). 11479 The values in the list are returned in commandIndex order with vendor-specific commands returned after 11480 other commands. Because of the other attributes, the commands may not be returned in strict numerical 11481 order. They will be in commandIndex order. 11482 Table 93 Definition of TPML_CCA Structure <OUT> 11483 Parameter 11484 11485 Type 11486 11487 Description 11488 11489 count 11490 11491 UINT32 11492 11493 number of values in the commandAttributes list; 11494 may be 0 11495 11496 commandAttributes[count]{:MAX_CAP_CC} 11497 11498 TPMA_CC 11499 11500 a list of command codes attributes 11501 11502 10.8.3 TPML_ALG 11503 This list is returned by TPM2_IncrementalSelfTest(). 11504 Table 94 Definition of TPML_ALG Structure 11505 Parameter 11506 11507 Type 11508 11509 Description 11510 11511 count 11512 11513 UINT32 11514 11515 number of algorithms in the algorithms list; may be 0 11516 11517 algorithms[count]{:MAX_ALG_LIST_SIZE} 11518 11519 TPM_ALG_ID a list of algorithm IDs 11520 The maximum only applies to an algorithm list in a 11521 command. The response size is limited only by the 11522 size of the parameter buffer. 11523 response code when count is greater than the 11524 maximum allowed list size 11525 11526 #TPM_RC_SIZE 11527 11528 10.8.4 TPML_HANDLE 11529 This structure is used when the TPM returns a list of loaded handles when the capability in 11530 TPM2_GetCapability() is TPM_CAP_HANDLE. 11531 NOTE 11532 11533 This list is not used as input to the TPM. 11534 11535 Table 95 Definition of TPML_HANDLE Structure <OUT> 11536 Name 11537 11538 Type 11539 11540 Description 11541 11542 count 11543 11544 UINT32 11545 11546 the number of handles in the list 11547 may have a value of 0 11548 11549 handle[count]{: MAX_CAP_HANDLES} 11550 11551 TPM_HANDLE 11552 11553 an array of handles 11554 11555 #TPM_RC_SIZE 11556 11557 Page 94 11558 October 31, 2013 11559 11560 response code when count is greater than the 11561 maximum allowed list size 11562 11563 Published 11564 Copyright TCG 2006-2013 11565 11566 Family 2.0 11567 Level 00 Revision 00.99 11568 11569 Trusted Platform Module Library 11571 11572 Part 2: Structures 11573 11574 10.8.5 TPML_DIGEST 11575 This list is used to convey a list of digest values. This type is used in TPM2_PolicyOR() and in 11576 TPM2_PCR_Read(). 11577 Table 96 Definition of TPML_DIGEST Structure 11578 Parameter 11579 11580 Type 11581 11582 Description 11583 11584 count {2:} 11585 11586 UINT32 11587 11588 number of digests in the list, minimum is two for 11589 TPM2_PolicyOR(). 11590 11591 digests[count]{:8} 11592 11593 TPM2B_DIGEST a list of digests 11594 For TPM2_PolicyOR(), all digests will have been 11595 computed using the digest of the policy session. For 11596 TPM2_PCR_Read(), each digest will be the size of the 11597 digest for the bank containing the PCR. 11598 11599 #TPM_RC_SIZE 11600 11601 response code when count is not at least two or is 11602 greater than eight 11603 11604 10.8.6 TPML_DIGEST_VALUES 11605 This list is used to convey a list of digest values. This type is returned by TPM2_Event() and 11606 TPM2_SequenceComplete() and is an input for TPM2_PCR_Extend(). 11607 NOTE 1 11608 11609 This construct limits the number of hashes in the list to the number of digests implemented in the TPM 11610 rather than the number of PCR banks. This allows extra values to appear in a call t o 11611 TPM2_PCR_Extend(). 11612 11613 NOTE 2 11614 11615 The digest for an unimplemented hash algorithm may not be in a list because the TPM may not recognize 11616 the algorithm as being a hash and it may not know the digest size. 11617 11618 Table 97 Definition of TPML_DIGEST_VALUES Structure 11619 Parameter 11620 11621 Type 11622 11623 Description 11624 11625 count 11626 11627 UINT32 11628 11629 number of digests in the list 11630 11631 digests[count]{:HASH_COUNT} 11632 11633 TPMT_HA 11634 11635 a list of tagged digests 11636 response code when count is greater than the possible 11637 number of banks 11638 11639 #TPM_RC_SIZE 11640 11641 10.8.7 TPM2B_DIGEST_VALUES 11642 Digest list in a sized buffer. This list is returned by TPM2_PCR_SequenceComplete(). 11643 Table 98 Definition of TPM2B_DIGEST_VALUES Structure 11644 Parameter 11645 11646 Type 11647 11648 Description 11649 11650 size 11651 11652 UINT16 11653 11654 size of the operand buffer 11655 11656 buffer [size] {:sizeof(TPML_DIGEST_VALUES)} 11657 11658 BYTE 11659 11660 the operand 11661 11662 Family 2.0 11663 Level 00 Revision 00.99 11664 11665 Published 11666 Copyright TCG 2006-2013 11667 11668 Page 95 11669 October 31, 2013 11670 11671 Part 2: Structures 11673 11674 Trusted Platform Module Library 11675 11676 10.8.8 TPML_PCR_SELECTION 11677 This list is used to indicate the PCR that are included in a selection when more than one PCR value may 11678 be selected. 11679 This structure is an input parameter to TPM2_PolicyPCR() to indicate the PCR that will be included in the 11680 digest of PCR for the authorization. The structure is used in TPM2_PCR_Read() command to indicate the 11681 PCR values to be returned and in the response to indicate which PCR are included in the list of returned 11682 digests. The structure is an output parameter from TPM2_Create() and indicates the PCR used in the 11683 digest of the PCR state when the object was created. The structure is also contained in the attestation 11684 structure of TPM2_Quote(). 11685 When this structure is used to select PCR to be included in a digest, the selected PCR are concatenated 11686 to create a message containing all of the PCR, and then the message is hashed using the contextspecific hash algorithm. 11687 Table 99 Definition of TPML_PCR_SELECTION Structure 11688 Parameter 11689 11690 Type 11691 11692 Description 11693 11694 count 11695 11696 UINT32 11697 11698 number of selection structures 11699 A value of zero is allowed. 11700 11701 pcrSelections[count]{:HASH_COUNT} 11702 11703 TPMS_PCR_SELECTION 11704 11705 list of selections 11706 response code when count is greater 11707 than the possible number of banks 11708 11709 #TPM_RC_SIZE 11710 11711 10.8.9 TPML_ALG_PROPERTY 11712 This list is used to report on a list of algorithm attributes. It is returned in a TPM2_GetCapability(). 11713 Table 100 Definition of TPML_ALG_PROPERTY Structure <OUT> 11714 Parameter 11715 11716 Type 11717 11718 Description 11719 11720 count 11721 11722 UINT32 11723 11724 number of algorithm properties structures 11725 A value of zero is allowed. 11726 11727 algProperties[count]{:MAX_CAP_ALGS} 11728 11729 TPMS_ALG_PROPERTY 11730 11731 list of properties 11732 11733 10.8.10 TPML_TAGGED_TPM_PROPERTY 11734 This list is used to report on a list of properties that are TPMS_TAGGED_PROPERTY values. It is 11735 returned by a TPM2_GetCapability(). 11736 Table 101 Definition of TPML_TAGGED_TPM_PROPERTY Structure <OUT> 11737 Parameter 11738 11739 Type 11740 11741 Description 11742 11743 count 11744 11745 UINT32 11746 11747 number of properties 11748 A value of zero is allowed. 11749 11750 tpmProperty[count]{:MAX_TPM_PROPERTIES} TPMS_TAGGED_PROPERTY 11751 11752 Page 96 11753 October 31, 2013 11754 11755 Published 11756 Copyright TCG 2006-2013 11757 11758 an array of tagged properties 11759 11760 Family 2.0 11761 Level 00 Revision 00.99 11762 11763 Trusted Platform Module Library 11765 11766 Part 2: Structures 11767 11768 10.8.11 TPML_TAGGED_PCR_PROPERTY 11769 This list is used to report on a list of properties that are TPMS_PCR_SELECT values. It is returned by a 11770 TPM2_GetCapability(). 11771 Table 102 Definition of TPML_TAGGED_PCR_PROPERTY Structure <OUT> 11772 Parameter 11773 11774 Type 11775 11776 Description 11777 11778 count 11779 11780 UINT32 11781 11782 number of properties 11783 A value of zero is allowed. 11784 11785 pcrProperty[count]{:MAX_PCR_PROPERTIES} 11786 11787 TPMS_TAGGED_PCR_SELECT a tagged PCR selection 11788 11789 10.8.12 TPML_ECC_CURVE 11790 This list is used to report the ECC curve ID values supported by the TPM. It is returned by a 11791 TPM2_GetCapability(). 11792 Table 103 Definition of {ECC} TPML_ECC_CURVE Structure <OUT> 11793 Parameter 11794 11795 Type 11796 11797 Description 11798 11799 count 11800 11801 UINT32 11802 11803 number of curves 11804 A value of zero is allowed. 11805 11806 eccCurves[count]{:MAX_ECC_CURVES} 11807 11808 TPM_ECC_CURVE 11809 11810 array of ECC curve identifiers 11811 11812 10.9 Capabilities Structures 11813 10.9.1 TPMU_CAPABILITIES 11814 Table 104 Definition of TPMU_CAPABILITIES Union <OUT> 11815 Parameter 11816 11817 Type 11818 11819 Selector 11820 11821 algorithms 11822 11823 TPML_ALG_PROPERTY 11824 11825 TPM_CAP_ALGS 11826 11827 handles 11828 11829 TPML_HANDLE 11830 11831 TPM_CAP_HANDLES 11832 11833 command 11834 11835 TPML_CCA 11836 11837 TPM_CAP_COMMANDS 11838 11839 ppCommands 11840 11841 TPML_CC 11842 11843 TPM_CAP_PP_COMMANDS 11844 11845 auditCommands 11846 11847 TPML_CC 11848 11849 TPM_CAP_AUDIT_COMMANDS 11850 11851 assignedPCR 11852 11853 TPML_PCR_SELECTION 11854 11855 TPM_CAP_PCRS 11856 11857 tpmProperties 11858 11859 TPML_TAGGED_TPM_PROPERTY 11860 11861 TPM_CAP_TPM_PROPERTIES 11862 11863 pcrProperties 11864 11865 TPML_TAGGED_PCR_PROPERTY 11866 11867 TPM_CAP_PCR_PROPERTIES 11868 11869 eccCurves 11870 11871 TPML_ECC_CURVE 11872 11873 TPM_CAP_ECC_CURVES 11874 11875 Family 2.0 11876 Level 00 Revision 00.99 11877 11878 Published 11879 Copyright TCG 2006-2013 11880 11881 Description 11882 11883 TPM_ALG_ECC 11884 11885 Page 97 11886 October 31, 2013 11887 11888 Part 2: Structures 11890 11891 Trusted Platform Module Library 11892 11893 10.9.2 TPMS_CAPABILITY_DATA 11894 This data area is returned in response to a TPM2_GetCapability(). 11895 Table 105 Definition of TPMS_CAPABILITY_DATA Structure <OUT> 11896 Parameter 11897 11898 Type 11899 11900 Description 11901 11902 capability 11903 11904 TPM_CAP 11905 11906 the capability 11907 11908 [capability]data 11909 11910 TPMU_CAPABILITIES 11911 11912 the capability data 11913 11914 10.10 Clock/Counter Structures 11915 10.10.1 TPMS_CLOCK_INFO 11916 This structure is used in each of the attestation commands. 11917 Table 106 Definition of TPMS_CLOCK_INFO Structure 11918 Parameter 11919 11920 Type 11921 11922 Description 11923 11924 clock 11925 11926 UINT64 11927 11928 time in milliseconds during which the TPM has been powered 11929 This structure element is used to report on the TPM's Clock value. 11930 The value of Clock shall be recorded in non-volatile memory no 11931 22 11932 less often than once per 2 milliseconds (~69.9 minutes) of TPM 11933 operation. The reference for the millisecond timer is the TPM 11934 oscillator. 11935 This value is reset to zero when the Storage Primary Seed is 11936 changed (TPM2_Clear()). 11937 This value may be advanced by TPM2_AdvanceClock(). 11938 11939 resetCount 11940 11941 UINT32 11942 11943 number of occurrences of TPM Reset since the last TPM2_Clear() 11944 11945 restartCount 11946 11947 UINT32 11948 11949 number of times that TPM2_Shutdown() or _TPM_Hash_Start have 11950 occurred since the last TPM Reset or TPM2_Clear(). 11951 11952 safe 11953 11954 TPMI_YES_NO 11955 11956 no value of Clock greater than the current value of Clock has been 11957 previously reported by the TPM. Set to YES on TPM2_Clear(). 11958 11959 10.10.2 Clock 11960 Clock is a monotonically increasing counter that advances whenever power is applied to the TPM. The 11961 value of Clock may be set forward with TPM2_ClockSet() if ownerAuth or platformAuth is provided. The 11962 value of Clock is incremented each millisecond. 11963 TPM2_Clear() will set Clock to zero. 11964 Clock will be non-volatile but may have a volatile component that is updated every millisecond with the 11965 non-volatile component updated at a lower rate. If the implementation uses a volatile component, the non22 11966 volatile component shall be updated no less frequently than every 2 milliseconds (~69.9 minutes). The 11967 update rate of the non-volatile portion of Clock shall be reported by a TPM2_GetCapability() with 11968 capability = TPM_CAP_TPM_PROPERTIES and property = TPM_PT_CLOCK_UPDATE. 11969 10.10.3 ResetCount 11970 This counter shall increment on each TPM Reset. This counter shall be reset to zero by TPM2_Clear(). 11971 11972 Page 98 11973 October 31, 2013 11974 11975 Published 11976 Copyright TCG 2006-2013 11977 11978 Family 2.0 11979 Level 00 Revision 00.99 11980 11981 Trusted Platform Module Library 11983 11984 Part 2: Structures 11985 11986 10.10.4 RestartCount 11987 This counter shall increment by one for each TPM Restart or TPM Resume. The restartCount shall be 11988 reset to zero on a TPM Reset or TPM2_Clear(). 11989 10.10.5 Safe 11990 This parameter is set to YES when the value reported in Clock is guaranteed to be unique for the current 11991 Owner. It is set to NO when the value of Clock may have been reported in a previous attestation or 11992 access. 11993 This parameter will be YES if a TPM2_Startup() was preceded by TPM2_Shutdown() with no intervening 11994 commands. It will also be YES after an update of the non-volatile bits of Clock have been updated at the 11995 end of an update interval. 11996 If a TPM implementation does not implement 11997 TPMS_CLOCK_INFO.clock shall always be zero. 11998 11999 Clock, 12000 12001 Safe 12002 12003 shall 12004 12005 always 12006 12007 be 12008 12009 NO 12010 12011 and 12012 12013 This parameter will be set to YES by TPM2_Clear(). 12014 10.10.6 TPMS_TIME_INFO 12015 This structure is used in the TPM2_TICK attestation. 12016 The Time value reported in this structure is reset whenever the TPM is reset. An implementation may 12017 reset the value of Time any time after _TPM_Init and before the TPM returns after TPM2_Start(). The 12018 value of Time shall increment continuously while power is applied to the TPM. 12019 Table 107 Definition of TPMS_TIME_INFO Structure 12020 Parameter 12021 12022 Type 12023 12024 Description 12025 12026 time 12027 12028 UINT64 12029 12030 time in milliseconds since the last _TPM_Init() or TPM2_Startup() 12031 This structure element is used to report on the TPM's Time value. 12032 12033 clockInfo 12034 12035 TPMS_CLOCK_INFO 12036 12037 a structure containing the clock information 12038 12039 Family 2.0 12040 Level 00 Revision 00.99 12041 12042 Published 12043 Copyright TCG 2006-2013 12044 12045 Page 99 12046 October 31, 2013 12047 12048 Part 2: Structures 12050 12051 Trusted Platform Module Library 12052 12053 10.11 TPM Attestation Structures 12054 10.11.1 Introduction 12055 This clause describes the structures that are used when a TPM creates a structure to be signed. The 12056 signing structures follow a standard format TPM2B_ATTEST with case-specific information embedded. 12057 10.11.2 TPMS_TIME_ATTEST_INFO 12058 This structure is used when the TPM performs TPM2_GetClock. 12059 Table 108 Definition of TPMS_TIME_ATTEST_INFO Structure <OUT> 12060 Parameter 12061 12062 Type 12063 12064 Description 12065 12066 time 12067 12068 TPMS_TIME_INFO 12069 12070 the Time, clock, resetCount, restartCount, and Safe indicator 12071 12072 firmwareVersion 12073 12074 UINT64 12075 12076 a vendor-specific value indicating the version number of the 12077 firmware 12078 12079 10.11.3 TPMS_CERTIFY_INFO 12080 This is the attested data for TPM2_Certify(). 12081 Table 109 Definition of TPMS_CERTIFY_INFO Structure <OUT> 12082 Parameter 12083 12084 Type 12085 12086 Description 12087 12088 name 12089 12090 TPM2B_NAME 12091 12092 Name of the certified object 12093 12094 qualifiedName 12095 12096 TPM2B_NAME 12097 12098 Qualified Name of the certified object 12099 12100 10.11.1 TPMS_QUOTE_INFO 12101 This is the attested data for TPM2_Quote(). 12102 Table 110 Definition of TPMS_QUOTE_INFO Structure <OUT> 12103 Parameter 12104 12105 Type 12106 12107 Description 12108 12109 pcrSelect 12110 12111 TPML_PCR_SELECTION 12112 12113 information on algID, PCR selected and digest 12114 12115 pcrDigest 12116 12117 TPM2B_DIGEST 12118 12119 digest of the selected PCR using the hash of the signing key 12120 12121 Page 100 12122 October 31, 2013 12123 12124 Published 12125 Copyright TCG 2006-2013 12126 12127 Family 2.0 12128 Level 00 Revision 00.99 12129 12130 Trusted Platform Module Library 12132 12133 Part 2: Structures 12134 12135 10.11.2 TPMS_COMMAND_AUDIT_INFO 12136 This is the attested data for TPM2_GetCommandAuditDigest(). 12137 Table 111 Definition of TPMS_COMMAND_AUDIT_INFO Structure <OUT> 12138 Parameter 12139 12140 Type 12141 12142 Description 12143 12144 auditCounter 12145 12146 UINT64 12147 12148 the monotonic audit counter 12149 12150 digestAlg 12151 12152 TPM_ALG_ID 12153 12154 hash algorithm used for the command audit 12155 12156 auditDigest 12157 12158 TPM2B_DIGEST 12159 12160 the current value of the audit digest 12161 12162 commandDigest 12163 12164 TPM2B_DIGEST 12165 12166 digest of the command codes being audited using digestAlg 12167 12168 10.11.3 TPMS_SESSION_AUDIT_INFO 12169 This is the attested data for TPM2_GetSessionAuditDigest(). 12170 Table 112 Definition of TPMS_SESSION_AUDIT_INFO Structure <OUT> 12171 Parameter 12172 12173 Type 12174 12175 Description 12176 12177 exclusiveSession 12178 12179 TPMI_YES_NO 12180 12181 current exclusive status of the session 12182 TRUE if all of the commands recorded in the sessionDigest were 12183 executed without any intervening TPM command that did not use 12184 this transport session 12185 12186 sessionDigest 12187 12188 TPM2B_DIGEST 12189 12190 the current value of the session audit digest 12191 12192 10.11.4 TPMS_CREATION_INFO 12193 This is the attested data for TPM2_CertifyCreation(). 12194 Table 113 Definition of TPMS_CREATION_INFO Structure <OUT> 12195 Parameter 12196 12197 Type 12198 12199 Description 12200 12201 objectName 12202 12203 TPM2B_NAME 12204 12205 Name of the object 12206 12207 creationHash 12208 12209 TPM2B_DIGEST 12210 12211 creationHash 12212 12213 10.11.5 TPMS_NV_CERTIFY_INFO 12214 This structure contains the Name and contents of the selected NV Index that is certified by 12215 TPM2_NV_Certify(). 12216 Table 114 Definition of TPMS_NV_CERTIFY_INFO Structure <OUT> 12217 Parameter 12218 12219 Type 12220 12221 Description 12222 12223 indexName 12224 12225 TPM2B_NAME 12226 12227 Name of the NV Index 12228 12229 offset 12230 12231 UINT16 12232 12233 the offset parameter of TPM2_NV_Certify() 12234 12235 nvContents 12236 12237 TPM2B_MAX_NV_BUFFER 12238 12239 contents of the NV Index 12240 12241 Family 2.0 12242 Level 00 Revision 00.99 12243 12244 Published 12245 Copyright TCG 2006-2013 12246 12247 Page 101 12248 October 31, 2013 12249 12250 Part 2: Structures 12252 12253 Trusted Platform Module Library 12254 12255 10.11.6 TPMI_ST_ATTEST 12256 Table 115 Definition of (TPM_ST) TPMI_ST_ATTEST Type <OUT> 12257 Value 12258 12259 Description 12260 12261 TPM_ST_ATTEST_CERTIFY 12262 12263 generated by TPM2_Certify() 12264 12265 TPM_ST_ATTEST_QUOTE 12266 12267 generated by TPM2_Quote() 12268 12269 TPM_ST_ATTEST_SESSION_AUDIT 12270 12271 generated by TPM2_GetSessionAuditDigest() 12272 12273 TPM_ST_ATTEST_COMMAND_AUDIT 12274 12275 generated by TPM2_GetCommandAuditDigest() 12276 12277 TPM_ST_ATTEST_TIME 12278 12279 generated by TPM2_GetTime() 12280 12281 TPM_ST_ATTEST_CREATION 12282 12283 generated by TPM2_CertifyCreation() 12284 12285 TPM_ST_ATTEST_NV 12286 12287 generated by TPM2_NV_Certify() 12288 12289 10.11.7 TPMU_ATTEST 12290 Table 116 Definition of TPMU_ATTEST Union <OUT> 12291 Parameter 12292 12293 Type 12294 12295 Selector 12296 12297 certify 12298 12299 TPMS_CERTIFY_INFO 12300 12301 TPM_ST_ATTEST_CERTIFY 12302 12303 creation 12304 12305 TPMS_CREATION_INFO 12306 12307 TPM_ST_ATTEST_CREATION 12308 12309 quote 12310 12311 TPMS_QUOTE_INFO 12312 12313 TPM_ST_ATTEST_QUOTE 12314 12315 commandAudit 12316 12317 TPMS_COMMAND_AUDIT_INFO TPM_ST_ATTEST_COMMAND_AUDIT 12318 12319 sessionAudit 12320 12321 TPMS_SESSION_AUDIT_INFO 12322 12323 TPM_ST_ATTEST_SESSION_AUDIT 12324 12325 time 12326 12327 TPMS_TIME_ATTEST_INFO 12328 12329 TPM_ST_ATTEST_TIME 12330 12331 nv 12332 12333 TPMS_NV_CERTIFY_INFO 12334 12335 TPM_ST_ATTEST_NV 12336 12337 Page 102 12338 October 31, 2013 12339 12340 Published 12341 Copyright TCG 2006-2013 12342 12343 Family 2.0 12344 Level 00 Revision 00.99 12345 12346 Trusted Platform Module Library 12348 12349 Part 2: Structures 12350 12351 10.11.8 TPMS_ATTEST 12352 This structure is used on each TPM-generated signed structure. The signature is over this structure. 12353 When the structure is signed by a key in the Storage hierarchy, the values of clockInfo.resetCount, 12354 clockInfo.restartCount, and firmwareVersion are obfuscated with a per-key obfuscation value. 12355 Table 117 Definition of TPMS_ATTEST Structure <OUT> 12356 Parameter 12357 12358 Type 12359 12360 Description 12361 12362 magic 12363 12364 TPM_GENERATED 12365 12366 the indication that this structure was created by a TPM (always 12367 TPM_GENERATED_VALUE) 12368 12369 type 12370 12371 TPMI_ST_ATTEST 12372 12373 type of the attestation structure 12374 12375 qualifiedSigner 12376 12377 TPM2B_NAME 12378 12379 Qualified Name of the signing key 12380 12381 extraData 12382 12383 TPM2B_DATA 12384 12385 external information supplied by caller 12386 NOTE 12387 12388 A TPM2B_DATA structure provides room for a digest and a 12389 method indicator to indicate the components of the digest. 12390 The definition of this method indicator is outside the scope 12391 of this specification. 12392 12393 clockInfo 12394 12395 TPMS_CLOCK_INFO 12396 12397 Clock, resetCount, restartCount, and Safe 12398 12399 firmwareVersion 12400 12401 UINT64 12402 12403 TPM-vendor-specific field identifying the firmware on the TPM 12404 12405 [type]attested 12406 12407 TPMU_ATTEST 12408 12409 the type-specific attestation information 12410 12411 10.11.9 TPM2B_ATTEST 12412 This sized buffer to contain the signed structure. The attestationData is the signed portion of the structure. 12413 The size parameter is not signed. 12414 Table 118 Definition of TPM2B_ATTEST Structure <OUT> 12415 Parameter 12416 12417 Type 12418 12419 Description 12420 12421 size 12422 12423 UINT16 12424 12425 size of the attestationData structure 12426 12427 attestationData[size]{:sizeof(TPMS_ATTEST)} 12428 12429 BYTE 12430 12431 the signed structure 12432 12433 Family 2.0 12434 Level 00 Revision 00.99 12435 12436 Published 12437 Copyright TCG 2006-2013 12438 12439 Page 103 12440 October 31, 2013 12441 12442 Part 2: Structures 12444 12445 Trusted Platform Module Library 12446 12447 10.12 Authorization Structures 12448 The structures in this clause are used for all authorizations. One or more of these structures will be 12449 present in a command or response that has a tag of TPM_ST_SESSIONS. 12450 10.12.1 TPMS_AUTH_COMMAND 12451 This is the format used for each of the authorizations in the session area of a command. 12452 Table 119 Definition of TPMS_AUTH_COMMAND Structure <IN> 12453 Parameter 12454 12455 Type 12456 12457 Description 12458 12459 sessionHandle 12460 12461 TPMI_SH_AUTH_SESSION+ 12462 12463 the session handle 12464 12465 nonce 12466 12467 TPM2B_NONCE 12468 12469 the session nonce, may be the Empty Buffer 12470 12471 sessionAttributes 12472 12473 TPMA_SESSION 12474 12475 the session attributes 12476 12477 hmac 12478 12479 TPM2B_AUTH 12480 12481 either an HMAC, a password, or an EmptyAuth 12482 12483 10.12.2 TPMS_AUTH_RESPONSE 12484 This is the format for each of the authorizations in the session area of the response. If the TPM returns 12485 TPM_RC_SUCCESS, then the session area of the response contains the same number of authorizations 12486 as the command and the authorizations are in the same order. 12487 Table 120 Definition of TPMS_AUTH_RESPONSE Structure <OUT> 12488 Parameter 12489 12490 Type 12491 12492 Description 12493 12494 nonce 12495 12496 TPM2B_NONCE 12497 12498 the session nonce, may be the Empty Buffer 12499 12500 sessionAttributes 12501 12502 TPMA_SESSION 12503 12504 the session attributes 12505 12506 hmac 12507 12508 TPM2B_AUTH 12509 12510 either an HMAC, a password, or an EmptyAuth 12511 12512 Page 104 12513 October 31, 2013 12514 12515 Published 12516 Copyright TCG 2006-2013 12517 12518 Family 2.0 12519 Level 00 Revision 00.99 12520 12521 Trusted Platform Module Library 12523 12524 Part 2: Structures 12525 12526 11 Algorithm Parameters and Structures 12527 11.1 Symmetric 12528 11.1.1 Introduction 12529 This clause defines the parameters and structures for describing symmetric algorithms. 12530 11.1.2 TPMI_AES_KEY_BITS 12531 This interface type defines the supported sizes for an AES key. This type is used to allow the 12532 unmarshaling routine to generate the proper validation code for the supported key sizes. An 12533 implementation that supports different key sizes would have a different set of selections. 12534 When used in TPM2_StartAuthSession(), the mode parameter shall be TPM_ALG_CFB. 12535 NOTE 1 12536 12537 Key size is expressed in bits. 12538 12539 NOTE 2 12540 12541 The definition for AES_KEY_SIZES_BITS used in the reference implementation is found in Annex B 12542 12543 Table 121 Definition of {AES} (TPM_KEY_BITS) TPMI_AES_KEY_BITS Type 12544 Parameter 12545 12546 Description 12547 12548 $AES_KEY_SIZES_BITS 12549 12550 number of bits in the key 12551 12552 #TPM_RC_VALUE 12553 12554 error when key size is not supported 12555 12556 11.1.3 TPMI_SM4_KEY_BITS 12557 This interface type defines the supported sizes for an SM4 key. This type is used to allow the 12558 unmarshaling routine to generate the proper validation code for the supported key sizes. An 12559 implementation that supports different key sizes would have a different set of selections. 12560 NOTE 12561 12562 SM4 only supports a key size of 128 bits. 12563 12564 Table 122 Definition of {SM4} (TPM_KEY_BITS) TPMI_SM4_KEY_BITS Type 12565 Parameter 12566 12567 Description 12568 12569 $SM4_KEY_SIZES_BITS 12570 12571 number of bits in the key 12572 12573 #TPM_RC_VALUE 12574 12575 Family 2.0 12576 Level 00 Revision 00.99 12577 12578 Published 12579 Copyright TCG 2006-2013 12580 12581 Page 105 12582 October 31, 2013 12583 12584 Part 2: Structures 12586 12587 Trusted Platform Module Library 12588 12589 11.1.4 TPMU_SYM_KEY_BITS 12590 This union is used to collect the symmetric encryption key sizes. 12591 The xor entry is a hash algorithms selector and not a key size in bits. This overload is used in order to 12592 avoid an additional level of indirection with another union and another set of selectors. 12593 The xor entry is only selected in a TPMT_SYM_DEF, which is used to select the parameter encryption 12594 value. 12595 Table 123 Definition of TPMU_SYM_KEY_BITS Union 12596 Parameter 12597 12598 Type 12599 12600 Selector 12601 12602 aes 12603 12604 TPMI_AES_KEY_BITS 12605 12606 TPM_ALG_AES 12607 12608 SM4 12609 12610 TPMI_SM4_KEY_BITS 12611 12612 TPM_ALG_SM4 12613 12614 sym 12615 12616 TPM_KEY_BITS 12617 12618 xor 12619 12620 TPMI_ALG_HASH 12621 12622 Description 12623 12624 when selector may be any of the 12625 symmetric block ciphers 12626 TPM_ALG_XOR 12627 12628 overload for using xor 12629 NOTE 12630 12631 null 12632 12633 TPM_ALG_NULL 12634 allowed 12635 12636 is 12637 12638 not 12639 12640 TPM_ALG_NULL 12641 12642 11.1.5 TPMU_SYM_MODE 12643 This union allows the mode value in a TPMT_SYM_DEF or TPMT_SYM_DEF_OBJECT to be empty. 12644 Table 124 Definition of TPMU_SYM_MODE Union 12645 Parameter 12646 12647 Type 12648 12649 Selector 12650 12651 Description 12652 12653 aes 12654 12655 TPMI_ALG_SYM_MODE 12656 12657 TPM_ALG_AES 12658 12659 NOTE 12660 12661 TPM_ALG_NULL 12662 allowed 12663 12664 is 12665 12666 not 12667 12668 SM4 12669 12670 TPMI_ALG_SYM_MODE 12671 12672 TPM_ALG_SM4 12673 12674 NOTE 12675 12676 TPM_ALG_NULL 12677 allowed 12678 12679 is 12680 12681 not 12682 12683 sym 12684 12685 TPMI_ALG_SYM_MODE 12686 12687 when selector may be any of the 12688 symmetric block ciphers 12689 12690 xor 12691 12692 TPM_ALG_XOR 12693 12694 no mode selector 12695 12696 null 12697 12698 TPM_ALG_NULL 12699 12700 no mode selector 12701 12702 Page 106 12703 October 31, 2013 12704 12705 Published 12706 Copyright TCG 2006-2013 12707 12708 Family 2.0 12709 Level 00 Revision 00.99 12710 12711 Trusted Platform Module Library 12713 12714 Part 2: Structures 12715 12716 11.1.6 TPMU_SYM_DETAILS 12717 This union allows additional parameters to be added for a symmetric cipher. Currently, no additional 12718 parameters are required for any of the symmetric algorithms. 12719 NOTE 12720 12721 The x character in the table title will suppress generation of this type as the parser is not, at this time, 12722 able to generate the proper values (a union of all empty data types). When an algorithm is added that 12723 requires additional parameterization, the Type column will contain a value and the x may be removed. 12724 12725 Table 125 xDefinition of TPMU_SYM_DETAILS Union 12726 Parameter 12727 12728 Type 12729 12730 Selector 12731 12732 aes 12733 12734 TPM_ALG_AES 12735 12736 SM4 12737 12738 Description 12739 12740 TPM_ALG_SM4 12741 12742 sym 12743 12744 when selector may be any of the 12745 symmetric block ciphers 12746 12747 xor 12748 12749 TPM_ALG_XOR 12750 12751 null 12752 12753 TPM_ALG_NULL 12754 12755 11.1.7 TPMT_SYM_DEF 12756 The TPMT_SYM_DEF structure is used to select an algorithm to be used for parameter encryption in 12757 those cases when different symmetric algorithms may be selected. 12758 Table 126 Definition of TPMT_SYM_DEF Structure 12759 Parameter 12760 12761 Type 12762 12763 Description 12764 12765 algorithm 12766 12767 +TPMI_ALG_SYM 12768 12769 indicates a symmetric algorithm 12770 12771 [algorithm]keyBits 12772 12773 TPMU_SYM_KEY_BITS 12774 12775 a supported key size 12776 12777 [algorithm]mode 12778 12779 TPMU_SYM_MODE 12780 12781 the mode for the key 12782 12783 //[algorithm]details 12784 12785 TPMU_SYM_DETAILS 12786 12787 contains additional algorithm details 12788 NOTE 12789 12790 This is commented out at this time as the parser 12791 may not produce the proper code for a union if 12792 none of the selectors produces any data. 12793 12794 11.1.8 TPMT_SYM_DEF_OBJECT 12795 This structure is used when different symmetric block cipher (not XOR) algorithms may be selected. 12796 Table 127 Definition of TPMT_SYM_DEF_OBJECT Structure 12797 Parameter 12798 12799 Type 12800 12801 Description 12802 12803 algorithm 12804 12805 +TPMI_ALG_SYM_OBJECT 12806 12807 selects a symmetric block cipher 12808 12809 [algorithm]keyBits 12810 12811 TPMU_SYM_KEY_BITS 12812 12813 the key size 12814 12815 [algorithm]mode 12816 12817 TPMU_SYM_MODE 12818 12819 default mode 12820 12821 //[algorithm]details 12822 12823 TPMU_SYM_DETAILS 12824 12825 contains the additional algorithm details, if any 12826 NOTE 12827 12828 Family 2.0 12829 Level 00 Revision 00.99 12830 12831 This is commented out at this time as the parser 12832 may not produce the proper code for a union if 12833 none of the selectors produces any data. 12834 12835 Published 12836 Copyright TCG 2006-2013 12837 12838 Page 107 12839 October 31, 2013 12840 12841 Part 2: Structures 12843 12844 Trusted Platform Module Library 12845 12846 11.1.9 TPM2B_SYM_KEY 12847 This structure is used to hold a symmetric key in the sensitive area of an asymmetric object. 12848 The number of bits in the key is in keyBits in the public area. When keyBits is not an even multiple of 8 12849 bits, the unused bits of buffer will be the most significant bits of buffer[0] and size will be rounded up to 12850 the number of octets required to hold all bits of the key. 12851 Table 128 Definition of TPM2B_SYM_KEY Structure 12852 Parameter 12853 12854 Type 12855 12856 Description 12857 12858 size 12859 12860 UINT16 12861 12862 size, in octets, of the buffer containing the key; may be 12863 zero 12864 12865 buffer [size] {:MAX_SYM_KEY_BYTES} 12866 12867 BYTE 12868 12869 the key 12870 12871 11.1.10 TPMS_SYMCIPHER_PARMS 12872 This structure contains the parameters for a symmetric block cipher object. 12873 Table 129 Definition of TPMS_SYMCIPHER_PARMS Structure 12874 Parameter 12875 12876 Type 12877 12878 Description 12879 12880 sym 12881 12882 TPMT_SYM_DEF_OBJECT 12883 12884 a symmetric block cipher 12885 12886 11.1.11 TPM2B_SENSITIVE_DATA 12887 This buffer holds the secret data of a data object. It can hold as much as 128 octets of data. 12888 MAX_SYM_DATA shall be 128. 12889 NOTE 12890 12891 A named value rather than a numeric is used to make coding clearer. A numeric value does not indicate 12892 the reason that it has the specific value that is has. 12893 12894 Table 130 Definition of TPM2B_SENSITIVE_DATA Structure 12895 Parameter 12896 12897 Type 12898 12899 size 12900 12901 UINT16 12902 12903 buffer[size]{: MAX_SYM_DATA} 12904 12905 BYTE 12906 12907 Page 108 12908 October 31, 2013 12909 12910 Description 12911 12912 the keyed hash private data structure 12913 12914 Published 12915 Copyright TCG 2006-2013 12916 12917 Family 2.0 12918 Level 00 Revision 00.99 12919 12920 Trusted Platform Module Library 12922 12923 Part 2: Structures 12924 12925 11.1.12 TPMS_SENSITIVE_CREATE 12926 This structure defines the values to be placed in the sensitive area of a created object. This structure is 12927 only used within a TPM2B_SENSITIVE_CREATE structure. 12928 NOTE 12929 12930 When sent to the TPM or unsealed, data is usually encrypted using parameter encryption. 12931 12932 If data.size is not zero, and the object is not a keyedHash, data.size must match the size indicated in the 12933 keySize of public.parameters. If the object is a keyedHash, data.size may be any value up to the 12934 maximum allowed in a TPM2B_SENSITIVE_DATA. 12935 For an asymmetric object, data shall be an Empty Buffer and sensitiveDataOrigin shall be SET. 12936 Table 131 Definition of TPMS_SENSITIVE_CREATE Structure <IN> 12937 Parameter 12938 12939 Type 12940 12941 Description 12942 12943 userAuth 12944 12945 TPM2B_AUTH 12946 12947 the USER auth secret value 12948 12949 data 12950 12951 TPM2B_SENSITIVE_DATA 12952 12953 data to be sealed 12954 12955 Family 2.0 12956 Level 00 Revision 00.99 12957 12958 Published 12959 Copyright TCG 2006-2013 12960 12961 Page 109 12962 October 31, 2013 12963 12964 Part 2: Structures 12966 12967 Trusted Platform Module Library 12968 12969 11.1.13 TPM2B_SENSITIVE_CREATE 12970 This structure contains the sensitive creation data in a sized buffer. This structure is defined so that both 12971 the userAuth and data values of the TPMS_SENSITIVE_CREATE may be passed as a single parameter 12972 for parameter encryption purposes. 12973 Table 132 Definition of TPM2B_SENSITIVE_CREATE Structure <IN, S> 12974 Parameter 12975 12976 Type 12977 12978 Description 12979 12980 size= 12981 12982 UINT16 12983 12984 size of sensitive in octets (may not be zero) 12985 NOTE 12986 12987 sensitive 12988 12989 TPMS_SENSITIVE_CREATE 12990 12991 The userAuth and data parameters in this buffer 12992 may both be zero length but the minimum size of 12993 this parameter will be the sum of the size fields of 12994 the 12995 two 12996 parameters 12997 of 12998 the 12999 TPMS_SENSITIVE_CREATE. 13000 13001 data to be sealed or a symmetric key value. 13002 13003 11.1.14 TPMS_SCHEME_SIGHASH 13004 This structure is the scheme data for schemes that only require a hash to complete the scheme definition. 13005 Table 133 Definition of TPMS_SCHEME_SIGHASH Structure 13006 Parameter 13007 13008 Type 13009 13010 Description 13011 13012 hashAlg 13013 13014 TPMI_ALG_HASH 13015 13016 the hash algorithm used to digest the message 13017 13018 11.1.15 TPMI_ALG_HASH_SCHEME 13019 This is the list of values that may appear in a keyedHash as the scheme parameter. 13020 Table 134 Definition of (TPM_ALG_ID) TPMI_ALG_KEYEDHASH_SCHEME Type 13021 Values 13022 13023 Comments 13024 13025 TPM_ALG_HMAC 13026 13027 the "signing" scheme 13028 13029 TPM_ALG_XOR 13030 13031 the "obfuscation" scheme 13032 13033 +TPM_ALG_NULL 13034 #TPM_RC_VALUE 13035 13036 11.1.16 HMAC_SIG_SCHEME 13037 Table 135 Definition of Types for HMAC_SIG_SCHEME 13038 Type 13039 13040 Name 13041 13042 TPMS_SCHEME_SIGHASH 13043 13044 TPMS_SCHEME_HMAC 13045 13046 Page 110 13047 October 31, 2013 13048 13049 Description 13050 13051 Published 13052 Copyright TCG 2006-2013 13053 13054 Family 2.0 13055 Level 00 Revision 00.99 13056 13057 Trusted Platform Module Library 13059 13060 Part 2: Structures 13061 13062 11.1.17 TPMS_SCHEME_XOR 13063 This structure is for the XOR encryption scheme. 13064 Table 136 Definition of TPMS_SCHEME_XOR Structure 13065 Parameter 13066 13067 Type 13068 13069 Description 13070 13071 hashAlg 13072 13073 +TPMI_ALG_HASH 13074 13075 the hash algorithm used to digest the message 13076 13077 kdf 13078 13079 TPMI_ALG_KDF 13080 13081 the key derivation function 13082 13083 11.1.18 TPMU_SCHEME_HMAC 13084 Table 137 Definition of TPMU_SCHEME_KEYEDHASH Union <IN/OUT, S> 13085 Parameter 13086 13087 Type 13088 13089 Selector 13090 13091 Description 13092 13093 hmac 13094 13095 TPMS_SCHEME_HMAC 13096 13097 TPM_ALG_HMAC 13098 13099 the "signing" scheme 13100 13101 xor 13102 13103 TPMS_SCHEME_XOR 13104 13105 TPM_ALG_XOR 13106 13107 the "obfuscation" scheme 13108 13109 null 13110 13111 TPM_ALG_NULL 13112 13113 11.1.19 TPMT_KEYEDHASH_SCHEME 13114 This structure is used for a hash signing object. 13115 Table 138 Definition of TPMT_KEYEDHASH_SCHEME Structure 13116 Parameter 13117 13118 Type 13119 13120 Description 13121 13122 scheme 13123 13124 +TPMI_ALG_KEYEDHASH_SCHEME 13125 13126 selects the scheme 13127 13128 [scheme]details 13129 13130 TPMU_SCHEME_KEYEDHASH 13131 13132 the scheme parameters 13133 13134 Family 2.0 13135 Level 00 Revision 00.99 13136 13137 Published 13138 Copyright TCG 2006-2013 13139 13140 Page 111 13141 October 31, 2013 13142 13143 Part 2: Structures 13145 13146 Trusted Platform Module Library 13147 13148 11.2 Asymmetric 13149 11.2.1 Signing Schemes 13150 11.2.1.1 13151 13152 Introduction 13153 13154 These structures are used to define the method in which the signature is to be created. These schemes 13155 would appear in an objects public area and in commands where the signing scheme is variable. 13156 Every scheme is required to indicate a hash that is used in digesting the message. 13157 11.2.1.2 13158 13159 RSA_SIG_SCHEMES 13160 13161 These are the RSA schemes that only need a hash algorithm as a scheme parameter. 13162 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 13163 always the largest salt value that will fit into the available space. 13164 Table 139 Definition of {RSA} Types for RSA_SIG_SCHEMES 13165 Type 13166 13167 Name 13168 13169 Description 13170 13171 TPMS_SCHEME_SIGHASH TPMS_SCHEME_RSASSA 13172 TPMS_SCHEME_SIGHASH TPMS_SCHEME_RSAPSS 13173 13174 11.2.1.3 13175 13176 ECC_SIG_SCHEMES 13177 13178 These are the ECC schemes that only need a hash algorithm as a controlling parameter. 13179 Table 140 Definition of {ECC} Types for ECC_SIG_SCHEMES 13180 Type 13181 13182 Name 13183 13184 Description 13185 13186 TPMS_SCHEME_SIGHASH TPMS_SCHEME_ECDSA 13187 TPMS_SCHEME_SIGHASH TPMS_SCHEME_SM2 13188 TPMS_SCHEME_SIGHASH TPMS_SCHEME_ECSCHNORR 13189 13190 11.2.1.4 TPMS_SCHEME_ECDAA 13191 Table 141 Definition of {ECC} TPMS_SCHEME_ECDAA Structure 13192 Parameter 13193 13194 Type 13195 13196 Description 13197 13198 hashAlg 13199 13200 TPMI_ALG_HASH 13201 13202 the hash algorithm used to digest the message 13203 13204 count 13205 13206 UINT16 13207 13208 the counter value that is used between TPM2_Commit() and the sign 13209 operation 13210 13211 Page 112 13212 October 31, 2013 13213 13214 Published 13215 Copyright TCG 2006-2013 13216 13217 Family 2.0 13218 Level 00 Revision 00.99 13219 13220 Trusted Platform Module Library 13222 11.2.1.5 13223 13224 Part 2: Structures 13225 13226 TPMU_SIG_SCHEME 13227 Table 142 Definition of TPMU_SIG_SCHEME Union <IN/OUT, S> 13228 13229 Parameter 13230 13231 Type 13232 13233 Selector 13234 13235 Description 13236 13237 rsassa 13238 13239 TPMS_SCHEME_RSASSA 13240 13241 TPM_ALG_RSASSA 13242 13243 the PKCS#1v1.5 scheme 13244 13245 rsapss 13246 13247 TPMS_SCHEME_RSAPSS 13248 13249 TPM_ALG_RSAPSS 13250 13251 the PKCS#1v2.1 PSS scheme 13252 13253 ecdsa 13254 13255 TPMS_SCHEME_ECDSA 13256 13257 TPM_ALG_ECDSA 13258 13259 the ECDSA scheme 13260 13261 sm2 13262 13263 TPMS_SCHEME_SM2 13264 13265 TPM_ALG_SM2 13266 13267 ECDSA from SM2 13268 13269 ecdaa 13270 13271 TPMS_SCHEME_ECDAA 13272 13273 TPM_ALG_ECDAA 13274 13275 the ECDAA scheme 13276 13277 ecSchnorr 13278 13279 TPMS_SCHEME_ECSCHNORR 13280 13281 TPM_ALG_ECSCHNORR 13282 13283 the EC Schnorr 13284 13285 hmac 13286 13287 TPMS_SCHEME_HMAC 13288 13289 TPM_ALG_HMAC 13290 13291 the HMAC scheme 13292 13293 any 13294 13295 TPMS_SCHEME_SIGHASH 13296 13297 null 13298 13299 11.2.1.6 13300 13301 selector that allows access to 13302 digest for any signing scheme 13303 TPM_ALG_NULL 13304 13305 no scheme or default 13306 13307 TPMT_SIG_SCHEME 13308 Table 143 Definition of TPMT_SIG_SCHEME Structure 13309 13310 Parameter 13311 13312 Type 13313 13314 Description 13315 13316 scheme 13317 13318 +TPMI_ALG_SIG_SCHEME 13319 13320 scheme selector 13321 13322 [scheme]details 13323 13324 TPMU_SIG_SCHEME 13325 13326 scheme parameters 13327 13328 Family 2.0 13329 Level 00 Revision 00.99 13330 13331 Published 13332 Copyright TCG 2006-2013 13333 13334 Page 113 13335 October 31, 2013 13336 13337 Part 2: Structures 13339 13340 Trusted Platform Module Library 13341 13342 11.2.2 Encryption Schemes 13343 11.2.2.1 13344 13345 Introduction 13346 13347 These structures are used to indicate the hash algorithm used for the encrypting process. These 13348 schemes would appear in an objects public area. 13349 11.2.2.2 13350 13351 TPMS_SCHEME_OAEP 13352 Table 144 Definition of {RSA} TPMS_SCHEME_OAEP Structure 13353 13354 Parameter 13355 13356 Type 13357 13358 Description 13359 13360 hashAlg 13361 13362 +TPMI_ALG_HASH 13363 13364 the hash algorithm used to digest the message 13365 13366 11.2.2.3 13367 13368 TPMS_SCHEME_ECDH 13369 13370 For ECDH, KDFe is used for the key derivation function that only a hash algorithm is needed to complete 13371 the definition. 13372 Table 145 Definition of {ECC} TPMS_SCHEME_ECDH Structure 13373 Parameter 13374 13375 Type 13376 13377 Description 13378 13379 hashAlg 13380 13381 +TPMI_ALG_HASH 13382 13383 the hash algorithm used in the KDF 13384 13385 11.2.3 Key Derivation Schemes 13386 11.2.3.1 13387 13388 Introduction 13389 13390 These structures are used to define the key derivation for symmetric secret sharing using asymmetric 13391 methods. A secret shareing scheme is required in any asymmetric key with the decrypt attribute SET. 13392 These schemes would appear in an objects public area and in commands where the secret sharing 13393 scheme is variable. 13394 Each scheme includes a symmetric algorithm and a KDF selection. 13395 11.2.3.2 13396 13397 TPMS_SCHEME_MGF1 13398 Table 146 Definition of TPMS_SCHEME_MGF1 Structure 13399 13400 Parameter 13401 13402 Type 13403 13404 Description 13405 13406 hashAlg 13407 13408 TPMI_ALG_HASH 13409 13410 the hash algorithm used in the KDF 13411 13412 11.2.3.3 13413 13414 TPMS_SCHEME_KDF1_SP800_56a 13415 Table 147 Definition of {ECC} TPMS_SCHEME_KDF1_SP800_56a 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 Page 114 13430 October 31, 2013 13431 13432 Published 13433 Copyright TCG 2006-2013 13434 13435 Family 2.0 13436 Level 00 Revision 00.99 13437 13438 Trusted Platform Module Library 13440 11.2.3.4 13441 13442 Part 2: Structures 13443 13444 TPMS_SCHEME_KDF2 13445 Table 148 Definition of TPMS_SCHEME_KDF2 Structure 13446 13447 Parameter 13448 13449 Type 13450 13451 Description 13452 13453 hashAlg 13454 13455 TPMI_ALG_HASH 13456 13457 the hash algorithm used in the KDF 13458 13459 11.2.3.5 13460 13461 TPMS_SCHEME_KDF1_SP800_108 13462 Table 149 Definition of TPMS_SCHEME_KDF1_SP800_108 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.6 13477 13478 TPMU_KDF_SCHEME 13479 Table 150 Definition of TPMU_KDF_SCHEME Union <IN/OUT, S> 13480 13481 Parameter 13482 13483 Type 13484 13485 Selector 13486 13487 mgf1 13488 13489 TPMS_SCHEME_MGF1 13490 13491 TPM_ALG_MGF1 13492 13493 kdf1_SP800_56a TPMS_SCHEME_KDF1_SP800_56a 13494 13495 TPM_ALG_KDF1_SP800_56a 13496 13497 kdf2 13498 13499 TPMS_SCHEME_KDF2 13500 13501 TPM_ALG_KDF2 13502 13503 kdf1_sp800_108 13504 13505 TPMS_SCHEME_KDF1_SP800_108 13506 13507 Description 13508 13509 TPM_ALG_KDF1_SP800_108 13510 13511 null 13512 13513 11.2.3.7 13514 13515 TPM_ALG_NULL 13516 13517 TPMT_KDF_SCHEME 13518 Table 151 Definition of TPMT_KDF_SCHEME Structure 13519 13520 Parameter 13521 13522 Type 13523 13524 Description 13525 13526 scheme 13527 13528 +TPMI_ALG_KDF 13529 13530 scheme selector 13531 13532 [scheme]details 13533 13534 TPMU_KDF_SCHEME 13535 13536 scheme parameters 13537 13538 Family 2.0 13539 Level 00 Revision 00.99 13540 13541 Published 13542 Copyright TCG 2006-2013 13543 13544 Page 115 13545 October 31, 2013 13546 13547 Part 2: Structures 13549 11.2.3.8 13550 13551 Trusted Platform Module Library 13552 13553 TPMI_ALG_ASYM_SCHEME 13554 13555 List of all of the scheme types for any asymmetric algorithm. This is used to define the 13556 TPMT_ASYM_SCHEME. 13557 Table 152 Definition of (TPM_ALG_ID) TPMI_ALG_ASYM_SCHEME Type <> 13558 Values 13559 13560 Comments 13561 13562 TPM_ALG_RSASSA 13563 13564 list of the allowed values 13565 13566 TPM_ALG_RSAPSS 13567 TPM_ALG_RSAES 13568 TPM_ALG_OAEP 13569 TPM_ALG_ECDSA 13570 TPM_ALG_SM2 13571 TPM_ALG_ECDAA 13572 TPM_ALG_ECDH 13573 +TPM_ALG_NULL 13574 #TPM_RC_VALUE 13575 13576 11.2.3.9 13577 13578 TPMU_ASYM_SCHEME 13579 13580 This union of all asymmetric schemes is used in each of the asymmetric scheme structures. The actual 13581 scheme structure is defined by the interface type used for the selector. 13582 EXAMPLE 13583 13584 The TPMT_RSA_SCHEME structure uses the TPMU_ASYM_SCHEME union but the selector type is 13585 TPMI_ALG_RSA_SCHEME. This means that the only elements of the union that can be selected for th e 13586 TPMT_RSA_SCHEME are those that are in TPMI_RSA_SCHEME. 13587 13588 Table 153 Definition of TPMU_ASYM_SCHEME Union 13589 Parameter 13590 13591 Type 13592 13593 Selector 13594 13595 Description 13596 13597 rsassa 13598 13599 TPMS_SCHEME_RSASSA 13600 13601 TPM_ALG_RSASSA 13602 13603 the PKCS#1v1.5 scheme 13604 13605 rsapss 13606 13607 TPMS_SCHEME_RSAPSS 13608 13609 TPM_ALG_RSAPSS 13610 13611 the PKCS#1v2.1 PSS scheme 13612 13613 TPM_ALG_RSAES 13614 13615 the PKCS#1v2.1 RSAES scheme 13616 13617 rsaes 13618 oaep 13619 13620 TPMS_SCHEME_OAEP 13621 13622 TPM_ALG_OAEP 13623 13624 the PKSC#1v2.1 OAEP scheme 13625 13626 ecdsa 13627 13628 TPMS_SCHEME_ECDSA 13629 13630 TPM_ALG_ECDSA 13631 13632 an ECDSA scheme 13633 13634 sm2 13635 13636 TPMS_SCHEME_SM2 13637 13638 TPM_ALG_SM2 13639 13640 sign or key exchange from SM2 13641 13642 ecdaa 13643 13644 TPMS_SCHEME_ECDAA 13645 13646 TPM_ALG_ECDAA 13647 13648 an ECDAA scheme 13649 13650 ecSchnorr 13651 13652 TPMS_SCHEME_ECSCHNORR 13653 13654 TPM_ALG_ECSCHNORR elliptic curve Schnorr signature 13655 13656 ecdh 13657 anySig 13658 13659 TPM_ALG_ECDH 13660 TPMS_SCHEME_SIGHASH 13661 13662 null 13663 13664 Page 116 13665 October 31, 2013 13666 13667 TPM_ALG_NULL 13668 13669 Published 13670 Copyright TCG 2006-2013 13671 13672 no scheme or default 13673 This selects the NULL Signature. 13674 13675 Family 2.0 13676 Level 00 Revision 00.99 13677 13678 Trusted Platform Module Library 13680 13681 Part 2: Structures 13682 13683 11.2.3.10 TPMT_ASYM_SCHEME 13684 This structure is defined to allow overlay of all of the schemes for any asymmetric object. This structure is 13685 not sent on the interface. 13686 Table 154 Definition of TPMT_ASYM_SCHEME Structure <> 13687 Parameter 13688 13689 Type 13690 13691 Description 13692 13693 scheme 13694 13695 +TPMI_ALG_ASYM_SCHEME 13696 13697 scheme selector 13698 13699 [scheme]details 13700 13701 TPMU_ASYM_SCHEME 13702 13703 scheme parameters 13704 13705 11.2.4 RSA 13706 11.2.4.1 13707 13708 TPMI_ALG_RSA_SCHEME 13709 13710 The list of values that may appear in the scheme parameter of a TPMS_RSA_PARMS structure. 13711 Table 155 Definition of (TPM_ALG_ID) {RSA} TPMI_ALG_RSA_SCHEME Type 13712 Values 13713 13714 Comments 13715 13716 TPM_ALG_RSASSA 13717 13718 list of the allowed values 13719 13720 TPM_ALG_RSAPSS 13721 TPM_ALG_RSAES 13722 TPM_ALG_OAEP 13723 +TPM_ALG_NULL 13724 #TPM_RC_VALUE 13725 13726 11.2.4.2 13727 13728 TPMT_RSA_SCHEME 13729 Table 156 Definition of {RSA} TPMT_RSA_SCHEME Structure 13730 13731 Parameter 13732 13733 Type 13734 13735 Description 13736 13737 scheme 13738 13739 +TPMI_ALG_RSA_SCHEME 13740 13741 scheme selector 13742 13743 [scheme]details 13744 13745 TPMU_ASYM_SCHEME 13746 13747 scheme parameters 13748 13749 Family 2.0 13750 Level 00 Revision 00.99 13751 13752 Published 13753 Copyright TCG 2006-2013 13754 13755 Page 117 13756 October 31, 2013 13757 13758 Part 2: Structures 13760 11.2.4.3 13761 13762 Trusted Platform Module Library 13763 13764 TPMI_ALG_RSA_DECRYPT 13765 13766 The list of values that are allowed in a decryption scheme selection as used in TPM2_RSA_Encrypt() and 13767 TPM2_RSA_Decrypt(). 13768 Table 157 Definition of (TPM_ALG_ID) {RSA} TPMI_ALG_RSA_DECRYPT Type 13769 Values 13770 13771 Comments 13772 13773 TPM_ALG_RSAES 13774 TPM_ALG_OAEP 13775 +TPM_ALG_NULL 13776 #TPM_RC_VALUE 13777 13778 11.2.4.4 13779 13780 TPMT_RSA_DECRYPT 13781 Table 158 Definition of {RSA} TPMT_RSA_DECRYPT Structure 13782 13783 Parameter 13784 13785 Type 13786 13787 Description 13788 13789 scheme 13790 13791 +TPMI_ALG_RSA_DECRYPT 13792 13793 scheme selector 13794 13795 [scheme]details 13796 13797 TPMU_ASYM_SCHEME 13798 13799 scheme parameters 13800 13801 11.2.4.5 13802 13803 TPM2B_PUBLIC_KEY_RSA 13804 13805 This sized buffer holds the largest RSA public key supported by the TPM. 13806 NOTE 13807 13808 The reference implementation only supports key sizes of 1,024 and 2,048 bits. 13809 13810 Table 159 Definition of {RSA} TPM2B_PUBLIC_KEY_RSA Structure 13811 Parameter 13812 13813 Type 13814 13815 Description 13816 13817 size 13818 13819 UINT16 13820 13821 size of the buffer 13822 The value of zero is only valid for create. 13823 13824 buffer[size] {: MAX_RSA_KEY_BYTES} 13825 13826 BYTE 13827 13828 Value 13829 13830 11.2.4.6 13831 13832 TPMI_RSA_KEY_BITS 13833 13834 This holds the value that is the maximum size allowed for an RSA key. 13835 NOTE 1 13836 13837 An implementation is allowed to provide limited support for smaller RSA key sizes. That is, a TPM may be 13838 able to accept a smaller RSA key size in TPM2_LoadExternal() when only the public area is loaded but 13839 not accept that smaller key size in any command that loads both the public and private portions of an RSA 13840 key. This would allow the TPM to validate signatures using the smaller key but would prevent the TPM 13841 from using the smaller key size for any other purpose. 13842 13843 NOTE 2 13844 13845 The definition for RSA_KEY_SIZES_BITS used in the reference implementation is found in Annex B 13846 13847 Page 118 13848 October 31, 2013 13849 13850 Published 13851 Copyright TCG 2006-2013 13852 13853 Family 2.0 13854 Level 00 Revision 00.99 13855 13856 Trusted Platform Module Library 13858 13859 Part 2: Structures 13860 13861 Table 160 Definition of {RSA} (TPM_KEY_BITS) TPMI_RSA_KEY_BITS Type 13862 Parameter 13863 13864 Description 13865 13866 $RSA_KEY_SIZES_BITS 13867 13868 the number of bits in the supported key 13869 13870 #TPM_RC_VALUE 13871 13872 error when key size is not supported 13873 13874 11.2.4.7 13875 13876 TPM2B_PRIVATE_KEY_RSA 13877 13878 This sized buffer holds the largest RSA prime number supported by the TPM. 13879 NOTE 13880 13881 All primes are required to have exactly half the number of significant bits as the public modulus , and the 13882 square of each prime is required to have the same number of significant bits as the public modulus. 13883 13884 Table 161 Definition of {RSA} TPM2B_PRIVATE_KEY_RSA Structure 13885 Parameter 13886 13887 Type 13888 13889 size 13890 13891 UINT16 13892 13893 buffer[size]{:MAX_RSA_KEY_BYTES/2} 13894 13895 BYTE 13896 13897 Family 2.0 13898 Level 00 Revision 00.99 13899 13900 Description 13901 13902 Published 13903 Copyright TCG 2006-2013 13904 13905 Page 119 13906 October 31, 2013 13907 13908 Part 2: Structures 13910 13911 Trusted Platform Module Library 13912 13913 11.2.5 ECC 13914 11.2.5.1 13915 13916 TPM2B_ECC_PARAMETER 13917 13918 This sized buffer holds the largest ECC parameter (coordinate) supported by the TPM. 13919 Table 162 Definition of {ECC} TPM2B_ECC_PARAMETER Structure 13920 Parameter 13921 13922 Type 13923 13924 Description 13925 13926 size 13927 13928 UINT16 13929 13930 size of buffer 13931 13932 buffer[size] {:MAX_ECC_KEY_BYTES} 13933 13934 BYTE 13935 13936 the parameter data 13937 13938 11.2.5.2 13939 13940 TPMS_ECC_POINT 13941 13942 This structure holds two ECC coordinates that, together, make up an ECC point. 13943 Table 163 Definition of {ECC} TPMS_ECC_POINT Structure 13944 Parameter 13945 13946 Type 13947 13948 Description 13949 13950 x 13951 13952 TPM2B_ECC_PARAMETER 13953 13954 X coordinate 13955 13956 y 13957 13958 TPM2B_ECC_PARAMETER 13959 13960 Y coordinate 13961 13962 11.2.5.3 13963 13964 TPM2B_ECC_POINT 13965 13966 This structure is defined to allow a point to be a single sized parameter so that it may be encrypted. 13967 NOTE 13968 13969 If the point is to be omitted, the X and Y coordinates need to be individual ly set to Empty Buffers. The 13970 minimum value for size will be four. It is checked indirectly by unmarshaling of the TPMS_ECC_POINT. If 13971 the type of point were BYTE, then size could have been zero. However, this would complicate the process 13972 of marshaling the structure. 13973 13974 Table 164 Definition of {ECC} TPM2B_ECC_POINT Structure 13975 Parameter 13976 13977 Type 13978 13979 Description 13980 13981 size= 13982 13983 UINT16 13984 13985 size of the remainder of this structure 13986 13987 point 13988 13989 TPMS_ECC_POINT 13990 13991 coordinates 13992 error returned if the unmarshaled size of point is 13993 not exactly equal to size 13994 13995 #TPM_RC_SIZE 13996 13997 Page 120 13998 October 31, 2013 13999 14000 Published 14001 Copyright TCG 2006-2013 14002 14003 Family 2.0 14004 Level 00 Revision 00.99 14005 14006 Trusted Platform Module Library 14008 11.2.5.4 14009 14010 Part 2: Structures 14011 14012 TPMI_ALG_ECC_SCHEME 14013 Table 165 Definition of (TPM_ALG_ID) {ECC} TPMI_ALG_ECC_SCHEME Type 14014 14015 Values 14016 14017 Comments 14018 14019 TPM_ALG_ECDSA 14020 14021 these are the selections allowed for an ECC key 14022 14023 TPM_ALG_SM2 14024 TPM_ALG_ECDAA 14025 TPM_ALG_ECSCHNORR 14026 TPM_ALG_ECDH 14027 +TPM_ALG_NULL 14028 #TPM_RC_SCHEME 14029 14030 11.2.5.5 14031 14032 TPMI_ECC_CURVE 14033 14034 The ECC curves implemented by the TPM. 14035 NOTE 14036 14037 The definition of ECC_CURVES used in the reference implementation is found in Annex B 14038 14039 Table 166 Definition of {ECC} (TPM_ECC_CURVE) TPMI_ECC_CURVE Type 14040 Parameter 14041 14042 Description 14043 14044 $ECC_CURVES 14045 14046 the list of implemented curves 14047 14048 #TPM_RC_CURVE 14049 14050 error when curve is not supported 14051 14052 11.2.5.6 14053 14054 TPMT_ECC_SCHEME 14055 14056 Table 167 Definition of (TPMT_SIG_SCHEME) {ECC} TPMT_ECC_SCHEME Structure 14057 Parameter 14058 14059 Type 14060 14061 Description 14062 14063 scheme 14064 14065 +TPMI_ALG_ECC_SCHEME 14066 14067 scheme selector 14068 14069 [scheme]details 14070 14071 TPMU_SIG_SCHEME 14072 14073 scheme parameters 14074 14075 Family 2.0 14076 Level 00 Revision 00.99 14077 14078 Published 14079 Copyright TCG 2006-2013 14080 14081 Page 121 14082 October 31, 2013 14083 14084 Part 2: Structures 14086 11.2.5.7 14087 14088 Trusted Platform Module Library 14089 14090 TPMS_ALGORITHM_DETAIL_ECC 14091 14092 This structure is used to report on the curve parameters of an ECC curve. It is returned by 14093 TPM2_ECC_Parameters(). 14094 Table 168 Definition of {ECC} TPMS_ALGORITHM_DETAIL_ECC Structure <OUT> 14095 Parameter 14096 14097 Type 14098 14099 Description 14100 14101 curveID 14102 14103 TPM_ECC_CURVE 14104 14105 identifier for the curve 14106 14107 keySize 14108 14109 UINT16 14110 14111 Size in bits of the key 14112 14113 kdf 14114 14115 TPMT_KDF_SCHEME 14116 14117 the default KDF and hash algorithm used in secret sharing 14118 operations 14119 14120 sign 14121 14122 TPMT_ECC_SCHEME+ 14123 14124 If not TPM_ALG_NULL, this is the mandatory signature 14125 scheme that is required to be used with this curve. 14126 14127 p 14128 14129 TPM2B_ECC_PARAMETER 14130 14131 Fp (the modulus) 14132 14133 a 14134 14135 TPM2B_ECC_PARAMETER 14136 14137 coefficient of the linear term in the curve equation 14138 14139 b 14140 14141 TPM2B_ECC_PARAMETER 14142 14143 constant term for curve equation 14144 14145 gX 14146 14147 TPM2B_ECC_PARAMETER 14148 14149 x coordinate of base point G 14150 14151 gY 14152 14153 TPM2B_ECC_PARAMETER 14154 14155 y coordinate of base point G 14156 14157 n 14158 14159 TPM2B_ECC_PARAMETER 14160 14161 order of G 14162 14163 h 14164 14165 TPM2B_ECC_PARAMETER 14166 14167 cofactor (a size of zero indicates a cofactor of 1) 14168 14169 11.3 Signatures 14170 11.3.1 TPMS_SIGNATURE_RSASSA 14171 Table 169 Definition of {RSA} TPMS_SIGNATURE_RSASSA Structure 14172 Parameter 14173 14174 Type 14175 14176 Description 14177 14178 hash 14179 14180 TPMI_ALG_HASH 14181 14182 the hash algorithm used to digest the message 14183 TPM_ALG_NULL is not allowed. 14184 14185 sig 14186 14187 TPM2B_PUBLIC_KEY_RSA 14188 14189 The signature is the size of a public key. 14190 14191 11.3.2 TPMS_SIGNATURE_RSAPSS 14192 When the TPM generates a PSS signature, the salt size is the largest size allowed by the key and hash 14193 combination. 14194 EXAMPLE 14195 14196 For a 2,048-bit public modulus key and SHA1 hash, the salt size is 256 20 2 = 234 octets. 14197 14198 NOTE 14199 14200 While this is significantly larger than required from a securit y perspective, it avoids issues of whether a 14201 particular size of salt value is sufficient. 14202 14203 Page 122 14204 October 31, 2013 14205 14206 Published 14207 Copyright TCG 2006-2013 14208 14209 Family 2.0 14210 Level 00 Revision 00.99 14211 14212 Trusted Platform Module Library 14214 14215 Part 2: Structures 14216 14217 Table 170 Definition of {RSA} TPMS_SIGNATURE_RSAPSS Structure 14218 Parameter 14219 14220 Type 14221 14222 Description 14223 14224 hash 14225 14226 TPMI_ALG_HASH 14227 14228 the hash algorithm used in the signature process 14229 TPM_ALG_NULL is not allowed. 14230 14231 sig 14232 14233 TPM2B_PUBLIC_KEY_RSA 14234 14235 The signature is the size of a public key. 14236 14237 11.3.3 TPMS_SIGNATURE_ECDSA 14238 Table 171 Definition of {ECC} TPMS_SIGNATURE_ECDSA Structure 14239 Parameter 14240 14241 Type 14242 14243 Description 14244 14245 hash 14246 14247 TPMI_ALG_HASH 14248 14249 the hash algorithm used in the signature process 14250 TPM_ALG_NULL is not allowed. 14251 14252 signatureR 14253 14254 TPM2B_ECC_PARAMETER 14255 14256 signatureS 14257 14258 TPM2B_ECC_PARAMETER 14259 14260 11.3.4 TPMU_SIGNATURE 14261 A TPMU_SIGNATURE_COMPOSITE is a union of the various signatures that is supported by a particular 14262 TPM implementation. The union allows substitution of any signature algorithm wherever a signature is 14263 required in a structure. Table 172 is an illustration of a TPMU_SIGNATURE for a TPM that implements 14264 both RSA and ECC signing. 14265 NOTE 1 14266 14267 All TPM are required to support a hash algorithm and the HMAC algorithm. 14268 14269 When a symmetric algorithm is used for signing, the signing algorithm is assumed to be an HMAC based 14270 on the indicated hash algorithm. The HMAC key will either be referenced as part of the usage or will be 14271 implied by context. 14272 NOTE 2 14273 14274 The table below is illustrative. It would be modified to reflect the signatures produced by the TPM. 14275 14276 Table 172 Definition of TPMU_SIGNATURE Union <IN/OUT, S> 14277 Parameter 14278 14279 Type 14280 14281 Selector 14282 14283 Description 14284 14285 rsassa 14286 14287 TPMS_SIGNATURE_RSASSA 14288 14289 TPM_ALG_RSASSA 14290 14291 a PKCS#1v1.5 signature 14292 14293 rsapss 14294 14295 TPMS_SIGNATURE_RSAPSS 14296 14297 TPM_ALG_RSAPSS 14298 14299 a PKCS#1v2.1PSS signature 14300 14301 ecdsa 14302 14303 TPMS_SIGNATURE_ECDSA 14304 14305 TPM_ALG_ECDSA 14306 14307 an ECDSA signature 14308 14309 sm2 14310 14311 TPMS_SIGNATURE_ECDSA 14312 14313 TPM_ALG_SM2 14314 14315 same format as ECDSA 14316 14317 ecdaa 14318 14319 TPMS_SIGNATURE_ECDSA 14320 14321 TPM_ALG_ECDAA 14322 14323 same format as ECDSA 14324 14325 ecschnorr 14326 14327 TPMS_SIGNATURE_ECDSA 14328 14329 TPM_ALG_ECSCHNORR 14330 14331 same format as ECDSA 14332 14333 hmac 14334 14335 TPMT_HA 14336 14337 TPM_ALG_HMAC 14338 14339 HMAC signature (required to 14340 be supported) 14341 14342 any 14343 14344 TPMS_SCHEME_SIGHASH 14345 14346 null 14347 14348 Family 2.0 14349 Level 00 Revision 00.99 14350 14351 used to access the hash 14352 TPM_ALG_NULL 14353 14354 Published 14355 Copyright TCG 2006-2013 14356 14357 the NULL signature 14358 14359 Page 123 14360 October 31, 2013 14361 14362 Part 2: Structures 14364 14365 Trusted Platform Module Library 14366 14367 11.3.5 TPMT_SIGNATURE 14368 Table 173 shows the basic algorithm-agile structure when a symmetric or asymmetric signature is 14369 indicated. The sigAlg parameter indicates the algorithm used for the signature. This structure is output 14370 from the attestation commands and is an input to TPM2_VerifySignature(), TPM2_PolicySigned(), and 14371 TPM2_FieldUpgradeStart(). 14372 Table 173 Definition of TPMT_SIGNATURE Structure 14373 Parameter 14374 14375 Type 14376 14377 Description 14378 14379 sigAlg 14380 14381 +TPMI_ALG_SIG_SCHEME 14382 14383 selector of the algorithm used to construct the signature 14384 14385 [sigAlg]signature 14386 14387 TPMU_SIGNATURE 14388 14389 This shall be the actual signature information. 14390 14391 11.4 Key/Secret Exchange 14392 11.4.1 Introduction 14393 The structures in this clause are used when a key or secret is being exchanged. The exchange may be in 14394 14395 14396 TPM2_StartAuthSession() where the secret is injected for salting the session, 14397 14398 14399 14400 TPM2_Duplicate(), TPM2_Import, or TPM2_Rewrap() where the secret is the symmetric encryption 14401 key for the outer wrapper of a duplication blob, or 14402 14403 14404 14405 TPM2_ActivateIdentity() or TPM2_CreateIdentity() where the secret is the symmetric encryption key 14406 for the credential blob. 14407 14408 Particulars are described in Part 1. 14409 11.4.2 TPMU_ENCRYPTED_SECRET 14410 This structure is used to hold either an ephemeral public point for ECDH, an OAEP-encrypted block for 14411 RSA, or a symmetrically encrypted value. This structure is defined for the limited purpose of determining 14412 the size of a TPM2B_ENCRYPTED_SECRET. 14413 The symmetrically encrypted value may use either CFB or XOR encryption. 14414 NOTE 14415 14416 Table 174 is illustrative. It would be modified depending on the algorithms supported in the TPM. 14417 14418 Table 174 Definition of TPMU_ENCRYPTED_SECRET Union <S> 14419 Parameter 14420 14421 Type 14422 14423 Selector 14424 14425 ecc[sizeof(TPMS_ECC_POINT)] 14426 14427 BYTE 14428 14429 TPM_ALG_ECC 14430 14431 rsa[MAX_RSA_KEY_BYTES] 14432 14433 BYTE 14434 14435 TPM_ALG_RSA 14436 14437 symmetric[sizeof(TPM2B_DIGEST)] 14438 14439 BYTE 14440 14441 TPM_ALG_SYMCIPHER 14442 14443 keyedHash[sizeof(TPM2B_DIGEST)] 14444 14445 BYTE 14446 14447 TPM_ALG_KEYEDHASH 14448 14449 Page 124 14450 October 31, 2013 14451 14452 Published 14453 Copyright TCG 2006-2013 14454 14455 Description 14456 14457 Any symmetrically encrypted 14458 secret value will be limited to 14459 be no larger than a digest. 14460 14461 Family 2.0 14462 Level 00 Revision 00.99 14463 14464 Trusted Platform Module Library 14466 14467 Part 2: Structures 14468 14469 11.4.3 TPM2B_ENCRYPTED_SECRET 14470 Table 175 Definition of TPM2B_ENCRYPTED_SECRET Structure 14471 Parameter 14472 14473 Type 14474 14475 Description 14476 14477 size 14478 14479 UINT16 14480 14481 size of the secret value 14482 14483 secret[size] {:sizeof(TPMU_ENCRYPTED_SECRET)} 14484 14485 BYTE 14486 14487 secret 14488 14489 Family 2.0 14490 Level 00 Revision 00.99 14491 14492 Published 14493 Copyright TCG 2006-2013 14494 14495 Page 125 14496 October 31, 2013 14497 14498 Part 2: Structures 14500 14501 Trusted Platform Module Library 14502 14503 12 Key/Object Complex 14504 12.1 Introduction 14505 An object description requires a TPM2B_PUBLIC structure and may require a TPMT_SENSITIVE 14506 structure. When the structure is stored off the TPM, the TPMT_SENSITIVE structure is encrypted within a 14507 TPM2B_PRIVATE structure. 14508 When the object requires two components for its description, those components are loaded as separate 14509 parameters in the TPM2_Load() command. When the TPM creates an object that requires both 14510 components, the TPM will return them as separate parameters from the TPM2_Create() operation. 14511 The TPM may produce multiple different TPM2B_PRIVATE structures for a single TPM2B_PUBLIC 14512 structure. Creation of a modified TPM2B_PRIVATE structure requires that the full structure be loaded with 14513 the TPM2_Load() command, modification of the TPMT_SENSITIVE data, and output of a new 14514 TPM2B_PRIVATE structure. 14515 12.2 Public Area Structures 14516 12.2.1 Description 14517 This clause defines the TPM2B_PUBLIC structure and the higher-level substructure that may be 14518 contained in a TPM2B_PUBLIC. The higher-level structures that are currently defined for inclusion in a 14519 TPM2B_PUBLIC are the 14520 14521 14522 structures for asymmetric keys, 14523 14524 14525 14526 structures for symmetric keys, and 14527 14528 14529 14530 structures for sealed data. 14531 14532 12.2.2 TPMI_ALG_PUBLIC 14533 Table 176 Definition of (TPM_ALG_ID) TPMI_ALG_PUBLIC Type 14534 Values 14535 14536 Comments 14537 14538 TPM_ALG_KEYEDHASH 14539 14540 required of all TPM 14541 14542 TPM_ALG_SYMCIPHER 14543 14544 required of all TPM 14545 14546 TPM_ALG_RSA 14547 14548 At least one asymmetric algorithm shall be implemented. 14549 14550 TPM_ALG_ECC 14551 14552 At least one asymmetric algorithm shall be implemented. 14553 14554 #TPM_RC_TYPE 14555 14556 response code when a public type is not supported 14557 14558 12.2.3 Type-Specific Parameters 14559 12.2.3.1 14560 14561 Description 14562 14563 The public area contains two fields (parameters and unique) that vary by object type. The parameters 14564 field varies according to the type of the object but the contents may be the same across multiple 14565 instances of a particular type. The unique field format also varies according to the type of the object and 14566 will also be unique for each instance. 14567 14568 Page 126 14569 October 31, 2013 14570 14571 Published 14572 Copyright TCG 2006-2013 14573 14574 Family 2.0 14575 Level 00 Revision 00.99 14576 14577 Trusted Platform Module Library 14579 14580 Part 2: Structures 14581 14582 For a symmetric key (type == TPM_ALG_SYMCIPHER), HMAC key (type == TPM_ALG_KEYEDHASH) 14583 or data object (also, type == TPM_ALG_KEYEDHASH), the contents of unique shall be computed from 14584 components of the sensitive area of the object as follows: 14585 14586 unique HnameAlg(seedValue || sensitive) 14587 14588 (8) 14589 14590 where 14591 14592 HnameAlg() 14593 14594 the hash algorithm used to compute the Name of the object 14595 14596 seedValue 14597 14598 the digest-sized obfuscation value in the sensitive area of a symmetric 14599 key 14600 or 14601 symmetric 14602 data 14603 object 14604 found 14605 in 14606 a 14607 TPMT_SENSITIVE.seedValue.buffer 14608 14609 sensitive 14610 14611 the 14612 secret 14613 key/data 14614 of 14615 TPMT_SENSITIVE.sensitive.any.buffer 14616 14617 12.2.3.2 14618 14619 the 14620 14621 object 14622 14623 in 14624 14625 the 14626 14627 TPMU_PUBLIC_ID 14628 Table 177 Definition of TPMU_PUBLIC_ID Union <IN/OUT, S> 14629 14630 Parameter 14631 14632 Type 14633 14634 Selector 14635 14636 keyedHash 14637 14638 TPM2B_DIGEST 14639 14640 TPM_ALG_KEYEDHASH 14641 14642 sym 14643 14644 TPM2B_DIGEST 14645 14646 TPM_ALG_SYMCIPHER 14647 14648 rsa 14649 14650 TPM2B_PUBLIC_KEY_RSA 14651 14652 TPM_ALG_RSA 14653 14654 ecc 14655 14656 TPMS_ECC_POINT 14657 14658 TPM_ALG_ECC 14659 14660 12.2.3.3 14661 14662 Description 14663 14664 TPMS_KEYEDHASH_PARMS 14665 14666 This structure describes the parameters that would appear in the public area of a KEYEDHASH object. 14667 Note 14668 14669 Although the names are the same, the types of the structures are not the same as for asymmetric 14670 parameter lists. 14671 14672 Table 178 Definition of TPMS_KEYEDHASH_PARMS Structure 14673 Parameter 14674 14675 Type 14676 14677 Description 14678 14679 scheme 14680 14681 TPMT_KEYEDHASH_SCHEME+ 14682 14683 Indicates the signing method used for a keyedHash signing 14684 object. This field also determines the size of the data field for a 14685 data object created with TPM2_Create(). This field shall not be set 14686 to TPM_ALG_NULL in a template if either sign or encrypt is SET. 14687 14688 12.2.3.4 14689 14690 TPMS_ASYM_PARMS 14691 14692 This structure contains the common public area parameters for an asymmetric key. The first two 14693 parameters of the parameter definition structures of an asymmetric key shall have the same two first 14694 components. 14695 NOTE 14696 14697 The sign parameter may have a different type in order to allow different schemes to be selected for each 14698 asymmetric type but the first parameter of each scheme definition shall be a TPM_ALG_ID for a valid 14699 signing scheme. 14700 14701 Family 2.0 14702 Level 00 Revision 00.99 14703 14704 Published 14705 Copyright TCG 2006-2013 14706 14707 Page 127 14708 October 31, 2013 14709 14710 Part 2: Structures 14712 14713 Trusted Platform Module Library 14714 Table 179 Definition of TPMS_ASYM_PARMS Structure <> 14715 14716 Parameter 14717 14718 Type 14719 14720 Description 14721 14722 symmetric 14723 14724 TPMT_SYM_DEF_OBJECT+ 14725 14726 the companion symmetric algorithm for a restricted 14727 decryption key and shall be set to a supported symmetric 14728 algorithm 14729 This field is optional for keys that are not decryption keys 14730 and shall be set to TPM_ALG_NULL if not used. 14731 14732 scheme 14733 14734 TPMT_ASYM_SCHEME+ 14735 14736 for a key with the sign attribute SET, a valid signing 14737 scheme for the key type 14738 for a key with the decrypt attribute SET, a valid key 14739 exchange protocol 14740 for a key with sign and decrypt attributes, shall be 14741 TPM_ALG_NULL 14742 14743 12.2.3.5 14744 14745 TPMS_RSA_PARMS 14746 14747 A TPM compatible with this specification and supporting RSA shall support numPrimes of two and an 14748 exponent of zero. Support for other values is optional. Use of other exponents in duplicated keys is not 14749 recommended because the resulting keys would not be interoperable with other TPMs. 14750 NOTE 1 14751 14752 Implementations are not required to check that exponent is the default exponent. They may fail to load the 14753 key if exponent is not zero. The reference implementation allows the values listed in the table. 14754 14755 Table 180 Definition of {RSA} TPMS_RSA_PARMS Structure 14756 Parameter 14757 14758 Type 14759 14760 Description 14761 14762 symmetric 14763 14764 TPMT_SYM_DEF_OBJECT+ for a restricted decryption key, shall be set to a 14765 supported symmetric algorithm, key size, and mode. 14766 if the key is not a restricted decryption key, this field 14767 shall be set to TPM_ALG_NULL. 14768 14769 scheme 14770 14771 TPMT_RSA_SCHEME+ 14772 14773 for a signing key, shall be either TPM_ALG_RSAPSS 14774 TPM_ALG_RSASSA or TPM_ALG_NULL 14775 for an unrestricted decryption key, shall be 14776 TPM_ALG_RSAES, 14777 TPM_ALG_OAEP, 14778 or 14779 TPM_ALG_NULL unless the object also has the sign 14780 attribute 14781 for a restricted decryption key, this field shall be 14782 TPM_ALG_NULL 14783 NOTE 14784 14785 keyBits 14786 14787 When both sign and decrypt are SET, restricted 14788 shall be CLEAR and scheme shall be 14789 TPM_ALG_NULL. 14790 14791 TPMI_RSA_KEY_BITS 14792 14793 number of bits in the public modulus 14794 14795 UINT32 14796 14797 the public exponent 14798 A prime number greater than 2. 14799 When zero, indicates that the exponent is the default 14800 16 14801 of 2 + 1 14802 14803 #TPM_RC_KEY_SIZE 14804 exponent 14805 14806 #TPM_RC_VALUE 14807 14808 Page 128 14809 October 31, 2013 14810 14811 Published 14812 Copyright TCG 2006-2013 14813 14814 Family 2.0 14815 Level 00 Revision 00.99 14816 14817 Trusted Platform Module Library 14819 12.2.3.6 14820 14821 Part 2: Structures 14822 14823 TPMS_ECC_PARMS 14824 14825 This structure contains the parameters for prime modulus ECC. 14826 Table 181 Definition of {ECC} TPMS_ECC_PARMS Structure 14827 Parameter 14828 14829 Type 14830 14831 Description 14832 14833 symmetric 14834 14835 TPMT_SYM_DEF_OBJECT+ 14836 14837 for a restricted decryption key, shall be set to a supported 14838 symmetric algorithm, key size. and mode. 14839 if the key is not a restricted decryption key, this field shall be 14840 set to TPM_ALG_NULL. 14841 14842 scheme 14843 14844 TPMT_ECC_SCHEME+ 14845 14846 If the sign attribute of the key is SET, then this shall be a valid 14847 signing scheme. 14848 NOTE 14849 14850 If the sign parameter in curveID indicates a mandatory 14851 scheme, then this field shall have the same value. 14852 14853 If the decrypt attribute of the key is SET, then this shall be a 14854 valid key exchange scheme or TPM_ALG_NULL. 14855 If the key is a Storage Key, then this field shall be 14856 TPM_ALG_NULL. 14857 curveID 14858 14859 TPMI_ECC_CURVE 14860 14861 ECC curve ID 14862 14863 kdf 14864 14865 TPMT_KDF_SCHEME+ 14866 14867 an optional key derivation scheme for generating a symmetric 14868 key from a Z value 14869 If the kdf 14870 parameter associated with curveID is not 14871 TPM_ALG_NULL then this is required to be NULL. 14872 NOTE 14873 14874 12.2.3.7 14875 14876 There are currently no commands where this parameter 14877 has effect and, in the reference code, this field needs to 14878 be set to TPM_ALG_NULL. 14879 14880 TPMU_PUBLIC_PARMS 14881 14882 Table 182 defines the possible parameter definition structures that may be contained in the public portion 14883 of a key. 14884 Table 182 Definition of TPMU_PUBLIC_PARMS Union <IN/OUT, S> 14885 Parameter 14886 14887 Type 14888 14889 (1) 14890 14891 Selector 14892 14893 Description 14894 14895 keyedHashDetail TPMS_KEYEDHASH_PARMS 14896 14897 TPM_ALG_KEYEDHASH 14898 14899 sign | encrypt | neither 14900 14901 symDetail 14902 14903 TPMS_SYMCIPHER_PARMS 14904 14905 TPM_ALG_SYMCIPHER 14906 14907 a symmetric block cipher 14908 14909 rsaDetail 14910 14911 TPMS_RSA_PARMS 14912 14913 TPM_ALG_RSA 14914 14915 decrypt + sign 14916 14917 (2) 14918 14919 eccDetail 14920 14921 TPMS_ECC_PARMS 14922 14923 TPM_ALG_ECC 14924 14925 decrypt + sign 14926 14927 (2) 14928 14929 asymDetail 14930 14931 TPMS_ASYM_PARMS 14932 14933 common scheme structure 14934 for RSA and ECC keys 14935 14936 NOTES 14937 1) 14938 14939 Description column indicates which of TPMA_OBJECT.decrypt or TPMA_OBJECT.sign may be set. 14940 14941 2) 14942 14943 + indicates that both may be set but one shall be set. | indicates the optional settings. 14944 14945 Family 2.0 14946 Level 00 Revision 00.99 14947 14948 Published 14949 Copyright TCG 2006-2013 14950 14951 Page 129 14952 October 31, 2013 14953 14954 Part 2: Structures 14956 12.2.3.8 14957 14958 Trusted Platform Module Library 14959 14960 TPMT_PUBLIC_PARMS 14961 14962 This structure is used in TPM2_TestParms() to validate that a set of algorithm parameters is supported by 14963 the TPM. 14964 Table 183 Definition of TPMT_PUBLIC_PARMS Structure 14965 Parameter 14966 14967 Type 14968 14969 Description 14970 14971 type 14972 14973 TPMI_ALG_PUBLIC 14974 14975 the algorithm to be tested 14976 14977 [type]parameters 14978 14979 TPMU_PUBLIC_PARMS the algorithm details 14980 14981 12.2.4 TPMT_PUBLIC 14982 Table 184 defines the public area structure. The Name of the object is nameAlg concatenated with the 14983 digest of this structure using nameAlg. 14984 Table 184 Definition of TPMT_PUBLIC Structure 14985 Parameter 14986 14987 Type 14988 14989 Description 14990 14991 type 14992 14993 TPMI_ALG_PUBLIC 14994 14995 algorithm associated with this object 14996 14997 nameAlg 14998 14999 +TPMI_ALG_HASH 15000 15001 algorithm used for computing the Name of the object 15002 NOTE 15003 15004 The "+" indicates that the instance of a TPMT_PUBLIC may have 15005 a "+" to indicate that the nameAlg may be TPM_ALG_NULL. 15006 15007 objectAttributes 15008 15009 TPMA_OBJECT 15010 15011 attributes that, along with type, determine the manipulations of this 15012 object 15013 15014 authPolicy 15015 15016 TPM2B_DIGEST 15017 15018 optional policy for using this key 15019 The policy is computed using the nameAlg of the object. 15020 NOTE 15021 15022 Shall be the Empty Buffer if no authorization policy is present. 15023 15024 [type]parameters 15025 15026 TPMU_PUBLIC_PARMS the algorithm or structure details 15027 15028 [type]unique 15029 15030 TPMU_PUBLIC_ID 15031 15032 Page 130 15033 October 31, 2013 15034 15035 the unique identifier of the structure 15036 For an asymmetric key, this would be the public key. 15037 15038 Published 15039 Copyright TCG 2006-2013 15040 15041 Family 2.0 15042 Level 00 Revision 00.99 15043 15044 Trusted Platform Module Library 15046 15047 Part 2: Structures 15048 15049 12.2.5 TPM2B_PUBLIC 15050 This sized buffer is used to embed a TPMT_PUBLIC in a command. 15051 Table 185 Definition of TPM2B_PUBLIC Structure 15052 Parameter 15053 15054 Type 15055 15056 Description 15057 15058 size= 15059 15060 UINT16 15061 15062 size of publicArea 15063 NOTE 15064 15065 publicArea 15066 15067 +TPMT_PUBLIC 15068 15069 The = will force the TPM to try to unmarshal a 15070 TPMT_PUBLIC and check that the unmarshaled size 15071 matches the value of size. If all the required fields of 15072 a TPMT_PUBLIC are not present, the TPM will return 15073 an error (generally TPM_RC_SIZE) when attempting 15074 to unmarshal the TPMT_PUBLIC. 15075 15076 the public area 15077 NOTE 15078 15079 The + indicates that the caller may specify that use 15080 of TPM_ALG_NULL is allowed for nameAlg. 15081 15082 12.3 Private Area Structures 15083 12.3.1 Introduction 15084 The structures in 12.3 define the contents and construction of the private portion of a TPM object. A 15085 TPM2B_PRIVATE along with a TPM2B_PUBLIC are needed to describe a TPM object. 15086 A TPM2B_PRIVATE area may be encrypted by different symmetric algorithms or, in some cases, not 15087 encrypted at all. 15088 12.3.2 Sensitive Data Structures 15089 12.3.2.1 15090 15091 Introduction 15092 15093 The structures in 12.3.2 define the presumptive internal representations of the sensitive areas of the 15094 various entities. A TPM may store the sensitive information in any desired format but when constructing a 15095 TPM_PRIVATE, the formats in this clause shall be used. 15096 12.3.2.2 15097 15098 TPM2B_PRIVATE_VENDOR_SPECIFIC 15099 15100 This structure is defined for coding purposes. For IO to the TPM, the sensitive portion of the key will be in 15101 a canonical form. For an RSA key, this will be one of the prime factors of the public modulus. After 15102 loading, it is typical that other values will be computed so that computations using the private key will not 15103 need to start with just one prime factor. This structure allows the vendor-specific structure to use the 15104 space of the 15105 The value for RSA_VENDOR_SPECIFIC is determined by the vendor. 15106 Table 186 Definition of {RSA} TPM2B_PRIVATE_VENDOR_SPECIFIC Structure<> 15107 Parameter 15108 15109 Type 15110 15111 size 15112 15113 UINT16 15114 15115 buffer[size]{:PRIVATE_VENDOR_SPECIFIC_BYTES} 15116 15117 BYTE 15118 15119 Family 2.0 15120 Level 00 Revision 00.99 15121 15122 Published 15123 Copyright TCG 2006-2013 15124 15125 Description 15126 15127 Page 131 15128 October 31, 2013 15129 15130 Part 2: Structures 15132 12.3.2.3 15133 15134 Trusted Platform Module Library 15135 15136 TPMU_SENSITIVE_COMPOSITE 15137 Table 187 Definition of TPMU_SENSITIVE_COMPOSITE Union <IN/OUT, S> 15138 15139 Parameter 15140 15141 Type 15142 15143 Selector 15144 15145 Description 15146 15147 rsa 15148 15149 TPM2B_PRIVATE_KEY_RSA 15150 15151 TPM_ALG_RSA 15152 15153 a prime factor of the public 15154 key 15155 15156 ecc 15157 15158 TPM2B_ECC_PARAMETER 15159 15160 TPM_ALG_ECC 15161 15162 the integer private key 15163 15164 bits 15165 15166 TPM2B_SENSITIVE_DATA 15167 15168 TPM_ALG_KEYEDHASH 15169 15170 the private data 15171 15172 sym 15173 15174 TPM2B_SYM_KEY 15175 15176 TPM_ALG_SYMCIPHER 15177 15178 the symmetric key 15179 15180 any 15181 15182 TPM2B_PRIVATE_VENDOR_SPECIFIC 15183 15184 12.3.2.4 15185 15186 vendor-specific size for key 15187 storage 15188 15189 TPMT_SENSITIVE 15190 Table 188 Definition of TPMT_SENSITIVE Structure 15191 15192 Parameter 15193 15194 Type 15195 15196 Description 15197 15198 sensitiveType 15199 15200 TPMI_ALG_PUBLIC 15201 15202 identifier for the sensitive area 15203 This shall be the same as the type parameter of the 15204 associated public area. 15205 15206 authValue 15207 15208 TPM2B_AUTH 15209 15210 user authorization data 15211 The authValue may be a zero-length string. 15212 This value shall not be larger than the size of the 15213 digest produced by the nameAlg of the object. 15214 15215 seedValue 15216 15217 TPM2B_DIGEST 15218 15219 for asymmetric key object, the optional protection 15220 seed; for other objects, the obfuscation value 15221 This value shall not be larger than the size of the 15222 digest produced by nameAlg of the object. 15223 15224 [sensitiveType]sensitive 15225 15226 TPMU_SENSITIVE_COMPOSITE 15227 15228 the type-specific private data 15229 15230 12.3.3 TPM2B_SENSITIVE 15231 The TPM2B_SENSITIVE structure is used as a parameter in TPM2_LoadExternal(). It is an unencrypted 15232 sensitive area but it may be encrypted using parameter encryption. 15233 NOTE 15234 15235 When this structure is unmarshaled, the size of the sensitiveType determines what type of value is 15236 unmarshaled. Each value of sensitiveType is associated with a TPM2B. It is the maximum size for each of 15237 the TPM2B values will determine if the unmarshal operation is successful . Since there is no selector for 15238 the any or vendor options for the union, the maximum input and output sizes for a TMP2B_SENSITIVE 15239 are not affected by the sizes of those parameters. 15240 15241 Table 189 Definition of TPM2B_SENSITIVE Structure <IN/OUT> 15242 Parameter 15243 15244 Type 15245 15246 Description 15247 15248 size 15249 15250 UINT16 15251 15252 size of the private structure 15253 15254 sensitiveArea 15255 15256 TPMT_SENSITIVE 15257 15258 an unencrypted sensitive area 15259 15260 Page 132 15261 October 31, 2013 15262 15263 Published 15264 Copyright TCG 2006-2013 15265 15266 Family 2.0 15267 Level 00 Revision 00.99 15268 15269 Trusted Platform Module Library 15271 15272 Part 2: Structures 15273 15274 12.3.4 Encryption 15275 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. 15276 The method of generating the key and IV is described in Protected Storage subclause Symmetric 15277 Encryption. in Part 1. 15278 12.3.5 Integrity 15279 The integrity computation is used to ensure that a protected object is modified when stored in memory 15280 outside of the TPM. 15281 The method of protecting the integrity of the sensitive area is described in Protected Storage subclause 15282 Integrity in Part 1. 15283 12.3.6 _PRIVATE 15284 This structure is defined to size the contents of a TPM2B_PRIVATE. This structure is not directly 15285 marshaled or unmarshaled. 15286 For TPM2_Duplicate() and TPM2_Import(), the TPM2B_PRIVATE may contain multiply encrypted data 15287 and two integrity values. In some cases, the sensitive data is not encrypted and the integrity value is not 15288 present. 15289 For TPM2_Load() and TPM2_Create(), integrityInner is always present. 15290 If integrityInner is present, it and sensitive are encrypted as a single block. 15291 When an integrity value is not needed, it is not present and it is not represented by an Empty Buffer. 15292 Table 190 Definition of _PRIVATE Structure <> 15293 Parameter 15294 15295 Type 15296 15297 Description 15298 15299 integrityOuter 15300 15301 TPM2B_DIGEST 15302 15303 integrityInner 15304 15305 TPM2B_DIGEST 15306 15307 could also be a TPM2B_IV 15308 15309 sensitive 15310 15311 TPMT_SENSITIVE 15312 15313 the sensitive area 15314 15315 12.3.7 TPM2B_PRIVATE 15316 The TPM2B_PRIVATE structure is used as a parameter in multiple commands that create, load, and 15317 modify the sensitive area of an object. 15318 Table 191 Definition of TPM2B_PRIVATE Structure <IN/OUT, S> 15319 Parameter 15320 15321 Type 15322 15323 Description 15324 15325 size 15326 15327 UINT16 15328 15329 size of the private structure 15330 15331 buffer[size] {:sizeof(_PRIVATE)} 15332 15333 BYTE 15334 15335 an encrypted private area 15336 15337 Family 2.0 15338 Level 00 Revision 00.99 15339 15340 Published 15341 Copyright TCG 2006-2013 15342 15343 Page 133 15344 October 31, 2013 15345 15346 Part 2: Structures 15348 15349 Trusted Platform Module Library 15350 15351 12.4 Identity Object 15352 12.4.1 Description 15353 An identity object is used to convey credential protection value (CV) to a TPM that can load the object 15354 associated with the object. The CV is encrypted to a storage key on the target TPM, and if the credential 15355 integrity checks and the proper object is loaded in the TPM, then the TPM will return the CV. 15356 12.4.2 _ID_OBJECT 15357 This structure is used for sizing the TPM2_ID_OBJECT. 15358 Table 192 Definition of _ID_OBJECT Structure <> 15359 Parameter 15360 15361 Type 15362 15363 Description 15364 15365 integrityHMAC 15366 15367 TPM2B_DIGEST 15368 15369 HMAC using the nameAlg of the storage key on the target 15370 TPM 15371 15372 encIdentity 15373 15374 TPM2B_DIGEST 15375 15376 credential protector information returned if name matches the 15377 referenced object 15378 All of the encIdentity is encrypted, including the size field. 15379 NOTE 15380 15381 The TPM is not required to check that the size is not larger 15382 than the digest of the nameAlg. However, if the size is 15383 larger, the ID object may not be usable on a TPM that has 15384 no digest larger than produced by nameAlg. 15385 15386 12.4.3 TPM2B_ID_OBJECT 15387 This structure is an output from TPM2_MakeCredential() and is an input to TPM2_ActivateCredential(). 15388 Table 193 Definition of TPM2B_ID_OBJECT Structure <IN/OUT> 15389 Parameter 15390 15391 Type 15392 15393 Description 15394 15395 size 15396 15397 UINT16 15398 15399 size of the credential structure 15400 15401 credential[size]{:sizeof(_ID_OBJECT)} 15402 15403 BYTE 15404 15405 an encrypted credential area 15406 15407 Page 134 15408 October 31, 2013 15409 15410 Published 15411 Copyright TCG 2006-2013 15412 15413 Family 2.0 15414 Level 00 Revision 00.99 15415 15416 Trusted Platform Module Library 15418 15419 Part 2: Structures 15420 15421 13 NV Storage Structures 15422 13.1 TPM_NV_INDEX 15423 A TPM_NV_INDEX is used to reference a defined location in NV memory. The format of the Index is 15424 changed from TPM 1.2 in order to include the Index in the reserved handle space. Handles in this range 15425 use the digest of the public area of the Index as the Name of the entity in authorization computations 15426 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 15427 available in the reserved handle space, the Index value format is changed as shown in Figure 5. 15428 3 3 2 2 2 2 2 2 2 15429 1 0 9 8 7 6 5 4 3 15430 15431 1 1 15432 6 5 15433 15434 T P U D reserved 15435 15436 0 15437 0 15438 15439 Purview 15440 15441 Index 15442 15443 Figure 4 TPM 1.2 TPM_NV_INDEX 15444 3 15445 1 15446 15447 2 2 15448 4 3 15449 15450 0 15451 0 15452 15453 TPM_HT_NV_INDEX 15454 15455 Index 15456 15457 Figure 5 TPM 2.0 TPM_NV_INDEX 15458 NOTE 15459 15460 This TPM_NV_INDEX format does not retain the Purview field and the D bit is not a part of an Index 15461 handle as in TPM 1.2. The TPMA_NV_PLATFORMCREATE attribute is a property of an Index that 15462 provides functionality similar to the D bit. 15463 15464 A valid Index handle will have an MSO of TPM_HT_NV_INDEX. 15465 NOTE 15466 15467 This structure is not used. It is defined here to indicate how the fields of the handle are assigned. The 15468 exemplary unmarshaling code unmarshals a TPM_HANDLE and validates that it is in the range for a 15469 TPM_NV_INDEX. 15470 15471 Table 194 Definition of (UINT32) TPM_NV_INDEX Bits <> 15472 Bit 15473 15474 Name 15475 15476 Definition 15477 15478 23:0 15479 15480 index 15481 15482 The index of the NV location 15483 15484 31:24 15485 15486 RH_NV 15487 15488 constant value of TPM_HT_NV_INDEX indicating the NV Index range 15489 15490 #TPM_RC_VALUE 15491 15492 response code returned if unmarshaling of this type fails because the handle 15493 value is incorrect 15494 15495 Family 2.0 15496 Level 00 Revision 00.99 15497 15498 Published 15499 Copyright TCG 2006-2013 15500 15501 Page 135 15502 October 31, 2013 15503 15504 Part 2: Structures 15506 15507 Trusted Platform Module Library 15508 Table 195 Options for space Field of TPM_NV_INDEX 15509 15510 Some prior versions of this specification contained a table here that assigned subsets of the index field to 15511 different entities. Since this assignment was a convention and not an architectural element of the TPM, 15512 the table was removed and the information is now contained in a registry document that is maintained by 15513 the TCG. 15514 13.2 TPMA_NV (NV Index Attributes) 15515 This structure allows the TPM to keep track of the data and permissions to manipulate an NV Index. 15516 The platform controls (TPMA_NV_PPWRITE and TPMA_NV_PPREAD) and owner controls 15517 (TPMA_NV_OWNERWRITE and TPMA_NV_OWNERREAD) give the platform and owner access to NV 15518 Indexes using platformAuth or ownerAuth rather than the authValue or authPolicy of the Index. 15519 If access to an NV Index is to be restricted based on PCR, then an appropriate authPolicy shall be 15520 provided. 15521 NOTE 15522 15523 platformAuth or ownerAuth can be provided in any type of authorization session or as a password. 15524 15525 If TPMA_NV_AUTHREAD is SET, then the Index may be read if the Index authValue is provided. If 15526 TPMA_NV_POLICYREAD is SET, then the Index may be read if the Index authPolicy is satisfied. 15527 At least one of TPMA_NV_PPREAD, 15528 TPMA_NV_POLICYREAD shall be SET. 15529 15530 TPMA_NV_OWNERREAD, 15531 15532 TPMA_NV_AUTHREAD, 15533 15534 or 15535 15536 If TPMA_NV_AUTHWRITE is SET, then the Index may be written if the Index authValue is provided. If 15537 TPMA_NV_POLICYWRITE is SET, then the Index may be written if the Index authPolicy is satisfied. 15538 At least one of TPMA_NV_PPWRITE, TPMA_NV_OWNERWRITE TPMA_NV_AUTHWRITE, or 15539 TPMA_NV_POLICYWRITE shall be SET. 15540 If TPMA_NV_WRITELOCKED is SET, then the Index may not be written. If TPMA_NV_WRITEDEFINE is 15541 SET, TPMA_NV_WRITELOCKED may not be CLEAR except by deleting and redefining the Index. If 15542 TPMA_NV_WRITEDEFINE is CLEAR, then TPMA_NV_WRITELOCK will be CLEAR on the next 15543 TPM2_Startup(TPM_SU_CLEAR). 15544 If TPMA_NV_READLOCKED is SET, then the Index may not be read. TPMA_NV_READLOCK will be 15545 CLEAR on the next TPM2_Startup(TPM_SU_CLEAR). 15546 NOTE 15547 15548 The TPM is expected to maintain indicators to indicate that the Index is temporarily locked. The state of 15549 these indicators is reported in the TPMA_NV_READLOCKED and TPMA_NV_WRITELOCKED attributes. 15550 15551 If TPMA_NV_EXTEND is SET, then writes to the Index will cause an update of the Index using the extend 15552 operation with the nameAlg used to create the digest. 15553 Only one of TPMA_NV_EXTEND, TPMA_NV_COUNTER, or TPMA_NV_BITS may be set. 15554 When 15555 the 15556 Index 15557 is 15558 created 15559 (TPM2_NV_DefineSpace()), 15560 TPMA_NV_WRITELOCKED, 15561 TPMA_NV_READLOCKED, TPMA_NV_WRITTEN shall all be CLEAR in the parameter that defines the 15562 attributes of the created Index. 15563 15564 Page 136 15565 October 31, 2013 15566 15567 Published 15568 Copyright TCG 2006-2013 15569 15570 Family 2.0 15571 Level 00 Revision 00.99 15572 15573 Trusted Platform Module Library 15575 15576 Part 2: Structures 15577 15578 Table 196 Definition of (UINT32) TPMA_NV Bits 15579 Bit 15580 15581 Name 15582 15583 Description 15584 15585 0 15586 15587 TPMA_NV_PPWRITE 15588 15589 SET (1): The Index data can be written if platformAuth is provided. 15590 CLEAR (0): Writing of the Index data cannot be authorized with 15591 platformAuth. 15592 15593 1 15594 15595 TPMA_NV_OWNERWRITE 15596 15597 SET (1): The Index data can be written if ownerAuth is provided. 15598 CLEAR (0): Writing of the Index data cannot be authorized with 15599 ownerAuth. 15600 15601 2 15602 15603 TPMA_NV_AUTHWRITE 15604 15605 SET (1): Authorizations to change the Index contents that require 15606 USER role may be provided with an HMAC session or password. 15607 CLEAR (0): Authorizations to change the Index contents that require 15608 USER role may not be provided with an HMAC session or password. 15609 15610 3 15611 15612 TPMA_NV_POLICYWRITE 15613 15614 SET (1): Authorizations to change the Index contents that require 15615 USER role may be provided with a policy session. 15616 CLEAR (0): Authorizations to change the Index contents that require 15617 USER role may not be provided with a policy session. 15618 NOTE 15619 15620 TPM2_NV_ChangeAuth() always requires that authorization be 15621 provided in a policy session. 15622 15623 4 15624 15625 TPMA_NV_COUNTER 15626 15627 SET (1): Index contains an 8-octet value that is to be used as a 15628 counter and can only be modified with TPM2_NV_Increment(). 15629 CLEAR (0): The Index is not a counter. 15630 15631 5 15632 15633 TPMA_NV_BITS 15634 15635 SET (1): Index contains an 8-octet value to be used as a bit field and 15636 can only be modified with TPM2_NV_SetBits(). 15637 CLEAR (0): The Index is not a bit field. 15638 15639 6 15640 15641 TPMA_NV_EXTEND 15642 15643 SET (1): Index contains a digest-sized value used like a PCR. The 15644 Index may only be modified using TPM2_NV_Extend. The extend will 15645 use the nameAlg of the Index. 15646 CLEAR (0): Index is not a PCR. 15647 15648 9:7 15649 15650 Reserved 15651 15652 shall be zero 15653 reserved for use in defining additional write controls 15654 15655 10 15656 15657 TPMA_NV_POLICY_DELETE 15658 15659 SET (1): Index may not be deleted unless the authPolicy is satisfied. 15660 CLEAR (0): Index may be deleted with proper platform or owner 15661 authorization. 15662 15663 11 15664 15665 TPMA_NV_WRITELOCKED 15666 15667 SET (1): Index cannot be written. 15668 CLEAR (0): Index can be written. 15669 15670 12 15671 15672 TPMA_NV_WRITEALL 15673 15674 SET (1): A partial write of the Index data is not allowed. The write 15675 size shall match the defined space size. 15676 CLEAR (0): Partial writes are allowed. This setting is required if 15677 TPMA_NV_BITS is SET. 15678 15679 13 15680 15681 TPMA_NV_WRITEDEFINE 15682 15683 SET (1): TPM2_NV_WriteLock() may be used to prevent further 15684 writes to this location. 15685 CLEAR (0): TPM2_NV_WriteLock() does not block subsequent 15686 writes. 15687 15688 14 15689 15690 TPMA_NV_WRITE_STCLEAR 15691 15692 SET (1): TPM2_NV_WriteLock() may be used to prevent further 15693 writes to this location until the next TPM Reset or TPM Restart. 15694 CLEAR (0): A write to this Index with a data size of zero does not 15695 change the write access. 15696 15697 Family 2.0 15698 Level 00 Revision 00.99 15699 15700 Published 15701 Copyright TCG 2006-2013 15702 15703 Page 137 15704 October 31, 2013 15705 15706 Part 2: Structures 15708 15709 Trusted Platform Module Library 15710 15711 Bit 15712 15713 Name 15714 15715 Description 15716 15717 15 15718 15719 TPMA_NV_GLOBALLOCK 15720 15721 SET (1): If TPM2_NV_GlobalWriteLock() is successful, then further 15722 writes to this location are not permitted until the next TPM Reset or 15723 TPM Restart. 15724 CLEAR (0): TPM2_NV_GlobalWriteLock() has no effect on the 15725 writing of the data at this Index. 15726 15727 16 15728 15729 TPMA_NV_PPREAD 15730 15731 SET (1): The Index data can be read if platformAuth is provided. 15732 CLEAR (0): Reading of the Index data cannot be authorized with 15733 platformAuth. 15734 15735 17 15736 15737 TPMA_NV_OWNERREAD 15738 15739 SET (1): The Index data can be read if ownerAuth is provided. 15740 CLEAR (0): Reading of the Index data cannot be authorized with 15741 ownerAuth. 15742 15743 18 15744 15745 TPMA_NV_AUTHREAD 15746 15747 SET (1): The Index data may be read if the authValue is provided. 15748 CLEAR (0): Reading of the Index data cannot be authorized with the 15749 Index authValue. 15750 15751 19 15752 15753 TPMA_NV_POLICYREAD 15754 15755 SET (1): The Index data may be read if the authPolicy is satisfied. 15756 CLEAR (0): Reading of the Index data cannot be authorized with the 15757 Index authPolicy. 15758 15759 Reserved 15760 15761 shall be zero 15762 reserved for use in defining additional read controls 15763 15764 25 15765 15766 TPMA_NV_NO_DA 15767 15768 SET (1): Authorization failures of the Index do not affect the DA logic 15769 and authorization of the Index is not blocked when the TPM is in 15770 Lockout mode. 15771 CLEAR (0): Authorization failures of the Index will increment the 15772 authorization failure counter and authorizations of this Index are not 15773 allowed when the TPM is in Lockout mode. 15774 15775 26 15776 15777 TPMA_NV_ORDERLY 15778 15779 SET (1): NV Index state is only required to be saved when the TPM 15780 performs an orderly shutdown (TPM2_Shutdown()). Only an Index 15781 with TPMA_NV_COUNTER SET may have this setting. 15782 CLEAR (0): NV Index state is required to be persistent after the 15783 command to update the Index completes successfully (that is, the NV 15784 update is synchronous with the update command). 15785 15786 27 15787 15788 TPMA_NV_CLEAR_STCLEAR 15789 15790 SET (1): TPMA_NV_WRITTEN for the Index is CLEAR by TPM 15791 Reset or TPM Restart. 15792 CLEAR (0): TPMA_NV_WRITTEN is not changed by TPM Restart. 15793 15794 24:20 15795 15796 NOTE 15797 15798 This attribute may only be SET if TPMA_NV_COUNTER is not 15799 SET. 15800 15801 NOTE 15802 15803 If the TPMA_NV_ORDERLY is SET, TPMA_NV_WRITTEN will 15804 be CLEAR by TPM Reset. 15805 15806 28 15807 15808 TPMA_NV_READLOCKED 15809 15810 SET (1): Reads of the Index are blocked until the next TPM Reset or 15811 TPM Restart. 15812 CLEAR (0): Reads of the Index are allowed if proper authorization is 15813 provided. 15814 15815 29 15816 15817 TPMA_NV_WRITTEN 15818 15819 SET (1): Index has been written. 15820 CLEAR (0): Index has not been written. 15821 15822 30 15823 15824 TPMA_NV_PLATFORMCREATE 15825 15826 SET (1): This Index may be undefined with platformAuth but not with 15827 ownerAuth. 15828 CLEAR (0): This Index may be undefined using ownerAuth but not 15829 with platformAuth. 15830 The TPM will validate that this attribute is SET when the Index is 15831 defined using platformAuth and will validate that this attribute is 15832 CLEAR when the Index is defined using ownerAuth. 15833 15834 Page 138 15835 October 31, 2013 15836 15837 Published 15838 Copyright TCG 2006-2013 15839 15840 Family 2.0 15841 Level 00 Revision 00.99 15842 15843 Trusted Platform Module Library 15845 15846 Part 2: Structures 15847 15848 Bit 15849 15850 Name 15851 15852 Description 15853 15854 31 15855 15856 TPMA_NV_READ_STCLEAR 15857 15858 SET (1): TPM2_NV_ReadLock() may be used to SET 15859 TPMA_NV_READLOCKED for this Index. 15860 CLEAR (0): TPM2_NV_ReadLock() has no effect on this Index. 15861 15862 13.3 TPMS_NV_PUBLIC 15863 This structure describes an NV Index. 15864 Table 197 Definition of TPMS_NV_PUBLIC Structure 15865 Name 15866 15867 Type 15868 15869 Description 15870 15871 nvIndex 15872 15873 TPMI_RH_NV_INDEX 15874 15875 the handle of the data area 15876 15877 nameAlg 15878 15879 TPMI_ALG_HASH 15880 15881 hash algorithm used to compute the name of the 15882 Index and used for the authPolicy 15883 15884 attributes 15885 15886 TPMA_NV 15887 15888 the Index attributes 15889 15890 authPolicy 15891 15892 TPM2B_DIGEST 15893 15894 the access policy for the Index 15895 15896 dataSize{:MAX_NV_INDEX_SIZE} 15897 15898 UINT16 15899 15900 the size of the data area 15901 The 15902 maximum 15903 size is implementationdependent. The minimum maximum size is 15904 platform-specific. 15905 15906 #TPM_RC_SIZE 15907 15908 response code returned when the requested size 15909 is too large for the implementation 15910 15911 13.4 TPM2B_NV_PUBLIC 15912 This structure is used when a TPMS_NV_PUBLIC is sent on the TPM interface. 15913 Table 198 Definition of TPM2B_NV_PUBLIC Structure 15914 Name 15915 15916 Type 15917 15918 Description 15919 15920 size= 15921 15922 UINT16 15923 15924 size of nvPublic 15925 15926 nvPublic 15927 15928 TPMS_NV_PUBLIC 15929 15930 the public area 15931 15932 Family 2.0 15933 Level 00 Revision 00.99 15934 15935 Published 15936 Copyright TCG 2006-2013 15937 15938 Page 139 15939 October 31, 2013 15940 15941 Part 2: Structures 15943 15944 Trusted Platform Module Library 15945 15946 14 Context Data 15947 14.1 Introduction 15948 This clause defines the contents of the 15949 TPM2_ContextLoad() command parameters. 15950 15951 TPM2_ContextSave() 15952 15953 response 15954 15955 parameters 15956 15957 and 15958 15959 If the parameters provided by the caller in TPM2_ContextLoad() do not match the values returned by the 15960 TPM when the context was saved, the integrity check of the TPM2B_CONTEXT will fail and the object or 15961 session will not be loaded. 15962 14.2 TPM2B_CONTEXT_SENSITIVE 15963 This structure holds the object or session context data. When saved, the full structure is encrypted. 15964 Table 199 Definition of TPM2B_CONTEXT_SENSITIVE Structure <IN/OUT> 15965 Parameter 15966 15967 Type 15968 15969 size 15970 15971 Description 15972 15973 UINT16 15974 15975 buffer[size]{:MAX_CONTEXT_SIZE} BYTE 15976 15977 the sensitive data 15978 15979 14.3 TPMS_CONTEXT_DATA 15980 This structure holds the integrity value and the encrypted data for a context. 15981 Table 200 Definition of TPMS_CONTEXT_DATA Structure <IN/OUT, S> 15982 Parameter 15983 15984 Type 15985 15986 Description 15987 15988 integrity 15989 15990 TPM2B_DIGEST 15991 15992 the integrity value 15993 15994 encrypted 15995 15996 TPM2B_CONTEXT_SENSITIVE 15997 15998 the sensitive area 15999 16000 14.4 TPM2B_CONTEXT_DATA 16001 This structure is used in a TPMS_CONTEXT. 16002 Table 201 Definition of TPM2B_CONTEXT_DATA Structure <IN/OUT> 16003 Parameter 16004 16005 Type 16006 16007 size 16008 16009 Description 16010 16011 UINT16 16012 16013 buffer[size] {:sizeof(TPMS_CONTEXT_DATA)} BYTE 16014 16015 Page 140 16016 October 31, 2013 16017 16018 Published 16019 Copyright TCG 2006-2013 16020 16021 Family 2.0 16022 Level 00 Revision 00.99 16023 16024 Trusted Platform Module Library 16026 16027 Part 2: Structures 16028 16029 14.5 TPMS_CONTEXT 16030 This structure is used in TPM2_ContextLoad() and TPM2_ContextSave(). If the values of the 16031 TPMS_CONTEXT structure in TPM2_ContextLoad() are not the same as the values when the context 16032 was saved (TPM2_ContextSave()), then the TPM shall not load the context. 16033 Saved object contexts shall not be loaded as long as the associated hierarchy is disabled. 16034 Saved object contexts are invalidated when the Primary Seed of their hierarchy changes. Objects in the 16035 Endorsement hierarchy are invalidated when either the EPS or SPS is changed. 16036 When an object has the stClear attribute, it shall not be possible to reload the context or any descendant 16037 object after a TPM Reset or TPM Restart. 16038 NOTE 1 16039 16040 The reference implementation prevents reloads after TPM Restart by including the curre nt value of a 16041 clearCount in the saved object context. When an object is loaded, this value is compared with the current 16042 value of the clearCount if the object has the stClear attribute. If the values are not the same, then the 16043 object cannot be loaded. 16044 16045 A sequence value is contained within the integrity-protected part of the saved context. The sequence 16046 value is repeated in the sequence parameter of the TPMS_CONTEXT of the context. The sequence 16047 parameter, along with other values, is used in the generation the protection values of the context. 16048 If the integrity value of the context is valid, but the sequence value of the decrypted context does not 16049 match the value in the sequence parameter, then TPM shall enter the failure mode because this is 16050 indicative of a specific type of attack on the context values. 16051 NOTE 2 16052 16053 If the integrity value is correct, but the decryption fails and produces the wrong value for sequence, this 16054 implies that either the TPM is faulty or an external entity is able to forge an integrity val ue for the context 16055 but they have insufficient information to know what the encryption key of the context. Since the TPM 16056 generated the valid context, then there is no reason for the sequence value in the context to be decrypted 16057 incorrectly other than the TPM is faulty or the TPM is under attack. In either case, it is appropriate for the 16058 TPM to enter failure more. 16059 16060 Table 202 Definition of TPMS_CONTEXT Structure 16061 Name 16062 16063 Type 16064 16065 Description 16066 16067 sequence 16068 16069 UINT64 16070 16071 the sequence number of the context 16072 NOTE 16073 16074 Transient object contexts and 16075 contexts used different counters. 16076 16077 session 16078 16079 savedHandle 16080 16081 TPMI_DH_CONTEXT 16082 16083 the handle of the session, object or sequence 16084 16085 hierarchy 16086 16087 TPMI_RH_HIERARCHY+ 16088 16089 the hierarchy of the context 16090 16091 contextBlob 16092 16093 TPM2B_CONTEXT_DATA 16094 16095 the context data and integrity HMAC 16096 16097 Family 2.0 16098 Level 00 Revision 00.99 16099 16100 Published 16101 Copyright TCG 2006-2013 16102 16103 Page 141 16104 October 31, 2013 16105 16106 Part 2: Structures 16108 16109 Trusted Platform Module Library 16110 16111 14.6 Parameters of TPMS_CONTEXT 16112 14.6.1 sequence 16113 The sequence parameter is used to differentiate the contexts and to allow the TPM to create a different 16114 encryption key for each context. Objects and sessions use different sequence counters. The sequence 16115 counter for objects (transient and sequence) is incremented when an object context is saved, and the 16116 sequence counter for sessions increments when a session is created or when it is loaded 16117 (TPM2_ContextLoad()). The session sequence number is the contextID counter. 16118 For a session, the sequence number also allows the TRM to find the older contexts so that they may be 16119 refreshed if the contextID are too widely separated. 16120 If an input value for sequence is larger than the value used in any saved context, the TPM shall return an 16121 error (TPM_RC_VALUE) and do no additional processing of the context. 16122 If the context is a session context and the input value for sequence is less than the current value of 16123 contextID minus the maximum range for sessions, the TPM shall return an error (TPM_RC_VALUE) and 16124 do no additional processing of the context. 16125 14.6.2 savedHandle 16126 For a session, this is the handle that was assigned to the session when it was saved. For a transient 16127 object, the handle will have one of the values shown in Table 203. 16128 If the handle type for savedHandle is TPM_HT_TRANSIENT, then the low order bits are used to 16129 differentiate static objects from sequence objects. 16130 If an input value for handle is outside of the range of values used by the TPM, the TPM shall return an 16131 error (TPM_RC_VALUE) and do no additional processing of the context. 16132 Table 203 Context Handle Values 16133 Value 16134 16135 Description 16136 16137 0x02xxxxxx 16138 16139 an HMAC session context 16140 16141 0x03xxxxxx 16142 16143 a policy session context 16144 16145 0x80000000 16146 16147 an ordinary transient object 16148 16149 0x80000001 16150 16151 a sequence object 16152 16153 0x80000002 16154 16155 a transient object with the stClear attribute SET 16156 16157 Page 142 16158 October 31, 2013 16159 16160 Published 16161 Copyright TCG 2006-2013 16162 16163 Family 2.0 16164 Level 00 Revision 00.99 16165 16166 Trusted Platform Module Library 16168 16169 Part 2: Structures 16170 16171 14.6.3 hierarchy 16172 This is the hierarchy (TPMI_RH_HIERARCHY) for the saved context and determines the proof value used 16173 in the construction of the encryption and integrity values for the context. For session and sequence 16174 contexts, the hierarchy is TPM_RC_NULL. The hierarchy for a transient object may be TPM_RH_NULL 16175 but it is not required. 16176 14.7 Context Protection 16177 14.7.1 Context Integrity 16178 The integrity of the context blob is protected by an HMAC. The integrity value is constructed such that 16179 changes to the component values will invalidate the context and prevent it from being loaded. 16180 Previously saved contexts for objects in the Platform hierarchy shall not be loadable after the PPS is 16181 changed. 16182 Previously saved contexts for objects in the Storage hierarchy shall not be loadable after the SPS is 16183 changed. 16184 Previously saved contexts for objects in the Endorsement hierarchy shall not be loadable after either the 16185 EPS or SPS is changed. 16186 Previously saved sessions shall not be loadable after the SPS changes. 16187 Previously saved contexts for objects that have their stClear attribute SET shall not be loadable after a 16188 TPM Restart. If a Storage Key has its stClear attribute SET, the descendants of this key shall not be 16189 loadable after TPM Restart. 16190 Previously saved contexts for a session and objects shall not be loadable after a TPM Reset. 16191 A saved context shall not be loaded if its HMAC is not valid. The equation for computing the HMAC for a 16192 context is found in Context Integrity Protection in Part 1. 16193 14.7.2 Context Confidentiality 16194 The context data of sessions and objects shall be protected by symmetric encryption using CFB. The 16195 method for computing the IV and encryption key is found in Context Confidentiality Protection in Part 1. 16196 16197 Family 2.0 16198 Level 00 Revision 00.99 16199 16200 Published 16201 Copyright TCG 2006-2013 16202 16203 Page 143 16204 October 31, 2013 16205 16206 Part 2: Structures 16208 16209 Trusted Platform Module Library 16210 16211 15 Creation Data 16212 15.1 TPMS_CREATION_DATA 16213 This structure provides information relating to the creation environment for the object. The creation data 16214 includes the parent Name, parent Qualified Name, and the digest of selected PCR. These values 16215 represent the environment in which the object was created. Creation data allows a relying party to 16216 determine if an object was created when some appropriate protections were present. 16217 When the object is created, the structure shown in Table 204 is generated and a ticket is computed over 16218 this data. 16219 If 16220 the 16221 parent 16222 is 16223 a 16224 permanent 16225 handle 16226 (TPM_RH_OWNER, 16227 TPM_RH_PLATFORM, 16228 TPM_RH_ENDORSEMENT, or TPM_RH_NULL), then parentName and parentQualifiedName will be set 16229 to the parent handle value and parentNameAlg will be TPM_ALG_NULL. 16230 Table 204 Definition of TPMS_CREATION_DATA Structure <OUT> 16231 Parameter 16232 16233 Type 16234 16235 Description 16236 16237 pcrSelect 16238 16239 TPML_PCR_SELECTION 16240 16241 list indicating the PCR included in pcrDigest 16242 16243 pcrDigest 16244 16245 TPM2B_DIGEST 16246 16247 digest of the selected PCR using nameAlg of the object for 16248 which this structure is being created 16249 pcrDigest.size shall be zero if the pcrSelect list is empty. 16250 16251 locality 16252 16253 TPMA_LOCALITY 16254 16255 the locality at which the object was created 16256 16257 parentNameAlg 16258 16259 TPM_ALG_ID 16260 16261 nameAlg of the parent 16262 16263 parentName 16264 16265 TPM2B_NAME 16266 16267 Name of the parent at time of creation 16268 The size will match digest size associated with parentNameAlg 16269 unless it is TPM_ALG_NULL, in which case the size will be 4 16270 and parentName will be the hierarchy handle. 16271 16272 parentQualifiedName 16273 16274 TPM2B_NAME 16275 16276 Qualified Name of the parent at the time of creation 16277 Size is the same as parentName. 16278 16279 outsideInfo 16280 16281 TPM2B_DATA 16282 16283 association with additional information added by the key 16284 creator 16285 This will be the contents of the outsideInfo parameter in 16286 TPM2_Create() or TPM2_CreatePrimary(). 16287 16288 15.2 TPM2B_CREATION_DATA 16289 This structure is created by TPM2_Create() and TPM2_CreatePrimary(). It is never entered into the TPM 16290 and never has a size of zero. 16291 Table 205 Definition of TPM2B_CREATION_DATA Structure <OUT> 16292 Parameter 16293 16294 Type 16295 16296 Description 16297 16298 size= 16299 16300 UINT16 16301 16302 size of the creation data 16303 16304 creationData 16305 16306 TPMS_CREATION_DATA 16307 16308 Page 144 16309 October 31, 2013 16310 16311 Published 16312 Copyright TCG 2006-2013 16313 16314 Family 2.0 16315 Level 00 Revision 00.99 16316 16317 Trusted Platform Module Library 16319 16320 Part 2: Structures 16321 16322 Annex A 16323 (informative) 16324 Algorithm Constants 16325 A.1 16326 16327 Introduction 16328 16329 This annex contains constants that are defined by algorithms. 16330 16331 A.2 16332 A.2.1 16333 16334 Allowed Hash Algorithms 16335 SHA1 16336 Table 206 Defines for SHA1 Hash Values 16337 16338 Name 16339 16340 Value 16341 16342 SHA1_DIGEST_SIZE 16343 16344 20 16345 16346 SHA1_BLOCK_SIZE 16347 16348 64 16349 16350 SHA1_DER_SIZE 16351 16352 Description 16353 16354 15 16355 16356 SHA1_DER 16357 16358 A.2.2 16359 16360 Values are in octets. 16361 16362 {0x30,0x21,0x30,0x09,0x06,0x05,0x2B,0x0E, 16363 0x03,0x02,0x1A,0x05,0x00,0x04,0x14} 16364 16365 SHA256 16366 Table 207 Defines for SHA256 Hash Values 16367 16368 Name 16369 16370 Value 16371 16372 SHA256_DIGEST_SIZE 16373 16374 32 16375 16376 SHA256_BLOCK_SIZE 16377 16378 64 16379 16380 SHA256_DER_SIZE 16381 16382 Description 16383 16384 19 16385 16386 SHA256_DER 16387 16388 A.2.3 16389 16390 Values are in octets. 16391 16392 {0x30,0x31,0x30,0x0d,0x06,0x09,0x60,0x86, 16393 0x48,0x01,0x65,0x03,0x04,0x02,0x01,0x05, 16394 0x00,0x04,0x20} 16395 16396 SHA384 16397 Table 208 Defines for SHA384 Hash Values 16398 16399 Name 16400 16401 Value 16402 16403 SHA384_DIGEST_SIZE 16404 16405 48 16406 16407 SHA384_BLOCK_SIZE 16408 16409 128 16410 16411 SHA384_DER_SIZE 16412 16413 Description 16414 16415 19 16416 16417 SHA384_DER 16418 16419 Family 2.0 16420 Level 00 Revision 00.99 16421 16422 Values are in octets. 16423 16424 {0x30,0x41,0x30,0x0d,0x06,0x09,0x60,0x86, 16425 0x48,0x01,0x65,0x03,0x04,0x02,0x02,0x05, 16426 0x00,0x04,0x30} 16427 16428 Published 16429 Copyright TCG 2006-2013 16430 16431 Page 145 16432 October 31, 2013 16433 16434 Part 2: Structures 16436 A.2.4 16437 16438 Trusted Platform Module Library 16439 16440 SHA512 16441 Table 209 Defines for SHA512 Hash Values 16442 16443 Name 16444 16445 Value 16446 16447 SHA512_DIGEST_SIZE 16448 16449 64 16450 16451 SHA512_BLOCK_SIZE 16452 16453 128 16454 16455 SHA512_DER_SIZE 16456 16457 Description 16458 16459 19 16460 16461 SHA512_DER 16462 16463 A.2.5 16464 16465 Values are in octets. 16466 16467 {0x30,0x51,0x30,0x0d,0x06,0x09,0x60,0x86, 16468 0x48,0x01,0x65,0x03,0x04,0x02,0x03,0x05, 16469 0x00,0x04,0x40} 16470 16471 SM3_256 16472 Table 210 Defines for SM3_256 Hash Values 16473 16474 Name 16475 16476 Value 16477 16478 Description 16479 16480 SM3_256_DIGEST_SIZE 16481 16482 32 16483 16484 Values are in octets. 16485 16486 SM3_256_BLOCK_SIZE 16487 16488 64 16489 16490 ?? 16491 16492 SM3_256_DER_SIZE 16493 16494 18 16495 16496 SM3_256_DER 16497 16498 A.3 16499 16500 {0x30,0x30,0x30,0x0c,0x06,0x08,0x2a,0x81, 16501 0x1c,0x81,0x45,0x01,0x83,0x11,0x05,0x00, 16502 0x04,0x20} 16503 16504 Unknown 16505 16506 Architectural Limits 16507 Table 211 Defines for Architectural Limits Values 16508 16509 Name 16510 MAX_SESSION_NUMBER 16511 16512 Page 146 16513 October 31, 2013 16514 16515 Value 16516 3 16517 16518 Description 16519 the maximum number of authorization sessions that may be in a 16520 command 16521 This value may be increased if new commands require more than 16522 two authorization handles. 16523 16524 Published 16525 Copyright TCG 2006-2013 16526 16527 Family 2.0 16528 Level 00 Revision 00.99 16529 16530 Trusted Platform Module Library 16532 16533 Part 2: Structures 16534 16535 Annex B 16536 (informative) 16537 Implementation Definitions 16538 B.1 16539 16540 Introduction 16541 16542 This annex contains some of the tables that are used to define the desired implementation for the 16543 automated tools. 16544 NOTE 16545 16546 B.2 16547 16548 The reference implementation assumes that stdint.h is used. 16549 16550 Logic Values 16551 16552 The values in this clause are used to see the generation of the subsequent tables. These values should 16553 not be changed. 16554 Table 212 Defines for Logic Values 16555 Name 16556 16557 Value 16558 16559 YES 16560 16561 1 16562 16563 NO 16564 16565 0 16566 16567 TRUE 16568 16569 1 16570 16571 FALSE 16572 16573 0 16574 16575 SET 16576 16577 1 16578 16579 CLEAR 16580 16581 Description 16582 16583 0 16584 16585 B.3 16586 16587 Processor Values 16588 16589 These values are used to control generation of octet-swapping routines. The canonical octet ordering for 16590 the TPM input/output buffer is big endian with the most significant octet of any datum at the lowest 16591 address. 16592 NOTE 16593 16594 The setting for the exemplar is for the x86 family of processor. 16595 16596 Table 213 Defines for Processor Values 16597 Name 16598 16599 Value 16600 16601 Description 16602 16603 BIG_ENDIAN_TPM 16604 16605 NO 16606 16607 set to YES or NO according to the processor 16608 16609 LITTLE_ENDIAN_TPM 16610 16611 YES 16612 16613 set to YES or NO according to the processor 16614 NOTE 16615 16616 NO_AUTO_ALIGN 16617 16618 NO 16619 16620 set to YES if the processor does not allow unaligned accesses 16621 NOTE 16622 16623 Family 2.0 16624 Level 00 Revision 00.99 16625 16626 BIG_ENDIAN and LITTLE_ENDIAN shall be set to opposite values. 16627 16628 If LITTLE_ENDIAN is YES, then the setting of this value has no effect. 16629 16630 Published 16631 Copyright TCG 2006-2013 16632 16633 Page 147 16634 October 31, 2013 16635 16636 Part 2: Structures 16638 16639 B.4 16640 16641 Trusted Platform Module Library 16642 16643 Implemented Algorithms 16644 16645 Table 214 is used to indicate the algorithms that are implemented in a TPM. The selections in the Value 16646 column may be changed to reflect the implementation. The values shown are illustrative. 16647 The "Implemented" column contains a "Y", "YES", or blank to indicate that the command is present in the 16648 implementation, an "N" or "NO" to indicate that the command is not implemented. 16649 The leading and trailing _ characters are to avoid name space collisions with some crypto libraries. 16650 16651 NOTE 16652 16653 Table 214 Defines for Implemented Algorithms 16654 Algorithm Name 16655 16656 Implemented 16657 16658 RSA 16659 16660 YES 16661 16662 SHA1 16663 16664 YES 16665 16666 HMAC 16667 16668 YES 16669 16670 AES 16671 16672 YES 16673 16674 MGF1 16675 16676 YES 16677 16678 XOR 16679 16680 YES 16681 16682 KEYEDHASH 16683 16684 YES 16685 16686 SHA256 16687 16688 YES 16689 16690 SHA384 16691 16692 NO 16693 16694 SHA512 16695 16696 NO 16697 16698 SM3_256 16699 16700 YES 16701 16702 SM4 16703 16704 Comments 16705 16706 YES 16707 16708 REQUIRED, do not change this value 16709 16710 REQUIRED, do not change this value 16711 16712 RSASSA 16713 16714 (YES * RSA) 16715 16716 requires RSA 16717 16718 RSAES 16719 16720 (YES * RSA) 16721 16722 requires RSA 16723 16724 RSAPSS 16725 16726 (YES * RSA) 16727 16728 requires RSA 16729 16730 OAEP 16731 16732 (YES * RSA) 16733 16734 requires RSA 16735 16736 ECC 16737 16738 YES 16739 16740 ECDH 16741 16742 (YES * ECC) 16743 16744 requires ECC 16745 16746 ECDSA 16747 16748 (YES * ECC) 16749 16750 requires ECC 16751 16752 ECDAA 16753 16754 (YES * ECC) 16755 16756 requires ECC 16757 16758 SM2 16759 16760 (YES * ECC) 16761 16762 requires ECC 16763 16764 ECSCHNORR 16765 16766 (YES * ECC) 16767 16768 requires ECC 16769 16770 ECMQV 16771 16772 (NO * ECC) 16773 16774 requires ECC 16775 16776 SYMCIPHER 16777 KDF1_SP800_56a 16778 16779 YES 16780 16781 REQUIRED, at least one symmetric algorithm shall be implemented 16782 16783 (YES * ECC) 16784 16785 KDF2 16786 16787 NO 16788 16789 KDF1_SP800_108 16790 16791 YES 16792 16793 CTR 16794 16795 YES 16796 16797 OFB 16798 16799 YES 16800 16801 CBC 16802 16803 YES 16804 16805 CFB 16806 16807 YES 16808 16809 ECB 16810 16811 requires ECC 16812 16813 YES 16814 16815 B.5 16816 16817 REQUIRED, do not change this value 16818 16819 Implemented Commands 16820 16821 Page 148 16822 October 31, 2013 16823 16824 Published 16825 Copyright TCG 2006-2013 16826 16827 Family 2.0 16828 Level 00 Revision 00.99 16829 16830 Trusted Platform Module Library 16832 16833 Part 2: Structures 16834 16835 This table is used to indicate which of the commands are implemented. In the reference implementation, 16836 this table determines which commands can be called and drives the generation of various commanddependent switch statements. 16837 The "Implemented or Dependent" column contains a "Y", "YES", or blank to indicate that the command is 16838 present in the implementation; an "N" or "NO" to indicate that the command is not implemented; and an 16839 algorithm value if implementation of the command is dependent on a setting in Table 214. Linkage to 16840 Table 214 is not required and is provide as a convenience. 16841 To indicate that the command is implemented, only "Y", "N", blank, or a value from Table 214 is allowed. 16842 Table 215 Defines for Implemented Commands 16843 Name 16844 ActivateCredential 16845 16846 Implemented 16847 or Dependent 16848 16849 Comments 16850 16851 YES 16852 16853 Certify 16854 16855 Y 16856 16857 CertifyCreation 16858 16859 Y 16860 16861 ChangeEPS 16862 16863 Y 16864 16865 ChangePPS 16866 16867 Y 16868 16869 Clear 16870 16871 Y 16872 16873 ClearControl 16874 16875 Y 16876 16877 ClockRateAdjust 16878 16879 Y 16880 16881 ClockSet 16882 16883 Y 16884 16885 Commit 16886 16887 ECC 16888 16889 ContextLoad 16890 16891 Y 16892 16893 Context 16894 16895 ContextSave 16896 16897 Y 16898 16899 Context 16900 16901 Create 16902 16903 Y 16904 16905 CreatePrimary 16906 16907 Y 16908 16909 DictionaryAttackLockReset 16910 16911 Y 16912 16913 DictionaryAttackParameters 16914 16915 Y 16916 16917 Duplicate 16918 16919 Y 16920 16921 ECC_Parameters 16922 16923 ECC 16924 16925 ECDH_KeyGen 16926 16927 ECC 16928 16929 ECDH_ZGen 16930 16931 ECC 16932 16933 EncryptDecrypt 16934 16935 Y 16936 16937 EventSequenceComplete 16938 16939 Y 16940 16941 EvictControl 16942 16943 Y 16944 16945 FieldUpgradeData 16946 16947 N 16948 16949 FieldUpgradeStart 16950 16951 N 16952 16953 FirmwareRead 16954 16955 N 16956 16957 FlushContext 16958 16959 Y 16960 16961 GetCapability 16962 16963 Y 16964 16965 GetCommandAuditDigest 16966 16967 Y 16968 16969 GetRandom 16970 16971 Y 16972 16973 GetSessionAuditDigest 16974 16975 Y 16976 16977 Family 2.0 16978 Level 00 Revision 00.99 16979 16980 Context 16981 16982 Published 16983 Copyright TCG 2006-2013 16984 16985 Page 149 16986 October 31, 2013 16987 16988 Part 2: Structures 16990 16991 Name 16992 16993 Trusted Platform Module Library 16994 Implemented 16995 or Dependent 16996 16997 Comments 16998 16999 GetTestResult 17000 17001 Y 17002 17003 GetTime 17004 17005 Y 17006 17007 Hash 17008 17009 Y 17010 17011 HashSequenceStart 17012 17013 Y 17014 17015 HierarchyChangeAuth 17016 17017 Y 17018 17019 HierarchyControl 17020 17021 Y 17022 17023 HMAC 17024 17025 Y 17026 17027 HMAC_Start 17028 17029 Y 17030 17031 Import 17032 17033 Y 17034 17035 IncrementalSelfTest 17036 17037 Y 17038 17039 Load 17040 17041 Y 17042 17043 LoadExternal 17044 17045 Y 17046 17047 MakeCredential 17048 17049 Y 17050 17051 NV_Certify 17052 17053 Y 17054 17055 NV_ChangeAuth 17056 17057 Y 17058 17059 NV_DefineSpace 17060 17061 Y 17062 17063 NV_Extend 17064 17065 Y 17066 17067 NV_GlobalWriteLock 17068 17069 Y 17070 17071 NV_Increment 17072 17073 Y 17074 17075 NV_Read 17076 17077 Y 17078 17079 NV_ReadLock 17080 17081 Y 17082 17083 NV_ReadPublic 17084 17085 Y 17086 17087 NV_SetBits 17088 17089 Y 17090 17091 NV_UndefineSpace 17092 17093 Y 17094 17095 NV_UndefineSpaceSpecial 17096 17097 Y 17098 17099 NV_Write 17100 17101 Y 17102 17103 NV_WriteLock 17104 17105 Y 17106 17107 ObjectChangeAuth 17108 17109 Y 17110 17111 PCR_Allocate 17112 17113 Y 17114 17115 PCR_Event 17116 17117 Y 17118 17119 PCR_Extend 17120 17121 Y 17122 17123 PCR_Read 17124 17125 Y 17126 17127 PCR 17128 17129 PCR_Reset 17130 17131 Y 17132 17133 PCR 17134 17135 PCR_SetAuthPolicy 17136 17137 Y 17138 17139 PCR_SetAuthValue 17140 17141 Y 17142 17143 PolicyAuthorize 17144 17145 Y 17146 17147 Policy 17148 17149 PolicyAuthValue 17150 17151 Y 17152 17153 Policy 17154 17155 PolicyCommandCode 17156 17157 Y 17158 17159 Policy 17160 17161 PolicyCounterTimer 17162 17163 Y 17164 17165 Policy 17166 17167 PolicyCpHash 17168 17169 Y 17170 17171 Policy 17172 17173 Page 150 17174 October 31, 2013 17175 17176 NV 17177 17178 PCR 17179 17180 Published 17181 Copyright TCG 2006-2013 17182 17183 Family 2.0 17184 Level 00 Revision 00.99 17185 17186 Trusted Platform Module Library 17188 17189 Part 2: Structures 17190 Implemented 17191 or Dependent 17192 17193 Name 17194 17195 Comments 17196 17197 PolicyDuplicationSelect 17198 17199 Y 17200 17201 Policy 17202 17203 PolicyGetDigest 17204 17205 Y 17206 17207 Policy 17208 17209 PolicyLocality 17210 17211 Y 17212 17213 Policy 17214 17215 PolicyNameHash 17216 17217 Y 17218 17219 Policy 17220 17221 PolicyNV 17222 17223 Y 17224 17225 Policy 17226 17227 PolicyOR 17228 17229 Y 17230 17231 Policy 17232 17233 PolicyPassword 17234 17235 Y 17236 17237 Policy 17238 17239 PolicyPCR 17240 17241 Y 17242 17243 Policy 17244 17245 PolicyPhysicalPresence 17246 17247 Y 17248 17249 Policy 17250 17251 PolicyRestart 17252 17253 Y 17254 17255 PolicySecret 17256 17257 Y 17258 17259 Policy 17260 17261 PolicySigned 17262 17263 Y 17264 17265 Policy 17266 17267 PolicyTicket 17268 17269 Y 17270 17271 Policy 17272 17273 PP_Commands 17274 17275 Y 17276 17277 Quote 17278 17279 Y 17280 17281 ReadClock 17282 17283 Y 17284 17285 ReadPublic 17286 17287 Y 17288 17289 Rewrap 17290 17291 Y 17292 17293 RSA_Decrypt 17294 17295 RSA 17296 17297 RSA_Encrypt 17298 17299 RSA 17300 17301 SelfTest 17302 17303 Y 17304 17305 SequenceComplete 17306 17307 Y 17308 17309 SequenceUpdate 17310 17311 Y 17312 17313 SetAlgorithmSet 17314 17315 Y 17316 17317 SetCommandCodeAuditStatus 17318 17319 Y 17320 17321 SetPrimaryPolicy 17322 17323 Y 17324 17325 Shutdown 17326 17327 Y 17328 17329 Sign 17330 17331 Y 17332 17333 StartAuthSession 17334 17335 Y 17336 17337 Startup 17338 17339 Y 17340 17341 StirRandom 17342 17343 Y 17344 17345 TestParms 17346 17347 Y 17348 17349 Unseal 17350 17351 Y 17352 17353 VerifySignature 17354 17355 Y 17356 17357 ZGen_2Phase 17358 17359 Y 17360 17361 EC_Ephemeral 17362 17363 Y 17364 17365 PolicyNvWritten 17366 17367 Y 17368 17369 B.6 17370 17371 Algorithm Constants 17372 17373 Family 2.0 17374 Level 00 Revision 00.99 17375 17376 Published 17377 Copyright TCG 2006-2013 17378 17379 Page 151 17380 October 31, 2013 17381 17382 Part 2: Structures 17384 B.6.1 17385 17386 Trusted Platform Module Library 17387 17388 RSA 17389 Table 216 Defines for RSA Algorithm Constants 17390 17391 Name 17392 17393 Value 17394 17395 Comments 17396 17397 RSA_KEY_SIZES_BITS 17398 17399 {1024, 2048} 17400 17401 braces because this is a 17402 list value 17403 17404 MAX_RSA_KEY_BITS 17405 17406 2048 17407 17408 MAX_RSA_KEY_BYTES 17409 17410 ((MAX_RSA_KEY_BITS + 7) / 8) 17411 17412 B.6.2 17413 17414 ECC 17415 Table 217 Defines for ECC Algorithm Constants 17416 17417 Name 17418 17419 Value 17420 17421 ECC_CURVES 17422 17423 {TPM_ECC_NIST_P256, TPM_ECC_BN_P256, 17424 TPM_ECC_SM2_P256} 17425 17426 ECC_KEY_SIZES_BITS 17427 17428 {256} 17429 17430 MAX_ECC_KEY_BITS 17431 17432 256 17433 17434 MAX_ECC_KEY_BYTES 17435 17436 ((MAX_ECC_KEY_BITS + 7) / 8) 17437 17438 B.6.3 17439 17440 Comments 17441 17442 this is a list value with 17443 length of one 17444 17445 AES 17446 Table 218 Defines for AES Algorithm Constants 17447 17448 Name 17449 17450 Value 17451 17452 AES_KEY_SIZES_BITS 17453 17454 {128} 17455 17456 MAX_AES_KEY_BITS 17457 17458 128 17459 17460 MAX_AES_BLOCK_SIZE_BYTES 17461 17462 16 17463 17464 MAX_AES_KEY_BYTES 17465 17466 ((MAX_AES_KEY_BITS + 7) / 8) 17467 17468 B.6.4 17469 17470 Comments 17471 17472 SM4 17473 Table 219 Defines for SM4 Algorithm Constants 17474 17475 Name 17476 17477 Value 17478 17479 SM4_KEY_SIZES_BITS 17480 17481 {128} 17482 17483 MAX_SM4_KEY_BITS 17484 17485 128 17486 17487 MAX_SM4_BLOCK_SIZE_BYTES 17488 17489 16 17490 17491 MAX_SM4_KEY_BYTES 17492 17493 ((MAX_SM4_KEY_BITS + 7) / 8) 17494 17495 Page 152 17496 October 31, 2013 17497 17498 Comments 17499 17500 Published 17501 Copyright TCG 2006-2013 17502 17503 Family 2.0 17504 Level 00 Revision 00.99 17505 17506 Trusted Platform Module Library 17508 B.6.5 17509 17510 Part 2: Structures 17511 17512 Symmetric 17513 17514 The definitions in this table are derived from the implemented symmetric algorithms. 17515 Table 220 Defines for Symmetric Algorithm Constants 17516 Name 17517 17518 Value 17519 17520 MAX_SYM_KEY_BITS 17521 17522 MAX_AES_KEY_BITS 17523 17524 MAX_SYM_KEY_BYTES 17525 17526 MAX_AES_KEY_BYTES 17527 17528 MAX_SYM_BLOCK_SIZE 17529 17530 MAX_AES_BLOCK_SIZE_BYTES 17531 17532 Family 2.0 17533 Level 00 Revision 00.99 17534 17535 Comments 17536 17537 Published 17538 Copyright TCG 2006-2013 17539 17540 Page 153 17541 October 31, 2013 17542 17543 Part 2: Structures 17545 17546 B.7 17547 17548 Trusted Platform Module Library 17549 17550 Implementation Specific Values 17551 17552 The values listed in Table 221 are defined for a specific TPM implementation. The numbers in the Value 17553 column may be changed to reflect the implementation. The values shown are illustrative. 17554 Table 221 Defines for Implementation Values 17555 Name 17556 17557 Value 17558 17559 Description 17560 17561 FIELD_UPGRADE_IMPLEMENTED 17562 17563 NO 17564 17565 temporary define 17566 17567 BSIZE 17568 17569 UINT16 17570 17571 size used for internal storage of 17572 the size field of a TPM2B 17573 This is the definition used for 17574 the reference design. 17575 Compilation with this value 17576 changed may cause warnings 17577 about conversions. 17578 17579 BUFFER_ALIGNMENT 17580 17581 4 17582 17583 sets the size granularity for the 17584 buffers in a TPM2B structure 17585 TPMxB buffers will be assigned 17586 a space that is a multiple of this 17587 value. This does not set the size 17588 limits for IO. Those are set by 17589 the canonical form of the 17590 TPMxB 17591 17592 IMPLEMENTATION_PCR 17593 17594 24 17595 17596 the number of PCR in the TPM 17597 17598 PLATFORM_PCR 17599 17600 24 17601 17602 the number of PCR required by 17603 the relevant platform 17604 specification 17605 17606 DRTM_PCR 17607 17608 17 17609 17610 the DRTM PCR 17611 17612 HCRTM_PCR 17613 17614 0 17615 17616 the PCR that will receive the HCRTM value at TPM2_Startup 17617 17618 NUM_LOCALITIES 17619 17620 5 17621 17622 the number of localities 17623 supported by the TPM 17624 This is expected to be either 5 17625 for a PC, or 1 for just about 17626 everything else. 17627 17628 MAX_HANDLE_NUM 17629 17630 3 17631 17632 the maximum number of 17633 handles in the handle area 17634 This should be produced by the 17635 Part 3 parser but is here for 17636 now. 17637 17638 MAX_ACTIVE_SESSIONS 17639 17640 64 17641 17642 the number of simultaneously 17643 active sessions that are 17644 supported by the TPM 17645 implementation 17646 17647 CONTEXT_SLOT 17648 17649 UINT16 17650 17651 the type of an entry in the array 17652 of saved contexts 17653 17654 CONTEXT_COUNTER 17655 17656 UINT64 17657 17658 the type of the saved session 17659 counter 17660 17661 MAX_LOADED_SESSIONS 17662 17663 3 17664 17665 the number of sessions that the 17666 TPM may have in memory 17667 17668 MAX_SESSION_NUM 17669 17670 3 17671 17672 this is the current maximum 17673 value 17674 17675 Page 154 17676 October 31, 2013 17677 17678 Published 17679 Copyright TCG 2006-2013 17680 17681 Family 2.0 17682 Level 00 Revision 00.99 17683 17684 Trusted Platform Module Library 17686 17687 Part 2: Structures 17688 17689 Name 17690 17691 Value 17692 17693 Description 17694 17695 MAX_LOADED_OBJECTS 17696 17697 3 17698 17699 the number of simultaneously 17700 loaded objects that are 17701 supported by the TPM; this 17702 number does not include the 17703 objects that may be placed in 17704 NV memory by 17705 TPM2_EvictControl(). 17706 17707 MIN_EVICT_OBJECTS 17708 17709 2 17710 17711 the minimum number of evict 17712 objects supported by the TPM 17713 17714 PCR_SELECT_MIN 17715 17716 ((PLATFORM_PCR+7)/8) 17717 17718 PCR_SELECT_MAX 17719 17720 ((IMPLEMENTATION_PCR+7)/8) 17721 17722 NUM_POLICY_PCR_GROUP 17723 17724 1 17725 17726 number of PCR groups that 17727 have individual policies 17728 17729 NUM_AUTHVALUE_PCR_GROUP 17730 17731 1 17732 17733 number of PCR groups that 17734 have individual authorization 17735 values 17736 17737 MAX_CONTEXT_SIZE 17738 17739 4000 17740 17741 This may be larger than 17742 necessary 17743 17744 MAX_DIGEST_BUFFER 17745 17746 1024 17747 17748 MAX_NV_INDEX_SIZE 17749 17750 2048 17751 17752 maximum data size allowed in 17753 an NV Index 17754 17755 MAX_NV_BUFFER_SIZE 17756 17757 1024 17758 17759 maximum data size in one NV 17760 read or write command 17761 17762 MAX_CAP_BUFFER 17763 17764 1024 17765 17766 NV_MEMORY_SIZE 17767 17768 16384 17769 17770 NUM_STATIC_PCR 17771 17772 16 17773 17774 MAX_ALG_LIST_SIZE 17775 17776 64 17777 17778 number of algorithms that can 17779 be in a list 17780 17781 TIMER_PRESCALE 17782 17783 100000 17784 17785 nominal value for the pre-scale 17786 value of Clock (the number of 17787 cycles of the TPM's oscillator for 17788 each increment of Clock) 17789 17790 PRIMARY_SEED_SIZE 17791 17792 32 17793 17794 size of the Primary Seed in 17795 octets 17796 17797 CONTEXT_ENCRYPT_ALG 17798 17799 TPM_ALG_AES 17800 17801 context encryption algorithm 17802 17803 CONTEXT_ENCRYPT_KEY_BITS 17804 17805 MAX_SYM_KEY_BITS 17806 17807 context encryption key size in 17808 bits 17809 17810 CONTEXT_ENCRYPT_KEY_BYTES 17811 17812 ((CONTEXT_ENCRYPT_KEY_BITS+7 17813 )/8) 17814 17815 CONTEXT_INTEGRITY_HASH_ALG 17816 17817 TPM_ALG_SHA256 17818 17819 context integrity hash algorithm 17820 17821 CONTEXT_INTEGRITY_HASH_SIZE 17822 17823 SHA256_DIGEST_SIZE 17824 17825 number of byes in the context 17826 integrity digest 17827 17828 PROOF_SIZE 17829 17830 CONTEXT_INTEGRITY_HASH_SIZE 17831 17832 size of proof value in octets 17833 This size of the proof should be 17834 consistent with the digest size 17835 used for context integrity. 17836 17837 NV_CLOCK_UPDATE_INTERVAL 17838 17839 12 17840 17841 the update interval expressed 17842 as a power of 2 seconds 17843 17844 size of NV memory in octets 17845 17846 A value of 12 is 4,096 seconds 17847 (~68 minutes). 17848 17849 Family 2.0 17850 Level 00 Revision 00.99 17851 17852 Published 17853 Copyright TCG 2006-2013 17854 17855 Page 155 17856 October 31, 2013 17857 17858 Part 2: Structures 17860 17861 Trusted Platform Module Library 17862 17863 Name 17864 17865 Value 17866 17867 Description 17868 17869 NUM_POLICY_PCR 17870 17871 1 17872 17873 number of PCR that allow 17874 policy/auth 17875 17876 MAX_COMMAND_SIZE 17877 17878 4096 17879 17880 maximum size of a command 17881 17882 MAX_RESPONSE_SIZE 17883 17884 4096 17885 17886 maximum size of a response 17887 17888 ORDERLY_BITS 17889 17890 8 17891 17892 number between 1 and 32 17893 inclusive 17894 17895 MAX_ORDERLY_COUNT 17896 17897 ((1 << ORDERLY_BITS) - 1) 17898 17899 maximum count of orderly 17900 counter before NV is updated 17901 This must be of the form 2N 1 17902 where 1 N 32. 17903 17904 ALG_ID_FIRST 17905 17906 TPM_ALG_FIRST 17907 17908 used by GetCapability() 17909 processing to bound the 17910 algorithm search 17911 17912 ALG_ID_LAST 17913 17914 TPM_ALG_LAST 17915 17916 used by GetCapability() 17917 processing to bound the 17918 algorithm search 17919 17920 MAX_SYM_DATA 17921 17922 128 17923 17924 this is the maximum number of 17925 octets that may be in a sealed 17926 blob. 17927 17928 MAX_RNG_ENTROPY_SIZE 17929 17930 64 17931 17932 RAM_INDEX_SPACE 17933 17934 512 17935 17936 RSA_DEFAULT_PUBLIC_EXPONENT 17937 17938 0x00010001 17939 17940 216 + 1 17941 17942 ENABLE_PCR_NO_INCREMENT 17943 17944 YES 17945 17946 indicates if the 17947 TPM_PT_PCR_NO_INCREME 17948 NT group is implemented 17949 17950 CRT_FORMAT_RSA 17951 17952 YES 17953 17954 PRIVATE_VENDOR_SPECIFIC_BYTES 17955 17956 ((MAX_RSA_KEY_BYTES/2) * (3 + 17957 CRT_FORMAT_RSA * 2)) 17958 17959 Page 156 17960 October 31, 2013 17961 17962 Published 17963 Copyright TCG 2006-2013 17964 17965 Family 2.0 17966 Level 00 Revision 00.99 17967 17968 17970
