      Trusted Platform Module Library
      Part 3: Commands

      Family “2.0”

      Level 00 Revision 01.16

      October 30, 2014


      Contact: admin@trustedcomputinggroup.org


      TCG Published
      Copyright © TCG 2006-2014


TCG
Part 3: Commands                                                               Trusted Platform Module Library


Licenses and Notices

1. Copyright Licenses:
         Trusted Computing Group (TCG) grants to the user of the source code in this specification (the
          “Source Code”) a worldwide, irrevocable, nonexclusive, royalty free, copyright license to
          reproduce, create derivative works, distribute, display and perform the Source Code and
          derivative works thereof, and to grant others the rights granted herein.
         The TCG grants to the user of the other parts of the specification (other than the Source Code)
          the rights to reproduce, distribute, display, and perform the specification solely for the purpose of
          developing products based on such documents.
2. Source Code Distribution Conditions:
         Redistributions of Source Code must retain the above copyright licenses, this list of conditions
          and the following disclaimers.
         Redistributions in binary form must reproduce the above copyright licenses, this list of conditions
          and the following disclaimers in the documentation and/or other materials provided with the
          distribution.
3. Disclaimers:
         THE COPYRIGHT LICENSES SET FORTH ABOVE DO NOT REPRESENT ANY FORM OF
          LICENSE OR WAIVER, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, WITH
          RESPECT TO PATENT RIGHTS HELD BY TCG MEMBERS (OR OTHER THIRD PARTIES)
          THAT MAY BE NECESSARY TO IMPLEMENT THIS SPECIFICATION OR OTHERWISE.
          Contact TCG Administration (admin@trustedcomputinggroup.org) for information on specification
          licensing rights available through TCG membership agreements.
         THIS SPECIFICATION IS PROVIDED "AS IS" WITH NO EXPRESS OR IMPLIED WARRANTIES
          WHATSOEVER, INCLUDING ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A
          PARTICULAR PURPOSE, ACCURACY, COMPLETENESS, OR NONINFRINGEMENT OF
          INTELLECTUAL PROPERTY RIGHTS, OR ANY WARRANTY OTHERWISE ARISING OUT OF
          ANY PROPOSAL, SPECIFICATION OR SAMPLE.
         Without limitation, TCG and its members and licensors disclaim all liability, including liability for
          infringement of any proprietary rights, relating to use of information in this specification and to the
          implementation of this specification, and TCG disclaims all liability for cost of procurement of
          substitute goods or services, lost profits, loss of use, loss of data or any incidental, consequential,
          direct, indirect, or special damages, whether under contract, tort, warranty or otherwise, arising in
          any way out of use or reliance upon this specification or any information herein.
Any marks and brands contained herein are the property of their respective owner.


Page ii                                         TCG Published                                      Family “2.0”
October 30, 2014                        Copyright © TCG 2006-2014                    Level 00 Revision 01.16
Trusted Platform Module Library                                                                                                      Part 3: Commands


                                                                    CONTENTS

1     Scope .................................................................................................................................................... 1
2     Terms and Definitions ........................................................................................................................... 1
3     Symbols and abbreviated terms ............................................................................................................ 1
4     Notation ................................................................................................................................................. 1
    4.1     Introduction ..................................................................................................................................... 1
    4.2     Table Decorations ........................................................................................................................... 1
    4.3     Handle and Parameter Demarcation .............................................................................................. 3
    4.4     AuthorizationSize and ParameterSize ............................................................................................ 3
5     Command Processing ........................................................................................................................... 4
    5.1     Introduction ..................................................................................................................................... 4
    5.2     Command Header Validation .......................................................................................................... 4
    5.3     Mode Checks .................................................................................................................................. 4
    5.4     Handle Area Validation ................................................................................................................... 5
    5.5     Session Area Validation .................................................................................................................. 6
    5.6     Authorization Checks ...................................................................................................................... 7
    5.7     Parameter Decryption ..................................................................................................................... 8
    5.8     Parameter Unmarshaling ................................................................................................................ 8
    5.9     Command Post Processing .......................................................................................................... 10
6     Response Values ................................................................................................................................ 12
    6.1     Tag ................................................................................................................................................ 12
    6.2     Response Codes .......................................................................................................................... 12
7     Implementation Dependent ................................................................................................................. 15
8     Detailed Actions Assumptions ............................................................................................................. 16
    8.1     Introduction ................................................................................................................................... 16
    8.2     Pre-processing .............................................................................................................................. 16
    8.3     Post Processing ............................................................................................................................ 16
9     Start-up ................................................................................................................................................ 17
    9.1     Introduction ................................................................................................................................... 17
    9.2     _TPM_Init...................................................................................................................................... 17
    9.3     TPM2_Startup ............................................................................................................................... 19
    9.4     TPM2_Shutdown .......................................................................................................................... 26
10    Testing ................................................................................................................................................. 30
    10.1    Introduction ................................................................................................................................... 30
    10.2    TPM2_SelfTest ............................................................................................................................. 31
    10.3    TPM2_IncrementalSelfTest .......................................................................................................... 34
    10.4    TPM2_GetTestResult ................................................................................................................... 37
11    Session Commands ............................................................................................................................ 40
    11.1    TPM2_StartAuthSession .............................................................................................................. 40
    11.2    TPM2_PolicyRestart ..................................................................................................................... 45
12    Object Commands............................................................................................................................... 48
    12.1    TPM2_Create................................................................................................................................ 48
    12.2    TPM2_Load .................................................................................................................................. 54

Family “2.0”                                                      TCG Published                                                                       Page iii
Level 00 Revision 01.16                                Copyright © TCG 2006-2014                                                     October 30, 2014
Part 3: Commands                                                                                            Trusted Platform Module Library


 12.3     TPM2_LoadExternal ..................................................................................................................... 58
 12.4     TPM2_ReadPublic ........................................................................................................................ 63
 12.5     TPM2_ActivateCredential ............................................................................................................. 66
 12.6     TPM2_MakeCredential ................................................................................................................. 70
 12.7     TPM2_Unseal ............................................................................................................................... 73
 12.8     TPM2_ObjectChangeAuth ............................................................................................................ 76
13   Duplication Commands ....................................................................................................................... 80
 13.1     TPM2_Duplicate ........................................................................................................................... 80
 13.2     TPM2_Rewrap .............................................................................................................................. 84
 13.3     TPM2_Import ................................................................................................................................ 88
14   Asymmetric Primitives ......................................................................................................................... 94
 14.1     Introduction ................................................................................................................................... 94
 14.2     TPM2_RSA_Encrypt ..................................................................................................................... 94
 14.3     TPM2_RSA_Decrypt .................................................................................................................... 99
 14.4     TPM2_ECDH_KeyGen ............................................................................................................... 103
 14.5     TPM2_ECDH_ZGen ................................................................................................................... 107
 14.6     TPM2_ECC_Parameters ............................................................................................................ 110
 14.7     TPM2_ZGen_2Phase ................................................................................................................. 112
15   Symmetric Primitives ......................................................................................................................... 116
 15.1     Introduction ................................................................................................................................. 116
 15.2     TPM2_EncryptDecrypt ................................................................................................................ 118
 15.3     TPM2_Hash ................................................................................................................................ 122
 15.4     TPM2_HMAC .............................................................................................................................. 125
16   Random Number Generator .............................................................................................................. 129
 16.1     TPM2_GetRandom ..................................................................................................................... 129
 16.2     TPM2_StirRandom ..................................................................................................................... 132
17   Hash/HMAC/Event Sequences ......................................................................................................... 135
 17.1     Introduction ................................................................................................................................. 135
 17.2     TPM2_HMAC_Start .................................................................................................................... 135
 17.3     TPM2_HashSequenceStart ........................................................................................................ 139
 17.4     TPM2_SequenceUpdate ............................................................................................................ 142
 17.5     TPM2_SequenceComplete......................................................................................................... 146
 17.6     TPM2_EventSequenceComplete ............................................................................................... 150
18   Attestation Commands ...................................................................................................................... 154
 18.1     Introduction ................................................................................................................................. 154
 18.2     TPM2_Certify .............................................................................................................................. 156
 18.3     TPM2_CertifyCreation ................................................................................................................ 160
 18.4     TPM2_Quote............................................................................................................................... 164
 18.5     TPM2_GetSessionAuditDigest ................................................................................................... 168
 18.6     TPM2_GetCommandAuditDigest ............................................................................................... 172
 18.7     TPM2_GetTime........................................................................................................................... 176
19   Ephemeral EC Keys .......................................................................................................................... 180
 19.1     Introduction ................................................................................................................................. 180
 19.2     TPM2_Commit ............................................................................................................................ 181


Page iv                                                        TCG Published                                                             Family “2.0”
October 30, 2014                                    Copyright © TCG 2006-2014                                        Level 00 Revision 01.16
Trusted Platform Module Library                                                                                                Part 3: Commands


  19.3    TPM2_EC_Ephemeral ................................................................................................................ 186
20   Signing and Signature Verification .................................................................................................... 189
  20.1    TPM2_VerifySignature ................................................................................................................ 189
  20.2    TPM2_Sign ................................................................................................................................. 193
21   Command Audit ................................................................................................................................. 197
  21.1    Introduction ................................................................................................................................. 197
  21.2    TPM2_SetCommandCodeAuditStatus ....................................................................................... 198
22   Integrity Collection (PCR) .................................................................................................................. 202
  22.1    Introduction ................................................................................................................................. 202
  22.2    TPM2_PCR_Extend ................................................................................................................... 203
  22.3    TPM2_PCR_Event ..................................................................................................................... 206
  22.4    TPM2_PCR_Read ...................................................................................................................... 209
  22.5    TPM2_PCR_Allocate .................................................................................................................. 212
  22.6    TPM2_PCR_SetAuthPolicy ........................................................................................................ 215
  22.7    TPM2_PCR_SetAuthValue ......................................................................................................... 218
  22.8    TPM2_PCR_Reset ..................................................................................................................... 221
  22.9    _TPM_Hash_Start ...................................................................................................................... 224
  22.10   _TPM_Hash_Data ...................................................................................................................... 226
  22.11   _TPM_Hash_End ....................................................................................................................... 228
23   Enhanced Authorization (EA) Commands ........................................................................................ 231
  23.1    Introduction ................................................................................................................................. 231
  23.2    Signed Authorization Actions ...................................................................................................... 232
  23.3    TPM2_PolicySigned ................................................................................................................... 236
  23.4    TPM2_PolicySecret .................................................................................................................... 242
  23.5    TPM2_PolicyTicket ..................................................................................................................... 246
  23.6    TPM2_PolicyOR ......................................................................................................................... 250
  23.7    TPM2_PolicyPCR ....................................................................................................................... 254
  23.8    TPM2_PolicyLocality .................................................................................................................. 259
  23.9    TPM2_PolicyNV .......................................................................................................................... 263
  23.10   TPM2_PolicyCounterTimer......................................................................................................... 268
  23.11   TPM2_PolicyCommandCode ..................................................................................................... 273
  23.12   TPM2_PolicyPhysicalPresence .................................................................................................. 276
  23.13   TPM2_PolicyCpHash .................................................................................................................. 279
  23.14   TPM2_PolicyNameHash ............................................................................................................. 283
  23.15   TPM2_PolicyDuplicationSelect ................................................................................................... 287
  23.16   TPM2_PolicyAuthorize ............................................................................................................... 291
  23.17   TPM2_PolicyAuthValue .............................................................................................................. 295
  23.18   TPM2_PolicyPassword ............................................................................................................... 298
  23.19   TPM2_PolicyGetDigest ............................................................................................................... 301
  23.20   TPM2_PolicyNvWritten ............................................................................................................... 304
24   Hierarchy Commands........................................................................................................................ 308
  24.1    TPM2_CreatePrimary ................................................................................................................. 308
  24.2    TPM2_HierarchyControl ............................................................................................................. 312
  24.3    TPM2_SetPrimaryPolicy ............................................................................................................. 316
  24.4    TPM2_ChangePPS .................................................................................................................... 320
  24.5    TPM2_ChangeEPS .................................................................................................................... 323

Family “2.0”                                                   TCG Published                                                                    Page v
Level 00 Revision 01.16                             Copyright © TCG 2006-2014                                                  October 30, 2014
Part 3: Commands                                                                                            Trusted Platform Module Library


 24.6      TPM2_Clear ................................................................................................................................ 326
 24.7      TPM2_ClearControl .................................................................................................................... 330
 24.8      TPM2_HierarchyChangeAuth ..................................................................................................... 333
25   Dictionary Attack Functions ............................................................................................................... 336
 25.1      Introduction ................................................................................................................................. 336
 25.2      TPM2_DictionaryAttackLockReset ............................................................................................. 336
 25.3      TPM2_DictionaryAttackParameters............................................................................................ 339
26   Miscellaneous Management Functions ............................................................................................. 342
 26.1      Introduction ................................................................................................................................. 342
 26.2      TPM2_PP_Commands ............................................................................................................... 342
 26.3      TPM2_SetAlgorithmSet .............................................................................................................. 345
27   Field Upgrade .................................................................................................................................... 348
 27.1      Introduction ................................................................................................................................. 348
 27.2      TPM2_FieldUpgradeStart ........................................................................................................... 350
 27.3      TPM2_FieldUpgradeData ........................................................................................................... 353
 27.4      TPM2_FirmwareRead ................................................................................................................. 356
28   Context Management ........................................................................................................................ 359
 28.1      Introduction ................................................................................................................................. 359
 28.2      TPM2_ContextSave .................................................................................................................... 359
 28.3      TPM2_ContextLoad .................................................................................................................... 364
 28.4      TPM2_FlushContext ................................................................................................................... 369
 28.5      TPM2_EvictControl ..................................................................................................................... 372
29   Clocks and Timers............................................................................................................................. 377
 29.1      TPM2_ReadClock ....................................................................................................................... 377
 29.2      TPM2_ClockSet .......................................................................................................................... 380
 29.3      TPM2_ClockRateAdjust .............................................................................................................. 383
30   Capability Commands ....................................................................................................................... 386
 30.1      Introduction ................................................................................................................................. 386
 30.2      TPM2_GetCapability ................................................................................................................... 386
 30.3      TPM2_TestParms ....................................................................................................................... 394
31   Non-volatile Storage .......................................................................................................................... 397
 31.1      Introduction ................................................................................................................................. 397
 31.2      NV Counters ............................................................................................................................... 398
 31.3      TPM2_NV_DefineSpace ............................................................................................................. 399
 31.4      TPM2_NV_UndefineSpace ......................................................................................................... 405
 31.5      TPM2_NV_UndefineSpaceSpecial ............................................................................................. 408
 31.6      TPM2_NV_ReadPublic ............................................................................................................... 411
 31.7      TPM2_NV_Write ......................................................................................................................... 414
 31.8      TPM2_NV_Increment ................................................................................................................. 418
 31.9      TPM2_NV_Extend ...................................................................................................................... 422
 31.10     TPM2_NV_SetBits ...................................................................................................................... 426
 31.11     TPM2_NV_WriteLock ................................................................................................................. 430
 31.12     TPM2_NV_GlobalWriteLock ....................................................................................................... 434
 31.13     TPM2_NV_Read ......................................................................................................................... 437


Page vi                                                         TCG Published                                                            Family “2.0”
October 30, 2014                                     Copyright © TCG 2006-2014                                       Level 00 Revision 01.16
Trusted Platform Module Library                                                                                         Part 3: Commands


  31.14 TPM2_NV_ReadLock ................................................................................................................. 440
  31.15 TPM2_NV_ChangeAuth ............................................................................................................. 444
  31.16 TPM2_NV_Certify ....................................................................................................................... 447


Family “2.0”                                                TCG Published                                                             Page vii
Level 00 Revision 01.16                           Copyright © TCG 2006-2014                                             October 30, 2014
Part 3: Commands                                                                                           Trusted Platform Module Library

Tables
Table 1 — Command Modifiers and Decoration ........................................................................................... 2
Table 2 — Separators ................................................................................................................................... 3
Table 3 — Unmarshaling Errors ................................................................................................................. 10
Table 4 — Command-Independent Response Codes ................................................................................ 13
Table 5 — TPM2_Startup Command .......................................................................................................... 22
Table 6 — TPM2_Startup Response .......................................................................................................... 22
Table 7 — TPM2_Shutdown Command ..................................................................................................... 27
Table 8 — TPM2_Shutdown Response ...................................................................................................... 27
Table 9 — TPM2_SelfTest Command ........................................................................................................ 32
Table 10 — TPM2_SelfTest Response ...................................................................................................... 32
Table 11 — TPM2_IncrementalSelfTest Command ................................................................................... 35
Table 12 — TPM2_IncrementalSelfTest Response ................................................................................... 35
Table 13 — TPM2_GetTestResult Command ............................................................................................ 38
Table 14 — TPM2_GetTestResult Response............................................................................................. 38
Table 15 — TPM2_StartAuthSession Command ....................................................................................... 42
Table 16 — TPM2_StartAuthSession Response ........................................................................................ 42
Table 17 — TPM2_PolicyRestart Command .............................................................................................. 46
Table 18 — TPM2_PolicyRestart Response .............................................................................................. 46
Table 19 — TPM2_Create Command ........................................................................................................ 51
Table 20 — TPM2_Create Response ......................................................................................................... 51
Table 21 — TPM2_Load Command ........................................................................................................... 55
Table 22 — TPM2_Load Response ............................................................................................................ 55
Table 23 — TPM2_LoadExternal Command .............................................................................................. 60
Table 24 — TPM2_LoadExternal Response .............................................................................................. 60
Table 25 — TPM2_ReadPublic Command ................................................................................................. 64
Table 26 — TPM2_ReadPublic Response ................................................................................................. 64
Table 27 — TPM2_ActivateCredential Command ...................................................................................... 67
Table 28 — TPM2_ActivateCredential Response ...................................................................................... 67
Table 29 — TPM2_MakeCredential Command .......................................................................................... 71
Table 30 — TPM2_MakeCredential Response .......................................................................................... 71
Table 31 — TPM2_Unseal Command ........................................................................................................ 74
Table 32 — TPM2_Unseal Response ........................................................................................................ 74
Table 33 — TPM2_ObjectChangeAuth Command ..................................................................................... 77
Table 34 — TPM2_ObjectChangeAuth Response ..................................................................................... 77
Table 35 — TPM2_Duplicate Command .................................................................................................... 81
Table 36 — TPM2_Duplicate Response ..................................................................................................... 81
Table 37 — TPM2_Rewrap Command ....................................................................................................... 85
Table 38 — TPM2_Rewrap Response ....................................................................................................... 85

Page viii                                                       TCG Published                                                          Family “2.0”
October 30, 2014                                     Copyright © TCG 2006-2014                                     Level 00 Revision 01.16
Trusted Platform Module Library                                                                                       Part 3: Commands

Table 39 — TPM2_Import Command ......................................................................................................... 90
Table 40 — TPM2_Import Response ......................................................................................................... 90
Table 41 — Padding Scheme Selection ..................................................................................................... 94
Table 42 — Message Size Limits Based on Padding ................................................................................. 95
Table 43 — TPM2_RSA_Encrypt Command.............................................................................................. 96
Table 44 — TPM2_RSA_Encrypt Response .............................................................................................. 96
Table 45 — TPM2_RSA_Decrypt Command ........................................................................................... 100
Table 46 — TPM2_RSA_Decrypt Response ............................................................................................ 100
Table 47 — TPM2_ECDH_KeyGen Command ........................................................................................ 104
Table 48 — TPM2_ECDH_KeyGen Response ........................................................................................ 104
Table 49 — TPM2_ECDH_ZGen Command ............................................................................................ 108
Table 50 — TPM2_ECDH_ZGen Response ............................................................................................ 108
Table 51 — TPM2_ECC_Parameters Command ..................................................................................... 110
Table 52 — TPM2_ECC_Parameters Response ..................................................................................... 110
Table 53 — TPM2_ZGen_2Phase Command .......................................................................................... 113
Table 54 — TPM2_ZGen_2Phase Response .......................................................................................... 113
Table 55 — Symmetric Chaining Process ................................................................................................ 117
Table 56 — TPM2_EncryptDecrypt Command......................................................................................... 119
Table 57 — TPM2_EncryptDecrypt Response ......................................................................................... 119
Table 58 — TPM2_Hash Command ......................................................................................................... 123
Table 59 — TPM2_Hash Response ......................................................................................................... 123
Table 60 — TPM2_HMAC Command ....................................................................................................... 126
Table 61 — TPM2_HMAC Response ....................................................................................................... 126
Table 62 — TPM2_GetRandom Command .............................................................................................. 130
Table 63 — TPM2_GetRandom Response .............................................................................................. 130
Table 64 — TPM2_StirRandom Command .............................................................................................. 133
Table 65 — TPM2_StirRandom Response ............................................................................................... 133
Table 66 — Hash Selection Matrix ........................................................................................................... 135
Table 67 — TPM2_HMAC_Start Command ............................................................................................. 136
Table 68 — TPM2_HMAC_Start Response ............................................................................................. 136
Table 69 — TPM2_HashSequenceStart Command ................................................................................. 140
Table 70 — TPM2_HashSequenceStart Response ................................................................................. 140
Table 71 — TPM2_SequenceUpdate Command ..................................................................................... 143
Table 72 — TPM2_SequenceUpdate Response ...................................................................................... 143
Table 73 — TPM2_SequenceComplete Command ................................................................................. 147
Table 74 — TPM2_SequenceComplete Response .................................................................................. 147
Table 75 — TPM2_EventSequenceComplete Command ........................................................................ 151
Table 76 — TPM2_EventSequenceComplete Response ......................................................................... 151
Table 77 — TPM2_Certify Command ....................................................................................................... 157
Family “2.0”                                                TCG Published                                                           Page ix
Level 00 Revision 01.16                           Copyright © TCG 2006-2014                                           October 30, 2014
Part 3: Commands                                                                                 Trusted Platform Module Library

Table 78 — TPM2_Certify Response ....................................................................................................... 157
Table 79 — TPM2_CertifyCreation Command ......................................................................................... 161
Table 80 — TPM2_CertifyCreation Response .......................................................................................... 161
Table 81 — TPM2_Quote Command ....................................................................................................... 165
Table 82 — TPM2_Quote Response ........................................................................................................ 165
Table 83 — TPM2_GetSessionAuditDigest Command ............................................................................ 169
Table 84 — TPM2_GetSessionAuditDigest Response ............................................................................ 169
Table 85 — TPM2_GetCommandAuditDigest Command ........................................................................ 173
Table 86 — TPM2_GetCommandAuditDigest Response ......................................................................... 173
Table 87 — TPM2_GetTime Command ................................................................................................... 177
Table 88 — TPM2_GetTime Response .................................................................................................... 177
Table 89 — TPM2_Commit Command ..................................................................................................... 182
Table 90 — TPM2_Commit Response ..................................................................................................... 182
Table 91 — TPM2_EC_Ephemeral Command ......................................................................................... 187
Table 92 — TPM2_EC_Ephemeral Response ......................................................................................... 187
Table 93 — TPM2_VerifySignature Command......................................................................................... 190
Table 94 — TPM2_VerifySignature Response ......................................................................................... 190
Table 95 — TPM2_Sign Command .......................................................................................................... 194
Table 96 — TPM2_Sign Response .......................................................................................................... 194
Table 97 — TPM2_SetCommandCodeAuditStatus Command ................................................................ 199
Table 98 — TPM2_SetCommandCodeAuditStatus Response ................................................................ 199
Table 99 — TPM2_PCR_Extend Command ............................................................................................ 204
Table 100 — TPM2_PCR_Extend Response ........................................................................................... 204
Table 101 — TPM2_PCR_Event Command ............................................................................................ 207
Table 102 — TPM2_PCR_Event Response ............................................................................................. 207
Table 103 — TPM2_PCR_Read Command ............................................................................................. 210
Table 104 — TPM2_PCR_Read Response ............................................................................................. 210
Table 105 — TPM2_PCR_Allocate Command ......................................................................................... 213
Table 106 — TPM2_PCR_Allocate Response ......................................................................................... 213
Table 107 — TPM2_PCR_SetAuthPolicy Command ............................................................................... 216
Table 108 — TPM2_PCR_SetAuthPolicy Response ............................................................................... 216
Table 109 — TPM2_PCR_SetAuthValue Command ............................................................................... 219
Table 110 — TPM2_PCR_SetAuthValue Response ................................................................................ 219
Table 111 — TPM2_PCR_Reset Command ............................................................................................ 222
Table 112 — TPM2_PCR_Reset Response ............................................................................................. 222
Table 113 — TPM2_PolicySigned Command .......................................................................................... 238
Table 114 — TPM2_PolicySigned Response ........................................................................................... 238
Table 115 — TPM2_PolicySecret Command ........................................................................................... 243
Table 116 — TPM2_PolicySecret Response ............................................................................................ 243
Page x                                                    TCG Published                                                   Family “2.0”
October 30, 2014                                Copyright © TCG 2006-2014                                Level 00 Revision 01.16
Trusted Platform Module Library                                                                                Part 3: Commands

Table 117 — TPM2_PolicyTicket Command ............................................................................................ 247
Table 118 — TPM2_PolicyTicket Response ............................................................................................ 247
Table 119 — TPM2_PolicyOR Command ................................................................................................ 251
Table 120 — TPM2_PolicyOR Response ................................................................................................. 251
Table 121 — TPM2_PolicyPCR Command .............................................................................................. 256
Table 122 — TPM2_PolicyPCR Response .............................................................................................. 256
Table 123 — TPM2_PolicyLocality Command ......................................................................................... 260
Table 124 — TPM2_PolicyLocality Response .......................................................................................... 260
Table 125 — TPM2_PolicyNV Command ................................................................................................. 264
Table 126 — TPM2_PolicyNV Response ................................................................................................. 264
Table 127 — TPM2_PolicyCounterTimer Command ............................................................................... 269
Table 128 — TPM2_PolicyCounterTimer Response ................................................................................ 269
Table 129 — TPM2_PolicyCommandCode Command ............................................................................ 274
Table 130 — TPM2_PolicyCommandCode Response ............................................................................. 274
Table 131 — TPM2_PolicyPhysicalPresence Command ......................................................................... 277
Table 132 — TPM2_PolicyPhysicalPresence Response ......................................................................... 277
Table 133 — TPM2_PolicyCpHash Command......................................................................................... 280
Table 134 — TPM2_PolicyCpHash Response ......................................................................................... 280
Table 135 — TPM2_PolicyNameHash Command.................................................................................... 284
Table 136 — TPM2_PolicyNameHash Response .................................................................................... 284
Table 137 — TPM2_PolicyDuplicationSelect Command .......................................................................... 288
Table 138 — TPM2_PolicyDuplicationSelect Response .......................................................................... 288
Table 139 — TPM2_PolicyAuthorize Command ...................................................................................... 292
Table 140 — TPM2_PolicyAuthorize Response ....................................................................................... 292
Table 141 — TPM2_PolicyAuthValue Command ..................................................................................... 296
Table 142 — TPM2_PolicyAuthValue Response ..................................................................................... 296
Table 143 — TPM2_PolicyPassword Command ...................................................................................... 299
Table 144 — TPM2_PolicyPassword Response ...................................................................................... 299
Table 145 — TPM2_PolicyGetDigest Command...................................................................................... 302
Table 146 — TPM2_PolicyGetDigest Response ...................................................................................... 302
Table 147 — TPM2_PolicyNvWritten Command ...................................................................................... 305
Table 148 — TPM2_PolicyNvWritten Response ...................................................................................... 305
Table 149 — TPM2_CreatePrimary Command ........................................................................................ 309
Table 150 — TPM2_CreatePrimary Response ........................................................................................ 309
Table 151 — TPM2_HierarchyControl Command .................................................................................... 313
Table 152 — TPM2_HierarchyControl Response .................................................................................... 313
Table 153 — TPM2_SetPrimaryPolicy Command .................................................................................... 317
Table 154 — TPM2_SetPrimaryPolicy Response .................................................................................... 317
Table 155 — TPM2_ChangePPS Command ........................................................................................... 321
Family “2.0”                                            TCG Published                                                        Page xi
Level 00 Revision 01.16                        Copyright © TCG 2006-2014                                       October 30, 2014
Part 3: Commands                                                                                Trusted Platform Module Library

Table 156 — TPM2_ChangePPS Response ............................................................................................ 321
Table 157 — TPM2_ChangeEPS Command ........................................................................................... 324
Table 158 — TPM2_ChangeEPS Response ............................................................................................ 324
Table 159 — TPM2_Clear Command ....................................................................................................... 327
Table 160 — TPM2_Clear Response ....................................................................................................... 327
Table 161 — TPM2_ClearControl Command ........................................................................................... 331
Table 162 — TPM2_ClearControl Response ........................................................................................... 331
Table 163 — TPM2_HierarchyChangeAuth Command ............................................................................ 334
Table 164 — TPM2_HierarchyChangeAuth Response ............................................................................ 334
Table 165 — TPM2_DictionaryAttackLockReset Command .................................................................... 337
Table 166 — TPM2_DictionaryAttackLockReset Response .................................................................... 337
Table 167 — TPM2_DictionaryAttackParameters Command .................................................................. 340
Table 168 — TPM2_DictionaryAttackParameters Response ................................................................... 340
Table 169 — TPM2_PP_Commands Command ...................................................................................... 343
Table 170 — TPM2_PP_Commands Response ...................................................................................... 343
Table 171 — TPM2_SetAlgorithmSet Command ..................................................................................... 346
Table 172 — TPM2_SetAlgorithmSet Response...................................................................................... 346
Table 173 — TPM2_FieldUpgradeStart Command .................................................................................. 351
Table 174 — TPM2_FieldUpgradeStart Response .................................................................................. 351
Table 175 — TPM2_FieldUpgradeData Command .................................................................................. 354
Table 176 — TPM2_FieldUpgradeData Response .................................................................................. 354
Table 177 — TPM2_FirmwareRead Command........................................................................................ 357
Table 178 — TPM2_FirmwareRead Response ........................................................................................ 357
Table 179 — TPM2_ContextSave Command........................................................................................... 360
Table 180 — TPM2_ContextSave Response ........................................................................................... 360
Table 181 — TPM2_ContextLoad Command ........................................................................................... 365
Table 182 — TPM2_ContextLoad Response ........................................................................................... 365
Table 183 — TPM2_FlushContext Command .......................................................................................... 370
Table 184 — TPM2_FlushContext Response .......................................................................................... 370
Table 185 — TPM2_EvictControl Command ............................................................................................ 374
Table 186 — TPM2_EvictControl Response ............................................................................................ 374
Table 187 — TPM2_ReadClock Command.............................................................................................. 378
Table 188 — TPM2_ReadClock Response .............................................................................................. 378
Table 189 — TPM2_ClockSet Command ................................................................................................. 381
Table 190 — TPM2_ClockSet Response ................................................................................................. 381
Table 191 — TPM2_ClockRateAdjust Command..................................................................................... 384
Table 192 — TPM2_ClockRateAdjust Response ..................................................................................... 384
Table 193 — TPM2_GetCapability Command.......................................................................................... 390
Table 194 — TPM2_GetCapability Response .......................................................................................... 390
Page xii                                                  TCG Published                                                  Family “2.0”
October 30, 2014                                Copyright © TCG 2006-2014                               Level 00 Revision 01.16
Trusted Platform Module Library                                                                               Part 3: Commands

Table 195 — TPM2_TestParms Command .............................................................................................. 395
Table 196 — TPM2_TestParms Response .............................................................................................. 395
Table 197 — TPM2_NV_DefineSpace Command ................................................................................... 401
Table 198 — TPM2_NV_DefineSpace Response .................................................................................... 401
Table 199 — TPM2_NV_UndefineSpace Command ............................................................................... 406
Table 200 — TPM2_NV_UndefineSpace Response ................................................................................ 406
Table 201 — TPM2_NV_UndefineSpaceSpecial Command .................................................................... 409
Table 202 — TPM2_NV_UndefineSpaceSpecial Response .................................................................... 409
Table 203 — TPM2_NV_ReadPublic Command ...................................................................................... 412
Table 204 — TPM2_NV_ReadPublic Response ...................................................................................... 412
Table 205 — TPM2_NV_Write Command ................................................................................................ 415
Table 206 — TPM2_NV_Write Response ................................................................................................ 415
Table 207 — TPM2_NV_Increment Command ........................................................................................ 419
Table 208 — TPM2_NV_Increment Response......................................................................................... 419
Table 209 — TPM2_NV_Extend Command ............................................................................................. 423
Table 210 — TPM2_NV_Extend Response ............................................................................................. 423
Table 211 — TPM2_NV_SetBits Command ............................................................................................. 427
Table 212 — TPM2_NV_SetBits Response ............................................................................................. 427
Table 213 — TPM2_NV_WriteLock Command ........................................................................................ 431
Table 214 — TPM2_NV_WriteLock Response......................................................................................... 431
Table 215 — TPM2_NV_GlobalWriteLock Command .............................................................................. 435
Table 216 — TPM2_NV_GlobalWriteLock Response .............................................................................. 435
Table 217 — TPM2_NV_Read Command................................................................................................ 438
Table 218 — TPM2_NV_Read Response ................................................................................................ 438
Table 219 — TPM2_NV_ReadLock Command ........................................................................................ 441
Table 220 — TPM2_NV_ReadLock Response ........................................................................................ 441
Table 221 — TPM2_NV_ChangeAuth Command .................................................................................... 445
Table 222 — TPM2_NV_ChangeAuth Response .................................................................................... 445
Table 223 — TPM2_NV_Certify Command .............................................................................................. 448
Table 224 — TPM2_NV_Certify Response .............................................................................................. 448


Family “2.0”                                            TCG Published                                                      Page xiii
Level 00 Revision 01.16                        Copyright © TCG 2006-2014                                      October 30, 2014
Trusted Platform Module Library                                                       Part 3: Commands


                              Trusted Platform Module Library
                                     Part 3: Commands

1     Scope

This TPM 2.0 Part 3 of the Trusted Platform Module Library specification contains the definitions of the
TPM commands. These commands make use of the constants, flags, structures, and union definitions
defined in TPM 2.0 Part 2.
The detailed description of the operation of the commands is written in the C language with extensive
comments. The behavior of the C code in this TPM 2.0 Part 3 is normative but does not fully describe the
behavior of a TPM. The combination of this TPM 2.0 Part 3 and TPM 2.0 Part 4 is sufficient to fully
describe the required behavior of a TPM.
The code in parts 3 and 4 is written to define the behavior of a compliant TPM. In some cases (e.g.,
firmware update), it is not possible to provide a compliant implementation. In those cases, any
implementation provided by the vendor that meets the general description of the function provided in TPM
2.0 Part 3 would be compliant.
The code in parts 3 and 4 is not written to meet any particular level of conformance nor does this
specification require that a TPM meet any particular level of conformance.


2     Terms and Definitions

For the purposes of this document, the terms and definitions given in TPM 2.0 Part 1 apply.


3     Symbols and abbreviated terms

For the purposes of this document, the symbols and abbreviated terms given in TPM 2.0 Part 1 apply.


4     Notation

4.1 Introduction

For the purposes of this document, the notation given in TPM 2.0 Part 1 applies.
Command and response tables use various decorations to indicate the fields of the command and the
allowed types. These decorations are described in this clause.

4.2    Table Decorations

The symbols and terms in the Notation column of Table 1 are used in the tables for the command
schematics. These values indicate various qualifiers for the parameters or descriptions with which they
are associated.


Family “2.0”                                TCG Published                                       Page 1
Level 00 Revision 01.16             Copyright © TCG 2006-2014                         October 30, 2014
Part 3: Commands                                                                      Trusted Platform Module Library

                             Table 1 — Command Modifiers and Decoration
  Notation     Meaning

     +         A Type decoration – When appended to a value in the Type column of a command, this symbol
               indicates that the parameter is allowed to use the “null” value of the data type (see "Conditional
               Types" in TPM 2.0 Part 2). The null value is usually TPM_RH_NULL for a handle or
               TPM_ALG_NULL for an algorithm selector.
     @         A Name decoration – When this symbol precedes a handle parameter in the “Name” column, it
               indicates that an authorization session is required for use of the entity associated with the handle.
               If a handle does not have this symbol, then an authorization session is not allowed.
    +PP        A Description modifier – This modifier may follow TPM_RH_PLATFORM in the “Description”
               column to indicate that Physical Presence is required when platformAuth/platformPolicy is
               provided.
    +{PP}      A Description modifier – This modifier may follow TPM_RH_PLATFORM to indicate that Physical
               Presence may be required when platformAuth/platformPolicy is provided. The commands with this
               notation may be in the setList or clearList of TPM2_PP_Commands().
    {NV}       A Description modifier – This modifier may follow the commandCode in the “Description” column
               to indicate that the command may result in an update of NV memory and be subject to rate
               throttling by the TPM. If the command code does not have this notation, then a write to NV
               memory does not occur as part of the command actions.
               NOTE        Any command that uses authorization may cause a write to NV if there is an authorization failure.
                           A TPM may use the occasion of command execution to update the NV copy of clock.

     {F}       A Description modifier – This modifier indicates that the “flushed” attribute will be SET in the
               TPMA_CC for the command. The modifier may follow the commandCode in the “Description”
               column to indicate that any transient handle context used by the command will be flushed from the
               TPM when the command completes. This may be combined with the {NV} modifier but not with the
               {E} modifier.
               EXAMPLE 1       {NV F}
               EXAMPLE 2       TPM2_SequenceComplete() will flush the context associated with the sequenceHandle.

     {E}       A Description modifier – This modifier indicates that the “extensive” attribute will be SET in the
               TPMA_CC for the command. This modifier may follow the commandCode in the “Description”
               column to indicate that the command may flush many objects and re-enumeration of the loaded
               context likely will be required. This may be combined with the {NV} modifier but not with the {F}
               modifier.
               EXAMPLE 1       {NV E}
               EXAMPLE 2       TPM2_Clear() will flush all contexts associated with the Storage hierarchy and the
                               Endorsement hierarchy.

 Auth Index:   A Description modifier – When a handle has a “@” decoration, the “Description” column will
               contain an “Auth Index:” entry for the handle. This entry indicates the number of the authorization
               session. The authorization sessions associated with handles will occur in the session area in the
               order of the handles with the “@” modifier. Sessions used only for encryption/decryption or only for
               audit will follow the handles used for authorization.


Page 2                                           TCG Published                                                Family “2.0”
October 30, 2014                        Copyright © TCG 2006-2014                            Level 00 Revision 01.16
Trusted Platform Module Library                                                                       Part 3: Commands


  Notation      Meaning

  Auth Role:    A Description modifier – This will be in the “Description” column of a handle with the “@”
                decoration. It may have a value of USER, ADMIN or DUP.
                If the handle has the Auth Role of USER and the handle is an Object, the type of authorization is
                determined by the setting of userWithAuth in the Object's attributes. If the handle is
                TPM_RH_OWNER, TPM_RH_ENDORSEMENT, or TPM_RH_PLATFORM, operation is as if
                userWithAuth is SET. If the handle references an NV Index, then the allowed authorizations are
                determined by the settings of the attributes of the NV Index as described in TPM 2.0 Part 2,
                "TPMA_NV (NV Index Attributes)."
                If the Auth Role is ADMIN and the handle is an Object, the type of authorization is determined by
                the setting of adminWithPolicy in the Object's attributes. If the handle is TPM_RH_OWNER,
                TPM_RH_ENDORSEMENT, or TPM_RH_PLATFORM, operation is as if adminWithPolicy is SET.
                If the handle is an NV index, operation is as if adminWithPolicy is SET (see 5.6 e)2)).
                If the DUP role is selected, authorization may only be with a policy session (DUP role only applies
                to Objects).
                When either ADMIN or DUP role is selected, a policy command that selects the command being
                authorized is required to be part of the policy.
                EXAMPLE    TPM2_Certify requires the ADMIN role for the first handle (objectHandle). The policy authorization
                           for objectHandle is required to contain TPM2_PolicyCommandCode(commandCode ==
                           TPM_CC_Certify). This sets the state of the policy so that it can be used for ADMIN role
                           authorization in TPM2_Certify().


4.3    Handle and Parameter Demarcation

The demarcations between the header, handle, and parameter parts are indicated by:

                                             Table 2 — Separators
               Separator            Meaning
                                    the values immediately following are in the handle area

                                    the values immediately following are in the parameter area


4.4    AuthorizationSize and ParameterSize

Authorization sessions are not shown in the command or response schematics. When the tag of a
command or response is TPM_ST_SESSIONS, then a 32-bit value will be present in the
command/response buffer to indicate the size of the authorization field or the parameter field. This value
shall immediately follow the handle area (which may contain no handles). For a command, this value
(authorizationSize) indicates the size of the Authorization Area and shall have a value of 9 or more. For a
response, this value (parameterSize) indicates the size of the parameter area and may have a value of
zero.
If the authorizationSize field is present in the command, parameterSize will be present in the response,
but only if the responseCode is TPM_RC_SUCCESS.
When authorization is required to use the TPM entity associated with a handle, then at least one session
will be present. To indicate this, the command tag Description field contains TPM_ST_SESSIONS.
Addional sessions for audit, encrypt, and decrypt may be present.
When the command tag Description field contains TPM_ST_NO_SESSIONS, then no sessions are
allowed and the authorizationSize field is not present.
When a command allows use of sessions when not required, the command tag Description field will
indicate the types of sessions that may be used with the command.


Family “2.0”                                     TCG Published                                                      Page 3
Level 00 Revision 01.16                 Copyright © TCG 2006-2014                                     October 30, 2014
Part 3: Commands                                                               Trusted Platform Module Library


5     Command Processing

5.1     Introduction

This clause defines the command validations that are required of any implementation and the response
code returned if the indicated check fails. Unless stated otherwise, the order of the checks is not
normative and different TPM may give different responses when a command has multiple errors.
In the description below, some statements that describe a check may be followed by a response code in
parentheses. This is the normative response code should the indicated check fail. A normative response
code may also be included in the statement.

5.2     Command Header Validation

Before a TPM may begin the actions associated with a command, a set of command format and
consistency checks shall be performed. These checks are listed below and should be performed in the
indicated order.
a) The TPM shall successfully unmarshal a TPMI_ST_COMMAND_TAG and verify that it is either
   TPM_ST_SESSIONS or TPM_ST_NO_SESSIONS (TPM_RC_BAD_TAG).
b) The TPM shall successfully unmarshal a UINT32 as the commandSize. If the TPM has an interface
   buffer that is loaded by some hardware process, the number of octets in the input buffer for the
   command reported by the hardware process shall exactly match the value in commandSize
   (TPM_RC_COMMAND_SIZE).

      NOTE          A TPM may have direct access to system memory and unmarshal direc tly from that memory.

c) The TPM shall successfully unmarshal a TPM_CC and verify that the command is implemented
   (TPM_RC_COMMAND_CODE).

5.3     Mode Checks

The following mode checks shall be performed in the order listed:
a) If the TPM is in Failure mode, then the commandCode is TPM_CC_GetTestResult or
   TPM_CC_GetCapability (TPM_RC_FAILURE) and the command tag is TPM_ST_NO_SESSIONS
   (TPM_RC_FAILURE).

      NOTE 1        In Failure mode, the TPM has no cryptographic capability and processing of sessions is not
                    supported.

b) The TPM is in Field Upgrade mode (FUM), the commandCode is TPM_CC_FieldUpgradeData
   (TPM_RC_UPGRADE).
c) If the TPM has not been initialized (TPM2_Startup()), then the commandCode is TPM_CC_Startup
   (TPM_RC_INITIALIZE).

      NOTE 2        The TPM may enter Failure mode during _TPM_Init processing, before TPM2_Startup(). Since
                    the platform firmware cannot know that the TPM is in Failure mode without accessing it, and
                    since the first command is required to be TPM2_Startup(), the expected sequence will be that
                    platform firmware (the CRTM) will issue TPM2_Startup() and receive TPM_RC_FAILURE
                    indicating that the TPM is in Failure mode.

                    There may be failures where a TPM cannot record that it received TPM2_Startup(). In those
                    cases, a TPM in failure mode may process TPM2_GetTestResult(), TPM2_GetCapability(), or
                    the field upgrade commands. As a side effect, that TPM may process TPM2_GetTestResult(),
                    TPM2_GetCapability() or the field upgrade commands before TPM2_Startup().

                    This is a corner case exception to the rule that TPM2_Startup() must be the first command.

Page 4                                        TCG Published                                         Family “2.0”
October 30, 2014                      Copyright © TCG 2006-2014                       Level 00 Revision 01.16
Trusted Platform Module Library                                                                      Part 3: Commands

The mode checks may be performed before or after the command header validation.

5.4 Handle Area Validation

After successfully unmarshaling and validating the command header, the TPM shall perform the following
checks on the handles and sessions. These checks may be performed in any order.

NOTE 1             A TPM is required to perform the handle area validation before the authorization checks because an
                   authorization cannot be performed unless the authorization values and attributes for the referenc ed
                   entity are known by the TPM. For them to be known, the referenced entity must be in the TPM and
                   accessible.

a) The TPM shall successfully unmarshal the number of handles required by the command and validate
   that the value of the handle is consistent with the command syntax. If not, the TPM shall return
   TPM_RC_VALUE.

    NOTE 2              The TPM may unmarshal a handle and validate that it references an entity on the TPM before
                        unmarshaling a subsequent handle.

    NOTE 3              If the submitted command contains fewer handles than re quired by the syntax of the command,
                        the TPM may continue to read into the next area and attempt to interpret the data as a handle.

b) For all handles in the handle area of the command, the TPM will validate that the referenced entity is
   present in the TPM.
    1) If the handle references a transient object, the handle shall reference a loaded object
       (TPM_RC_REFERENCE_H0 + N where N is the number of the handle in the command).

         NOTE 3             If the hierarchy for a transient object is disabled, then the transient objects will be flushed
                            so this check will fail.

    2) If the handle references a persistent object, then
         i)    the hierarchy associated with the object (platform or storage, based on the handle value) is
               enabled (TPM_RC_HANDLE);
         ii)   the handle shall reference a persistent object that is currently in TPM non-volatile memory
               (TPM_RC_HANDLE);
         iii) if the handle references a persistent object that is associated with the endorsement hierarchy,
              that the endorsement hierarchy is not disabled (TPM_RC_HANDLE); and

               NOTE 4           The reference implementation keeps an internal attribute, passed down from a primary
                                key to its descendents, indicating the object's hierarchy.

         iv) if the TPM implementation moves a persistent object to RAM for command processing then
             sufficient RAM space is available (TPM_RC_OBJECT_MEMORY).
    3) If the handle references an NV Index, then
         i)    an Index exists that corresponds to the handle (TPM_RC_HANDLE); and
         ii)   the hierarchy associated with the existing NV Index is not disabled (TPM_RC_HANDLE).
         iii) If the command requires write access to the index data then TPMA_NV_WRITELOCKED is
              not SET (TPM_RC_LOCKED)
         iv) If the command requires read access to the index data then TPMA_NV_READLOCKED is
             not SET (TPM_RC_LOCKED)
    4) If the handle references a session, then the session context shall be present in TPM memory
       (TPM_RC_REFERENCE_S0 + N).


Family “2.0”                                       TCG Published                                                  Page 5
Level 00 Revision 01.16                   Copyright © TCG 2006-2014                                  October 30, 2014
Part 3: Commands                                                                Trusted Platform Module Library

      5) If the handle references a primary seed for a hierarchy (TPM_RH_ENDORSEMENT,
         TPM_RH_OWNER, or TPM_RH_PLATFORM) then the enable for the hierarchy is SET
         (TPM_RC_HIERARCHY).
      6) If the handle references a PCR, then the value is within the range of PCR supported by the TPM
         (TPM_RC_VALUE)

          NOTE 5           In the reference implementation, this TPM_RC_VALUE is returned by the unmarshaling
                           code for a TPMI_DH_PCR.


5.5      Session Area Validation

a) If the tag is TPM_ST_SESSIONS and the command requires TPM_ST_NO_SESSIONS, the TPM will
   return TPM_RC_AUTH_CONTEXT.
b) If the tag is TPM_ST_NO_SESSIONS and the command requires TPM_ST_SESSIONS, the TPM will
   return TPM_RC_AUTH_MISSING.
c) If the tag is TPM_ST_SESSIONS, the TPM will attempt to unmarshal an authorizationSize and return
   TPM_RC_AUTHSIZE if the value is not within an acceptable range.
      1) The minimum value is (sizeof(TPM_HANDLE) + sizeof(UINT16) + sizeof(TPMA_SESSION) +
         sizeof(UINT16)).
      2) The maximum value of authorizationSize is equal to commandSize – (sizeof(TPM_ST) +
         sizeof(UINT32) + sizeof(TPM_CC) + (N * sizeof(TPM_HANDLE)) + sizeof(UINT32)) where N is
         the number of handles associated with the commandCode and may be zero.

          NOTE 1           (sizeof(TPM_ST) + sizeof(UINT32) + sizeof(TPM_CC)) is the size of a command header.
                           The last UINT32 contains the authorizationSize octets, which are not counted as being in
                           the authorization session area.

d) The TPM will unmarshal the authorization sessions and perform the following validations:
      1) If the session handle is not a handle for an HMAC session, a handle for a policy session, or,
         TPM_RS_PW then the TPM shall return TPM_RC_HANDLE.
      2) If the session is not loaded, the TPM will return the warning TPM_RC_REFERENCE_S0 + N
         where N is the number of the session. The first session is session zero, N = 0.

          NOTE 2           If the HMAC and policy session contexts use the same memory, the type of the context
                           must match the type of the handle.

      3) If the maximum allowed number of sessions have been unmarshaled and fewer octets than
         indicated in authorizationSize were unmarshaled (that is, authorizationSize is too large), the TPM
         shall return TPM_RC_AUTHSIZE.
      4) The consistency of the authorization session attributes is checked.
          i)   Only one session is allowed for:
               (a) session auditing (TPM_RC_ATTRIBUTES) – this session may be used for encrypt or
                   decrypt but may not be a session that is also used for authorization;
               (b) decrypting a command parameter (TPM_RC_ATTRIBUTES) – this may be any of the
                   authorization sessions, or the audit session, or a session may be added for the single
                   purpose of decrypting a command parameter, as long as the total number of sessions
                   does not exceed three; and
               (c) encrypting a response parameter (TPM_RC_ATTRIBUTES) – this may be any of the
                   authorization sessions, or the audit session if present, ora session may be added for the
                   single purpose of encrypting a response parameter, as long as the total number of
                   sessions does not exceed three.

Page 6                                            TCG Published                                      Family “2.0”
October 30, 2014                        Copyright © TCG 2006-2014                     Level 00 Revision 01.16
Trusted Platform Module Library                                                                    Part 3: Commands

                    NOTE 3            A session used for decrypting a command parameter may also be used for
                                      encrypting a response parameter.

          ii)   If a session is not being used for authorization, at least one of decrypt, encrypt, or audit must
                be SET. (TPM_RC_ATTRIBUTES).


      5) An authorization session is present for each of the handles with the “@” decoration
         (TPM_RC_AUTH_MISSING).


5.6      Authorization Checks

After unmarshaling and validating the handles and the consistency of the authorization sessions, the
authorizations shall be checked. Authorization checks only apply to handles if the handle in the command
schematic has the “@” decoration.
a) The public and sensitive portions                   of   the     object   shall   be     present      on     the   TPM
   (TPM_RC_AUTH_UNAVAILABLE).
b) If the associated handle is TPM_RH_PLATFORM, and the command requires confirmation with
   physical presence, then physical presence is asserted (TPM_RC_PP).
c) If the object or NV Index is subject to DA protection, and the authorization is with an HMAC or
   password, then the TPM is not in lockout (TPM_RC_LOCKOUT).

      NOTE 1            An object is subject to DA protection if its noDA attribute is CLEAR. An NV Index is subject to
                        DA protection if its TPMA_NV_NO_DA attribute is CLEAR.

      NOTE 2            An HMAC or password is required in a policy               session   when   the    policy   contains
                        TPM2_PolicyAuthValue() or TPM2_PolicyPassword().

d) If the command requires a handle to have DUP role authorization, then the associated authorization
   session is a policy session (TPM_RC_POLICY_FAIL).
e) If the command requires a handle to have ADMIN role authorization:
      1) If the entity being authorized is an object and its adminWithPolicy attribute is SET, or a hierarchy,
         then the authorization session is a policy session (TPM_RC_POLICY_FAIL).

          NOTE 3             If adminWithPolicy is CLEAR, then any type of authorization session is allowed .

      2) If the entity being authorized is an NV Index, then the associated authorization session is a policy
         session.

          NOTE 4             The only commands that are currently defined that require use of ADMIN role authorization
                             are commands that operate on objects and NV Indices.

f)    If the command requires a handle to have USER role authorization:
      1) If the entity being authorized is an object and its userWithAuth attribute is CLEAR, then the
         associated authorization session is a policy session (TPM_RC_POLICY_FAIL).

          NOTE 5             There is no check for a hierarchy, because a hierarchy operates as if userWithAuth is SET.

      2) If the entity being authorized is an NV Index;
          i)    if the authorization session is a policy session;
                (a) the TPMA_NV_POLICYWRITE attribute of the NV Index is SET if the command modifies
                    the NV Index data (TPM_RC_AUTH_UNAVAILABLE);

Family “2.0”                                       TCG Published                                                   Page 7
Level 00 Revision 01.16                    Copyright © TCG 2006-2014                               October 30, 2014
Part 3: Commands                                                               Trusted Platform Module Library

               (b) the TPMA_NV_POLICYREAD attribute of the NV Index is SET if the command reads the
                   NV Index data (TPM_RC_AUTH_UNAVAILABLE);
         ii)   if the authorization is an HMAC session or a password;
               (a) the TPMA_NV_AUTHWRITE attribute of the NV Index is SET if the command modifies
                   the NV Index data (TPM_RC_AUTH_UNAVAILABLE);
               (b) the TPMA_NV_AUTHREAD attribute of the NV Index is SET if the command reads the
                   NV Index data (TPM_RC_AUTH_UNAVAILABLE).
g) If the authorization is provided by a policy session, then:
      1) if policySession→timeOut          has     been    set,   the   session   shall     not   have     expired
         (TPM_RC_EXPIRED);
      2) if policySession→cpHash has been set, it shall match the cpHash of the command
         (TPM_RC_POLICY_FAIL);
      3) if policySession→commandCode has been set, then commandCode of the command shall match
         (TPM_RC_POLICY_CC);
      4) policySession→policyDigest       shall    match    the   authPolicy   associated     with   the   handle
         (TPM_RC_POLICY_FAIL);
      5) if policySession→pcrUpdateCounter has been set, then it shall match the value of
         pcrUpdateCounter (TPM_RC_PCR_CHANGED);
      6) if policySession->commandLocality has been set, it shall match the locality of the command
         (TPM_RC_LOCALITY), and
h) if the authorization uses an HMAC, then the HMAC is properly constructed using the authValue
   associated with the handle and/or the session secret (TPM_RC_AUTH_FAIL or
   TPM_RC_BAD_AUTH).

         NOTE 6            A policy session may require proof of knowledge of the authValue of the object being
                           authorized.

i)    if the authorization uses a password, then the password matches the authValue associated with the
      handle (TPM_RC_AUTH_FAIL or TPM_RC_BAD_AUTH).
If the TPM returns an error other than TPM_RC_AUTH_FAIL then the TPM shall not alter any TPM state.
If the TPM return TPM_RC_AUTH_FAIL, then the TPM shall not alter any TPM state other than
lockoutCount.

NOTE 7             The TPM may decrease failedTries regardless of any other processing performed by the TPM. That
                   is, the TPM may exit Lockout mode, regardless of the return code.


5.7      Parameter Decryption

If an authorization session has the TPMA_SESSION.decrypt attribute SET, and the command does not
allow a command parameter to be encrypted, then the TPM will return TPM_RC_ATTRIBUTES.
Otherwise, the TPM will decrypt the parameter using the values associated with the session before
parsing parameters.

5.8      Parameter Unmarshaling

5.8.1    Introduction

The detailed actions for each command assume that the input parameters of the command have been
unmarshaled into a command-specific structure with the structure defined by the command schematic.


Page 8                                            TCG Published                                      Family “2.0”
October 30, 2014                        Copyright © TCG 2006-2014                    Level 00 Revision 01.16
Trusted Platform Module Library                                                             Part 3: Commands

Additionally, a response-specific output structure is assumed which will receive the values produced by
the detailed actions.

NOTE            An implementation is not required to process parameters in this manner or to separate the
                parameter parsing from the command actions. This method was chosen for the specification so that
                the normative behavior described by the detailed actions would be clear and unencumbered.

Unmarshaling is the process of processing the parameters in the input buffer and preparing the
parameters for use by the command-specific action code. No data movement need take place but it is
required that the TPM validate that the parameters meet the requirements of the expected data type as
defined in TPM 2.0 Part 2.

5.8.2   Unmarshaling Errors

When an error is encountered while unmarshaling a command parameter, an error response code is
returned and no command processing occurs. A table defining a data type may have response codes
embedded in the table to indicate the error returned when the input value does not match the parameters
of the table.

NOTE            In the reference implementation, a parameter number is added to the response code so that the
                offending parameter can be isolated. This is optional.

In many cases, the table contains no specific response code value and the return code will be determined
as defined in Table 3.


Family “2.0”                                  TCG Published                                             Page 9
Level 00 Revision 01.16               Copyright © TCG 2006-2014                            October 30, 2014
Part 3: Commands                                                               Trusted Platform Module Library

                                    Table 3 — Unmarshaling Errors
 Response Code                 Meaning

 TPM_RC_ASYMMETRIC             a parameter that should be an asymmetric algorithm selection does not have a
                               value that is supported by the TPM
 TPM_RC_BAD_TAG                a parameter that should be a command tag selection has a value that is not
                               supported by the TPM
 TPM_RC_COMMAND_CODE           a parameter that should be a command code does not have a value that is
                               supported by the TPM
 TPM_RC_HASH                   a parameter that should be a hash algorithm selection does not have a value that
                               is supported by the TPM
 TPM_RC_INSUFFICIENT           the input buffer did not contain enough octets to allow unmarshaling of the
                               expected data type;
 TPM_RC_KDF                    a parameter that should be a key derivation scheme (KDF) selection does not
                               have a value that is supported by the TPM
 TPM_RC_KEY_SIZE               a parameter that is a key size has a value that is not supported by the TPM
 TPM_RC_MODE                   a parameter that should be a symmetric encryption mode selection does not have
                               a value that is supported by the TPM
 TPM_RC_RESERVED               a non-zero value was found in a reserved field of an attribute structure (TPMA_)
 TPM_RC_SCHEME                 a parameter that should be signing or encryption scheme selection does not have
                               a value that is supported by the TPM
 TPM_RC_SIZE                   the value of a size parameter is larger or smaller than allowed
 TPM_RC_SYMMETRIC              a parameter that should be a symmetric algorithm selection does not have a
                               value that is supported by the TPM
 TPM_RC_TAG                    a parameter that should be a structure tag has a value that is not supported by
                               the TPM
 TPM_RC_TYPE                   The type parameter of a TPMT_PUBLIC or TPMT_SENSITIVE has a value that is
                               not supported by the TPM
 TPM_RC_VALUE                  a parameter does not have one of its allowed values

In some commands, a parameter may not be used because of various options of that command.
However, the unmarshaling code is required to validate that all parameters have values that are allowed
by the TPM 2.0 Part 2 definition of the parameter type even if that parameter is not used in the command
actions.

5.9    Command Post Processing

When the code that implements the detailed actions of the command completes, it returns a response
code. If that code is not TPM_RC_SUCCESS, the post processing code will not update any session or
audit data and will return a 10-octet response packet.
If the command completes successfully, the tag of the command determines if any authorization sessions
will be in the response. If so, the TPM will encrypt the first parameter of the response if indicated by the
authorization attributes. The TPM will then generate a new nonce value for each session and, if
appropriate, generate an HMAC.
If authorization HMAC computations are performed on the response, the HMAC keys used in the
response will be the same as the HMAC keys used in processing the HMAC in the command.


Page 10                                       TCG Published                                         Family “2.0”
October 30, 2014                     Copyright © TCG 2006-2014                        Level 00 Revision 01.16
Trusted Platform Module Library                                                              Part 3: Commands

NOTE 1         This primarily affects authorizations associated with a first write to an NV Index using a bound
               session. The computation of the HMAC in the response is performed as if the Name of the Index did
               not change as a consequence of the command actions. The session binding to the NV Index will not
               persist to any subsequent command.

NOTE 2         The authorization attributes were validated during the session area validation to ensure that only
               one session was used for parameter encryption of the response and that the command allowed
               encryption in the response.

NOTE 3         No session nonce value is used for a password authorization but the session data is present.

Additionally, if the command is being audited by Command Audit, the audit digest is updated with the
cpHash of the command and rpHash of the response.


Family “2.0”                                  TCG Published                                             Page 11
Level 00 Revision 01.16              Copyright © TCG 2006-2014                               October 30, 2014
Part 3: Commands                                                          Trusted Platform Module Library


6     Response Values

6.1    Tag

When a command completes successfully, the tag parameter in the response shall have the same value
as the tag parameter in the command (TPM_ST_SESSIONS or TPM_RC_NO_SESSIONS). When a
command fails (the responseCode is not TPM_RC_SUCCESS), then the tag parameter in the response
shall be TPM_ST_NO_SESSIONS.
A special case exists when the command tag parameter is not an allowed value (TPM_ST_SESSIONS or
TPM_ST_NO_SESSIONS). For this case, it is assumed that the system software is attempting to send a
command formatted for a TPM 1.2 but the TPM is not capable of executing TPM 1.2 commands. So that
the TPM 1.2 compatible software will have a recognizable response, the TPM sets tag to
TPM_ST_RSP_COMMAND, responseSize to 00 00 00 0A16 and responseCode to TPM_RC_BAD_TAG.
This is the same response as the TPM 1.2 fatal error for TPM_BADTAG.

6.2    Response Codes

The normal response for any command is TPM_RC_SUCCESS. Any other value indicates that the
command did not complete and the state of the TPM is unchanged. An exception to this general rule is
that the logic associated with dictionary attack protection is allowed to be modified when an authorization
failure occurs.
Commands have response codes that are specific to that command, and those response codes are
enumerated in the detailed actions of each command. The codes associated with the unmarshaling of
parameters are documented Table 3. Another set of response code values are not command specific and
indicate a problem that is not specific to the command. That is, if the indicated problem is remedied, the
same command could be resubmitted and may complete normally.
The response codes that are not command specific are listed and described in Table 4.
The reference code for the command actions may have code that generates specific response codes
associated with a specific check but the listing of responses may not have that response code listed.


Page 12                                     TCG Published                                    Family “2.0”
October 30, 2014                     Copyright © TCG 2006-2014                  Level 00 Revision 01.16
Trusted Platform Module Library                                                                 Part 3: Commands

                        Table 4 — Command-Independent Response Codes
Response Code                Meaning

                             This response code may be returned by a TPM that supports command cancel.
                             When the TPM receives an indication that the current command should be
TPM_RC_CANCELED              cancelled, the TPM may complete the command or return this code. If this code
                             is returned, then the TPM state is not changed and the same command may be
                             retried.
                             This response code can be returned for commands that manage session
                             contexts. It indicates that the gap between the lowest numbered active session
TPM_RC_CONTEXT_GAP           and the highest numbered session is at the limits of the session tracking logic.
                             The remedy is to load the session context with the lowest number so that its
                             tracking number can be updated.
                             This response indicates that authorizations for objects subject to DA protection
TPM_RC_LOCKOUT               are not allowed at this time because the TPM is in DA lockout mode. The remedy
                             is to wait or to exeucte TPM2_DictionaryAttackLockoutReset().
                             A TPM may use a common pool of memory for objects, sessions, and other
                             purposes. When the TPM does not have enough memory available to perform
                             the actions of the command, it may return TPM_RC_MEMORY. This indicates
TPM_RC_MEMORY                that the TPM resource manager may flush either sessions or objects in order to
                             make memory available for the command execution. A TPM may choose to
                             return TPM_RC_OBJECT_MEMORY or TPM_RC_SESSION_MEMORY if it
                             needs contexts of a particular type to be flushed.
                             This response code indicates that the TPM is rate-limiting writes to the NV
                             memory in order to prevent wearout. This response is possible for any command
TPM_RC_NV_RATE               that explicity writes to NV or commands that incidentally use NV such as a
                             command that uses authorization session that may need to update the dictionary
                             attack logic.
                             This response code is similar to TPM_RC_NV_RATE but indicates that access to
                             NV memory is currently not available and the command is not allowed to proceed
TPM_RC_NV_UNAVAILABLE
                             until it is. This would occur in a system where the NV memory used by the TPM
                             is not exclusive to the TPM and is a shared system resource.
                             This response code indicates that the TPM has exhausted its handle space and
                             no new objects can be loaded unless the TPM is rebooted. This does not occur in
                             the reference implementation because of the way that object handles are
TPM_RC_OBJECT_HANDLES
                             allocated. However, other implementations are allowed to assign each object a
                             unique handle each time the object is loaded. A TPM using this implementation
                                                    24
                             would be able to load 2 objects before the object space is exhausted.
                             This response code can be returned by any command that causes the TPM to
                             need an object 'slot'. The most common case where this might be returned is
                             when an object is loaded (TPM2_Load, TPM2_CreatePrimary(), or
                             TPM2_ContextLoad()). However, the TPM implementation is allowed to use
                             object slots for other reasons. In the reference implementation, the TPM copies a
TPM_RC_OBJECT_MEMORY
                             referenced persistent object into RAM for the duration of the commannd. If all the
                             slots are previously occupied, the TPM may return this value. A TPM is allowed
                             to use object slots for other purposes and return this value. The remedy when
                             this response is returned is for the TPM resource manager to flush a transient
                             object.
                             This response code indicates that a handle in the handle area of the command is
                             not associated with a loaded object. The value of 'x' is in the range 0 to 6 with a
                                                         st                                 th
                             value of 0 indicating the 1 handle and 6 representing the 7 . Upper values are
TPM_RC_REFERENCE_Hx          provided for future use. The TPM resource manager needs to find the correct
                             object and load it. It may then adjust the handle and retry the command.
                             NOTE       Usually, this error indicates that the TPM resource manager has a corrupted
                                        database.


Family “2.0”                               TCG Published                                                    Page 13
Level 00 Revision 01.16             Copyright © TCG 2006-2014                                  October 30, 2014
Part 3: Commands                                                                Trusted Platform Module Library


Response Code                 Meaning

                              This response code indicates that a handle in the session area of the command
                              is not associated with a loaded session. The value of 'x' is in the range 0 to 6 with
                                                           st                                          th
                              a value of 0 indicating the 1 session handle and 6 representing the 7 . Upper
TPM_RC_REFERENCE_Sx           values are provided for future use. The TPM resource manager needs to find the
                              correct session and load it. It may then retry the command.
                              NOTE Usually, this error indicates that the TPM resource manager has a
                              corrupted database.
TPM_RC_RETRY                  the TPM was not able to start the command
                       This response code indicates that the TPM does not have a handle to assign to a
                       new session. This respose is only returned by TPM2_StartAuthSession(). It is
TPM_RC_SESSION_HANDLES
                       listed here because the command is not in error and the TPM resource manager
                       can remedy the situation by flushing a session (TPM2_FlushContext().
                              This response code can be returned by any command that causes the TPM to
                              need a session 'slot'. The most common case where this might be returned is
                              when a session is loaded (TPM2_StartAuthSession() or TPM2_ContextLoad()).
TPM_RC_SESSION_MEMORY
                              However, the TPM implementation is allowed to use object slots for other
                              purposes. The remedy when this response is returned is for the TPM resource
                              manager to flush a transient object.
                              Normal completion for any command. If the responseCode is
                              TPM_RC_SUCCESS, then the rest of the response has the format indicated in
TPM_RC_SUCCESS
                              the response schematic. Otherwise, the response is a 10 octet value indicating
                              an error.
                              This response code indicates that the TPM is performing tests and cannot
TPM_RC_TESTING
                              respond to the request at this time. The command may be retried.
                              the TPM has suspended operation on the command; forward progress was made
                              and the command may be retried.
TPM_RC_YIELDED
                              See TPM 2.0 Part 1, “Multi-tasking.”
                              NOTE        This cannot occur on the reference implementation.


Page 14                                      TCG Published                                           Family “2.0”
October 30, 2014                     Copyright © TCG 2006-2014                          Level 00 Revision 01.16
Trusted Platform Module Library                                                        Part 3: Commands


7   Implementation Dependent

The actions code for each command makes assumptions about the behavior of various sub-systems.
There are many possible implementations of the subsystems that would achieve equivalent results. The
actions code is not written to anticipate all possible implementations of the sub-systems. Therefore, it is
the responsibility of the implementer to ensure that the necessary changes are made to the actions code
when the sub-system behavior changes.


Family “2.0”                                TCG Published                                        Page 15
Level 00 Revision 01.16              Copyright © TCG 2006-2014                         October 30, 2014
Part 3: Commands                                                                Trusted Platform Module Library


8     Detailed Actions Assumptions

8.1       Introduction

The C code in the Detailed Actions for each command is written with a set of assumptions about the
processing performed before the action code is called and the processing that will be done after the
action code completes.

8.2       Pre-processing

Before calling the command actions code, the following actions have occurred.
         Verification that the handles in the handle area reference entities that are resident on the TPM.

      NOTE            If a handle is in the parameter portion of the command, the associated entity does not have to
                      be loaded, but the handle is required to be the correct type.

         If use of a handle requires authorization, the Password, HMAC, or Policy session associated with
          the handle has been verified.
         If a command parameter was encrypted using parameter encryption, it was decrypted before
          being unmarshaled.
         If the command uses handles or parameters, the calling stack contains a pointer to a data
          structure (in) that holds the unmarshaled values for the handles and command parameters. If
          the response has handles or parameters, the calling stack contains a pointer to a data structure
          (out) to hold the handles and response parameters generated by the command.
         All parameters of the in structure have been validated and meet the requirements of the
          parameter type as defined in TPM 2.0 Part 2.
         Space set aside for the out structure is sufficient to hold the largest out structure that could be
          produced by the command

8.3       Post Processing

When the function implementing the command actions completes,
         response parameters that require parameter encryption will be encrypted after the command
          actions complete;
         audit and session contexts will be updated if the command response is TPM_RC_SUCCESS;
          and
         the command header and command response parameters will be marshaled to the response
          buffer.


Page 16                                         TCG Published                                        Family “2.0”
October 30, 2014                        Copyright © TCG 2006-2014                      Level 00 Revision 01.16
Trusted Platform Module Library                                                               Part 3: Commands


9     Start-up

9.1      Introduction

This clause contains the commands used to manage the startup and restart state of a TPM.

9.2      _TPM_Init

9.2.1 General Description

_TPM_Init initializes a TPM.
Initialization actions include testing code required to execute the next expected command. If the TPM is in
FUM, the next expected command is TPM2_FieldUpgradeData(); otherwise, the next expected command
is TPM2_Startup().

NOTE 1           If the TPM performs self-tests after receiving _TPM_Init() and the TPM enters Failure mode before
                 receiving TPM2_Startup() or TPM2_FieldUpgradeData(), then the TPM may be able to accept
                 TPM2_GetTestResult() or TPM2_GetCapability().

The means of signaling _TPM_Init shall be defined in the platform-specific specifications that define the
physical interface to the TPM. The platform shall send this indication whenever the platform starts its boot
process and only when the platform starts its boot process.
There shall be no software method of generating this indication that does not also reset the platform and
begin execution of the CRTM.

NOTE 2           In the reference implementation, this signal causes an internal flag ( s_initialized) to be CLEAR.
                 While this flag is CLEAR, the TPM will only accept the next expected command described above.


Family “2.0”                                   TCG Published                                             Page 17
Level 00 Revision 01.16                Copyright © TCG 2006-2014                              October 30, 2014
     Part 3: Commands                                                 Trusted Platform Module Library


     9.2.2   Detailed Actions

     This function is used to process a _TPM_Init() indication.

 1   #include "InternalRoutines.h"
 2   LIB_EXPORT void
 3   _TPM_Init(
 4       void
 5       )
 6   {
 7       // Clear the failure mode flags
 8       g_inFailureMode = FALSE;
 9       g_forceFailureMode = FALSE;
10
11       // Initialize the NvEnvironment.
12       g_nvOk = NvPowerOn();
13
14       // Initialize crypto engine
15       CryptInitUnits();
16
17       // Start clock
18       TimePowerOn();
19
20       // Set initialization state
21       TPMInit();
22
23       // Initialize object table
24       ObjectStartup();
25
26       // Set g_DRTMHandle as unassigned
27       g_DRTMHandle = TPM_RH_UNASSIGNED;
28
29       // No H-CRTM, yet.
30       g_DrtmPreStartup = FALSE;
31
32       return;
33   }


     Page 18                                      TCG Published                         Family “2.0”
     October 30, 2014                     Copyright © TCG 2006-2014        Level 00 Revision 01.16
Trusted Platform Module Library                                                                  Part 3: Commands


9.3       TPM2_Startup

9.3.1 General Description

TPM2_Startup() is always preceded by _TPM_Init, which is the physical indication that TPM initialization
is necessary because of a system-wide reset. TPM2_Startup() is only valid after _TPM_Init. Additional
TPM2_Startup() commands are not allowed after it has completed successfully. If a TPM requires
TPM2_Startup() and another command is received, or if the TPM receives TPM2_Startup() when it is not
required, the TPM shall return TPM_RC_INITIALIZE.

NOTE 1            See 9.2.1 for other command options for a TPM supporting field upgrade mode.

NOTE 2            _TPM_Hash_Start, _TPM_Hash_Data, and _TPM_Hash_End are not commands and a platform -
                  specific specification may allow t hese indications between _TPM_Init and TPM2_Startup().

If in Failure mode, the TPM shall accept TPM2_GetTestResult() and TPM2_GetCapability() even if
TPM2_Startup() is not completed successfully or processed at all.
A platform-specific specification may restrict the localities at which TPM2_Startup() may be received.
A Shutdown/Startup sequence determines the way in which the TPM will operate in response to
TPM2_Startup(). The three sequences are:
1) TPM Reset – This is a Startup(CLEAR) preceded by either Shutdown(CLEAR) or no
   TPM2_Shutdown(). On TPM Reset, all variables go back to their default initialization state.

      NOTE 3          Only those values that are specified as having a default initialization state are changed by TPM
                      Reset. Persistent values that have no defa ult initialization state are not changed by this
                      command. Values such as seeds have no default initialization state and only change due to
                      specific commands.

2) TPM Restart – This is a Startup(CLEAR) preceded by Shutdown(STATE). This preserves much of the
   previous state of the TPM except that PCR and the controls associated with the Platform hierarchy
   are all returned to their default initialization state;
3) TPM Resume – This is a Startup(STATE) preceded by Shutdown(STATE). This preserves the
   previous state of the TPM including the static Root of Trust for Measurement (S-RTM) PCR and the
   platform controls other than the phEnable and phEnableNV.
If a TPM receives Startup(STATE) and that was not preceded by Shutdown(STATE), the TPM shall return
TPM_RC_VALUE.
If, during TPM Restart or TPM Resume, the TPM fails to restore the state saved at the last
Shutdown(STATE), the TPM shall enter Failure Mode and return TPM_RC_FAILURE.
On any TPM2_Startup(),
         phEnable and phEnableNV shall be SET;
         all transient contexts (objects, sessions, and sequences) shall be flushed from TPM memory;
         TPMS_TIME_INFO.time shall be reset to zero; and
         use of lockoutAuth shall be enabled if lockoutRecovery is zero.
Additional actions are performed based on the Shutdown/Startup sequence.
On TPM Reset


Family “2.0”                                    TCG Published                                              Page 19
Level 00 Revision 01.16                 Copyright © TCG 2006-2014                                October 30, 2014
Part 3: Commands                                                                 Trusted Platform Module Library


      platformAuth and platformPolicy shall be set to the Empty Buffer,
      For each NV index with TPMA_NV_WRITE_DEFINE CLEAR or TPMA_NV_WRITTEN CLEAR,
       TPMA_NV_WRITELOCKED shall be CLEAR,
      For each NV index with TPMA_NV_CLEAR_STCLEAR SET, TPMA_NV_WRITTEN shall be
       CLEAR,
      tracking data for saved session contexts shall be set to its initial value,
      the object context sequence number is reset to zero,
      a new context encryption key shall be generated,
      TPMS_CLOCK_INFO.restartCount shall be reset to zero,
      TPMS_CLOCK_INFO.resetCount shall be incremented,
      the PCR Update Counter shall be clear to zero,
      shEnable and ehEnable shall be SET, and
      PCR in all banks are reset to their default initial conditions as determined by the relevant
       platform-specific specification and the H-CRTM state (for exceptions, see TPM 2.0 Part 1, H-
       CRTM before TPM2_Startup() and TPM2_Startup without H-CRTM)

   NOTE 4           PCR may be initialized any time between _TPM_Init and the end of TPM2_Startup(). PCR that
                    are preserved by TPM Resume will need to be restored during TPM2_Startup().

   NOTE 5           See "Initializing PCR" in TPM 2.0 Part 1 for a description of the default initial conditions for a
                    PCR.

On TPM Restart
      TPMS_CLOCK_INFO.restartCount shall be incremented,
      shEnable and ehEnable shall be SET,
      platformAuth and platformPolicy shall be set to the Empty Buffer,
      For each NV index with TPMA_NV_WRITE_DEFINE CLEAR or TPMA_NV_WRITTEN CLEAR,
       TPMA_NV_WRITELOCKED shall be CLEAR,
      For each NV index with TPMA_NV_CLEAR_STCLEAR SET, TPMA_NV_WRITTEN shall be
       CLEAR, and
      PCR in all banks are reset to their default initial conditions.
      If an H-CRTM Event Sequence is active, extend the PCR designated by the platform-specific
       specification.
On TPM Resume
      the H-CRTM startup method is the same for this TPM2_Startup() as for the previous
       TPM2_Startup(); (TPM_RC_LOCALITY)
      TPMS_CLOCK_INFO.restartCount shall be incremented; and
      PCR that are specified in a platform-specific specification to be preserved on TPM Resume are
       restored to their saved state and other PCR are set to their initial value as determined by a
       platform-specific specification. For constraints, see TPM 2.0 Part 1, H-CRTM before
       TPM2_Startup() and TPM2_Startup without H-CRTM.
Other TPM state may change as required to meet the needs of the implementation.
If the startupType is TPM_SU_STATE and the TPM requires TPM_SU_CLEAR, then the TPM shall return
TPM_RC_VALUE.


Page 20                                        TCG Published                                           Family “2.0”
October 30, 2014                      Copyright © TCG 2006-2014                         Level 00 Revision 01.16
Trusted Platform Module Library                                                        Part 3: Commands

NOTE 6         The TPM will require     TPM_SU_CLEAR      when   no   shutdown   was   performed   or   after
               Shutdown(CLEAR).

NOTE 7         If startupType is neither TPM_SU_STATE nor TPM_SU_CLEAR, then the unmarshaling code returns
               TPM_RC_VALUE.


Family “2.0”                               TCG Published                                           Page 21
Level 00 Revision 01.16            Copyright © TCG 2006-2014                           October 30, 2014
Part 3: Commands                                                Trusted Platform Module Library


9.3.2    Command and Response

                           Table 5 — TPM2_Startup Command
Type                     Name                  Description

TPMI_ST_COMMAND_TAG      tag                   TPM_ST_NO_SESSIONS
UINT32                   commandSize
TPM_CC                   commandCode           TPM_CC_Startup {NV}

TPM_SU                   startupType           TPM_SU_CLEAR or TPM_SU_STATE


                           Table 6 — TPM2_Startup Response
Type                     Name                  Description

TPM_ST                   tag                   see clause 6
UINT32                   responseSize
TPM_RC                   responseCode


Page 22                                 TCG Published                             Family “2.0”
October 30, 2014               Copyright © TCG 2006-2014             Level 00 Revision 01.16
     Trusted Platform Module Library                                                             Part 3: Commands


     9.3.3   Detailed Actions

1    #include "InternalRoutines.h"
2    #include "Startup_fp.h"
3    #ifdef TPM_CC_Startup // Conditional expansion of this file


     Error Returns                     Meaning

     TPM_RC_LOCALITY                   a Startup(STATE) does not have the same H-CRTM state as the
                                       previous Startup() or the locality of the startup is not 0 pr 3
     TPM_RC_NV_UNINITIALIZED           the saved state cannot be recovered and a Startup(CLEAR) is
                                       requried.
     TPM_RC_VALUE                      start up type is not compatible with previous shutdown sequence

 4   TPM_RC
 5   TPM2_Startup(
 6       Startup_In        *in                 // IN: input parameter list
 7       )
 8   {
 9       STARTUP_TYPE            startup;
10       TPM_RC                  result;
11       BOOL                    prevDrtmPreStartup;
12       BOOL                    prevStartupLoc3;
13       BYTE                    locality = _plat__LocalityGet();
14
15       // In the PC Client specification, only locality 0 and 3 are allowed
16       if(locality != 0 && locality != 3)
17           return TPM_RC_LOCALITY;
18       // Indicate that the locality was 3 unless there was an H-CRTM
19       if(g_DrtmPreStartup)
20           locality = 0;
21       g_StartupLocality3 = (locality == 3);
22
23       // The command needs NV update. Check if NV is available.
24       // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
25       // this point
26       result = NvIsAvailable();
27       if(result != TPM_RC_SUCCESS)
28           return result;
29
30   // Input Validation
31
32       // Read orderly shutdown states from previous power cycle
33       NvReadReserved(NV_ORDERLY, &g_prevOrderlyState);
34
35       // See if the orderly state indicates that state was saved
36       if(     (g_prevOrderlyState & ~(PRE_STARTUP_FLAG | STARTUP_LOCALITY_3))
37           == TPM_SU_STATE)
38       {
39           // If so, extrat the saved flags (HACK)
40           prevDrtmPreStartup = (g_prevOrderlyState & PRE_STARTUP_FLAG) != 0;
41           prevStartupLoc3 = (g_prevOrderlyState & STARTUP_LOCALITY_3) != 0;
42           g_prevOrderlyState = TPM_SU_STATE;
43       }
44       else
45       {
46           prevDrtmPreStartup = 0;
47           prevStartupLoc3 = 0;
48       }
49       // if this startup is a TPM Resume, then the H-CRTM states have to match.
50       if(in->startupType == TPM_SU_STATE)

     Family “2.0”                                  TCG Published                                         Page 23
     Level 00 Revision 01.16               Copyright © TCG 2006-2014                             October 30, 2014
      Part 3: Commands                                               Trusted Platform Module Library

 51      {
 52             if(g_DrtmPreStartup != prevDrtmPreStartup)
 53                 return TPM_RC_VALUE + RC_Startup_startupType;
 54             if(g_StartupLocality3 != prevStartupLoc3)
 55                 return TPM_RC_LOCALITY;
 56      }
 57
 58      // if the previous power cycle was shut down with no StateSave command, or
 59      // with StateSave command for CLEAR, or the part of NV used for TPM_SU_STATE
 60      // cannot be recovered, then this cycle can not startup up with STATE
 61      if(in->startupType == TPM_SU_STATE)
 62      {
 63          if(     g_prevOrderlyState == SHUTDOWN_NONE
 64             ||   g_prevOrderlyState == TPM_SU_CLEAR)
 65              return TPM_RC_VALUE + RC_Startup_startupType;
 66
 67             if(g_nvOk == FALSE)
 68                 return TPM_RC_NV_UNINITIALIZED;
 69      }
 70
 71   // Internal Date Update
 72
 73      // Translate the TPM2_ShutDown and TPM2_Startup sequence into the startup
 74      // types. Will only be a SU_RESTART if the NV is OK
 75      if(     in->startupType == TPM_SU_CLEAR
 76          && g_prevOrderlyState == TPM_SU_STATE
 77          && g_nvOk == TRUE)
 78      {
 79          startup = SU_RESTART;
 80          // Read state reset data
 81          NvReadReserved(NV_STATE_RESET, &gr);
 82      }
 83      // In this check, we don't need to look at g_nvOk because that was checked
 84      // above
 85      else if(in->startupType == TPM_SU_STATE && g_prevOrderlyState == TPM_SU_STATE)
 86      {
 87          // Read state clear and state reset data
 88          NvReadReserved(NV_STATE_CLEAR, &gc);
 89          NvReadReserved(NV_STATE_RESET, &gr);
 90          startup = SU_RESUME;
 91      }
 92      else
 93      {
 94          startup = SU_RESET;
 95      }
 96
 97      // Read persistent data from NV
 98      NvReadPersistent();
 99
100      // Crypto Startup
101      CryptUtilStartup(startup);
102
103      // Read the platform unique value that is used as VENDOR_PERMANENT auth value
104      g_platformUniqueDetails.t.size = (UINT16)_plat__GetUnique(1,
105                                         sizeof(g_platformUniqueDetails.t.buffer),
106                                         g_platformUniqueDetails.t.buffer);
107
108      // Start up subsystems
109      // Start counters and timers
110      TimeStartup(startup);
111
112      // Start dictionary attack subsystem
113      DAStartup(startup);
114
115      // Enable hierarchies
116      HierarchyStartup(startup);

      Page 24                                  TCG Published                             Family “2.0”
      October 30, 2014                  Copyright © TCG 2006-2014          Level 00 Revision 01.16
      Trusted Platform Module Library                                              Part 3: Commands

117
118       // Restore/Initialize PCR
119       PCRStartup(startup, locality);
120
121       // Restore/Initialize command audit information
122       CommandAuditStartup(startup);
123
124       // Object context variables
125       if(startup == SU_RESET)
126       {
127           // Reset object context ID to 0
128           gr.objectContextID = 0;
129           // Reset clearCount to 0
130           gr.clearCount= 0;
131       }
132
133       // Initialize session table
134       SessionStartup(startup);
135
136       // Initialize index/evict data.   This function clear read/write locks
137       // in NV index
138       NvEntityStartup(startup);
139
140       // Initialize the orderly shut down flag for this cycle to SHUTDOWN_NONE.
141       gp.orderlyState = SHUTDOWN_NONE;
142       NvWriteReserved(NV_ORDERLY, &gp.orderlyState);
143
144       // Update TPM internal states if command succeeded.
145       // Record a TPM2_Startup command has been received.
146       TPMRegisterStartup();
147
148       // The H-CRTM state no longer matters
149       g_DrtmPreStartup = FALSE;
150
151       return TPM_RC_SUCCESS;
152
153   }
154   #endif // CC_Startup


      Family “2.0”                              TCG Published                              Page 25
      Level 00 Revision 01.16           Copyright © TCG 2006-2014                  October 30, 2014
Part 3: Commands                                                       Trusted Platform Module Library


9.4       TPM2_Shutdown

9.4.1 General Description

This command is used to prepare the TPM for a power cycle. The shutdownType parameter indicates
how the subsequent TPM2_Startup() will be processed.
For a shutdownType of any type, the volatile portion of Clock is saved to NV memory and the orderly
shutdown indication is SET. NV with the TPMA_NV_ORDERY attribute will be updated.
For a shutdownType of TPM_SU_STATE, the following additional items are saved:
         tracking information for saved session contexts;
         the session context counter;
         PCR that are designated as being preserved by TPM2_Shutdown(TPM_SU_STATE);
         the PCR Update Counter;
         flags associated with supporting the TPMA_NV_WRITESTCLEAR and
          TPMA_NV_READSTCLEAR attributes; and
          the command audit digest and count.
The following items shall not be saved and will not be in TPM memory after the next TPM2_Startup:
         TPM-memory-resident session contexts;
         TPM-memory-resident transient objects; or
         TPM-memory-resident hash contexts created by TPM2_HashSequenceStart().
Some values may be either derived from other values or saved to NV memory.
This command saves TPM state but does not change the state other than the internal indication that the
context has been saved. The TPM shall continue to accept commands. If a subsequent command
changes TPM state saved by this command, then the effect of this command is nullified. The TPM MAY
nullify this command for any subsequent command rather than check whether the command changed
state saved by this command. If this command is nullified. and if no TPM2_Shutdown() occurs before the
next TPM2_Startup(), then the next TPM2_Startup() shall be TPM2_Startup(CLEAR).


Page 26                                       TCG Published                               Family “2.0”
October 30, 2014                         Copyright © TCG 2006-2014           Level 00 Revision 01.16
Trusted Platform Module Library                                                      Part 3: Commands


9.4.2    Command and Response

                                  Table 7 — TPM2_Shutdown Command
Type                          Name                  Description

                                                    TPM_ST_SESSIONS if an audit session is present;
TPMI_ST_COMMAND_TAG           tag
                                                    otherwise, TPM_ST_NO_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode           TPM_CC_Shutdown {NV}

TPM_SU                        shutdownType          TPM_SU_CLEAR or TPM_SU_STATE


                                  Table 8 — TPM2_Shutdown Response
Type                          Name                  Description

TPM_ST                        tag                   see clause 6
UINT32                        responseSize
TPM_RC                        responseCode


Family “2.0”                                 TCG Published                                    Page 27
Level 00 Revision 01.16              Copyright © TCG 2006-2014                      October 30, 2014
     Part 3: Commands                                                          Trusted Platform Module Library


     9.4.3   Detailed Actions

1    #include "InternalRoutines.h"
2    #include "Shutdown_fp.h"
3    #ifdef TPM_CC_Shutdown // Conditional expansion of this file


     Error Returns                   Meaning

     TPM_RC_TYPE                     if PCR bank has been re-configured, a CLEAR StateSave() is
                                     required

 4   TPM_RC
 5   TPM2_Shutdown(
 6       Shutdown_In       *in               // IN: input parameter list
 7       )
 8   {
 9       TPM_RC            result;
10
11       // The command needs NV update. Check if NV is available.
12       // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
13       // this point
14       result = NvIsAvailable();
15       if(result != TPM_RC_SUCCESS) return result;
16
17   // Input Validation
18
19       // If PCR bank has been reconfigured, a CLEAR state save is required
20       if(g_pcrReConfig && in->shutdownType == TPM_SU_STATE)
21           return TPM_RC_TYPE + RC_Shutdown_shutdownType;
22
23   // Internal Data Update
24
25       // PCR private date state save
26       PCRStateSave(in->shutdownType);
27
28       // Get DRBG state
29       CryptDrbgGetPutState(GET_STATE);
30
31       // Save all orderly data
32       NvWriteReserved(NV_ORDERLY_DATA, &go);
33
34       // Save RAM backed NV index data
35       NvStateSave();
36
37       if(in->shutdownType == TPM_SU_STATE)
38       {
39           // Save STATE_RESET and STATE_CLEAR data
40           NvWriteReserved(NV_STATE_CLEAR, &gc);
41           NvWriteReserved(NV_STATE_RESET, &gr);
42       }
43       else if(in->shutdownType == TPM_SU_CLEAR)
44       {
45           // Save STATE_RESET data
46           NvWriteReserved(NV_STATE_RESET, &gr);
47       }
48
49       // Write orderly shut down state
50       if(in->shutdownType == TPM_SU_CLEAR)
51           gp.orderlyState = TPM_SU_CLEAR;
52       else if(in->shutdownType == TPM_SU_STATE)
53       {
54           gp.orderlyState = TPM_SU_STATE;
55           // Hack for the H-CRTM and Startup locality settings

     Page 28                                     TCG Published                                    Family “2.0”
     October 30, 2014                    Copyright © TCG 2006-2014                    Level 00 Revision 01.16
     Trusted Platform Module Library                                               Part 3: Commands

56             if(g_DrtmPreStartup)
57                 gp.orderlyState |= PRE_STARTUP_FLAG;
58             else if(g_StartupLocality3)
59                 gp.orderlyState |= STARTUP_LOCALITY_3;
60       }
61       else
62           pAssert(FALSE);
63
64       NvWriteReserved(NV_ORDERLY, &gp.orderlyState);
65
66       //   If PRE_STARTUP_FLAG was SET, then it will stay set in gp.orderlyState even
67       //   if the TPM isn't actually shut down. This is OK because all other checks
68       //   of gp.orderlyState are to see if it is SHUTDOWN_NONE. So, having
69       //   gp.orderlyState set to another value that is also not SHUTDOWN_NONE, is not
70       //   an issue. This must be the case, otherwise, it would be impossible to add
71       //   an additional shutdown type without major changes to the code.
72
73       return TPM_RC_SUCCESS;
74   }
75   #endif // CC_Shutdown


     Family “2.0”                             TCG Published                                 Page 29
     Level 00 Revision 01.16           Copyright © TCG 2006-2014                   October 30, 2014
Part 3: Commands                                                            Trusted Platform Module Library


10     Testing

10.1    Introduction

Compliance to standards for hardware security modules may require that the TPM test its functions
before the results that depend on those functions may be returned. The TPM may perform operations
using testable functions before those functions have been tested as long as the TPM returns no value
that depends on the correctness of the testable function.

EXAMPLE          TPM2_PCR_Event() may be executed before the hash algorithms have been tested. However, until
                 the hash algorithms have been tested, the contents of a PCR may not be used in any command if
                 that command may result in a value being returned to the TPM user. This means that
                 TPM2_PCR_Read() or TPM2_PolicyPCR() could not complete until the hashes have been checked
                 but other TPM2_PCR_Event() commands may be executed even though the operation uses previous
                 PCR values.

If a command is received that requires return of a value that depends on untested functions, the TPM
shall test the required functions before completing the command.
Once the TPM has received TPM2_SelfTest() and before completion of all tests, the TPM is required to
return TPM_RC_TESTING for any command that uses a function that requires a test.
If a self-test fails at any time, the TPM will enter Failure mode. While in Failure mode, the TPM will return
TPM_RC_FAILURE for any command other than TPM2_GetTestResult() and TPM2_GetCapability(). The
TPM will remain in Failure mode until the next _TPM_Init.


Page 30                                       TCG Published                                     Family “2.0”
October 30, 2014                      Copyright © TCG 2006-2014                   Level 00 Revision 01.16
Trusted Platform Module Library                                                                   Part 3: Commands


10.2     TPM2_SelfTest

10.2.1 General Description

This command causes the TPM to perform a test of its capabilities. If the fullTest is YES, the TPM will test
all functions. If fullTest = NO, the TPM will only test those functions that have not previously been tested.
If any tests are required, the TPM shall either
a) return TPM_RC_TESTING and begin self-test of the required functions, or

    NOTE 1           If fullTest is NO, and all functions have been tested, the TPM shall return TPM_RC_SUCCESS.

b) perform the tests and return the test result when complete.
If the TPM uses option a), the TPM shall return TPM_RC_TESTING for any command that requires use
of a testable function, even if the functions required for completion of the command have already been
tested.

NOTE 2          This command may cause the TPM to continue processing after it has returned the response. So
                that software can be notified of the completion of the testing, the interface may include controls that
                would allow the TPM to generate an interrupt when th e “background” processing is complete. This
                would be in addition to the interrupt that may be available for signaling normal command completion.
                It is not necessary that there be two interrupts, but the interface should provide a way to indicate the
                nature of the interrupt (normal command or deferred command).


Family “2.0”                                    TCG Published                                                Page 31
Level 00 Revision 01.16                Copyright © TCG 2006-2014                                  October 30, 2014
Part 3: Commands                                                  Trusted Platform Module Library


10.2.2 Command and Response

                         Table 9 — TPM2_SelfTest Command
Type                   Name                  Description

                                             TPM_ST_SESSIONS if an audit session is present;
TPMI_ST_COMMAND_TAG    tag
                                             otherwise, TPM_ST_NO_SESSIONS
UINT32                 commandSize
TPM_CC                 commandCode           TPM_CC_SelfTest {NV}

                                             YES if full test to be performed
TPMI_YES_NO            fullTest
                                             NO if only test of untested functions required


                        Table 10 — TPM2_SelfTest Response
Type                   Name                  Description

TPM_ST                 tag                   see clause 6
UINT32                 responseSize
TPM_RC                 responseCode


Page 32                               TCG Published                                      Family “2.0”
October 30, 2014             Copyright © TCG 2006-2014                   Level 00 Revision 01.16
     Trusted Platform Module Library                                                        Part 3: Commands


     10.2.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "SelfTest_fp.h"
3    #ifdef TPM_CC_SelfTest // Conditional expansion of this file


     Error Returns                     Meaning

     TPM_RC_CANCELED                   the command was canceled (some incremental process may have
                                       been made)
     TPM_RC_TESTING                    self test in process

 4   TPM_RC
 5   TPM2_SelfTest(
 6       SelfTest_In      *in                   // IN: input parameter list
 7       )
 8   {
 9   // Command Output
10
11       // Call self test function in crypt module
12       return CryptSelfTest(in->fullTest);
13   }
14   #endif // CC_SelfTest


     Family “2.0”                                   TCG Published                                    Page 33
     Level 00 Revision 01.16                Copyright © TCG 2006-2014                       October 30, 2014
Part 3: Commands                                                                    Trusted Platform Module Library


10.3     TPM2_IncrementalSelfTest

10.3.1 General Description

This command causes the TPM to perform a test of the selected algorithms.

NOTE 1           The toTest list indicates the algorithms that software would like the TPM to test in anticipation of
                 future use. This allows tests to be done so that a future commands will not be delayed due to
                 testing.

                 The implementation may treat algorithms on the toTest list as either 'test each completely' or 'test
                 this combination.'

EXAMPLE          If the toTest list includes AES and CTR mode, it may be interpreted as a request to test only AES in
                 CTR mode. Alternatively, it may be interpreted as a request to test AES in all modes and CTR mode
                 for all symmetric algorithms.


If toTest contains an algorithm that has already been tested, it will not be tested again.

NOTE 2           The only way to force retesting of an algorithm is with TPM2_SelfTest( fullTest = YES).

The TPM will return in toDoList a list of algorithms that are yet to be tested. This list is not the list of
algorithms that are scheduled to be tested but the algorithms/functions that have not been tested. Only
the algorithms on the toTest list are scheduled to be tested by this command.

NOTE 3           An algorithm remains on the toDoList while any part of it remains untested.

EXAMPLE          A symmetric algorithm remains untested until it is tested with all its modes.

Making toTest an empty list allows the determination of the algorithms that remain untested without
triggering any testing.
If toTest is not an empty list, the TPM shall return TPM_RC_SUCCESS for this command and then return
TPM_RC_TESTING for any subsequent command (including TPM2_IncrementalSelfTest()) until the
requested testing is complete.

NOTE 4           If toDoList is empty, then no additional tests are required and TPM_RC_TESTING will not be
                 returned in subsequent commands and no additional delay will occur in a command due to testing.

NOTE 5           If none of the algorithms listed in toTest is in the toDoList, then no tests will be performed.

NOTE 6           The TPM cannot return TPM_RC_TESTING for this command, even when testing is not complete,
                 because response parameters can only returned with the TPM_RC_SUCCESS return code.

If all the parameters in this command are valid, the TPM returns TPM_RC_SUCCESS and the toDoList
(which may be empty).

NOTE 7           An implementation may perform all requested tests before returning TPM_RC_SUCCESS, or it may
                 return TPM_RC_SUCCESS for this command and then return TPM_RC_TESTING for all
                 subsequence commands (including TPM2_IncrementatSelfTest()) until the requested tests are
                 complete.


Page 34                                           TCG Published                                            Family “2.0”
October 30, 2014                         Copyright © TCG 2006-2014                          Level 00 Revision 01.16
Trusted Platform Module Library                                                            Part 3: Commands


10.3.2 Command and Response

                          Table 11 — TPM2_IncrementalSelfTest Command
Type                          Name                  Description

                                                    TPM_ST_SESSIONS if an audit session is present;
TPMI_ST_COMMAND_TAG           tag
                                                    otherwise, TPM_ST_NO_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode           TPM_CC_IncrementalSelfTest {NV}

TPML_ALG                      toTest                list of algorithms that should be tested


                          Table 12 — TPM2_IncrementalSelfTest Response
Type                          Name                  Description

TPM_ST                        tag                   see clause 6
UINT32                        responseSize
TPM_RC                        responseCode

TPML_ALG                      toDoList              list of algorithms that need testing


Family “2.0”                                 TCG Published                                         Page 35
Level 00 Revision 01.16             Copyright © TCG 2006-2014                              October 30, 2014
     Part 3: Commands                                                            Trusted Platform Module Library


     10.3.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "IncrementalSelfTest_fp.h"
3    #ifdef TPM_CC_IncrementalSelfTest // Conditional expansion of this file


     Error Returns                 Meaning

     TPM_RC_CANCELED               the command was canceled (some tests may have completed)
     TPM_RC_VALUE                  an algorithm in the toTest list is not implemented

 4   TPM_RC
 5   TPM2_IncrementalSelfTest(
 6       IncrementalSelfTest_In        *in,                // IN: input parameter list
 7       IncrementalSelfTest_Out       *out                // OUT: output parameter list
 8       )
 9   {
10       TPM_RC                         result;
11   // Command Output
12
13       // Call incremental self test function in crypt module. If this function
14       // returns TPM_RC_VALUE, it means that an algorithm on the 'toTest' list is
15       // not implemented.
16       result = CryptIncrementalSelfTest(&in->toTest, &out->toDoList);
17       if(result == TPM_RC_VALUE)
18           return TPM_RCS_VALUE + RC_IncrementalSelfTest_toTest;
19       return result;
20   }
21   #endif // CC_IncrementalSelfTest


     Page 36                                    TCG Published                                      Family “2.0”
     October 30, 2014                   Copyright © TCG 2006-2014                       Level 00 Revision 01.16
Trusted Platform Module Library                                                      Part 3: Commands


10.4   TPM2_GetTestResult

10.4.1 General Description

This command returns manufacturer-specific information regarding the results of a self-test and an
indication of the test status.
If TPM2_SelfTest() has not been executed and a testable function has not been tested, testResult will be
TPM_RC_NEEDS_TEST. If TPM2_SelfTest() has been received and the tests are not complete,
testResult will be TPM_RC_TESTING. If testing of all functions is complete without functional failures,
testResult will be TPM_RC_SUCCESS. If any test failed, testResult will be TPM_RC_FAILURE.
This command will operate when the TPM is in Failure mode so that software can determine the test
status of the TPM and so that diagnostic information can be obtained for use in failure analysis. If the
TPM is in Failure mode, then tag is required to be TPM_ST_NO_SESSIONS or the TPM shall return
TPM_RC_FAILURE.


Family “2.0”                               TCG Published                                       Page 37
Level 00 Revision 01.16             Copyright © TCG 2006-2014                        October 30, 2014
Part 3: Commands                                                   Trusted Platform Module Library


10.4.2 Command and Response

                       Table 13 — TPM2_GetTestResult Command
 Type                   Name                  Description

                                              TPM_ST_SESSIONS if an audit session is present;
 TPMI_ST_COMMAND_TAG    tag
                                              otherwise, TPM_ST_NO_SESSIONS
 UINT32                 commandSize
 TPM_CC                 commandCode           TPM_CC_GetTestResult


                       Table 14 — TPM2_GetTestResult Response
 Type                   Name                  Description

 TPMI_ST_COMMAND_TAG    tag                   see clause 6
 UINT32                 responseSize
 TPM_RC                 responseCode

                                              test result data
 TPM2B_MAX_BUFFER       outData
                                              contains manufacturer-specific information
 TPM_RC                 testResult


Page 38                                TCG Published                                       Family “2.0”
October 30, 2014               Copyright © TCG 2006-2014                 Level 00 Revision 01.16
     Trusted Platform Module Library                                                         Part 3: Commands


     10.4.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "GetTestResult_fp.h"
3    #ifdef TPM_CC_GetTestResult // Conditional expansion of this file

     In the reference implementation, this function is only reachable if the TPM is not in failure mode meaning
     that all tests that have been run have completed successfully. There is not test data and the test result is
     TPM_RC_SUCCESS.

 4   TPM_RC
 5   TPM2_GetTestResult(
 6       GetTestResult_Out      *out               // OUT: output parameter list
 7       )
 8   {
 9   // Command Output
10
11       // Call incremental self test function in crypt module
12       out->testResult = CryptGetTestResult(&out->outData);
13
14       return TPM_RC_SUCCESS;
15   }
16   #endif // CC_GetTestResult


     Family “2.0”                                 TCG Published                                        Page 39
     Level 00 Revision 01.16              Copyright © TCG 2006-2014                          October 30, 2014
Part 3: Commands                                                                    Trusted Platform Module Library


11     Session Commands

11.1     TPM2_StartAuthSession

11.1.1 General Description

This command is used to start an authorization session using alternative methods of establishing the
session key (sessionKey). The session key is then used to derive values used for authorization and for
encrypting parameters.
This command allows injection of a secret into the TPM using either asymmetric or symmetric encryption.
The type of tpmKey determines how the value in encryptedSalt is encrypted. The decrypted secret value
is used to compute the sessionKey.

NOTE 1           If tpmKey Is TPM_RH_NULL, then encryptedSalt is required to be an Empty Buffer.

The label value of “SECRET” (see “Terms and Definitions” in TPM 2.0 Part 1) is used in the recovery of
the secret value.
The TPM generates the sessionKey from the recovered secret value.
No authorization is required for tpmKey or bind.

NOTE 2           The justification for using tpmKey without providing authorization is that the result of using the key is
                 not available to the caller, except indirectly through the sessionKey. This does not represent a point
                 of attack on the value of the key. If th e caller attempts to use the session without knowing the
                 sessionKey value, it is an authorization failure that will trigger the dictionary attack logic.

The entity referenced with the bind parameter contributes an authorization value to the sessionKey
generation process.
If both tpmKey and bind are TPM_ALG_NULL, then sessionKey is set to the Empty Buffer. If tpmKey is
not TPM_ALG_NULL, then encryptedSalt is used in the computation of sessionKey. If bind is not
TPM_ALG_NULL, the authValue of bind is used in the sessionKey computation.
If symmetric specifies a block cipher, then TPM_ALG_CFB is the only allowed value for the mode field in
the symmetric parameter (TPM_RC_MODE).
This command starts an authorization session and returns the session handle along with an initial
nonceTPM in the response.
If the TPM does not have                 a   free    slot   for   an   authorization     session,     it   shall   return
TPM_RC_SESSION_HANDLES.
If the TPM implements a “gap” scheme for assigning contextID values, then the TPM shall return
TPM_RC_CONTEXT_GAP if creating the session would prevent recycling of old saved contexts (See
“Context Management” in TPM 2.0 Part 1).
If tpmKey is not TPM_ALG_NULL then encryptedSalt shall be a TPM2B_ENCRYPTED_SECRET of the
proper type for tpmKey. The TPM shall return TPM_RC_HANDLE if the sensitive portion of tpmKey is not
loaded. The TPM shall return TPM_RC_VALUE if:
a) tpmKey references an RSA key and
     1) encryptedSalt does not contain a value that is the size of the public modulus of tpmKey,
     2) encryptedSalt has a value that is greater than the public modulus of tpmKey,
     3) encryptedSalt is not a properly encoded OAEP value, or
     4) the decrypted salt value is larger than the size of the digest produced by the nameAlg of tpmKey;
        or


Page 40                                          TCG Published                                             Family “2.0”
October 30, 2014                         Copyright © TCG 2006-2014                         Level 00 Revision 01.16
Trusted Platform Module Library                                                                 Part 3: Commands

b) tpmKey references an ECC key and encryptedSalt
    1) does not contain a TPMS_ECC_POINT or
    2) is not a point on the curve of tpmKey;

    NOTE 3           When ECC is used, the point multiply process produces a value (Z) that is used in a KDF to
                     produce the final secret value. The size of the secret value is an input parameter to the KDF
                     and the result will be set to be the size of the digest produced by the nameAlg of tpmKey.

c) tpmKey references a symmetric block cipher or a keyedHash object and encryptedSalt contains a
   value that is larger than the size of the digest produced by the nameAlg of tpmKey.
If bind references a transient object, then the TPM shall return TPM_RC_HANDLE if the sensitive portion
of the object is not loaded.
For all session types, this command will cause initialization of the sessionKey and may establish binding
between the session and an object (the bind object). If sessionType is TPM_SE_POLICY or
TPM_SE_TRIAL, the additional session initialization is:
        set policySession→policyDigest to a Zero Digest (the digest size for policySession→policyDigest
         is the size of the digest produced by authHash);
        authorization may be given at any locality;
        authorization may apply to any command code;
        authorization may apply to any command parameters or handles;
        the authorization has no time limit;
        an authValue is not needed when the authorization is used;
        the session is not bound;
        the session is not an audit session; and
        the time at which the policy session was created is recorded.
Additionally, if sessionType is TPM_SE_TRIAL, the session will not be usable for authorization but can be
used to compute the authPolicy for an object.

NOTE 4           Although this command changes the session allocation information in the TPM, it does not invalidate
                 a saved context. That is, TPM2_Shutdown() is not required after this command in order to re-
                 establish the orderly state of the TPM. This is because the created cont ext will occupy an available
                 slot in the TPM and sessions in the TPM do not survive any TPM2_Startup(). However, if a created
                 session is context saved, the orderly state does change.

The TPM shall return TPM_RC_SIZE if nonceCaller is less than 16 octets or is greater than the size of
the digest produced by authHash.


Family “2.0”                                    TCG Published                                              Page 41
Level 00 Revision 01.16                 Copyright © TCG 2006-2014                               October 30, 2014
Part 3: Commands                                                      Trusted Platform Module Library


11.1.2 Command and Response

                       Table 15 — TPM2_StartAuthSession Command
Type                      Name                  Description

                                                TPM_ST_SESSIONS if an audit, decrypt, or encrypt
TPMI_ST_COMMAND_TAG       tag                   session is present; otherwise,
                                                TPM_ST_NO_SESSIONS
UINT32                    commandSize
TPM_CC                    commandCode           TPM_CC_StartAuthSession

                                                handle of a loaded decrypt key used to encrypt salt
TPMI_DH_OBJECT+           tpmKey                may be TPM_RH_NULL
                                                Auth Index: None
                                                entity providing the authValue
TPMI_DH_ENTITY+           bind                  may be TPM_RH_NULL
                                                Auth Index: None

                                                initial nonceCaller, sets nonce size for the session
TPM2B_NONCE               nonceCaller
                                                shall be at least 16 octets
                                                value encrypted according to the type of tpmKey
TPM2B_ENCRYPTED_SECRET encryptedSalt            If tpmKey is TPM_RH_NULL, this shall be the Empty
                                                Buffer.
                                                indicates the type of the session; simple HMAC or policy
TPM_SE                    sessionType
                                                (including a trial policy)
                                                the algorithm and key size for parameter encryption
TPMT_SYM_DEF+             symmetric
                                                may select TPM_ALG_NULL
                                                hash algorithm to use for the session
TPMI_ALG_HASH             authHash              Shall be a hash algorithm supported by the TPM and
                                                not TPM_ALG_NULL


                       Table 16 — TPM2_StartAuthSession Response
Type                      Name                  Description
TPM_ST                    tag                   see clause 6
UINT32                    responseSize
TPM_RC                    responseCode

TPMI_SH_AUTH_SESSION      sessionHandle         handle for the newly created session

                                                the initial nonce from the TPM, used in the computation
TPM2B_NONCE               nonceTPM
                                                of the sessionKey


Page 42                                  TCG Published                                      Family “2.0”
October 30, 2014                 Copyright © TCG 2006-2014                   Level 00 Revision 01.16
     Trusted Platform Module Library                                                                Part 3: Commands


     11.1.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "StartAuthSession_fp.h"
3    #ifdef TPM_CC_StartAuthSession // Conditional expansion of this file


     Error Returns                     Meaning

     TPM_RC_ATTRIBUTES                 tpmKey does not reference a decrypt key
     TPM_RC_CONTEXT_GAP                the difference between the most recently created active context and
                                       the oldest active context is at the limits of the TPM
     TPM_RC_HANDLE                     input decrypt key handle only has public portion loaded
     TPM_RC_MODE                       symmetric specifies a block cipher but the mode is not
                                       TPM_ALG_CFB.
     TPM_RC_SESSION_HANDLES            no session handle is available
     TPM_RC_SESSION_MEMORY             no more slots for loading a session
     TPM_RC_SIZE                       nonce less than 16 octets or greater than the size of the digest
                                       produced by authHash
     TPM_RC_VALUE                      secret size does not match decrypt key type; or the recovered secret
                                       is larger than the digest size of the nameAlg of tpmKey; or, for an
                                       RSA decrypt key, if encryptedSecret is greater than the public
                                       exponent of tpmKey.

 4   TPM_RC
 5   TPM2_StartAuthSession(
 6       StartAuthSession_In       *in,                   // IN: input parameter buffer
 7       StartAuthSession_Out      *out                   // OUT: output parameter buffer
 8       )
 9   {
10       TPM_RC                     result = TPM_RC_SUCCESS;
11       OBJECT                    *tpmKey;                // TPM key for decrypt salt
12       SESSION                   *session;               // session internal data
13       TPM2B_DATA                 salt;
14
15   // Input Validation
16
17       // Check input nonce size. IT should be at least 16 bytes but not larger
18       // than the digest size of session hash.
19       if(    in->nonceCaller.t.size < 16
20           || in->nonceCaller.t.size > CryptGetHashDigestSize(in->authHash))
21           return TPM_RC_SIZE + RC_StartAuthSession_nonceCaller;
22
23       // If an decrypt key is passed in, check its validation
24       if(in->tpmKey != TPM_RH_NULL)
25       {
26           // secret size cannot be 0
27           if(in->encryptedSalt.t.size == 0)
28               return TPM_RC_VALUE + RC_StartAuthSession_encryptedSalt;
29
30           // Get pointer to loaded decrypt key
31           tpmKey = ObjectGet(in->tpmKey);
32
33           // Decrypting salt requires accessing the private portion of a key.
34           // Therefore, tmpKey can not be a key with only public portion loaded
35           if(tpmKey->attributes.publicOnly)
36               return TPM_RC_HANDLE + RC_StartAuthSession_tpmKey;
37
38           // HMAC session input handle check.

     Family “2.0”                                   TCG Published                                             Page 43
     Level 00 Revision 01.16               Copyright © TCG 2006-2014                                October 30, 2014
     Part 3: Commands                                                  Trusted Platform Module Library

39             // tpmKey should be a decryption key
40             if(tpmKey->publicArea.objectAttributes.decrypt != SET)
41                 return TPM_RC_ATTRIBUTES + RC_StartAuthSession_tpmKey;
42
43             // Secret Decryption. A TPM_RC_VALUE, TPM_RC_KEY or Unmarshal errors
44             // may be returned at this point
45             result = CryptSecretDecrypt(in->tpmKey, &in->nonceCaller, "SECRET",
46                                         &in->encryptedSalt, &salt);
47             if(result != TPM_RC_SUCCESS)
48                 return TPM_RC_VALUE + RC_StartAuthSession_encryptedSalt;
49
50      }
51      else
52      {
53          // secret size must be 0
54          if(in->encryptedSalt.t.size != 0)
55              return TPM_RC_VALUE + RC_StartAuthSession_encryptedSalt;
56          salt.t.size = 0;
57      }
58      // If the bind handle references a transient object, make sure that the
59      // sensitive area is loaded so that the authValue can be accessed.
60      if(     HandleGetType(in->bind) == TPM_HT_TRANSIENT
61          && ObjectGet(in->bind)->attributes.publicOnly == SET)
62          return TPM_RC_HANDLE + RC_StartAuthSession_bind;
63
64      // If 'symmetric' is a symmetric block cipher (not TPM_ALG_NULL or TPM_ALG_XOR)
65      // then the mode must be CFB.
66      if(    in->symmetric.algorithm != TPM_ALG_NULL
67          && in->symmetric.algorithm != TPM_ALG_XOR
68          && in->symmetric.mode.sym != TPM_ALG_CFB)
69          return TPM_RC_MODE + RC_StartAuthSession_symmetric;
70
71   // Internal Data Update
72
73      // Create internal session structure. TPM_RC_CONTEXT_GAP, TPM_RC_NO_HANDLES
74      // or TPM_RC_SESSION_MEMORY errors may be returned returned at this point.
75      //
76      // The detailed actions for creating the session context are not shown here
77      // as the details are implementation dependent
78      // SessionCreate sets the output handle
79      result = SessionCreate(in->sessionType, in->authHash,
80                             &in->nonceCaller, &in->symmetric,
81                             in->bind, &salt, &out->sessionHandle);
82
83      if(result != TPM_RC_SUCCESS)
84          return result;
85
86   // Command Output
87
88      // Get session pointer
89      session = SessionGet(out->sessionHandle);
90
91      // Copy nonceTPM
92      out->nonceTPM = session->nonceTPM;
93
94       return TPM_RC_SUCCESS;
95   }
96   #endif // CC_StartAuthSession


     Page 44                                  TCG Published                              Family “2.0”
     October 30, 2014                  Copyright © TCG 2006-2014            Level 00 Revision 01.16
Trusted Platform Module Library                                                     Part 3: Commands


11.2   TPM2_PolicyRestart

11.2.1 General Description

This command allows a policy authorization session to be returned to its initial state. This command is
used after the TPM returns TPM_RC_PCR_CHANGED. That response code indicates that a policy will
fail because the PCR have changed after TPM2_PolicyPCR() was executed. Restarting the session
allows the authorizations to be replayed because the session restarts with the same nonceTPM. If the
PCR are valid for the policy, the policy may then succeed.
This command does not reset the policy ID or the policy start time.


Family “2.0”                                TCG Published                                     Page 45
Level 00 Revision 01.16              Copyright © TCG 2006-2014                      October 30, 2014
Part 3: Commands                                                  Trusted Platform Module Library


11.2.2 Command and Response

                      Table 17 — TPM2_PolicyRestart Command
Type                   Name                  Description

                                             TPM_ST_SESSIONS if an audit session is present;
TPMI_ST_COMMAND_TAG    tag
                                             otherwise, TPM_ST_NO_SESSIONS
UINT32                 commandSize
TPM_CC                 commandCode           TPM_CC_PolicyRestart

TPMI_SH_POLICY         sessionHandle         the handle for the policy session


                      Table 18 — TPM2_PolicyRestart Response
Type                   Name                  Description

TPM_ST                 tag                   see clause 6
UINT32                 responseSize
TPM_RC                 responseCode


Page 46                               TCG Published                                 Family “2.0”
October 30, 2014             Copyright © TCG 2006-2014                   Level 00 Revision 01.16
     Trusted Platform Module Library                                          Part 3: Commands


     11.2.3 Detailed Actions

 1   #include "InternalRoutines.h"
 2   #include "PolicyRestart_fp.h"
 3   #ifdef TPM_CC_PolicyRestart // Conditional expansion of this file
 4   TPM_RC
 5   TPM2_PolicyRestart(
 6       PolicyRestart_In      *in              // IN: input parameter list
 7       )
 8   {
 9       SESSION                     *session;
10       BOOL                         wasTrialSession;
11
12   // Internal Data Update
13
14       session = SessionGet(in->sessionHandle);
15       wasTrialSession = session->attributes.isTrialPolicy == SET;
16
17       // Initialize policy session
18       SessionResetPolicyData(session);
19
20       session->attributes.isTrialPolicy = wasTrialSession;
21
22       return TPM_RC_SUCCESS;
23   }
24   #endif // CC_PolicyRestart


     Family “2.0”                               TCG Published                         Page 47
     Level 00 Revision 01.16             Copyright © TCG 2006-2014            October 30, 2014
Part 3: Commands                                                              Trusted Platform Module Library


12     Object Commands

12.1    TPM2_Create

12.1.1 General Description

This command is used to create an object that can be loaded into a TPM using TPM2_Load(). If the
command completes successfully, the TPM will create the new object and return the object’s creation
data (creationData), its public area (outPublic), and its encrypted sensitive area (outPrivate). Preservation
of the returned data is the responsibility of the caller. The object will need to be loaded (TPM2_Load())
before it may be used.
TPM2B_PUBLIC template (inPublic) contains all of the fields necessary to define the properties of the
new object. The setting for these fields is defined in “Public Area Template” in TPM 2.0 Part 1 and
“TPMA_OBJECT” in TPM 2.0 Part 2.
The parentHandle parameter shall reference a loaded decryption key that has both the public and
sensitive area loaded.
When defining the object, the caller provides a template structure for the object in a TPM2B_PUBLIC
structure (inPublic), an initial value for the object’s authValue (inSensitive.userAuth), and, if the object is a
symmetric object, an optional initial data value (inSensitive.data). The TPM shall validate the consistency
of inPublic.attributes according to the Creation rules in “TPMA_OBJECT” in TPM 2.0 Part 2.
The inSensitive parameter may be encrypted using parameter encryption.
The methods in this clause are used by both TPM2_Create() and TPM2_CreatePrimary(). When a value
is indicated as being TPM-generated, the value is filled in by bits from the RNG if the command is
TPM2_Create() and with values from KDFa() if the command is TPM2_CreatePrimary(). The parameters
of each creation value are specified in TPM 2.0 Part 1.
The sensitiveDataOrigin attribute of inPublic shall be SET if inSensitive.data is an Empty Buffer and
CLEAR if inSensitive.data is not an Empty Buffer or the TPM shall return TPM_RC_ATTRIBUTES.
The TPM will create new data for the sensitive area and compute a TPMT_PUBLIC.unique from the
sensitive area based on the object type:
a) For a symmetric key:
     1) If inSensitive.sensitive.data is the Empty Buffer, a TPM-generated key value is placed in the new
        object’s TPMT_SENSITIVE.sensitive.sym. The size of the key will be determined by
        inPublic.publicArea.parameters.
     2) If inSensitive.sensitive.data is not the Empty Buffer, the TPM will validate that the size of
        inSensitive.data is no larger than the key size indicated in the inPublic template (TPM_RC_SIZE)
        and copy the inSensitive.data to TPMT_SENSITIVE.sensitive.sym of the new object.
     3) A TPM-generated obfuscation value is placed in TPMT_SENSITIVE.sensitive.seedValue. The
        size of the obfuscation value is the size of the digest produced by the nameAlg in inPublic. This
        value prevents the public unique value from leaking information about the sensitive area.
     4) The TPMT_PUBLIC.unique.sym value for the new object is then generated, as shown in equation
        (1) below, by hashing the key and obfuscation values in the TPMT_SENSITIVE with the nameAlg
        of the object.
                   unique ≔ HnameAlg(sensitive.seedValue.buffer || sensitive.any.buffer)                     (1)
b) If the Object is an asymmetric key:
     1) If inSensitive.sensitive.data is not the Empty Buffer, then the TPM shall return TPM_RC_VALUE.


Page 48                                        TCG Published                                       Family “2.0”
October 30, 2014                       Copyright © TCG 2006-2014                     Level 00 Revision 01.16
Trusted Platform Module Library                                                                  Part 3: Commands

    2) A TPM-generated private key value is created with the size determined by the parameters of
       inPublic.publicArea.parameters.
    3) If the key is a Storage Key, a TPM-generated TPMT_SENSITIVE.seedValue value is created;
       otherwise, TPMT_SENSITIVE.seedValue.size is set to zero.

         NOTE 1       An Object that is not a storage key has no child Objects to encrypt, so it does not need a
                      symmetric key.

    4) The public unique value is computed from the private key according to the methods of the key
       type.
    5) If the key is an ECC key and the scheme required by the curveID is not the same as scheme in
       the public area of the template, then the TPM shall return TPM_RC_SCHEME.
    6) If the key is an ECC key and the KDF required by the curveID is not the same as kdf in the pubic
       area of the template, then the TPM shall return TPM_RC_KDF.

         NOTE 2            There is currently no command in which the caller may specify the KDF to be used with an
                           ECC decryption key. Since there is no use for this capability, the reference implementation
                           requires that the kdf in the template be set to TPM_ALG_NULL or TPM_RC_KDF is
                           returned.

c) If the Object is a keyedHash object:
    1) If inSensitive.sensitive.data is an Empty Buffer, and neither sign nor decrypt is SET in
       inPublic.attributes, the TPM shall return TPM_RC_ATTRIBUTES. This would be a data object
       with no data.
    2) If inSensitive.sensitive.data is not an Empty Buffer, the TPM will                                  copy    the
       inSensitive.sensitive.data to TPMT_SENSITIVE.sensitive,bits of the new object.

         NOTE 3            The size of inSensitive.sensitive.data is limited to be no larger than the largest value of
                           TPMT_SENSITIVE.sensitive.bits by MAX_SYM_DATA.

    3) If inSensitive.sensitive.data is an Empty Buffer, a TPM-generated key value that is the size of the
       digest produced by the nameAlg in inPublic is placed in TPMT_SENSITIVE.sensitive.bits.
    4) A TPM-generated obfuscation value that is the size of the digest produced by the nameAlg of
       inPublic is placed in TPMT_SENSITIVE.seedValue.
    5) The TPMT_PUBLIC.unique.keyedHash value for the new object is then generated, as shown in
       equation (1) above, by hashing the key and obfuscation values in the TPMT_SENSITIVE with the
       nameAlg of the object.
For TPM2_Load(), the TPM will apply normal symmetric protections to the created TPMT_SENSITIVE to
create outPublic.

NOTE 4            The encryption key is derived from the symmetric seed in the sensitive area of the parent.

In addition to outPublic and outPrivate, the TPM will build a TPMS_CREATION_DATA structure for the
object. TPMS_CREATION_DATA.outsideInfo is set to outsideInfo. This structure is returned in
creationData. Additionally, the digest of this structure is returned in creationHash, and, finally, a
TPMT_TK_CREATION is created so that the association between the creation data and the object may
be validated by TPM2_CertifyCreation().
If the object being created is a Storage Key and inPublic.objectAttributes.fixedParent is SET, then the
algorithms and parameters of inPublic are required to match those of the parent. The algorithms that must
match are inPublic.type, inPublic.nameAlg, and inPublic.parameters. If inPublic.type does not match, the
TPM shall return TPM_RC_TYPE. If inPublic.nameAlg does not match, the TPM shall return
TPM_RC_HASH. If inPublic.parameters does not match, the TPM shall return TPM_RC_ASSYMETRIC.
The TPM shall not differentiate between mismatches of the components of inPublic.parameters.


Family “2.0”                                     TCG Published                                                 Page 49
Level 00 Revision 01.16                  Copyright © TCG 2006-2014                               October 30, 2014
Part 3: Commands                                                           Trusted Platform Module Library

EXAMPLE      If the inPublic.parameters.ecc.symmetric.algorithm does not match the parent, the TPM shall return
             TPM_RC_ ASYMMETRIC rather than TPM_RC_SYMMETRIC.


Page 50                                    TCG Published                                        Family “2.0”
October 30, 2014                   Copyright © TCG 2006-2014                      Level 00 Revision 01.16
Trusted Platform Module Library                                                          Part 3: Commands


12.1.2 Command and Response

                                  Table 19 — TPM2_Create Command
Type                          Name                  Description

TPMI_ST_COMMAND_TAG           tag                   TPM_ST_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode           TPM_CC_Create

                                                    handle of parent for new object
TPMI_DH_OBJECT                @parentHandle         Auth Index: 1
                                                    Auth Role: USER

TPM2B_SENSITIVE_CREATE        inSensitive           the sensitive data
TPM2B_PUBLIC                  inPublic              the public template
                                                    data that will be included in the creation data for this
TPM2B_DATA                    outsideInfo           object to provide permanent, verifiable linkage between
                                                    this object and some object owner data
TPML_PCR_SELECTION            creationPCR           PCR that will be used in creation data


                                  Table 20 — TPM2_Create Response
Type                          Name                  Description

TPM_ST                        tag                   see clause 6
UINT32                        responseSize
TPM_RC                        responseCode

TPM2B_PRIVATE                 outPrivate            the private portion of the object
TPM2B_PUBLIC                  outPublic             the public portion of the created object
TPM2B_CREATION_DATA           creationData          contains a TPMS_CREATION_DATA
TPM2B_DIGEST                  creationHash          digest of creationData using nameAlg of outPublic
                                                    ticket used by TPM2_CertifyCreation() to validate that
TPMT_TK_CREATION              creationTicket
                                                    the creation data was produced by the TPM


Family “2.0”                                 TCG Published                                         Page 51
Level 00 Revision 01.16             Copyright © TCG 2006-2014                            October 30, 2014
     Part 3: Commands                                                            Trusted Platform Module Library


     12.1.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "Object_spt_fp.h"
3    #include "Create_fp.h"
4    #ifdef TPM_CC_Create // Conditional expansion of this file


     Error Returns               Meaning

     TPM_RC_ASYMMETRIC           non-duplicable storage key and its parent have different public
                                 parameters
     TPM_RC_ATTRIBUTES           sensitiveDataOrigin is CLEAR when 'sensitive.data' is an Empty
                                 Buffer, or is SET when 'sensitive.data' is not empty; fixedTPM,
                                 fixedParent, or encryptedDuplication attributes are inconsistent
                                 between themselves or with those of the parent object; inconsistent
                                 restricted, decrypt and sign attributes; attempt to inject sensitive data
                                 for an asymmetric key; attempt to create a symmetric cipher key that
                                 is not a decryption key
     TPM_RC_HASH                 non-duplicable storage key and its parent have different name
                                 algorithm
     TPM_RC_KDF                  incorrect KDF specified for decrypting keyed hash object
     TPM_RC_KEY                  invalid key size values in an asymmetric key public area
     TPM_RC_KEY_SIZE             key size in public area for symmetric key differs from the size in the
                                 sensitive creation area; may also be returned if the TPM does not
                                 allow the key size to be used for a Storage Key
     TPM_RC_RANGE                the exponent value of an RSA key is not supported.
     TPM_RC_SCHEME               inconsistent attributes decrypt, sign, restricted and key's scheme ID;
                                 or hash algorithm is inconsistent with the scheme ID for keyed hash
                                 object
     TPM_RC_SIZE                 size of public auth policy or sensitive auth value does not match
                                 digest size of the name algorithm sensitive data size for the keyed
                                 hash object is larger than is allowed for the scheme
     TPM_RC_SYMMETRIC            a storage key with no symmetric algorithm specified; or non-storage
                                 key with symmetric algorithm different from TPM_ALG_NULL
     TPM_RC_TYPE                 unknown object type; non-duplicable storage key and its parent have
                                 different types; parentHandle does not reference a restricted
                                 decryption key in the storage hierarchy with both public and sensitive
                                 portion loaded
     TPM_RC_VALUE                exponent is not prime or could not find a prime using the provided
                                 parameters for an RSA key; unsupported name algorithm for an ECC
                                 key
     TPM_RC_OBJECT_MEMORY        there is no free slot for the object. This implementation does not
                                 return this error.

 5   TPM_RC
 6   TPM2_Create(
 7       Create_In        *in,            // IN: input parameter list
 8       Create_Out       *out            // OUT: output parameter list
 9       )
10   {
11       TPM_RC                  result = TPM_RC_SUCCESS;
12       TPMT_SENSITIVE          sensitive;
13       TPM2B_NAME              name;
14

     Page 52                                  TCG Published                                             Family “2.0”
     October 30, 2014                 Copyright © TCG 2006-2014                         Level 00 Revision 01.16
     Trusted Platform Module Library                                                Part 3: Commands

15   // Input Validation
16
17       OBJECT       *parentObject;
18
19       parentObject = ObjectGet(in->parentHandle);
20
21       // Does parent have the proper attributes?
22       if(!AreAttributesForParent(parentObject))
23           return TPM_RC_TYPE + RC_Create_parentHandle;
24
25       // The sensitiveDataOrigin attribute must be consistent with the setting of
26       // the size of the data object in inSensitive.
27       if(   (in->inPublic.t.publicArea.objectAttributes.sensitiveDataOrigin == SET)
28          != (in->inSensitive.t.sensitive.data.t.size == 0))
29           // Mismatch between the object attributes and the parameter.
30           return TPM_RC_ATTRIBUTES + RC_Create_inSensitive;
31
32       // Check attributes in input public area. TPM_RC_ASYMMETRIC, TPM_RC_ATTRIBUTES,
33       // TPM_RC_HASH, TPM_RC_KDF, TPM_RC_SCHEME, TPM_RC_SIZE, TPM_RC_SYMMETRIC,
34       // or TPM_RC_TYPE error may be returned at this point.
35       result = PublicAttributesValidation(FALSE, in->parentHandle,
36                                           &in->inPublic.t.publicArea);
37       if(result != TPM_RC_SUCCESS)
38           return RcSafeAddToResult(result, RC_Create_inPublic);
39
40       // Validate the sensitive area values
41       if( MemoryRemoveTrailingZeros(&in->inSensitive.t.sensitive.userAuth)
42               > CryptGetHashDigestSize(in->inPublic.t.publicArea.nameAlg))
43           return TPM_RC_SIZE + RC_Create_inSensitive;
44
45   // Command Output
46
47       // Create object crypto data
48       result = CryptCreateObject(in->parentHandle, &in->inPublic.t.publicArea,
49                                  &in->inSensitive.t.sensitive, &sensitive);
50       if(result != TPM_RC_SUCCESS)
51           return result;
52
53       // Fill in creation data
54       FillInCreationData(in->parentHandle, in->inPublic.t.publicArea.nameAlg,
55                          &in->creationPCR, &in->outsideInfo,
56                          &out->creationData, &out->creationHash);
57
58       // Copy public area from input to output
59       out->outPublic.t.publicArea = in->inPublic.t.publicArea;
60
61       // Compute name from public area
62       ObjectComputeName(&(out->outPublic.t.publicArea), &name);
63
64       // Compute creation ticket
65       TicketComputeCreation(EntityGetHierarchy(in->parentHandle), &name,
66                             &out->creationHash, &out->creationTicket);
67
68       // Prepare output private data from sensitive
69       SensitiveToPrivate(&sensitive, &name, in->parentHandle,
70                          out->outPublic.t.publicArea.nameAlg,
71                          &out->outPrivate);
72
73       return TPM_RC_SUCCESS;
74   }
75   #endif // CC_Create


     Family “2.0”                           TCG Published                                   Page 53
     Level 00 Revision 01.16           Copyright © TCG 2006-2014                    October 30, 2014
Part 3: Commands                                                                    Trusted Platform Module Library


12.2     TPM2_Load

12.2.1 General Description

This command is used to load objects into the TPM. This command is used when both a TPM2B_PUBLIC
and TPM2B_PRIVATE are to be loaded. If only a TPM2B_PUBLIC is to be loaded, the
TPM2_LoadExternal command is used.

NOTE 1            Loading an object is not the same as restoring a saved object context.

The object’s TPMA_OBJECT attributes will be checked according to the rules defined in
“TPMA_OBJECT” in TPM 2.0 Part 2 of this specification.
Objects loaded using this command will have a Name. The Name is the concatenation of nameAlg and
the digest of the public area using the nameAlg.

NOTE 2            nameAlg is a parameter in the public area of the inPublic structure.

If inPrivate.size is zero, the load will fail.
After inPrivate.buffer is decrypted using the symmetric key of the parent, the integrity value shall be
checked before the sensitive area is used, or unmarshaled.

NOTE 3            Checking the integrity before the data is used prevents attacks on the sensitive area by fuzzing the
                  data and looking at the differences in the response codes.

The command returns a handle for the loaded object and the Name that the TPM computed for
inPublic.public (that is, the digest of the TPMT_PUBLIC structure in inPublic).

NOTE 4            The TPM-computed Name is provided as a convenience to the caller for those cases where the
                  caller does not implement the hash algorithms specified in the nameAlg of the object.

NOTE 5            The returned handle is associated with the object until the object is flushed (TPM2_FlushContext) o r
                  until the next TPM2_Startup.

For all objects, the size of the key in the sensitive area shall be consistent with the key size indicated in
the public area or the TPM shall return TPM_RC_KEY_SIZE.
Before use, a loaded object shall be checked to validate that the public and sensitive portions are
properly linked, cryptographically. Use of an object includes use in any policy command. If the parts of the
object are not properly linked, the TPM shall return TPM_RC_BINDING.

EXAMPLE 1         For a symmetric object, the unique value in the public area shall be the digest of the sensitive key
                  and the obfuscation value.

EXAMPLE 2         For a two-prime RSA key, the remainder when dividing the public modulus by the private key shall
                  be zero and it shall be possible to form a priv ate exponent from the two prime factors of the public
                  modulus.

EXAMPLE 3         For an ECC key, the public point shall be f(x) where x is the private key.


Page 54                                           TCG Published                                         Family “2.0”
October 30, 2014                          Copyright © TCG 2006-2014                        Level 00 Revision 01.16
Trusted Platform Module Library                                                         Part 3: Commands


12.2.2 Command and Response

                                    Table 21 — TPM2_Load Command
Type                          Name                  Description

TPMI_ST_COMMAND_TAG           tag                   TPM_ST_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode           TPM_CC_Load

                                                    TPM handle of parent key; shall not be a reserved
                                                    handle
TPMI_DH_OBJECT                @parentHandle
                                                    Auth Index: 1
                                                    Auth Role: USER

TPM2B_PRIVATE                 inPrivate             the private portion of the object
TPM2B_PUBLIC                  inPublic              the public portion of the object


                                    Table 22 — TPM2_Load Response
Type                          Name                  Description

TPM_ST                        tag                   see clause 6
UINT32                        responseSize
TPM_RC                        responseCode

                                                    handle of type TPM_HT_TRANSIENT for the loaded
TPM_HANDLE                    objectHandle
                                                    object

TPM2B_NAME                    name                  Name of the loaded object


Family “2.0”                                 TCG Published                                        Page 55
Level 00 Revision 01.16              Copyright © TCG 2006-2014                          October 30, 2014
     Part 3: Commands                                                            Trusted Platform Module Library


     12.2.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "Load_fp.h"
3    #ifdef TPM_CC_Load // Conditional expansion of this file
4    #include "Object_spt_fp.h"


     Error Returns               Meaning

     TPM_RC_ASYMMETRIC           storage key with different asymmetric type than parent
     TPM_RC_ATTRIBUTES           inPulblic attributes are not allowed with selected parent
     TPM_RC_BINDING              inPrivate and inPublic are not cryptographically bound
     TPM_RC_HASH                 incorrect hash selection for signing key
     TPM_RC_INTEGRITY            HMAC on inPrivate was not valid
     TPM_RC_KDF                  KDF selection not allowed
     TPM_RC_KEY                  the size of the object's unique field is not consistent with the indicated
                                 size in the object's parameters
     TPM_RC_OBJECT_MEMORY        no available object slot
     TPM_RC_SCHEME               the signing scheme is not valid for the key
     TPM_RC_SENSITIVE            the inPrivate did not unmarshal correctly
     TPM_RC_SIZE                 inPrivate missing, or authPolicy size for inPublic or is not valid
     TPM_RC_SYMMETRIC            symmetric algorithm not provided when required
     TPM_RC_TYPE                 parentHandle is not a storage key, or the object to load is a storage
                                 key but its parameters do not match the parameters of the parent.
     TPM_RC_VALUE                decryption failure

 5   TPM_RC
 6   TPM2_Load(
 7       Load_In         *in,             // IN: input parameter list
 8       Load_Out        *out             // OUT: output parameter list
 9       )
10   {
11       TPM_RC                  result = TPM_RC_SUCCESS;
12       TPMT_SENSITIVE          sensitive;
13       TPMI_RH_HIERARCHY       hierarchy;
14       OBJECT                 *parentObject = NULL;
15       BOOL                    skipChecks = FALSE;
16
17   // Input Validation
18       if(in->inPrivate.t.size == 0)
19           return TPM_RC_SIZE + RC_Load_inPrivate;
20
21       parentObject = ObjectGet(in->parentHandle);
22       // Is the object that is being used as the parent actually a parent.
23       if(!AreAttributesForParent(parentObject))
24           return TPM_RC_TYPE + RC_Load_parentHandle;
25
26       // If the parent is fixedTPM, then the attributes of the object
27       // are either "correct by construction" or were validated
28       // when the object was imported. If they pass the integrity
29       // check, then the values are valid
30       if(parentObject->publicArea.objectAttributes.fixedTPM)
31           skipChecks = TRUE;
32       else

     Page 56                                  TCG Published                                             Family “2.0”
     October 30, 2014                 Copyright © TCG 2006-2014                         Level 00 Revision 01.16
     Trusted Platform Module Library                                             Part 3: Commands

33       {
34           // If parent doesn't have fixedTPM SET, then this can't have
35           // fixedTPM SET.
36           if(in->inPublic.t.publicArea.objectAttributes.fixedTPM == SET)
37               return TPM_RC_ATTRIBUTES + RC_Load_inPublic;
38
39           // Perform self check on input public area. A TPM_RC_SIZE, TPM_RC_SCHEME,
40           // TPM_RC_VALUE, TPM_RC_SYMMETRIC, TPM_RC_TYPE, TPM_RC_HASH,
41           // TPM_RC_ASYMMETRIC, TPM_RC_ATTRIBUTES or TPM_RC_KDF error may be returned
42           // at this point
43           result = PublicAttributesValidation(TRUE, in->parentHandle,
44                                               &in->inPublic.t.publicArea);
45           if(result != TPM_RC_SUCCESS)
46               return RcSafeAddToResult(result, RC_Load_inPublic);
47       }
48
49       // Compute the name of object
50       ObjectComputeName(&in->inPublic.t.publicArea, &out->name);
51
52       // Retrieve sensitive data. PrivateToSensitive() may return TPM_RC_INTEGRITY or
53       // TPM_RC_SENSITIVE
54       // errors may be returned at this point
55       result = PrivateToSensitive(&in->inPrivate, &out->name, in->parentHandle,
56                                   in->inPublic.t.publicArea.nameAlg,
57                                   &sensitive);
58       if(result != TPM_RC_SUCCESS)
59           return RcSafeAddToResult(result, RC_Load_inPrivate);
60
61   // Internal Data Update
62
63       // Get hierarchy of parent
64       hierarchy = ObjectGetHierarchy(in->parentHandle);
65
66       // Create internal object. A lot of different errors may be returned by this
67       // loading operation as it will do several validations, including the public
68       // binding check
69       result = ObjectLoad(hierarchy, &in->inPublic.t.publicArea, &sensitive,
70                           &out->name, in->parentHandle, skipChecks,
71                           &out->objectHandle);
72
73       if(result != TPM_RC_SUCCESS)
74           return result;
75
76       return TPM_RC_SUCCESS;
77   }
78   #endif // CC_Load


     Family “2.0”                            TCG Published                                 Page 57
     Level 00 Revision 01.16            Copyright © TCG 2006-2014                October 30, 2014
Part 3: Commands                                                                  Trusted Platform Module Library


12.3     TPM2_LoadExternal

12.3.1 General Description

This command is used to load an object that is not a Protected Object into the TPM. The command allows
loading of a public area or both a public and sensitive area.

NOTE 1          Typical use for loading a public area is to allow the TPM to validate an asymmetric signature.
                Typical use for loading both a public and sensitive area is to allow the TPM to be used as a crypto
                accelerator.

Load of a public external object area allows the object be associated with a hierarchy so that the correct
algorithms may be used when creating tickets. The hierarchy parameter provides this association. If the
public and sensitive portions of the object are loaded, hierarchy is required to be TPM_RH_NULL.

NOTE 2          If both the public and private portions of an object are loaded, the object is not allowed to appear to
                be part of a hierarchy.

The object’s TPMA_OBJECT attributes will be checked according to the rules defined in
“TPMA_OBJECT” in TPM 2.0 Part 2. In particular, fixedTPM, fixedParent, and restricted shall be CLEAR
if inPrivate is not the Empty Buffer.

NOTE 3          The duplication status of a public key needs to be able to be the same as the full key which may be
                resident on a different TPM. If both the public and private parts of the key are loaded , then it is not
                possible for the key to be either fixedTPM or fixedParent, since, its private area would not be
                available in the clear to load.

Objects loaded using this command will have a Name. The Name is the nameAlg of the object
concatenated with the digest of the public area using the nameAlg. The Qualified Name for the object will
be the same as its Name. The TPM will validate that the authPolicy is either the size of the digest
produced by nameAlg or the Empty Buffer.

NOTE 4          If nameAlg is TPM_ALG_NULL, then the Name is the Empty Buffer. When the authorization value for
                an object with no Name is computed, no Name value is included in the HMAC. To ensure that these
                unnamed entities are not substituted, they should have an authValue that is statistically unique.

NOTE 5          The digest size for TPM_ALG_NULL is zero.

If the nameAlg is TPM_ALG_NULL, the TPM shall not verify the cryptographic binding between the public
and sensitive areas, but the TPM will validate that the size of the key in the sensitive area is consistent
with the size indicated in the public area. If it is not, the TPM shall return TPM_RC_KEY_SIZE.

NOTE 6          For an ECC object, the TPM will verify that the public key is on the curve of the key before the public
                area is used.

If nameAlg is not TPM_ALG_NULL, then the same consistency checks between inPublic and inPrivate
are made as for TPM2_Load().

NOTE 7          Consistency checks are necessary because an object with a Name needs to have the public and
                sensitive portions cryptographically bound so that an attacker cannot mix pubic and sensitive areas.

The command returns a handle for the loaded object and the Name that the TPM computed for
inPublic.public (that is, the TPMT_PUBLIC structure in inPublic).

NOTE 8          The TPM-computed Name is provided as a convenience to the caller for those cases where the
                caller does not implement the hash algorithm specified in the nameAlg of the object.


Page 58                                         TCG Published                                           Family “2.0”
October 30, 2014                       Copyright © TCG 2006-2014                         Level 00 Revision 01.16
Trusted Platform Module Library                                                           Part 3: Commands

The hierarchy parameter associates the external object with a hierarchy. External objects are flushed
when their associated hierarchy is disabled. If hierarchy is TPM_RH_NULL, the object is part of no
hierarchy, and there is no implicit flush.
If hierarchy is TPM_RH_NULL or nameAlg is TPM_ALG_NULL, a ticket produced using the object shall
be a NULL Ticket.

EXAMPLE        If a key is loaded with hierarchy set to TPM_RH_NULL, then TPM2_VerifySignature() will produce a
               NULL Ticket of the required type.

External objects are Temporary Objects. The saved external object contexts shall be invalidated at the
next TPM Reset.


Family “2.0”                                 TCG Published                                           Page 59
Level 00 Revision 01.16              Copyright © TCG 2006-2014                            October 30, 2014
Part 3: Commands                                                   Trusted Platform Module Library


12.3.2 Command and Response

                      Table 23 — TPM2_LoadExternal Command
Type                   Name                  Description

                                             TPM_ST_SESSIONS if an audit, encrypt, or derypt
TPMI_ST_COMMAND_TAG    tag                   session is present; otherwise,
                                             TPM_ST_NO_SESSIONS
UINT32                 commandSize
TPM_CC                 commandCode           TPM_CC_LoadExternal

TPM2B_SENSITIVE        inPrivate             the sensitive portion of the object (optional)
TPM2B_PUBLIC+          inPublic              the public portion of the object
TPMI_RH_HIERARCHY+     hierarchy             hierarchy with which the object area is associated


                      Table 24 — TPM2_LoadExternal Response
Type                   Name                  Description

TPM_ST                 tag                   see clause 6
UINT32                 responseSize
TPM_RC                 responseCode

                                             handle of type TPM_HT_TRANSIENT for the loaded
TPM_HANDLE             objectHandle
                                             object

TPM2B_NAME             name                  name of the loaded object


Page 60                               TCG Published                                       Family “2.0”
October 30, 2014              Copyright © TCG 2006-2014                   Level 00 Revision 01.16
     Trusted Platform Module Library                                                                   Part 3: Commands


     12.3.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "LoadExternal_fp.h"
3    #ifdef TPM_CC_LoadExternal // Conditional expansion of this file
4    #include "Object_spt_fp.h"


     Error Returns                     Meaning

     TPM_RC_ATTRIBUTES                 'fixedParent" and fixedTPM must be CLEAR on on an external key if
                                       both public and sensitive portions are loaded
     TPM_RC_BINDING                    the inPublic and inPrivate structures are not cryptographically bound.
     TPM_RC_HASH                       incorrect hash selection for signing key
     TPM_RC_HIERARCHY                  hierarchy is turned off, or only NULL hierarchy is allowed when
                                       loading public and private parts of an object
     TPM_RC_KDF                        incorrect KDF selection for decrypting keyedHash object
     TPM_RC_KEY                        the size of the object's unique field is not consistent with the indicated
                                       size in the object's parameters
     TPM_RC_OBJECT_MEMORY              if there is no free slot for an object
     TPM_RC_SCHEME                     the signing scheme is not valid for the key
     TPM_RC_SIZE                       authPolicy is not zero and is not the size of a digest produced by the
                                       object's nameAlg TPM_RH_NULL hierarchy
     TPM_RC_SYMMETRIC                  symmetric algorithm not provided when required
     TPM_RC_TYPE                       inPublic and inPrivate are not the same type

 5   TPM_RC
 6   TPM2_LoadExternal(
 7       LoadExternal_In       *in,                   // IN: input parameter list
 8       LoadExternal_Out      *out                   // OUT: output parameter list
 9       )
10   {
11       TPM_RC                 result;
12       TPMT_SENSITIVE        *sensitive;
13       BOOL                   skipChecks;
14
15   // Input Validation
16
17       // If the target hierarchy is turned off, the object can not be loaded.
18       if(!HierarchyIsEnabled(in->hierarchy))
19           return TPM_RC_HIERARCHY + RC_LoadExternal_hierarchy;
20
21       // the size of authPolicy is either 0 or the digest size of nameAlg
22       if(in->inPublic.t.publicArea.authPolicy.t.size != 0
23               && in->inPublic.t.publicArea.authPolicy.t.size !=
24               CryptGetHashDigestSize(in->inPublic.t.publicArea.nameAlg))
25           return TPM_RC_SIZE + RC_LoadExternal_inPublic;
26
27       // For loading an object with both public and sensitive
28       if(in->inPrivate.t.size != 0)
29       {
30           // An external object can only be loaded at TPM_RH_NULL hierarchy
31           if(in->hierarchy != TPM_RH_NULL)
32               return TPM_RC_HIERARCHY + RC_LoadExternal_hierarchy;
33           // An external object with a sensitive area must have fixedTPM == CLEAR
34           // fixedParent == CLEAR, and must have restrict CLEAR so that it does not
35           // appear to be a key that was created by this TPM.

     Family “2.0”                                    TCG Published                                                  Page 61
     Level 00 Revision 01.16                Copyright © TCG 2006-2014                                  October 30, 2014
     Part 3: Commands                                                  Trusted Platform Module Library

36             if(   in->inPublic.t.publicArea.objectAttributes.fixedTPM != CLEAR
37                || in->inPublic.t.publicArea.objectAttributes.fixedParent != CLEAR
38                || in->inPublic.t.publicArea.objectAttributes.restricted != CLEAR
39               )
40                 return TPM_RC_ATTRIBUTES + RC_LoadExternal_inPublic;
41       }
42
43       // Validate the scheme parameters
44       result = SchemeChecks(TRUE, TPM_RH_NULL, &in->inPublic.t.publicArea);
45       if(result != TPM_RC_SUCCESS)
46               return RcSafeAddToResult(result, RC_LoadExternal_inPublic);
47
48   // Internal Data Update
49       // Need the name to compute the qualified name
50       ObjectComputeName(&in->inPublic.t.publicArea, &out->name);
51       skipChecks = (in->inPublic.t.publicArea.nameAlg == TPM_ALG_NULL);
52
53       // If a sensitive area was provided, load it
54       if(in->inPrivate.t.size != 0)
55           sensitive = &in->inPrivate.t.sensitiveArea;
56       else
57           sensitive = NULL;
58
59       // Create external object. A TPM_RC_BINDING, TPM_RC_KEY, TPM_RC_OBJECT_MEMORY
60       // or TPM_RC_TYPE error may be returned by ObjectLoad()
61       result = ObjectLoad(in->hierarchy, &in->inPublic.t.publicArea,
62                           sensitive, &out->name, TPM_RH_NULL, skipChecks,
63                           &out->objectHandle);
64       return result;
65   }
66   #endif // CC_LoadExternal


     Page 62                                  TCG Published                              Family “2.0”
     October 30, 2014                  Copyright © TCG 2006-2014             Level 00 Revision 01.16
Trusted Platform Module Library                                                                Part 3: Commands


12.4   TPM2_ReadPublic

12.4.1 General Description

This command allows access to the public area of a loaded object.
Use of the objectHandle does not require authorization.

NOTE            Since the caller is not likely to know the public area of the object associated with objectHandle, it
                would not be possible to include the Name associated with objectHandle in the cpHash computation.

If objectHandle references a sequence object, the TPM shall return TPM_RC_SEQUENCE.


Family “2.0”                                   TCG Published                                              Page 63
Level 00 Revision 01.16                Copyright © TCG 2006-2014                               October 30, 2014
Part 3: Commands                                                  Trusted Platform Module Library


12.4.2 Command and Response

                      Table 25 — TPM2_ReadPublic Command
Type                   Name                  Description

                                             TPM_ST_SESSIONS if an audit or encrypt session is
TPMI_ST_COMMAND_TAG    tag
                                             present; otherwise, TPM_ST_NO_SESSIONS
UINT32                 commandSize
TPM_CC                 commandCode           TPM_CC_ReadPublic

                                             TPM handle of an object
TPMI_DH_OBJECT         objectHandle
                                             Auth Index: None


                      Table 26 — TPM2_ReadPublic Response
Type                   Name                  Description

TPM_ST                 tag                   see clause 6
UINT32                 responseSize
TPM_RC                 responseCode

TPM2B_PUBLIC           outPublic             structure containing the public area of an object
TPM2B_NAME             name                  name of the object
TPM2B_NAME             qualifiedName         the Qualified Name of the object


Page 64                               TCG Published                                      Family “2.0”
October 30, 2014              Copyright © TCG 2006-2014                  Level 00 Revision 01.16
     Trusted Platform Module Library                                                       Part 3: Commands


     12.4.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "ReadPublic_fp.h"
3    #ifdef TPM_CC_ReadPublic // Conditional expansion of this file


     Error Returns                     Meaning

     TPM_RC_SEQUENCE                   can not read the public area of a sequence object

 4   TPM_RC
 5   TPM2_ReadPublic(
 6       ReadPublic_In     *in,                // IN: input parameter list
 7       ReadPublic_Out    *out                // OUT: output parameter list
 8       )
 9   {
10       OBJECT                    *object;
11
12   // Input Validation
13
14       // Get loaded object pointer
15       object = ObjectGet(in->objectHandle);
16
17       // Can not read public area of a sequence object
18       if(ObjectIsSequence(object))
19           return TPM_RC_SEQUENCE;
20
21   // Command Output
22
23       // Compute size of public area in canonical form
24       out->outPublic.t.size = TPMT_PUBLIC_Marshal(&object->publicArea, NULL, NULL);
25
26       // Copy public area to output
27       out->outPublic.t.publicArea = object->publicArea;
28
29       // Copy name to output
30       out->name.t.size = ObjectGetName(in->objectHandle, &out->name.t.name);
31
32       // Copy qualified name to output
33       ObjectGetQualifiedName(in->objectHandle, &out->qualifiedName);
34
35       return TPM_RC_SUCCESS;
36   }
37   #endif // CC_ReadPublic


     Family “2.0”                                  TCG Published                                   Page 65
     Level 00 Revision 01.16               Copyright © TCG 2006-2014                       October 30, 2014
Part 3: Commands                                                           Trusted Platform Module Library


12.5   TPM2_ActivateCredential

12.5.1 General Description

This command enables the association of a credential with an object in a way that ensures that the TPM
has validated the parameters of the credentialed object.
If both the public and private portions of activateHandle and keyHandle are not loaded, then the TPM
shall return TPM_RC_AUTH_UNAVAILABLE.
If keyHandle is not a Storage Key, then the TPM shall return TPM_RC_TYPE.
Authorization for activateHandle requires the ADMIN role.
The key associated with keyHandle is used to recover a seed from secret, which is the encrypted seed.
The Name of the object associated with activateHandle and the recovered seed are used in a KDF to
recover the symmetric key. The recovered seed (but not the Name) is used in a KDF to recover the
HMAC key.
The HMAC is used to validate that the credentialBlob is associated with activateHandle and that the data
in credentialBlob has not been modified. The linkage to the object associated with activateHandle is
achieved by including the Name in the HMAC calculation.
If the integrity checks succeed, credentialBlob is decrypted and returned as certInfo.


Page 66                                      TCG Published                                   Family “2.0”
October 30, 2014                     Copyright © TCG 2006-2014                   Level 00 Revision 01.16
Trusted Platform Module Library                                                            Part 3: Commands


12.5.2 Command and Response

                          Table 27 — TPM2_ActivateCredential Command
Type                              Name               Description

TPMI_ST_COMMAND_TAG               tag                TPM_ST_SESSIONS
UINT32                            commandSize
TPM_CC                            commandCode        TPM_CC_ActivateCredential

                                                     handle of the object associated with certificate in
                                                     credentialBlob
TPMI_DH_OBJECT                    @activateHandle
                                                     Auth Index: 1
                                                     Auth Role: ADMIN
                                                     loaded key used to decrypt the TPMS_SENSITIVE in
                                                     credentialBlob
TPMI_DH_OBJECT                    @keyHandle
                                                     Auth Index: 2
                                                     Auth Role: USER

TPM2B_ID_OBJECT                   credentialBlob     the credential
                                                     keyHandle algorithm-dependent encrypted seed that
TPM2B_ENCRYPTED_SECRET            secret
                                                     protects credentialBlob


                          Table 28 — TPM2_ActivateCredential Response
Type                          Name                   Description

TPM_ST                        tag                    see clause 6
UINT32                        responseSize
TPM_RC                        responseCode

                                                     the decrypted certificate information
TPM2B_DIGEST                  certInfo               the data should be no larger than the size of the digest
                                                     of the nameAlg associated with keyHandle


Family “2.0”                                 TCG Published                                            Page 67
Level 00 Revision 01.16                 Copyright © TCG 2006-2014                          October 30, 2014
     Part 3: Commands                                                           Trusted Platform Module Library


     12.5.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "ActivateCredential_fp.h"
3    #ifdef TPM_CC_ActivateCredential // Conditional expansion of this file
4    #include "Object_spt_fp.h"


     Error Returns                Meaning

     TPM_RC_ATTRIBUTES            keyHandle does not reference a decryption key
     TPM_RC_ECC_POINT             secret is invalid (when keyHandle is an ECC key)
     TPM_RC_INSUFFICIENT          secret is invalid (when keyHandle is an ECC key)
     TPM_RC_INTEGRITY             credentialBlob fails integrity test
     TPM_RC_NO_RESULT             secret is invalid (when keyHandle is an ECC key)
     TPM_RC_SIZE                  secret size is invalid or the credentialBlob does not unmarshal
                                  correctly
     TPM_RC_TYPE                  keyHandle does not reference an asymmetric key.
     TPM_RC_VALUE                 secret is invalid (when keyHandle is an RSA key)

 5   TPM_RC
 6   TPM2_ActivateCredential(
 7       ActivateCredential_In    *in,                 // IN: input parameter list
 8       ActivateCredential_Out   *out                 // OUT: output parameter list
 9       )
10   {
11       TPM_RC                        result = TPM_RC_SUCCESS;
12       OBJECT                       *object;        // decrypt key
13       OBJECT                       *activateObject;// key associated with
14       // credential
15       TPM2B_DATA                      data;              // credential data
16
17   // Input Validation
18
19       // Get decrypt key pointer
20       object = ObjectGet(in->keyHandle);
21
22       // Get certificated object pointer
23       activateObject = ObjectGet(in->activateHandle);
24
25       // input decrypt key must be an asymmetric, restricted decryption key
26       if(   !CryptIsAsymAlgorithm(object->publicArea.type)
27          || object->publicArea.objectAttributes.decrypt == CLEAR
28          || object->publicArea.objectAttributes.restricted == CLEAR)
29           return TPM_RC_TYPE + RC_ActivateCredential_keyHandle;
30
31   // Command output
32
33       // Decrypt input credential data via asymmetric decryption. A
34       // TPM_RC_VALUE, TPM_RC_KEY or unmarshal errors may be returned at this
35       // point
36       result = CryptSecretDecrypt(in->keyHandle, NULL,
37                                   "IDENTITY", &in->secret, &data);
38       if(result != TPM_RC_SUCCESS)
39       {
40           if(result == TPM_RC_KEY)
41               return TPM_RC_FAILURE;
42           return RcSafeAddToResult(result, RC_ActivateCredential_secret);
43       }

     Page 68                                     TCG Published                                      Family “2.0”
     October 30, 2014                    Copyright © TCG 2006-2014                     Level 00 Revision 01.16
     Trusted Platform Module Library                                             Part 3: Commands

44
45       // Retrieve secret data. A TPM_RC_INTEGRITY error or unmarshal
46       // errors may be returned at this point
47       result = CredentialToSecret(&in->credentialBlob,
48                                   &activateObject->name,
49                                   (TPM2B_SEED *) &data,
50                                   in->keyHandle,
51                                   &out->certInfo);
52       if(result != TPM_RC_SUCCESS)
53           return RcSafeAddToResult(result,RC_ActivateCredential_credentialBlob);
54
55       return TPM_RC_SUCCESS;
56   }
57   #endif // CC_ActivateCredential


     Family “2.0”                           TCG Published                                Page 69
     Level 00 Revision 01.16           Copyright © TCG 2006-2014                 October 30, 2014
Part 3: Commands                                                         Trusted Platform Module Library


12.6   TPM2_MakeCredential

12.6.1 General Description

This command allows the TPM to perform the actions required of a Certificate Authority (CA) in creating a
TPM2B_ID_OBJECT containing an activation credential.
The TPM will produce a TPM_ID_OBJECT according to the methods in “Credential Protection” in TPM
2.0 Part 1.
The loaded public area referenced by handle is required to be the public area of a Storage key,
otherwise, the credential cannot be properly sealed.
This command does not use any TPM secrets nor does it require authorization. It is a convenience
function, using the TPM to perform cryptographic calculations that could be done externally.


Page 70                                    TCG Published                                    Family “2.0”
October 30, 2014                    Copyright © TCG 2006-2014                  Level 00 Revision 01.16
Trusted Platform Module Library                                                         Part 3: Commands


12.6.2 Command and Response

                           Table 29 — TPM2_MakeCredential Command
Type                          Name                  Description

                                                    TPM_ST_SESSIONS if an audit, encrypt, or decrypt
TPMI_ST_COMMAND_TAG           tag                   session is present; otherwise,
                                                    TPM_ST_NO_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode           TPM_CC_MakeCredential

                                                    loaded public area, used to encrypt the sensitive area
TPMI_DH_OBJECT                handle                containing the credential key
                                                    Auth Index: None

TPM2B_DIGEST                  credential            the credential information
TPM2B_NAME                    objectName            Name of the object to which the credential applies


                           Table 30 — TPM2_MakeCredential Response
Type                          Name                  Description

TPM_ST                        tag                   see clause 6
UINT32                        responseSize
TPM_RC                        responseCode

TPM2B_ID_OBJECT               credentialBlob        the credential
                                                    handle algorithm-dependent data that wraps the key
TPM2B_ENCRYPTED_SECRET secret
                                                    that encrypts credentialBlob


Family “2.0”                                 TCG Published                                         Page 71
Level 00 Revision 01.16             Copyright © TCG 2006-2014                           October 30, 2014
     Part 3: Commands                                                              Trusted Platform Module Library


     12.6.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "MakeCredential_fp.h"
3    #ifdef TPM_CC_MakeCredential // Conditional expansion of this file
4    #include "Object_spt_fp.h"


     Error Returns                   Meaning

     TPM_RC_KEY                      handle referenced an ECC key that has a unique field that is not a
                                     point on the curve of the key
     TPM_RC_SIZE                     credential is larger than the digest size of Name algorithm of handle
     TPM_RC_TYPE                     handle does not reference an asymmetric decryption key

 5   TPM_RC
 6   TPM2_MakeCredential(
 7       MakeCredential_In    *in,                 // IN: input parameter list
 8       MakeCredential_Out   *out                 // OUT: output parameter list
 9       )
10   {
11       TPM_RC                    result = TPM_RC_SUCCESS;
12
13       OBJECT                    *object;
14       TPM2B_DATA                data;
15
16   // Input Validation
17
18       // Get object pointer
19       object = ObjectGet(in->handle);
20
21       // input key must be an asymmetric, restricted decryption key
22       // NOTE: Needs to be restricted to have a symmetric value.
23       if(   !CryptIsAsymAlgorithm(object->publicArea.type)
24          || object->publicArea.objectAttributes.decrypt == CLEAR
25          || object->publicArea.objectAttributes.restricted == CLEAR
26         )
27           return TPM_RC_TYPE + RC_MakeCredential_handle;
28
29       // The credential information may not be larger than the digest size used for
30       // the Name of the key associated with handle.
31       if(in->credential.t.size > CryptGetHashDigestSize(object->publicArea.nameAlg))
32           return TPM_RC_SIZE + RC_MakeCredential_credential;
33
34   // Command Output
35
36       // Make encrypt key and its associated secret structure.
37       // Even though CrypeSecretEncrypt() may return
38       out->secret.t.size = sizeof(out->secret.t.secret);
39       result = CryptSecretEncrypt(in->handle, "IDENTITY", &data, &out->secret);
40       if(result != TPM_RC_SUCCESS)
41           return result;
42
43       // Prepare output credential data from secret
44       SecretToCredential(&in->credential, &in->objectName, (TPM2B_SEED *) &data,
45                          in->handle, &out->credentialBlob);
46
47       return TPM_RC_SUCCESS;
48   }
49   #endif // CC_MakeCredential


     Page 72                                      TCG Published                                           Family “2.0”
     October 30, 2014                    Copyright © TCG 2006-2014                        Level 00 Revision 01.16
Trusted Platform Module Library                                                        Part 3: Commands


12.7   TPM2_Unseal

12.7.1 General Description

This command returns the data in a loaded Sealed Data Object.

NOTE            A random, TPM-generated, Sealed Data Object may be created by the TPM with TPM2_Create() or
                TPM2_CreatePrimary() using the template for a Sealed Data Object.

The returned value may be encrypted using authorization session encryption.
If either restricted, decrypt, or sign is SET in the attributes of itemHandle, then the TPM shall return
TPM_RC_ATTRIBUTES. If the type of itemHandle is not TPM_ALG_KEYEDHASH, then the TPM shall
return TPM_RC_TYPE.


Family “2.0”                                TCG Published                                        Page 73
Level 00 Revision 01.16             Copyright © TCG 2006-2014                          October 30, 2014
Part 3: Commands                                                  Trusted Platform Module Library


12.7.2 Command and Response

                        Table 31 — TPM2_Unseal Command
Type                   Name                  Description

TPMI_ST_COMMAND_TAG    tag                   TPM_ST_SESSIONS
UINT32                 commandSize
TPM_CC                 commandCode           TPM_CC_Unseal

                                             handle of a loaded data object
TPMI_DH_OBJECT         @itemHandle           Auth Index: 1
                                             Auth Role: USER


                         Table 32 — TPM2_Unseal Response
Type                   Name                  Description

TPM_ST                 tag                   see clause 6
UINT32                 responseSize
TPM_RC                 responseCode

                                             unsealed data
TPM2B_SENSITIVE_DATA   outData
                                             Size of outData is limited to be no more than 128 octets.


Page 74                               TCG Published                                     Family “2.0”
October 30, 2014             Copyright © TCG 2006-2014                   Level 00 Revision 01.16
     Trusted Platform Module Library                                               Part 3: Commands


     12.7.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "Unseal_fp.h"
3    #ifdef TPM_CC_Unseal // Conditional expansion of this file


     Error Returns                     Meaning

     TPM_RC_ATTRIBUTES                 itemHandle has wrong attributes
     TPM_RC_TYPE                       itemHandle is not a KEYEDHASH data object

 4   TPM_RC
 5   TPM2_Unseal(
 6       Unseal_In         *in,
 7       Unseal_Out        *out
 8       )
 9   {
10       OBJECT                    *object;
11
12   // Input Validation
13
14       // Get pointer to loaded object
15       object = ObjectGet(in->itemHandle);
16
17       // Input handle must be a data object
18       if(object->publicArea.type != TPM_ALG_KEYEDHASH)
19           return TPM_RC_TYPE + RC_Unseal_itemHandle;
20       if(   object->publicArea.objectAttributes.decrypt == SET
21          || object->publicArea.objectAttributes.sign == SET
22          || object->publicArea.objectAttributes.restricted == SET)
23           return TPM_RC_ATTRIBUTES + RC_Unseal_itemHandle;
24
25   // Command Output
26
27       // Copy data
28       MemoryCopy2B(&out->outData.b, &object->sensitive.sensitive.bits.b,
29                    sizeof(out->outData.t.buffer));
30
31       return TPM_RC_SUCCESS;
32   }
33   #endif // CC_Unseal


     Family “2.0”                                  TCG Published                           Page 75
     Level 00 Revision 01.16               Copyright © TCG 2006-2014               October 30, 2014
Part 3: Commands                                                                Trusted Platform Module Library


12.8     TPM2_ObjectChangeAuth

12.8.1 General Description

This command is used to change the authorization secret for a TPM-resident object.
If successful, a new private area for the TPM-resident object associated with objectHandle is returned,
which includes the new authorization value.
This command does not change the authorization of the TPM-resident object on which it operates.
Therefore, the old authValue (of the TPM-resident object) is used when generating the response HMAC
key if required.

NOTE 1         The returned outPrivate will need to be loaded before the new authorization will apply.

NOTE 2         The TPM-resident object may be persistent and changing the authorization value of the persistent
               object could prevent other users from accessing the object. This is why this command does not
               change the TPM-resident object.

EXAMPLE        If a persistent key is being used as a Storage Root Key and the authorization of the key is a well -
               known value so that the key can be used generally, then changing the authorization value in the
               persistent key would deny access to other users.

This command may not be used to change the authorization value for an NV Index or a Primary Object.

NOTE 3         If an NV Index is to have a new authorization, it is done with TPM2_NV_ChangeAuth().

NOTE 4         If a Primary Object is to have a new authorization, it needs to be recreated (TPM2_CreatePrimary()).


Page 76                                       TCG Published                                              Family “2.0”
October 30, 2014                      Copyright © TCG 2006-2014                        Level 00 Revision 01.16
Trusted Platform Module Library                                                         Part 3: Commands


12.8.2 Command and Response

                          Table 33 — TPM2_ObjectChangeAuth Command
Type                          Name                  Description

TPMI_ST_COMMAND_TAG           tag                   TPM_ST_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode           TPM_CC_ObjectChangeAuth

                                                    handle of the object
TPMI_DH_OBJECT                @objectHandle         Auth Index: 1
                                                    Auth Role: ADMIN
                                                    handle of the parent
TPMI_DH_OBJECT                parentHandle
                                                    Auth Index: None

TPM2B_AUTH                    newAuth               new authorization value


                          Table 34 — TPM2_ObjectChangeAuth Response
Type                          Name                  Description

TPM_ST                        tag                   see clause 6
UINT32                        responseSize
TPM_RC                        responseCode

TPM2B_PRIVATE                 outPrivate            private area containing the new authorization value


Family “2.0”                                 TCG Published                                         Page 77
Level 00 Revision 01.16             Copyright © TCG 2006-2014                           October 30, 2014
     Part 3: Commands                                                          Trusted Platform Module Library


     12.8.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "ObjectChangeAuth_fp.h"
3    #ifdef TPM_CC_ObjectChangeAuth // Conditional expansion of this file
4    #include "Object_spt_fp.h"


     Error Returns               Meaning

     TPM_RC_SIZE                 newAuth is larger than the size of the digest of the Name algorithm of
                                 objectHandle
     TPM_RC_TYPE                 the key referenced by parentHandle is not the parent of the object
                                 referenced by objectHandle; or objectHandle is a sequence object.

 5   TPM_RC
 6   TPM2_ObjectChangeAuth(
 7       ObjectChangeAuth_In    *in,                // IN: input parameter list
 8       ObjectChangeAuth_Out   *out                // OUT: output parameter list
 9       )
10   {
11       TPMT_SENSITIVE          sensitive;
12
13       OBJECT                 *object;
14       TPM2B_NAME              objectQN, QNCompare;
15       TPM2B_NAME              parentQN;
16
17   // Input Validation
18
19       // Get object pointer
20       object = ObjectGet(in->objectHandle);
21
22       // Can not change auth on sequence object
23       if(ObjectIsSequence(object))
24           return TPM_RC_TYPE + RC_ObjectChangeAuth_objectHandle;
25
26       // Make sure that the auth value is consistent with the nameAlg
27       if( MemoryRemoveTrailingZeros(&in->newAuth)
28               > CryptGetHashDigestSize(object->publicArea.nameAlg))
29           return TPM_RC_SIZE + RC_ObjectChangeAuth_newAuth;
30
31       // Check parent for object
32       // parent handle must be the parent of object handle. In this
33       // implementation we verify this by checking the QN of object. Other
34       // implementation may choose different method to verify this attribute.
35       ObjectGetQualifiedName(in->parentHandle, &parentQN);
36       ObjectComputeQualifiedName(&parentQN, object->publicArea.nameAlg,
37                                  &object->name, &QNCompare);
38
39       ObjectGetQualifiedName(in->objectHandle, &objectQN);
40       if(!Memory2BEqual(&objectQN.b, &QNCompare.b))
41           return TPM_RC_TYPE + RC_ObjectChangeAuth_parentHandle;
42
43   // Command Output
44
45       // Copy internal sensitive area
46       sensitive = object->sensitive;
47       // Copy authValue
48       sensitive.authValue = in->newAuth;
49
50       // Prepare output private data from sensitive
51       SensitiveToPrivate(&sensitive, &object->name, in->parentHandle,
52                          object->publicArea.nameAlg,

     Page 78                                  TCG Published                                           Family “2.0”
     October 30, 2014                  Copyright © TCG 2006-2014                     Level 00 Revision 01.16
     Trusted Platform Module Library                               Part 3: Commands

53                           &out->outPrivate);
54
55       return TPM_RC_SUCCESS;
56   }
57   #endif // CC_ObjectChangeAuth


     Family “2.0”                            TCG Published                 Page 79
     Level 00 Revision 01.16           Copyright © TCG 2006-2014   October 30, 2014
Part 3: Commands                                                                Trusted Platform Module Library


13     Duplication Commands

13.1     TPM2_Duplicate

13.1.1 General Description

This command duplicates a loaded object so that it may be used in a different hierarchy. The new parent
key for the duplicate may be on the same or different TPM or TPM_RH_NULL. Only the public area of
newParentHandle is required to be loaded.

NOTE 1          Since the new parent may only be extant on a different TPM, it is likely that the new parent’s
                sensitive area could not be loaded in the TPM from which objectHandle is being duplicated.

If encryptedDuplication is SET in the object being duplicated, then the TPM shall return
TPM_RC_SYMMETRIC if symmetricAlg is TPM_RH_NULL or TPM_RC_HIERARCHY if
newParentHandle is TPM_RH_NULL.
The authorization for this command shall be with a policy session.
If fixedParent of objectHandle→attributes is SET, the TPM shall return TPM_RC_ATTRIBUTES. If
objectHandle→nameAlg is TPM_ALG_NULL, the TPM shall return TPM_RC_TYPE.
The policySession→commandCode parameter in the policy session is required to be TPM_CC_Duplicate
to indicate that authorization for duplication has been provided. This indicates that the policy that is being
used is a policy that is for duplication, and not a policy that would approve another use. That is, authority
to use an object does not grant authority to duplicate the object.
The policy is likely to include cpHash in order to restrict where duplication can occur.        If
TPM2_PolicyCpHash() has been executed as part of the policy, the policySession→cpHash is compared
to the cpHash of the command.
If TPM2_PolicyDuplicationSelect() has             been     executed      as     part    of    the    policy,    the
policySession→nameHash is compared to
                       HpolicyAlg(objectHandle→Name || newParentHandle→Name)                                     (2)
If the compared hashes are not the same, then the TPM shall return TPM_RC_POLICY_FAIL.

NOTE 2          It is allowed that policySesion→nameHash and policySession→cpHash share the same memory
                space.

NOTE 3          A duplication policy is not required to have either TPM2_PolicyDuplicationSelect() or
                TPM2_PolicyCpHash() as part of the policy. If neither is present, then the duplication policy may be
                satisfied with a policy that only contains TPM2_PolicyComman dCode(code = TPM_CC_Duplicate).

The TPM shall follow the process of encryption defined in the “Duplication” subclause of “Protected
Storage Hierarchy” in TPM 2.0 Part 1.


Page 80                                        TCG Published                                         Family “2.0”
October 30, 2014                       Copyright © TCG 2006-2014                       Level 00 Revision 01.16
Trusted Platform Module Library                                                          Part 3: Commands


13.1.2 Command and Response

                              Table 35 — TPM2_Duplicate Command
Type                          Name                  Description

TPMI_ST_COMMAND_TAG           tag                   TPM_ST_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode           TPM_CC_Duplicate

                                                    loaded object to duplicate
TPMI_DH_OBJECT                @objectHandle         Auth Index: 1
                                                    Auth Role: DUP
                                                    shall reference the public area of an asymmetric key
TPMI_DH_OBJECT+               newParentHandle
                                                    Auth Index: None

                                                    optional symmetric encryption key
TPM2B_DATA                    encryptionKeyIn       The size for this key is set to zero when the TPM is to
                                                    generate the key. This parameter may be encrypted.
                                                    definition for the symmetric algorithm to be used for the
TPMT_SYM_DEF_OBJECT+          symmetricAlg          inner wrapper
                                                    may be TPM_ALG_NULL if no inner wrapper is applied


                              Table 36 — TPM2_Duplicate Response
Type                          Name                  Description

TPM_ST                        tag                   see clause 6
UINT32                        responseSize
TPM_RC                        responseCode

                                                    If the caller provided an encryption key or if
                                                    symmetricAlg was TPM_ALG_NULL, then this will be
TPM2B_DATA                    encryptionKeyOut      the Empty Buffer; otherwise, it shall contain the TPM-
                                                    generated, symmetric encryption key for the inner
                                                    wrapper.
                                                    private area that may be encrypted by encryptionKeyIn;
TPM2B_PRIVATE                 duplicate
                                                    and may be doubly encrypted
                                                    seed protected by the asymmetric algorithms of new
TPM2B_ENCRYPTED_SECRET outSymSeed
                                                    parent (NP)


Family “2.0”                                 TCG Published                                          Page 81
Level 00 Revision 01.16             Copyright © TCG 2006-2014                            October 30, 2014
     Part 3: Commands                                                           Trusted Platform Module Library


     13.1.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "Duplicate_fp.h"
3    #ifdef TPM_CC_Duplicate // Conditional expansion of this file
4    #include "Object_spt_fp.h"


     Error Returns                Meaning

     TPM_RC_ATTRIBUTES            key to duplicate has fixedParent SET
     TPM_RC_HIERARCHY             encryptedDuplication is SET and newParentHandle specifies Null
                                  Hierarchy
     TPM_RC_KEY                   newParentHandle references invalid ECC key (public point not on the
                                  curve)
     TPM_RC_SIZE                  input encryption key size does not match the size specified in
                                  symmetric algorithm
     TPM_RC_SYMMETRIC             encryptedDuplication is SET but no symmetric algorithm is provided
     TPM_RC_TYPE                  newParentHandle is neither a storage key nor TPM_RH_NULL; or
                                  the object has a NULL nameAlg

 5   TPM_RC
 6   TPM2_Duplicate(
 7       Duplicate_In      *in,            // IN: input parameter list
 8       Duplicate_Out     *out            // OUT: output parameter list
 9       )
10   {
11       TPM_RC                   result = TPM_RC_SUCCESS;
12       TPMT_SENSITIVE           sensitive;
13
14       UINT16                   innerKeySize = 0; // encrypt key size for inner wrap
15
16       OBJECT                   *object;
17       TPM2B_DATA               data;
18
19   // Input Validation
20
21       // Get duplicate object pointer
22       object = ObjectGet(in->objectHandle);
23
24       // duplicate key must have fixParent bit CLEAR.
25       if(object->publicArea.objectAttributes.fixedParent == SET)
26           return TPM_RC_ATTRIBUTES + RC_Duplicate_objectHandle;
27
28       // Do not duplicate object with NULL nameAlg
29       if(object->publicArea.nameAlg == TPM_ALG_NULL)
30           return TPM_RC_TYPE + RC_Duplicate_objectHandle;
31
32       // new parent key must be a storage object or TPM_RH_NULL
33       if(in->newParentHandle != TPM_RH_NULL
34               && !ObjectIsStorage(in->newParentHandle))
35           return TPM_RC_TYPE + RC_Duplicate_newParentHandle;
36
37       // If the duplicates object has encryptedDuplication SET, then there must be
38       // an inner wrapper and the new parent may not be TPM_RH_NULL
39       if(object->publicArea.objectAttributes.encryptedDuplication == SET)
40       {
41           if(in->symmetricAlg.algorithm == TPM_ALG_NULL)
42               return TPM_RC_SYMMETRIC + RC_Duplicate_symmetricAlg;
43           if(in->newParentHandle == TPM_RH_NULL)

     Page 82                                   TCG Published                                       Family “2.0”
     October 30, 2014                 Copyright © TCG 2006-2014                       Level 00 Revision 01.16
     Trusted Platform Module Library                                              Part 3: Commands

44                return TPM_RC_HIERARCHY + RC_Duplicate_newParentHandle;
45       }
46
47       if(in->symmetricAlg.algorithm == TPM_ALG_NULL)
48       {
49           // if algorithm is TPM_ALG_NULL, input key size must be 0
50           if(in->encryptionKeyIn.t.size != 0)
51               return TPM_RC_SIZE + RC_Duplicate_encryptionKeyIn;
52       }
53       else
54       {
55           // Get inner wrap key size
56           innerKeySize = in->symmetricAlg.keyBits.sym;
57
58           // If provided the input symmetric key must match the size of the algorithm
59           if(in->encryptionKeyIn.t.size != 0
60                   && in->encryptionKeyIn.t.size != (innerKeySize + 7) / 8)
61               return TPM_RC_SIZE + RC_Duplicate_encryptionKeyIn;
62       }
63
64   // Command Output
65
66       if(in->newParentHandle != TPM_RH_NULL)
67       {
68
69           // Make encrypt key and its associated secret structure. A TPM_RC_KEY
70           // error may be returned at this point
71           out->outSymSeed.t.size = sizeof(out->outSymSeed.t.secret);
72           result = CryptSecretEncrypt(in->newParentHandle,
73                                       "DUPLICATE", &data, &out->outSymSeed);
74           pAssert(result != TPM_RC_VALUE);
75           if(result != TPM_RC_SUCCESS)
76               return result;
77       }
78       else
79       {
80           // Do not apply outer wrapper
81           data.t.size = 0;
82           out->outSymSeed.t.size = 0;
83       }
84
85       // Copy sensitive area
86       sensitive = object->sensitive;
87
88       // Prepare output private data from sensitive
89       SensitiveToDuplicate(&sensitive, &object->name, in->newParentHandle,
90                            object->publicArea.nameAlg, (TPM2B_SEED *) &data,
91                            &in->symmetricAlg, &in->encryptionKeyIn,
92                            &out->duplicate);
93
94       out->encryptionKeyOut = in->encryptionKeyIn;
95
96       return TPM_RC_SUCCESS;
97   }
98   #endif // CC_Duplicate


     Family “2.0”                            TCG Published                                 Page 83
     Level 00 Revision 01.16           Copyright © TCG 2006-2014                  October 30, 2014
Part 3: Commands                                                        Trusted Platform Module Library


13.2   TPM2_Rewrap

13.2.1 General Description

This command allows the TPM to serve in the role as a Duplication Authority. If proper authorization for
use of the oldParent is provided, then an HMAC key and a symmetric key are recovered from inSymSeed
and used to integrity check and decrypt inDuplicate. A new protection seed value is generated according
to the methods appropriate for newParent and the blob is re-encrypted and a new integrity value is
computed. The re-encrypted blob is returned in outDuplicate and the symmetric key returned in
outSymKey.
In the rewrap process, L is “DUPLICATE” (see “Terms and Definitions” in TPM 2.0 Part 1).
If inSymSeed has a zero length, then oldParent is required to be TPM_RH_NULL and no decryption of
inDuplicate takes place.
If newParent is TPM_RH_NULL, then no encryption is performed on outDuplicate. outSymSeed will have
a zero length. See TPM 2.0 Part 2 encryptedDuplication.


Page 84                                    TCG Published                                   Family “2.0”
October 30, 2014                    Copyright © TCG 2006-2014                 Level 00 Revision 01.16
Trusted Platform Module Library                                                        Part 3: Commands


13.2.2 Command and Response

                                  Table 37 — TPM2_Rewrap Command
Type                          Name                  Description

TPMI_ST_COMMAND_TAG           tag                   TPM_ST_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode           TPM_CC_Rewrap

                                                    parent of object
TPMI_DH_OBJECT+               @oldParent            Auth Index: 1
                                                    Auth Role: User
                                                    new parent of the object
TPMI_DH_OBJECT+               newParent
                                                    Auth Index: None

                                                    an object encrypted using symmetric key derived from
TPM2B_PRIVATE                 inDuplicate
                                                    inSymSeed
TPM2B_NAME                    name                  the Name of the object being rewrapped
                                                    seed for symmetric key
TPM2B_ENCRYPTED_SECRET inSymSeed                    needs oldParent private key to recover the seed and
                                                    generate the symmetric key


                                  Table 38 — TPM2_Rewrap Response
Type                          Name                  Description

TPM_ST                        tag                   see clause 6
UINT32                        responseSize
TPM_RC                        responseCode

                                                    an object encrypted using symmetric key derived from
TPM2B_PRIVATE                 outDuplicate
                                                    outSymSeed
                                                    seed for a symmetric key protected by newParent
TPM2B_ENCRYPTED_SECRET outSymSeed
                                                    asymmetric key


Family “2.0”                                 TCG Published                                       Page 85
Level 00 Revision 01.16              Copyright © TCG 2006-2014                         October 30, 2014
     Part 3: Commands                                                            Trusted Platform Module Library


     13.2.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "Rewrap_fp.h"
3    #ifdef TPM_CC_Rewrap // Conditional expansion of this file
4    #include "Object_spt_fp.h"


     Error Returns                 Meaning

     TPM_RC_ATTRIBUTES             newParent is not a decryption key
     TPM_RC_HANDLE                 oldParent does not consistent with inSymSeed
     TPM_RC_INTEGRITY              the integrity check of inDuplicate failed
     TPM_RC_KEY                    for an ECC key, the public key is not on the curve of the curve ID
     TPM_RC_KEY_SIZE               the decrypted input symmetric key size does not matches the
                                   symmetric algorithm key size of oldParent
     TPM_RC_TYPE                   oldParent is not a storage key, or 'newParent is not a storage key
     TPM_RC_VALUE                  for an 'oldParent; RSA key, the data to be decrypted is greater than
                                   the public exponent
     Unmarshal errors              errors during unmarshaling the input encrypted buffer to a ECC public
                                   key, or unmarshal the private buffer to sensitive

 5   TPM_RC
 6   TPM2_Rewrap(
 7       Rewrap_In         *in,             // IN: input parameter list
 8       Rewrap_Out        *out             // OUT: output parameter list
 9       )
10   {
11       TPM_RC                   result = TPM_RC_SUCCESS;
12       OBJECT                   *oldParent;
13       TPM2B_DATA               data;               // symmetric key
14       UINT16                   hashSize = 0;
15       TPM2B_PRIVATE            privateBlob;        // A temporary private blob
16                                                    // to transit between old
17                                                    // and new wrappers
18
19   // Input Validation
20
21       if((in->inSymSeed.t.size == 0 && in->oldParent != TPM_RH_NULL)
22               || (in->inSymSeed.t.size != 0 && in->oldParent == TPM_RH_NULL))
23           return TPM_RC_HANDLE + RC_Rewrap_oldParent;
24
25       if(in->oldParent != TPM_RH_NULL)
26       {
27           // Get old parent pointer
28           oldParent = ObjectGet(in->oldParent);
29
30             // old parent key must be a storage object
31             if(!ObjectIsStorage(in->oldParent))
32                 return TPM_RC_TYPE + RC_Rewrap_oldParent;
33
34             // Decrypt input secret data via asymmetric decryption. A
35             // TPM_RC_VALUE, TPM_RC_KEY or unmarshal errors may be returned at this
36             // point
37             result = CryptSecretDecrypt(in->oldParent, NULL,
38                                         "DUPLICATE", &in->inSymSeed, &data);
39             if(result != TPM_RC_SUCCESS)
40                 return TPM_RC_VALUE + RC_Rewrap_inSymSeed;
41

     Page 86                                    TCG Published                                           Family “2.0”
     October 30, 2014                   Copyright © TCG 2006-2014                       Level 00 Revision 01.16
      Trusted Platform Module Library                                             Part 3: Commands

 42           // Unwrap Outer
 43           result = UnwrapOuter(in->oldParent, &in->name,
 44                                oldParent->publicArea.nameAlg, (TPM2B_SEED *) &data,
 45                                FALSE,
 46                                in->inDuplicate.t.size, in->inDuplicate.t.buffer);
 47           if(result != TPM_RC_SUCCESS)
 48               return RcSafeAddToResult(result, RC_Rewrap_inDuplicate);
 49
 50           // Copy unwrapped data to temporary variable, remove the integrity field
 51           hashSize = sizeof(UINT16) +
 52                      CryptGetHashDigestSize(oldParent->publicArea.nameAlg);
 53           privateBlob.t.size = in->inDuplicate.t.size - hashSize;
 54           MemoryCopy(privateBlob.t.buffer, in->inDuplicate.t.buffer + hashSize,
 55                      privateBlob.t.size, sizeof(privateBlob.t.buffer));
 56       }
 57       else
 58       {
 59           // No outer wrap from input blob.   Direct copy.
 60           privateBlob = in->inDuplicate;
 61       }
 62
 63       if(in->newParent != TPM_RH_NULL)
 64       {
 65           OBJECT          *newParent;
 66           newParent = ObjectGet(in->newParent);
 67
 68           // New parent must be a storage object
 69           if(!ObjectIsStorage(in->newParent))
 70               return TPM_RC_TYPE + RC_Rewrap_newParent;
 71
 72           // Make new encrypt key and its associated secret structure. A
 73           // TPM_RC_VALUE error may be returned at this point if RSA algorithm is
 74           // enabled in TPM
 75           out->outSymSeed.t.size = sizeof(out->outSymSeed.t.secret);
 76           result = CryptSecretEncrypt(in->newParent,
 77                                       "DUPLICATE", &data, &out->outSymSeed);
 78           if(result != TPM_RC_SUCCESS) return result;
 79
 80   // Command output
 81           // Copy temporary variable to output, reserve the space for integrity
 82           hashSize = sizeof(UINT16) +
 83                      CryptGetHashDigestSize(newParent->publicArea.nameAlg);
 84           out->outDuplicate.t.size = privateBlob.t.size;
 85           MemoryCopy(out->outDuplicate.t.buffer + hashSize, privateBlob.t.buffer,
 86                      privateBlob.t.size, sizeof(out->outDuplicate.t.buffer));
 87
 88           // Produce outer wrapper for output
 89           out->outDuplicate.t.size = ProduceOuterWrap(in->newParent, &in->name,
 90                                      newParent->publicArea.nameAlg,
 91                                      (TPM2B_SEED *) &data,
 92                                      FALSE,
 93                                      out->outDuplicate.t.size,
 94                                      out->outDuplicate.t.buffer);
 95
 96       }
 97       else // New parent is a null key so there is no seed
 98       {
 99           out->outSymSeed.t.size = 0;
100
101           // Copy privateBlob directly
102           out->outDuplicate = privateBlob;
103       }
104
105       return TPM_RC_SUCCESS;
106   }
107   #endif // CC_Rewrap

      Family “2.0”                           TCG Published                                Page 87
      Level 00 Revision 01.16           Copyright © TCG 2006-2014                 October 30, 2014
Part 3: Commands                                                                      Trusted Platform Module Library


13.3     TPM2_Import

13.3.1 General Description

This command allows an object to be encrypted using the symmetric encryption values of a Storage Key.
After encryption, the object may be loaded and used in the new hierarchy. The imported object (duplicate)
may be singly encrypted, multiply encrypted, or unencrypted.
If fixedTPM or fixedParent is SET in objectPublic, the TPM shall return TPM_RC_ATTRIBUTES.
If encryptedDuplication is SET in the object referenced by parentHandle, then encryptedDuplication shall
be SET in objectPublic (TPM_RC_ATTRIBUTES).
If encryptedDuplication is SET in objectPublic, then inSymSeed and encryptionKey shall not be Empty
buffers (TPM_RC_ATTRIBUTES). Recovery of the sensitive data of the object occurs in the TPM in a
multi--step process in the following order:
a) If inSymSeed has a non-zero size:
    1) The asymmetric parameters and private key of parentHandle are used to recover the seed used
       in the creation of the HMAC key and encryption keys used to protect the duplication blob.

         NOTE 1       When recovering the seed from inSymSeed, L is “DUPLICATE”.

    2) The integrity value in duplicate.buffer.integrityOuter is used to verify the integrity of the inner data
       blob, which is the remainder of duplicate.buffer (TPM_RC_INTEGRITY).

         NOTE 2            The inner data blob will contain a TPMT_SENSITIVE and may contain a TPM2B_DIGEST
                           for the innerIntegrity.

    3) The symmetric key recovered in 1) (2)is used to decrypt the inner data blob.

         NOTE 3            Checking the integrity before the data is used prevents attacks on the sensitive area by
                           fuzzing the data and looking at the differences in the response codes.

b) If encryptionKey is not an Empty Buffer:
    1) Use encryptionKey to decrypt the inner blob.
    2) Use the TPM2B_DIGEST at the start of the inner blob to verify the integrity of the inner blob
       (TPM_RC_INTEGRITY).
c) Unmarshal the sensitive area

NOTE 4            It is not necessary to validate that the sensitive area data is cryptographically bound to the public
                  area other than that the Name of the public area is included in the HMAC. However, if the binding is
                  not validated by this command, the binding must be checked each time the object is loaded. For an
                  object that is imported under a parent with fixedTPM SET, binding need only be checked at import. If
                  the parent has fixedTPM CLEAR, then the binding needs to be checked each time the object is
                  loaded, or before the TPM performs an operation for which the binding affects the outcome of the
                  operation (for example, TPM2_PolicySigned() or TPM2_Certify()).

                  Similarly, if the new parent's fixedTPM is set, the encryptedDuplication state need only be checked
                  at import.

                  If the new parent is not fixedTPM, then that object will be loadable on any TPM (including SW
                  versions) on which the new parent exists. This means that, each time an object is loaded under a
                  parent that is not fixedTPM, it is necessary to validate all of the properties of that object. If the
                  parent is fixedTPM, then the new private blob is integrity protec ted by the TPM that “owns” the
                  parent. So, it is sufficient to validate the object’s properties (attribute and public -private binding) on
                  import and not again.

After integrity checks and decryption, the TPM will create a new symmetrically encrypted private area
using the encryption key of the parent.

Page 88                                            TCG Published                                             Family “2.0”
October 30, 2014                          Copyright © TCG 2006-2014                          Level 00 Revision 01.16
Trusted Platform Module Library                                                             Part 3: Commands

NOTE 5         The symmetric re-encryption is the normal integrity generation and symmetric encryption applied to
               a child object.


Family “2.0”                                 TCG Published                                             Page 89
Level 00 Revision 01.16              Copyright © TCG 2006-2014                              October 30, 2014
Part 3: Commands                                                    Trusted Platform Module Library


13.3.2 Command and Response

                         Table 39 — TPM2_Import Command
Type                   Name                  Description

TPMI_ST_COMMAND_TAG    tag                   TPM_ST_SESSIONS
UINT32                 commandSize
TPM_CC                 commandCode           TPM_CC_Import

                                             the handle of the new parent for the object
TPMI_DH_OBJECT         @parentHandle         Auth Index: 1
                                             Auth Role: USER

                                             the optional symmetric encryption key used as the inner
                                             wrapper for duplicate
TPM2B_DATA             encryptionKey
                                             If symmetricAlg is TPM_ALG_NULL, then this
                                             parameter shall be the Empty Buffer.
                                             the public area of the object to be imported
                                             This is provided so that the integrity value for duplicate
TPM2B_PUBLIC           objectPublic          and the object attributes can be checked.
                                             NOTE        Even if the integrity value of the object is not
                                                         checked on input, the object Name is required to
                                                         create the integrity value for the imported object.

                                             the symmetrically encrypted duplicate object that may
TPM2B_PRIVATE          duplicate
                                             contain an inner symmetric wrapper
                                             symmetric key used to encrypt duplicate
TPM2B_ENCRYPTED_SECRET inSymSeed             inSymSeed is encrypted/encoded using the algorithms
                                             of newParent.
                                             definition for the symmetric algorithm to use for the inner
                                             wrapper
TPMT_SYM_DEF_OBJECT+   symmetricAlg
                                             If this algorithm is TPM_ALG_NULL, no inner wrapper is
                                             present and encryptionKey shall be the Empty Buffer.


                         Table 40 — TPM2_Import Response
Type                   Name                  Description

TPM_ST                 tag                   see clause 6
UINT32                 responseSize
TPM_RC                 responseCode

                                             the sensitive area encrypted with the symmetric key of
TPM2B_PRIVATE          outPrivate
                                             parentHandle


Page 90                               TCG Published                                          Family “2.0”
October 30, 2014             Copyright © TCG 2006-2014                      Level 00 Revision 01.16
    Trusted Platform Module Library                                                                Part 3: Commands


    13.3.3 Detailed Actions

1   #include "InternalRoutines.h"
2   #include "Import_fp.h"
3   #ifdef TPM_CC_Import // Conditional expansion of this file
4   #include "Object_spt_fp.h"


    Error Returns                     Meaning

    TPM_RC_ASYMMETRIC                 non-duplicable storage key represented by objectPublic and its
                                      parent referenced by parentHandle have different public parameters
    TPM_RC_ATTRIBUTES                 attributes FixedTPM and fixedParent of objectPublic are not both
                                      CLEAR; or inSymSeed is nonempty and parentHandle does not
                                      reference a decryption key; or objectPublic and parentHandle have
                                      incompatible or inconsistent attributes; or encrytpedDuplication is
                                      SET in objectPublic but the inner or outer wrapper is missing.

    NOTE:           if the TPM provides parameter values, the parameter number will indicate symmetricKey (missing
                    inner wrapper) or inSymSeed (missing outer wrapper).


    TPM_RC_BINDING                    duplicate and objectPublic are not cryptographically
                                      bound

    TPM_RC_ECC_POINT                  inSymSeed is nonempty and ECC point in inSymSeed is not on the
                                      curve
    TPM_RC_HASH                       non-duplicable storage key represented by objectPublic and its
                                      parent referenced by parentHandle have different name algorithm
    TPM_RC_INSUFFICIENT               inSymSeed is nonempty and failed to retrieve ECC point from the
                                      secret; or unmarshaling sensitive value from duplicate failed the
                                      result of inSymSeed decryption
    TPM_RC_INTEGRITY                  duplicate integrity is broken
    TPM_RC_KDF                        objectPublic representing decrypting keyed hash object specifies
                                      invalid KDF
    TPM_RC_KEY                        inconsistent parameters of objectPublic; or inSymSeed is nonempty
                                      and parentHandle does not reference a key of supported type; or
                                      invalid key size in objectPublic representing an asymmetric key
    TPM_RC_NO_RESULT                  inSymSeed is nonempty and multiplication resulted in ECC point at
                                      infinity
    TPM_RC_OBJECT_MEMORY              no available object slot
    TPM_RC_SCHEME                     inconsistent attributes decrypt, sign, restricted and key's scheme ID
                                      in objectPublic; or hash algorithm is inconsistent with the scheme ID
                                      for keyed hash object
    TPM_RC_SIZE                       authPolicy size does not match digest size of the name algorithm in
                                      objectPublic; or symmetricAlg and encryptionKey have different
                                      sizes; or inSymSeed is nonempty and it size is not consistent with the
                                      type of parentHandle; or unmarshaling sensitive value from duplicate
                                      failed
    TPM_RC_SYMMETRIC                  objectPublic is either a storage key with no symmetric algorithm or a
                                      non-storage key with symmetric algorithm different from
                                      TPM_ALG_NULL
    TPM_RC_TYPE                       unsupported type of objectPublic; or non-duplicable storage key
                                      represented by objectPublic and its parent referenced by
                                      parentHandle are of different types; or parentHandle is not a storage
                                      key; or only the public portion of parentHandle is loaded; or

    Family “2.0”                                   TCG Published                                               Page 91
    Level 00 Revision 01.16                Copyright © TCG 2006-2014                               October 30, 2014
     Part 3: Commands                                                           Trusted Platform Module Library

                                  objectPublic and duplicate are of different types
     TPM_RC_VALUE                 nonempty inSymSeed and its numeric value is greater than the
                                  modulus of the key referenced by parentHandle or inSymSeed is
                                  larger than the size of the digest produced by the name algorithm of
                                  the symmetric key referenced by parentHandle

 5   TPM_RC
 6   TPM2_Import(
 7       Import_In         *in,            // IN: input parameter list
 8       Import_Out        *out            // OUT: output parameter list
 9       )
10   {
11
12       TPM_RC                   result = TPM_RC_SUCCESS;
13       OBJECT                   *parentObject;
14       TPM2B_DATA               data;                   // symmetric key
15       TPMT_SENSITIVE           sensitive;
16       TPM2B_NAME               name;
17
18       UINT16                   innerKeySize = 0;             // encrypt key size for inner
19                                                              // wrapper
20
21   // Input Validation
22
23       // FixedTPM and fixedParent must be CLEAR
24       if(   in->objectPublic.t.publicArea.objectAttributes.fixedTPM == SET
25          || in->objectPublic.t.publicArea.objectAttributes.fixedParent == SET)
26           return TPM_RC_ATTRIBUTES + RC_Import_objectPublic;
27
28       // Get parent pointer
29       parentObject = ObjectGet(in->parentHandle);
30
31       if(!AreAttributesForParent(parentObject))
32           return TPM_RC_TYPE + RC_Import_parentHandle;
33
34       if(in->symmetricAlg.algorithm != TPM_ALG_NULL)
35       {
36           // Get inner wrap key size
37           innerKeySize = in->symmetricAlg.keyBits.sym;
38           // Input symmetric key must match the size of algorithm.
39           if(in->encryptionKey.t.size != (innerKeySize + 7) / 8)
40               return TPM_RC_SIZE + RC_Import_encryptionKey;
41       }
42       else
43       {
44           // If input symmetric algorithm is NULL, input symmetric key size must
45           // be 0 as well
46           if(in->encryptionKey.t.size != 0)
47               return TPM_RCS_SIZE + RC_Import_encryptionKey;
48           // If encryptedDuplication is SET, then the object must have an inner
49           // wrapper
50           if(in->objectPublic.t.publicArea.objectAttributes.encryptedDuplication)
51               return TPM_RCS_ATTRIBUTES + RC_Import_encryptionKey;
52       }
53
54       // See if there is an outer wrapper
55       if(in->inSymSeed.t.size != 0)
56       {
57           // Decrypt input secret data via asymmetric decryption. TPM_RC_ATTRIBUTES,
58           // TPM_RC_ECC_POINT, TPM_RC_INSUFFICIENT, TPM_RC_KEY, TPM_RC_NO_RESULT,
59           // TPM_RC_SIZE, TPM_RC_VALUE may be returned at this point
60           result = CryptSecretDecrypt(in->parentHandle, NULL, "DUPLICATE",
61                                       &in->inSymSeed, &data);
62           pAssert(result != TPM_RC_BINDING);


     Page 92                                   TCG Published                                         Family “2.0”
     October 30, 2014                 Copyright © TCG 2006-2014                       Level 00 Revision 01.16
      Trusted Platform Module Library                                               Part 3: Commands

 63           if(result != TPM_RC_SUCCESS)
 64               return RcSafeAddToResult(result, RC_Import_inSymSeed);
 65       }
 66       else
 67       {
 68           // If encrytpedDuplication is set, then the object must have an outer
 69           // wrapper
 70           if(in->objectPublic.t.publicArea.objectAttributes.encryptedDuplication)
 71               return TPM_RCS_ATTRIBUTES + RC_Import_inSymSeed;
 72           data.t.size = 0;
 73       }
 74
 75       // Compute name of object
 76       ObjectComputeName(&(in->objectPublic.t.publicArea), &name);
 77
 78       // Retrieve sensitive from private.
 79       // TPM_RC_INSUFFICIENT, TPM_RC_INTEGRITY, TPM_RC_SIZE may be returned here.
 80       result = DuplicateToSensitive(&in->duplicate, &name, in->parentHandle,
 81                                     in->objectPublic.t.publicArea.nameAlg,
 82                                     (TPM2B_SEED *) &data, &in->symmetricAlg,
 83                                     &in->encryptionKey, &sensitive);
 84       if(result != TPM_RC_SUCCESS)
 85           return RcSafeAddToResult(result, RC_Import_duplicate);
 86
 87       // If the parent of this object has fixedTPM SET, then fully validate this
 88       // object so that validation can be skipped when it is loaded
 89       if(parentObject->publicArea.objectAttributes.fixedTPM == SET)
 90       {
 91           TPM_HANDLE       objectHandle;
 92
 93           // Perform self check on input public area. A TPM_RC_SIZE, TPM_RC_SCHEME,
 94           // TPM_RC_VALUE, TPM_RC_SYMMETRIC, TPM_RC_TYPE, TPM_RC_HASH,
 95           // TPM_RC_ASYMMETRIC, TPM_RC_ATTRIBUTES or TPM_RC_KDF error may be returned
 96           // at this point
 97           result = PublicAttributesValidation(TRUE, in->parentHandle,
 98                                               &in->objectPublic.t.publicArea);
 99           if(result != TPM_RC_SUCCESS)
100               return RcSafeAddToResult(result, RC_Import_objectPublic);
101
102           // Create internal object. A TPM_RC_KEY_SIZE, TPM_RC_KEY or
103           // TPM_RC_OBJECT_MEMORY error may be returned at this point
104           result = ObjectLoad(TPM_RH_NULL, &in->objectPublic.t.publicArea,
105                               &sensitive, NULL, in->parentHandle, FALSE,
106                               &objectHandle);
107           if(result != TPM_RC_SUCCESS)
108               return result;
109
110           // Don't need the object, just needed the checks to be performed so
111           // flush the object
112           ObjectFlush(objectHandle);
113       }
114
115   // Command output
116
117       // Prepare output private data from sensitive
118       SensitiveToPrivate(&sensitive, &name, in->parentHandle,
119                          in->objectPublic.t.publicArea.nameAlg,
120                          &out->outPrivate);
121
122       return TPM_RC_SUCCESS;
123   }
124   #endif // CC_Import


      Family “2.0”                           TCG Published                                  Page 93
      Level 00 Revision 01.16           Copyright © TCG 2006-2014                   October 30, 2014
Part 3: Commands                                                              Trusted Platform Module Library


14     Asymmetric Primitives

14.1    Introduction

The commands in this clause provide low-level primitives for access to the asymmetric algorithms
implemented in the TPM. Many of these commands are only allowed if the asymmetric key is an
unrestricted key.

14.2    TPM2_RSA_Encrypt

14.2.1 General Description

This command performs RSA encryption using the indicated padding scheme according to IETF RFC
3447. If the scheme of keyHandle is TPM_ALG_NULL, then the caller may use inScheme to specify the
padding scheme. If scheme of keyHandle is not TPM_ALG_NULL, then inScheme shall either be
TPM_ALG_NULL or be the same as scheme (TPM_RC_SCHEME).
The key referenced by keyHandle is required to be an RSA key (TPM_RC_KEY) with the decrypt attribute
SET (TPM_RC_ATTRIBUTES).

NOTE            Requiring that the decrypt attribute be set allows the TPM to ensure that the scheme selection is
                done with the presumption that the scheme of the key is a decryption scheme selection. It is
                understood that this command will operate on a key with only the public part loaded so the caller
                may modify any key in any desired way. So, this constraint only serves to simplify the TPM logic.

The three types of allowed padding are:
1) TPM_ALG_OAEP – Data is OAEP padded as described in 7.1 of IETF RFC 3447 (PKCS#1).
   The only supported mask generation is MGF1.
2) TPM_ALG_RSAES – Data is padded as described in 7.2 of IETF RFC 3447 (PKCS#1).
3) TPM_ALG_NULL – Data is not padded by the TPM and the TPM will treat message as an
   unsigned integer and perform a modular exponentiation of message using the public
   exponent of the key referenced by keyHandle. This scheme is only used if both the scheme
   in the key referenced by keyHandle is TPM_ALG_NULL, and the inScheme parameter of the
   command is TPM_ALG_NULL. The input value cannot be larger than the public modulus of
   the key referenced by keyHandle.

                                 Table 41 — Padding Scheme Selection
 keyHandle→scheme             inScheme                          padding scheme used

                              TPM_ALG_NULL                      none
 TPM_ALG_NULL                 TPM_ALG_RSAES                     RSAES
                              TPM_ALG_OAEP                      OAEP
                              TPM_ALG_NULL                      RSAES
 TPM_ALG_RSAES                TPM_ALG_RSAES                     RSAES
                              TPM_ALG_OAEP                      error (TPM_RC_SCHEME)
                              TPM_ALG_NULL                      OAEP
 TPM_ALG_OAEP                 TPM_ALG_RSAES                     error (TPM_RC_SCHEME)
                              TPM_AGL_OAEP                      OAEP

After padding, the data is RSAEP encrypted according to 5.1.1 of IETF RFC 3447 (PKCS#1).


Page 94                                       TCG Published                                        Family “2.0”
October 30, 2014                      Copyright © TCG 2006-2014                     Level 00 Revision 01.16
Trusted Platform Module Library                                                                       Part 3: Commands

NOTE 1             It is required that decrypt be SET so that the commands that load a key can validate that the
                   scheme is consistent rather than have that deferred until the key is used.

NOTE 2             If it is desired to use a key that had restricted SET, the caller may CLEAR restricted and load the
                   public part of the key and use that unrestricted version of the key for encryption.

If inScheme is used, and the scheme requires a hash algorithm it may not be TPM_ALG_NULL.

NOTE 3             Because only the public portion of the key needs to be loaded for this command, th e caller can
                   manipulate the attributes of the key in any way desired. As a result , the TPM shall not check the
                   consistency of the attributes. The only property checking is that the key is an RSA key and that the
                   padding scheme is supported.

The message parameter is limited in size by the padding scheme according to the following table:

                              Table 42 — Message Size Limits Based on Padding
                                          Maximum Message Length
Scheme                                    (mLen) in Octets                     Comments

TPM_ALG_OAEP                              mLen  k – 2hLen – 2
TPM_ALG_RSAES                             mLen  k – 11
TPM_ALG_NULL                              mLen  k                             The numeric value of the message must be
                                                                               less than the numeric value of the public
                                                                               modulus (n).
NOTES
1)   k ≔ the number of byes in the public modulus
2)   hLen ≔ the number of octets in the digest produced by the hash algorithm used in the process

The label parameter is optional. If provided (label.size != 0) then the TPM shall return TPM_RC_VALUE if
the last octet in label is not zero. If a zero octet occurs before label.buffer[label.size-1], the TPM shall
truncate the label at that point. The terminating octet of zero is included in the label used in the padding
scheme.

NOTE 4             If the scheme does not use a label, the TPM will still verify that label is properly formatted if label is
                   present.

The function returns padded and encrypted value outData.
The message parameter in the command may be encrypted using parameter encryption.

NOTE 5             Only the public area of keyHandle is required to be loaded. A public key may be loaded with any
                   desired scheme. If the scheme is to be changed, a different public area must be loaded.


Family “2.0”                                         TCG Published                                                Page 95
Level 00 Revision 01.16                     Copyright © TCG 2006-2014                                 October 30, 2014
Part 3: Commands                                                    Trusted Platform Module Library


14.2.2 Command and Response

                       Table 43 — TPM2_RSA_Encrypt Command
Type                    Name                  Description

                                              TPM_ST_SESSIONS if an audit, encrypt, or decrypt
TPMI_ST_COMMAND_TAG     tag                   session is present; otherwise,
                                              TPM_ST_NO_SESSIONS
UINT32                  commandSize
TPM_CC                  commandCode           TPM_CC_RSA_Encrypt

                                              reference to public portion of RSA key to use for
TPMI_DH_OBJECT          keyHandle             encryption
                                              Auth Index: None

                                              message to be encrypted
                                              NOTE 1     The data type was chosen because it limits the
TPM2B_PUBLIC_KEY_RSA    message                          overall size of the input to no greater than the size
                                                         of the largest RSA public key. This may be larger
                                                         than allowed for keyHandle.

                                              the padding scheme to use if scheme associated with
TPMT_RSA_DECRYPT+       inScheme
                                              keyHandle is TPM_ALG_NULL
                                              optional label L to be associated with the message
TPM2B_DATA              label                 Size of the buffer is zero if no label is present
                                              NOTE 2     See description of label above.


                       Table 44 — TPM2_RSA_Encrypt Response
Type                    Name                  Description

TPM_ST                  tag                   see clause 6
UINT32                  responseSize
TPM_RC                  responseCode

TPM2B_PUBLIC_KEY_RSA    outData               encrypted output


Page 96                                TCG Published                                          Family “2.0”
October 30, 2014                Copyright © TCG 2006-2014                   Level 00 Revision 01.16
     Trusted Platform Module Library                                                                 Part 3: Commands


     14.2.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "RSA_Encrypt_fp.h"
3    #ifdef TPM_CC_RSA_Encrypt // Conditional expansion of this file
4    #ifdef TPM_ALG_RSA


     Error Returns                     Meaning

     TPM_RC_ATTRIBUTES                 decrypt attribute is not SET in key referenced by keyHandle
     TPM_RC_KEY                        keyHandle does not reference an RSA key
     TPM_RC_SCHEME                     incorrect input scheme, or the chosen scheme is not a valid RSA
                                       decrypt scheme
     TPM_RC_VALUE                      the numeric value of message is greater than the public modulus of
                                       the key referenced by keyHandle, or label is not a null-terminated
                                       string

 5   TPM_RC
 6   TPM2_RSA_Encrypt(
 7       RSA_Encrypt_In        *in,                 // IN: input parameter list
 8       RSA_Encrypt_Out       *out                 // OUT: output parameter list
 9       )
10   {
11       TPM_RC                    result;
12       OBJECT                    *rsaKey;
13       TPMT_RSA_DECRYPT          *scheme;
14       char                      *label = NULL;
15
16   // Input Validation
17
18       rsaKey = ObjectGet(in->keyHandle);
19
20       // selected key must be an RSA key
21       if(rsaKey->publicArea.type != TPM_ALG_RSA)
22           return TPM_RC_KEY + RC_RSA_Encrypt_keyHandle;
23
24       // selected key must have the decryption attribute
25       if(rsaKey->publicArea.objectAttributes.decrypt != SET)
26           return TPM_RC_ATTRIBUTES + RC_RSA_Encrypt_keyHandle;
27
28       // Is there a label?
29       if(in->label.t.size > 0)
30       {
31           // label is present, so make sure that is it NULL-terminated
32           if(in->label.t.buffer[in->label.t.size - 1] != 0)
33               return TPM_RC_VALUE + RC_RSA_Encrypt_label;
34           label = (char *)in->label.t.buffer;
35       }
36
37   // Command Output
38
39       // Select a scheme for encryption
40       scheme = CryptSelectRSAScheme(in->keyHandle, &in->inScheme);
41       if(scheme == NULL)
42           return TPM_RC_SCHEME + RC_RSA_Encrypt_inScheme;
43
44       // Encryption. TPM_RC_VALUE, or TPM_RC_SCHEME errors my be returned buy
45       // CryptEncyptRSA. Note: It can also return TPM_RC_ATTRIBUTES if the key does
46       // not have the decrypt attribute but that was checked above.
47       out->outData.t.size = sizeof(out->outData.t.buffer);
48       result = CryptEncryptRSA(&out->outData.t.size, out->outData.t.buffer, rsaKey,

     Family “2.0”                                  TCG Published                                             Page 97
     Level 00 Revision 01.16               Copyright © TCG 2006-2014                                 October 30, 2014
     Part 3: Commands                                              Trusted Platform Module Library

49                              scheme, in->message.t.size, in->message.t.buffer,
50                              label);
51       return result;
52   }
53   #endif
54   #endif // CC_RSA_Encrypt


     Page 98                              TCG Published                              Family “2.0”
     October 30, 2014              Copyright © TCG 2006-2014             Level 00 Revision 01.16
Trusted Platform Module Library                                                        Part 3: Commands


14.3     TPM2_RSA_Decrypt

14.3.1 General Description

This command performs RSA decryption using the indicated padding scheme according to IETF RFC
3447 ((PKCS#1).
The scheme selection for this command is the same as for TPM2_RSA_Encrypt() and is shown in Table
41.
The key referenced by keyHandle shall be an RSA key (TPM_RC_KEY) with restricted CLEAR and
decrypt SET (TPM_RC_ATTRIBUTES).
This command uses the private key of keyHandle for this operation and authorization is required.
The TPM will perform a modular exponentiation of ciphertext using the private exponent associated with
keyHandle (this is described in IETF RFC 3447 (PKCS#1), clause 5.1.2). It will then validate the padding
according to the selected scheme. If the padding checks fail, TPM_RC_VALUE is returned. Otherwise,
the data is returned with the padding removed. If no padding is used, the returned value is an unsigned
integer value that is the result of the modular exponentiation of cipherText using the private exponent of
keyHandle. The returned value may include leading octets zeros so that it is the same size as the public
modulus. For the other padding schemes, the returned value will be smaller than the public modulus but
will contain all the data remaining after padding is removed and this may include leading zeros if the
original encrypted value contained leading zeros.
If a label is used in the padding process of the scheme during encryption, the label parameter is required
to be present in the decryption process and label is required to be the same in both cases. If label is not
the same, the decrypt operation is very likely to fail ((TPM_RC_VALUE). If label is present (label.size !=
0), it shall be a NULL-terminated string or the TPM will return TPM_RC_VALUE.

NOTE 1          The size of label includes the terminating null.

The message parameter in the response may be encrypted using parameter encryption.
If inScheme is used, and the scheme requires a hash algorithm it may not be TPM_ALG_NULL.
If the scheme does not require a label, the value in label is not used but the size of the label field is
checked for consistency with the indicated data type (TPM2B_DATA). That is, the field may not be larger
than allowed for a TPM2B_DATA.


Family “2.0”                                    TCG Published                                      Page 99
Level 00 Revision 01.16                 Copyright © TCG 2006-2014                      October 30, 2014
Part 3: Commands                                                   Trusted Platform Module Library


14.3.2 Command and Response

                       Table 45 — TPM2_RSA_Decrypt Command
Type                    Name                  Description

TPMI_ST_COMMAND_TAG     tag                   TPM_ST_SESSIONS
UINT32                  commandSize
TPM_CC                  commandCode           TPM_CC_RSA_Decrypt

                                              RSA key to use for decryption
TPMI_DH_OBJECT          @keyHandle            Auth Index: 1
                                              Auth Role: USER

                                              cipher text to be decrypted
TPM2B_PUBLIC_KEY_RSA    cipherText            NOTE       An encrypted RSA data block is the size of the
                                                         public modulus.

                                              the padding scheme to use if scheme associated with
TPMT_RSA_DECRYPT+       inScheme
                                              keyHandle is TPM_ALG_NULL
                                              label whose association with the message is to be
TPM2B_DATA              label
                                              verified


                       Table 46 — TPM2_RSA_Decrypt Response
Type                    Name                  Description

TPM_ST                  tag                   see clause 6
UINT32                  responseSize
TPM_RC                  responseCode

TPM2B_PUBLIC_KEY_RSA    message               decrypted output


Page 100                               TCG Published                                       Family “2.0”
October 30, 2014                Copyright © TCG 2006-2014                   Level 00 Revision 01.16
     Trusted Platform Module Library                                                                   Part 3: Commands


     14.3.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "RSA_Decrypt_fp.h"
3    #ifdef TPM_CC_RSA_Decrypt // Conditional expansion of this file
4    #ifdef TPM_ALG_RSA


     Error Returns                     Meaning

     TPM_RC_BINDING                    The public an private parts of the key are not properly bound
     TPM_RC_KEY                        keyHandle does not reference an unrestricted decrypt key
     TPM_RC_SCHEME                     incorrect input scheme, or the chosen scheme is not a valid RSA
                                       decrypt scheme
     TPM_RC_SIZE                       cipherText is not the size of the modulus of key referenced by
                                       keyHandle
     TPM_RC_VALUE                      label is not a null terminated string or the value of cipherText is
                                       greater that the modulus of keyHandle

 5   TPM_RC
 6   TPM2_RSA_Decrypt(
 7       RSA_Decrypt_In        *in,                   // IN: input parameter list
 8       RSA_Decrypt_Out       *out                   // OUT: output parameter list
 9       )
10   {
11       TPM_RC                             result;
12       OBJECT                            *rsaKey;
13       TPMT_RSA_DECRYPT                  *scheme;
14       char                              *label = NULL;
15
16   // Input Validation
17
18       rsaKey = ObjectGet(in->keyHandle);
19
20       // The selected key must be an RSA key
21       if(rsaKey->publicArea.type != TPM_ALG_RSA)
22           return TPM_RC_KEY + RC_RSA_Decrypt_keyHandle;
23
24       // The selected key must be an unrestricted decryption key
25       if(   rsaKey->publicArea.objectAttributes.restricted == SET
26          || rsaKey->publicArea.objectAttributes.decrypt == CLEAR)
27           return TPM_RC_ATTRIBUTES + RC_RSA_Decrypt_keyHandle;
28
29       //   NOTE: Proper operation of this command requires that the sensitive area
30       //   of the key is loaded. This is assured because authorization is required
31       //   to use the sensitive area of the key. In order to check the authorization,
32       //   the sensitive area has to be loaded, even if authorization is with policy.
33
34       // If label is present, make sure that it is a NULL-terminated string
35       if(in->label.t.size > 0)
36       {
37           // Present, so make sure that it is NULL-terminated
38           if(in->label.t.buffer[in->label.t.size - 1] != 0)
39               return TPM_RC_VALUE + RC_RSA_Decrypt_label;
40           label = (char *)in->label.t.buffer;
41       }
42
43   // Command Output
44
45       // Select a scheme for decrypt.
46       scheme = CryptSelectRSAScheme(in->keyHandle, &in->inScheme);

     Family “2.0”                                   TCG Published                                             Page 101
     Level 00 Revision 01.16                Copyright © TCG 2006-2014                                  October 30, 2014
     Part 3: Commands                                               Trusted Platform Module Library

47      if(scheme == NULL)
48          return TPM_RC_SCHEME + RC_RSA_Decrypt_inScheme;
49
50      // Decryption. TPM_RC_VALUE, TPM_RC_SIZE, and TPM_RC_KEY error may be
51      // returned by CryptDecryptRSA.
52      // NOTE: CryptDecryptRSA can also return TPM_RC_ATTRIBUTES or TPM_RC_BINDING
53      // when the key is not a decryption key but that was checked above.
54      out->message.t.size = sizeof(out->message.t.buffer);
55      result = CryptDecryptRSA(&out->message.t.size, out->message.t.buffer, rsaKey,
56                               scheme, in->cipherText.t.size,
57                               in->cipherText.t.buffer,
58                               label);
59
60       return result;
61   }
62   #endif
63   #endif // CC_RSA_Decrypt


     Page 102                              TCG Published                                Family “2.0”
     October 30, 2014               Copyright © TCG 2006-2014             Level 00 Revision 01.16
Trusted Platform Module Library                                                                Part 3: Commands


14.4   TPM2_ECDH_KeyGen

14.4.1 General Description

This command uses the TPM to generate an ephemeral key pair ( de, Qe where Qe ≔ [de]G). It uses the
private ephemeral key and a loaded public key (QS) to compute the shared secret value (P ≔ [hde]QS).
keyHandle shall refer to a loaded ECC key. The sensitive portion of this key need not be loaded.
The curve parameters of the loaded ECC key are used to generate the ephemeral key.

NOTE 1          This function is the equivalent of encrypting data to another object’s public key. The seed value is
                used in a KDF to generate a symmetric key and that key is used to encrypt the data. Once the data
                is encrypted and the symmetric key discarded, only the ob ject with the private portion of the
                keyHandle will be able to decrypt it.

The zPoint in the response may be encrypted using parameter encryption.


Family “2.0”                                   TCG Published                                            Page 103
Level 00 Revision 01.16                Copyright © TCG 2006-2014                              October 30, 2014
Part 3: Commands                                                 Trusted Platform Module Library


14.4.2 Command and Response

                      Table 47 — TPM2_ECDH_KeyGen Command
Type                   Name                  Description

                                             TPM_ST_SESSIONS if an audit or encrypt session is
TPMI_ST_COMMAND_TAG    tag
                                             present; otherwise, TPM_ST_NO_SESSIONS
UINT32                 commandSize
TPM_CC                 commandCode           TPM_CC_ECDH_KeyGen

                                             Handle of a loaded ECC key public area.
TPMI_DH_OBJECT         keyHandle
                                             Auth Index: None


                      Table 48 — TPM2_ECDH_KeyGen Response
Type                   Name                  Description

TPM_ST                 tag                   see clause 6
UINT32                 responseSize
TPM_RC                 responseCode

TPM2B_ECC_POINT        zPoint                results of P ≔ h[de]Qs

TPM2B_ECC_POINT        pubPoint              generated ephemeral public point (Qe)


Page 104                              TCG Published                                    Family “2.0”
October 30, 2014             Copyright © TCG 2006-2014                  Level 00 Revision 01.16
     Trusted Platform Module Library                                                            Part 3: Commands


     14.4.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "ECDH_KeyGen_fp.h"
3    #ifdef TPM_CC_ECDH_KeyGen // Conditional expansion of this file
4    #ifdef TPM_ALG_ECC


     Error Returns                     Meaning

     TPM_RC_KEY                        keyHandle does not reference a non-restricted decryption ECC key

 5   TPM_RC
 6   TPM2_ECDH_KeyGen(
 7       ECDH_KeyGen_In        *in,                 // IN: input parameter list
 8       ECDH_KeyGen_Out       *out                 // OUT: output parameter list
 9       )
10   {
11       OBJECT                    *eccKey;
12       TPM2B_ECC_PARAMETER        sensitive;
13       TPM_RC                     result;
14
15   // Input Validation
16
17       eccKey = ObjectGet(in->keyHandle);
18
19       // Input key must be a non-restricted, decrypt ECC key
20       if(   eccKey->publicArea.type != TPM_ALG_ECC)
21           return TPM_RCS_KEY + RC_ECDH_KeyGen_keyHandle;
22
23       if(     eccKey->publicArea.objectAttributes.restricted == SET
24          ||   eccKey->publicArea.objectAttributes.decrypt != SET
25         )
26           return TPM_RC_KEY + RC_ECDH_KeyGen_keyHandle;
27
28   // Command Output
29       do
30       {
31           // Create ephemeral ECC key
32           CryptNewEccKey(eccKey->publicArea.parameters.eccDetail.curveID,
33                          &out->pubPoint.t.point, &sensitive);
34
35           out->pubPoint.t.size = TPMS_ECC_POINT_Marshal(&out->pubPoint.t.point,
36                                  NULL, NULL);
37
38           // Compute Z
39           result = CryptEccPointMultiply(&out->zPoint.t.point,
40                                      eccKey->publicArea.parameters.eccDetail.curveID,
41                                      &sensitive, &eccKey->publicArea.unique.ecc);
42           // The point in the key is not on the curve. Indicate that the key is bad.
43           if(result == TPM_RC_ECC_POINT)
44               return TPM_RC_KEY + RC_ECDH_KeyGen_keyHandle;
45           // The other possible error is TPM_RC_NO_RESULT indicating that the
46           // multiplication resulted in the point at infinity, so get a new
47           // random key and start over (hardly ever happens).
48       }
49       while(result == TPM_RC_NO_RESULT);
50
51       if(result == TPM_RC_SUCCESS)
52           // Marshal the values to generate the point.
53           out->zPoint.t.size = TPMS_ECC_POINT_Marshal(&out->zPoint.t.point,
54                                                       NULL, NULL);
55
56       return result;

     Family “2.0”                                  TCG Published                                          Page 105
     Level 00 Revision 01.16               Copyright © TCG 2006-2014                            October 30, 2014
     Part 3: Commands                                       Trusted Platform Module Library

57   }
58   #endif
59   #endif // CC_ECDH_KeyGen


     Page 106                        TCG Published                            Family “2.0”
     October 30, 2014           Copyright © TCG 2006-2014        Level 00 Revision 01.16
Trusted Platform Module Library                                                         Part 3: Commands


14.5   TPM2_ECDH_ZGen

14.5.1 General Description

This command uses the TPM to recover the Z value from a public point (QB) and a private key (ds). It will
perform the multiplication of the provided inPoint (QB) with the private key (ds) and return the coordinates
of the resultant point (Z = (xZ , yZ) ≔ [hds]QB; where h is the cofactor of the curve).
keyHandle shall refer to a loaded, ECC key (TPM_RC_KEY) with the restricted attribute CLEAR and the
decrypt attribute SET (TPM_RC_ATTRIBUTES).
The scheme of the key referenced by keyHandle is required to be either TPM_ALG_ECDH or
TPM_ALG_NULL (TPM_RC_SCHEME).
inPoint is required to be on the curve of the key referenced by keyHandle (TPM_RC_ECC_POINT).
The parameters of the key referenced by keyHandle are used to perform the point multiplication.


Family “2.0”                                 TCG Published                                       Page 107
Level 00 Revision 01.16              Copyright © TCG 2006-2014                          October 30, 2014
Part 3: Commands                                                   Trusted Platform Module Library


14.5.2 Command and Response

                      Table 49 — TPM2_ECDH_ZGen Command
Type                   Name                  Description

TPMI_ST_COMMAND_TAG    tag                   TPM_ST_SESSIONS
UINT32                 commandSize
TPM_CC                 commandCode           TPM_CC_ECDH_ZGen

                                             handle of a loaded ECC key
TPMI_DH_OBJECT         @keyHandle            Auth Index: 1
                                             Auth Role: USER

TPM2B_ECC_POINT        inPoint               a public key


                      Table 50 — TPM2_ECDH_ZGen Response
Type                   Name                  Description

TPM_ST                 tag                   see clause 6
UINT32                 responseSize
TPM_RC                 responseCode

                                             X and Y coordinates of the product of the multiplication
TPM2B_ECC_POINT        outPoint
                                             Z = (xZ , yZ) ≔ [hdS]QB


Page 108                              TCG Published                                     Family “2.0”
October 30, 2014             Copyright © TCG 2006-2014                   Level 00 Revision 01.16
     Trusted Platform Module Library                                                               Part 3: Commands


     14.5.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "ECDH_ZGen_fp.h"
3    #ifdef TPM_CC_ECDH_ZGen // Conditional expansion of this file
4    #ifdef TPM_ALG_ECC


     Error Returns                     Meaning

     TPM_RC_ATTRIBUTES                 key referenced by keyA is restricted or not a decrypt key
     TPM_RC_KEY                        key referenced by keyA is not an ECC key
     TPM_RC_NO_RESULT                  multiplying inPoint resulted in a point at infinity
     TPM_RC_SCHEME                     the scheme of the key referenced by keyA is not TPM_ALG_NULL,
                                       TPM_ALG_ECDH,

 5   TPM_RC
 6   TPM2_ECDH_ZGen(
 7       ECDH_ZGen_In      *in,                  // IN: input parameter list
 8       ECDH_ZGen_Out     *out                  // OUT: output parameter list
 9       )
10   {
11       TPM_RC                     result;
12       OBJECT                    *eccKey;
13
14   // Input Validation
15
16       eccKey = ObjectGet(in->keyHandle);
17
18       // Input key must be a non-restricted, decrypt ECC key
19       if(   eccKey->publicArea.type != TPM_ALG_ECC)
20           return TPM_RCS_KEY + RC_ECDH_ZGen_keyHandle;
21
22       if(     eccKey->publicArea.objectAttributes.restricted == SET
23          ||   eccKey->publicArea.objectAttributes.decrypt != SET
24         )
25           return TPM_RC_KEY + RC_ECDH_ZGen_keyHandle;
26
27       // Make sure the scheme allows this use
28       if(     eccKey->publicArea.parameters.eccDetail.scheme.scheme != TPM_ALG_ECDH
29           && eccKey->publicArea.parameters.eccDetail.scheme.scheme != TPM_ALG_NULL)
30           return TPM_RC_SCHEME + RC_ECDH_ZGen_keyHandle;
31
32   // Command Output
33
34       // Compute Z. TPM_RC_ECC_POINT or TPM_RC_NO_RESULT may be returned here.
35       result = CryptEccPointMultiply(&out->outPoint.t.point,
36                                      eccKey->publicArea.parameters.eccDetail.curveID,
37                                      &eccKey->sensitive.sensitive.ecc,
38                                      &in->inPoint.t.point);
39       if(result != TPM_RC_SUCCESS)
40           return RcSafeAddToResult(result, RC_ECDH_ZGen_inPoint);
41
42       out->outPoint.t.size = TPMS_ECC_POINT_Marshal(&out->outPoint.t.point,
43                                                     NULL, NULL);
44
45       return TPM_RC_SUCCESS;
46   }
47   #endif
48   #endif // CC_ECDH_ZGen


     Family “2.0”                                    TCG Published                                        Page 109
     Level 00 Revision 01.16                Copyright © TCG 2006-2014                              October 30, 2014
Part 3: Commands                                                       Trusted Platform Module Library


14.6   TPM2_ECC_Parameters

14.6.1 General Description

This command returns the parameters of an ECC curve identified by its TCG-assigned curveID.

14.6.2 Command and Response

                          Table 51 — TPM2_ECC_Parameters Command
Type                              Name                  Description

                                                        TPM_ST_SESSIONS if an audit session is
TPMI_ST_COMMAND_TAG               tag
                                                        present; otherwise, TPM_ST_NO_SESSIONS
UINT32                            commandSize
TPM_CC                            commandCode           TPM_CC_ECC_Parameters

TPMI_ECC_CURVE                    curveID               parameter set selector


                          Table 52 — TPM2_ECC_Parameters Response
Type                              Name                  Description

TPM_ST                            tag                   see clause 6
UINT32                            responseSize
TPM_RC                            responseCode

TPMS_ALGORITHM_DETAIL_ECC         parameters            ECC parameters for the selected curve


Page 110                                    TCG Published                                   Family “2.0”
October 30, 2014                   Copyright © TCG 2006-2014                     Level 00 Revision 01.16
     Trusted Platform Module Library                                               Part 3: Commands


     14.6.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "ECC_Parameters_fp.h"
3    #ifdef TPM_CC_ECC_Parameters // Conditional expansion of this file
4    #ifdef TPM_ALG_ECC


     Error Returns                     Meaning

     TPM_RC_VALUE                      Unsupported ECC curve ID

 5   TPM_RC
 6   TPM2_ECC_Parameters(
 7       ECC_Parameters_In     *in,                // IN: input parameter list
 8       ECC_Parameters_Out    *out                // OUT: output parameter list
 9       )
10   {
11   // Command Output
12
13       // Get ECC curve parameters
14       if(CryptEccGetParameters(in->curveID, &out->parameters))
15           return TPM_RC_SUCCESS;
16       else
17           return TPM_RC_VALUE + RC_ECC_Parameters_curveID;
18   }
19   #endif
20   #endif // CC_ECC_Parameters


     Family “2.0”                                 TCG Published                           Page 111
     Level 00 Revision 01.16               Copyright © TCG 2006-2014               October 30, 2014
Part 3: Commands                                                                 Trusted Platform Module Library


14.7     TPM2_ZGen_2Phase

14.7.1    General Description

This command supports two-phase key exchange protocols. The command is used in combination with
TPM2_EC_Ephemeral(). TPM2_EC_Ephemeral() generates an ephemeral key and returns the public
point of that ephemeral key along with a numeric value that allows the TPM to regenerate the associated
private key.
The input parameters for this command are a static public key (inQsU), an ephemeral key (inQeU) from
party B, and the commitCounter returned by TPM2_EC_Ephemeral(). The TPM uses the counter value to
regenerate the ephemeral private key (de,V) and the associated public key (Qe,V). keyA provides the static
ephemeral elements ds,V and Qs,V. This provides the two pairs of ephemeral and static keys that are
required for the schemes supported by this command.
The TPM will compute Z or Zs and Ze according to the selected scheme. If the scheme is not a two-phase
key exchange scheme or if the scheme is not supported, the TPM will return TPM_RC_SCHEME.
It is an error if inQsB or inQeB are not on the curve of keyA (TPM_RC_ECC_POINT).

The two-phase key schemes that were assigned an algorithm ID as of the time of the publication of this
specification are TPM_ALG_ECDH, TPM_ALG_ECMQV, and TPM_ALG_SM2.

If this command is supported, then support for TPM_ALG_ECDH is required. Support for
TPM_ALG_ECMQV or TPM_ALG_SM2 is optional.

NOTE 1          If SM2 is supported and this command is supported, then the implementation is required to support
                the key exchange protocol of SM2, part 3.


For TPM_ALG_ECDH outZ1 will be Zs and outZ2 will Ze as defined in 6.1.1.2 of SP800-56A.

NOTE 2          An unrestricted decryption key using ECDH may be used in either TPM2_ECDH_ZGen() or
                TPM2_ZGen_2Phase as the computation done with the private part of keyA is the same in both
                cases.


For TPM_ALG_ECMQV or TPM_ALG_SM2 outZ1 will be Z and outZ2 will be an Empty Point.

NOTE 3          An Empty Point has two Empty Buffers as coordinates meaning the minimum size value for outZ2
                will be four.


If the input scheme is TPM_ALG_ECDH, then outZ1 will be Zs and outZ2 will be Ze. For schemes like
MQV (including SM2), outZ1 will contain the computed value and outZ2 will be an Empty Point.

NOTE            The Z values returned by the TPM are a full point and not just an x -coordinate.

If a computation of either Z produces the point at infinity, then the corresponding Z value will be an Empty
Point.


Page 112                                        TCG Published                                      Family “2.0”
October 30, 2014                       Copyright © TCG 2006-2014                        Level 00 Revision 01.16
Trusted Platform Module Library                                                              Part 3: Commands


14.7.2   Command and Response

                            Table 53 — TPM2_ZGen_2Phase Command
Type                          Name                  Description

TPMI_ST_COMMAND_TAG           tag                   TPM_ST_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode           TPM_CC_ ZGen_2Phase

                                                    handle of an unrestricted decryption key ECC
                                                    The private key referenced by this handle is used as dS,A
TPMI_DH_OBJECT                @keyA
                                                    Auth Index: 1
                                                    Auth Role: USER

TPM2B_ECC_POINT               inQsB                 other party’s static public key (Qs,B = (Xs,B, Ys,B))

TPM2B_ECC_POINT               inQeB                 other party's ephemeral public key (Qe,B = (Xe,B, Ye,B))
TPMI_ECC_KEY_EXCHANGE         inScheme              the key exchange scheme
UINT16                        counter               value returned by TPM2_EC_Ephemeral()


                            Table 54 — TPM2_ZGen_2Phase Response
Type                          Name                  Description

TPM_ST                        tag
UINT32                        responseSize
TPM_RC                        responseCode

                                                    X and Y coordinates of the computed value (scheme
TPM2B_ECC_POINT               outZ1
                                                    dependent)
                                                    X and Y coordinates of the second computed value
TPM2B_ECC_POINT               outZ2
                                                    (scheme dependent)


Family “2.0”                                 TCG Published                                              Page 113
Level 00 Revision 01.16               Copyright © TCG 2006-2014                              October 30, 2014
     Part 3: Commands                                                               Trusted Platform Module Library


     14.7.3   Detailed Actions

1    #include "InternalRoutines.h"
2    #include "ZGen_2Phase_fp.h"
3    #ifdef TPM_CC_ZGen_2Phase // Conditional expansion of this file

     This command uses the TPM to recover one or two Z values in a two phase key exchange protocol

     Error Returns                    Meaning

     TPM_RC_ATTRIBUTES                key referenced by keyA is restricted or not a decrypt key
     TPM_RC_ECC_POINT                 inQsB or inQeB is not on the curve of the key reference by keyA
     TPM_RC_KEY                       key referenced by keyA is not an ECC key
     TPM_RC_SCHEME                    the scheme of the key referenced by keyA is not TPM_ALG_NULL,
                                      TPM_ALG_ECDH, TPM_ALG_ECMQV or TPM_ALG_SM2

 4   TPM_RC
 5   TPM2_ZGen_2Phase(
 6       ZGen_2Phase_In        *in,                 // IN: input parameter list
 7       ZGen_2Phase_Out       *out                 // OUT: output parameter list
 8       )
 9   {
10       TPM_RC                    result;
11       OBJECT                   *eccKey;
12       TPM2B_ECC_PARAMETER       r;
13       TPM_ALG_ID                scheme;
14
15   // Input Validation
16
17       eccKey = ObjectGet(in->keyA);
18
19       // keyA must be an ECC key
20       if(eccKey->publicArea.type != TPM_ALG_ECC)
21           return TPM_RC_KEY + RC_ZGen_2Phase_keyA;
22
23       // keyA must not be restricted and must be a decrypt key
24       if(   eccKey->publicArea.objectAttributes.restricted == SET
25          || eccKey->publicArea.objectAttributes.decrypt != SET
26         )
27           return TPM_RC_ATTRIBUTES + RC_ZGen_2Phase_keyA;
28
29       // if the scheme of keyA is TPM_ALG_NULL, then use the input scheme; otherwise
30       // the input scheme must be the same as the scheme of keyA
31       scheme = eccKey->publicArea.parameters.asymDetail.scheme.scheme;
32       if(scheme != TPM_ALG_NULL)
33       {
34           if(scheme != in->inScheme)
35               return TPM_RC_SCHEME + RC_ZGen_2Phase_inScheme;
36       }
37       else
38           scheme = in->inScheme;
39       if(scheme == TPM_ALG_NULL)
40           return TPM_RC_SCHEME + RC_ZGen_2Phase_inScheme;
41
42       // Input points must be on the curve of keyA
43       if(!CryptEccIsPointOnCurve(eccKey->publicArea.parameters.eccDetail.curveID,
44                                  &in->inQsB.t.point))
45           return TPM_RC_ECC_POINT + RC_ZGen_2Phase_inQsB;
46
47       if(!CryptEccIsPointOnCurve(eccKey->publicArea.parameters.eccDetail.curveID,
48                                  &in->inQeB.t.point))


     Page 114                                      TCG Published                                        Family “2.0”
     October 30, 2014                     Copyright © TCG 2006-2014                       Level 00 Revision 01.16
     Trusted Platform Module Library                                             Part 3: Commands

49           return TPM_RC_ECC_POINT + RC_ZGen_2Phase_inQeB;
50
51       if(!CryptGenerateR(&r, &in->counter,
52                          eccKey->publicArea.parameters.eccDetail.curveID,
53                          NULL))
54               return TPM_RC_VALUE + RC_ZGen_2Phase_counter;
55
56   // Command Output
57
58       result = CryptEcc2PhaseKeyExchange(&out->outZ1.t.point,
59                                       &out->outZ2.t.point,
60                                       eccKey->publicArea.parameters.eccDetail.curveID,
61                                       scheme,
62                                       &eccKey->sensitive.sensitive.ecc,
63                                       &r,
64                                       &in->inQsB.t.point,
65                                       &in->inQeB.t.point);
66       if(result == TPM_RC_SCHEME)
67           return TPM_RC_SCHEME + RC_ZGen_2Phase_inScheme;
68
69       if(result == TPM_RC_SUCCESS)
70           CryptEndCommit(in->counter);
71
72       return result;
73   }
74   #endif


     Family “2.0”                           TCG Published                                   Page 115
     Level 00 Revision 01.16           Copyright © TCG 2006-2014                 October 30, 2014
Part 3: Commands                                                        Trusted Platform Module Library


15     Symmetric Primitives

15.1    Introduction

The commands in this clause provide low-level primitives for access to the symmetric algorithms
implemented in the TPM that operate on blocks of data. These include symmetric encryption and
decryption as well as hash and HMAC. All of the commands in this group are stateless. That is, they have
no persistent state that is retained in the TPM when the command is complete.
For hashing, HMAC, and Events that require large blocks of data with retained state, the sequence
commands are provided (see clause 1).
Some of the symmetric encryption/decryption modes use an IV. When an IV is used, it may be an
initiation value or a chained value from a previous stage. The chaining for each mode is:


Page 116                                   TCG Published                                   Family “2.0”
October 30, 2014                    Copyright © TCG 2006-2014                 Level 00 Revision 01.16
Trusted Platform Module Library                                                                          Part 3: Commands

                               Table 55 — Symmetric Chaining Process
Mode                 Chaining process

TPM_ALG_CTR          The TPM will increment the entire IV provided by the caller. The next count value will be
                     returned to the caller as ivOut. This can be the input value to the next encrypt or decrypt
                     operation.
                     ivIn is required to be the size of a block encrypted by the selected algorithm and key
                     combination. If the size of ivIn is not correct, the TPM shall return TPM_RC_SIZE.
                     EXAMPLE 1 AES requires that ivIn be 128 bits (16 octets).
                     ivOut will be the size of a cipher block and not the size of the last encrypted block.
                     NOTE         ivOut will be the value of the counter after the last block is encrypted.
                     EXAMPLE 2 If ivIn were 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0016 and four data blocks
                                   were encrypted, ivOut will have a value of
                                   00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0416.
                     All the bits of the IV are incremented as if it were an unsigned integer.
TPM_ALG_OFB          In Output Feedback (OFB), the output of the pseudo-random function (the block encryption
                     algorithm) is XORed with a plaintext block to produce a ciphertext block. ivOut will be the
                     value that was XORed with the last plaintext block. That value can be used as the ivIn for a
                     next buffer.
                     ivIn is required to be the size of a block encrypted by the selected algorithm and key
                     combination. If the size of ivIn is not correct, the TPM shall return TPM_RC_SIZE.
                     ivOut will be the size of a cipher block and not the size of the last encrypted block.
TPM_ALG_CBC          For Cipher Block Chaining (CBC), a block of ciphertext is XORed with the next plaintext
                     block and that block is encrypted. The encrypted block is then input to the encryption of the
                     next block. The last ciphertext block then is used as an IV for the next buffer.
                     Even though the last ciphertext block is evident in the encrypted data, it is also returned in
                     ivOut.
                     ivIn is required to be the size of a block encrypted by the selected algorithm and key
                     combination. If the size of ivIn is not correct, the TPM shall return TPM_RC_SIZE.
                     inData is required to be an even multiple of the block encrypted by the selected algorithm
                     and key combination. If the size of inData is not correct, the TPM shall return
                     TPM_RC_SIZE.
TPM_ALG_CFB          Similar to CBC in that the last ciphertext block is an input to the encryption of the next block.
                     ivOut will be the value that was XORed with the last plaintext block. That value can be used
                     as the ivIn for a next buffer.
                     ivIn is required to be the size of a block encrypted by the selected algorithm and key
                     combination. If the size of ivIn is not correct, the TPM shall return TPM_RC_SIZE.
                     ivOut will be the size of a cipher block and not the size of the last encrypted block.
TPM_ALG_ECB          Electronic Codebook (ECB) has no chaining. Each block of plaintext is encrypted using the
                     key. ECB does not support chaining and ivIn shall be the Empty Buffer. ivOut will be the
                     Empty Buffer.
                     inData is required to be an even multiple of the block encrypted by the selected algorithm
                     and key combination. If the size of inData is not correct, the TPM shall return
                     TPM_RC_SIZE.


Family “2.0”                                     TCG Published                                                  Page 117
Level 00 Revision 01.16                Copyright © TCG 2006-2014                                         October 30, 2014
Part 3: Commands                                                    Trusted Platform Module Library


15.2   TPM2_EncryptDecrypt

15.2.1 General Description

This command performs symmetric encryption or decryption.
keyHandle shall reference a symmetric cipher object (TPM_RC_KEY).
For a restricted key, mode shall be either the same as the mode of the key, or TPM_ALG_NULL
(TPM_RC_VALUE). For an unrestricted key, mode may be the same or different from the mode of the key
but both shall not be TPM_ALG_NULL (TPM_RC_VALUE). If different, mode overrides the mode of the
key.
If the TPM allows this command to be canceled before completion, then the TPM may produce
incremental results and return TPM_RC_SUCCESS rather than TPM_RC_CANCELED. In such case,
outData may be less than inData.


Page 118                                 TCG Published                                Family “2.0”
October 30, 2014                  Copyright © TCG 2006-2014               Level 00 Revision 01.16
Trusted Platform Module Library                                                           Part 3: Commands


15.2.2 Command and Response

                           Table 56 — TPM2_EncryptDecrypt Command
Type                          Name                  Description

TPMI_ST_COMMAND_TAG           tag                   TPM_ST_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode           TPM_CC_EncryptDecrypt

                                                    the symmetric key used for the operation
TPMI_DH_OBJECT                @keyHandle            Auth Index: 1
                                                    Auth Role: USER

                                                    if YES, then the operation is decryption; if NO, the
TPMI_YES_NO                   decrypt
                                                    operation is encryption
                                                    symmetric mode
TPMI_ALG_SYM_MODE+            mode                  For a restricted key, this field shall match the default
                                                    mode of the key or be TPM_ALG_NULL.
TPM2B_IV                      ivIn                  an initial value as required by the algorithm
TPM2B_MAX_BUFFER              inData                the data to be encrypted/decrypted


                           Table 57 — TPM2_EncryptDecrypt Response
Type                          Name                  Description

TPM_ST                        tag                   see clause 6
UINT32                        responseSize
TPM_RC                        responseCode

TPM2B_MAX_BUFFER              outData               encrypted or decrypted output
TPM2B_IV                      ivOut                 chaining value to use for IV in next round


Family “2.0”                                 TCG Published                                          Page 119
Level 00 Revision 01.16               Copyright © TCG 2006-2014                           October 30, 2014
     Part 3: Commands                                                               Trusted Platform Module Library


     15.2.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "EncryptDecrypt_fp.h"
3    #ifdef TPM_CC_EncryptDecrypt // Conditional expansion of this file


     Error Returns                   Meaning

     TPM_RC_KEY                      is not a symmetric decryption key with both public and private
                                     portions loaded
     TPM_RC_SIZE                     IvIn size is incompatible with the block cipher mode; or inData size is
                                     not an even multiple of the block size for CBC or ECB mode
     TPM_RC_VALUE                    keyHandle is restricted and the argument mode does not match the
                                     key's mode

 4   TPM_RC
 5   TPM2_EncryptDecrypt(
 6       EncryptDecrypt_In    *in,                 // IN: input parameter list
 7       EncryptDecrypt_Out   *out                 // OUT: output parameter list
 8       )
 9   {
10       OBJECT               *symKey;
11       UINT16               keySize;
12       UINT16               blockSize;
13       BYTE                 *key;
14       TPM_ALG_ID           alg;
15
16   // Input Validation
17       symKey = ObjectGet(in->keyHandle);
18
19       // The input key should be a symmetric decrypt key.
20       if(    symKey->publicArea.type != TPM_ALG_SYMCIPHER
21          || symKey->attributes.publicOnly == SET)
22           return TPM_RC_KEY + RC_EncryptDecrypt_keyHandle;
23
24       // If the input mode is TPM_ALG_NULL, use the key's mode
25       if( in->mode == TPM_ALG_NULL)
26           in->mode = symKey->publicArea.parameters.symDetail.sym.mode.sym;
27
28       // If the key is restricted, the input symmetric mode should match the key's
29       // symmetric mode
30       if(   symKey->publicArea.objectAttributes.restricted == SET
31          && symKey->publicArea.parameters.symDetail.sym.mode.sym != in->mode)
32           return TPM_RC_VALUE + RC_EncryptDecrypt_mode;
33
34       // If the mode is null, then we have a problem.
35       // Note: Construction of a TPMT_SYM_DEF does not allow the 'mode' to be
36       // TPM_ALG_NULL so setting in->mode to the mode of the key should have
37       // produced a valid mode. However, this is suspenders.
38       if(in->mode == TPM_ALG_NULL)
39           return TPM_RC_VALUE + RC_EncryptDecrypt_mode;
40
41       // The input iv for ECB mode should be null. All the other modes should
42       // have an iv size same as encryption block size
43
44       keySize = symKey->publicArea.parameters.symDetail.sym.keyBits.sym;
45       alg = symKey->publicArea.parameters.symDetail.sym.algorithm;
46       blockSize = CryptGetSymmetricBlockSize(alg, keySize);
47       if(   (in->mode == TPM_ALG_ECB && in->ivIn.t.size != 0)
48          || (in->mode != TPM_ALG_ECB && in->ivIn.t.size != blockSize))
49           return TPM_RC_SIZE + RC_EncryptDecrypt_ivIn;

     Page 120                                     TCG Published                                           Family “2.0”
     October 30, 2014                    Copyright © TCG 2006-2014                         Level 00 Revision 01.16
     Trusted Platform Module Library                                             Part 3: Commands

50
51       // The input data size of CBC mode or ECB mode must be an even multiple of
52       // the symmetric algorithm's block size
53       if(   (in->mode == TPM_ALG_CBC || in->mode == TPM_ALG_ECB)
54          && (in->inData.t.size % blockSize) != 0)
55           return TPM_RC_SIZE + RC_EncryptDecrypt_inData;
56
57       // Copy IV
58       // Note: This is copied here so that the calls to the encrypt/decrypt functions
59       // will modify the output buffer, not the input buffer
60       out->ivOut = in->ivIn;
61
62   // Command Output
63
64       key = symKey->sensitive.sensitive.sym.t.buffer;
65       // For symmetric encryption, the cipher data size is the same as plain data
66       // size.
67       out->outData.t.size = in->inData.t.size;
68       if(in->decrypt == YES)
69       {
70           // Decrypt data to output
71           CryptSymmetricDecrypt(out->outData.t.buffer,
72                                 alg,
73                                 keySize, in->mode, key,
74                                 &(out->ivOut),
75                                 in->inData.t.size,
76                                 in->inData.t.buffer);
77       }
78       else
79       {
80           // Encrypt data to output
81           CryptSymmetricEncrypt(out->outData.t.buffer,
82                                 alg,
83                                 keySize,
84                                 in->mode, key,
85                                 &(out->ivOut),
86                                 in->inData.t.size,
87                                 in->inData.t.buffer);
88       }
89
90       return TPM_RC_SUCCESS;
91   }
92   #endif // CC_EncryptDecrypt


     Family “2.0”                           TCG Published                                  Page 121
     Level 00 Revision 01.16           Copyright © TCG 2006-2014                 October 30, 2014
Part 3: Commands                                                                 Trusted Platform Module Library


15.3   TPM2_Hash

15.3.1 General Description

This command performs a hash operation on a data buffer and returns the results.

NOTE            If the data buffer to be hashed is larger than will fit into the TPM’s input buffer, then the sequence
                hash commands will need to be used.

If the results of the hash will be used in a signing operation that uses a restricted signing key, then the
ticket returned by this command can indicate that the hash is safe to sign.
If the digest is not safe to sign, then the TPM will return a TPMT_TK_HASHCHECK with the hierarchy set
to TPM_RH_NULL and digest set to the Empty Buffer.
If hierarchy is TPM_RH_NULL, then digest in the ticket will be the Empty Buffer.


Page 122                                       TCG Published                                           Family “2.0”
October 30, 2014                       Copyright © TCG 2006-2014                        Level 00 Revision 01.16
Trusted Platform Module Library                                                          Part 3: Commands


15.3.2 Command and Response

                                  Table 58 — TPM2_Hash Command
Type                          Name                  Description

                                                    TPM_ST_SESSIONS if an audit, decrypt, or encrypt
TPMI_ST_COMMAND_TAG           tag                   session is present; otherwise,
                                                    TPM_ST_NO_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode           TPM_CC_Hash

TPM2B_MAX_BUFFER              data                  data to be hashed
                                                    algorithm for the hash being computed – shall not be
TPMI_ALG_HASH                 hashAlg
                                                    TPM_ALG_NULL
TPMI_RH_HIERARCHY+            hierarchy             hierarchy to use for the ticket (TPM_RH_NULL allowed)


                                    Table 59 — TPM2_Hash Response
Type                          Name                  Description

TPM_ST                        tag                   see clause 6
UINT32                        responseSize
TPM_RC                        responseCode

TPM2B_DIGEST                  outHash               results
                                                    ticket indicating that the sequence of octets used to
                                                    compute outDigest did not start with
TPMT_TK_HASHCHECK             validation            TPM_GENERATED_VALUE
                                                    will be a NULL ticket if the digest may not be signed
                                                    with a restricted key


Family “2.0”                                 TCG Published                                        Page 123
Level 00 Revision 01.16              Copyright © TCG 2006-2014                          October 30, 2014
     Part 3: Commands                                                   Trusted Platform Module Library


     15.3.3 Detailed Actions

 1   #include "InternalRoutines.h"
 2   #include "Hash_fp.h"
 3   #ifdef TPM_CC_Hash // Conditional expansion of this file
 4   TPM_RC
 5   TPM2_Hash(
 6       Hash_In         *in,            // IN: input parameter list
 7       Hash_Out        *out            // OUT: output parameter list
 8       )
 9   {
10       HASH_STATE         hashState;
11
12   // Command Output
13
14       // Output hash
15           // Start hash stack
16       out->outHash.t.size = CryptStartHash(in->hashAlg, &hashState);
17           // Adding hash data
18       CryptUpdateDigest2B(&hashState, &in->data.b);
19           // Complete hash
20       CryptCompleteHash2B(&hashState, &out->outHash.b);
21
22       // Output ticket
23       out->validation.tag = TPM_ST_HASHCHECK;
24       out->validation.hierarchy = in->hierarchy;
25
26       if(in->hierarchy == TPM_RH_NULL)
27       {
28           // Ticket is not required
29           out->validation.hierarchy = TPM_RH_NULL;
30           out->validation.digest.t.size = 0;
31       }
32       else if( in->data.t.size >= sizeof(TPM_GENERATED)
33               && !TicketIsSafe(&in->data.b))
34       {
35           // Ticket is not safe
36           out->validation.hierarchy = TPM_RH_NULL;
37           out->validation.digest.t.size = 0;
38       }
39       else
40       {
41           // Compute ticket
42           TicketComputeHashCheck(in->hierarchy, in->hashAlg,
43                                  &out->outHash, &out->validation);
44       }
45
46       return TPM_RC_SUCCESS;
47   }
48   #endif // CC_Hash


     Page 124                               TCG Published                                 Family “2.0”
     October 30, 2014                Copyright © TCG 2006-2014               Level 00 Revision 01.16
Trusted Platform Module Library                                                              Part 3: Commands


15.4   TPM2_HMAC

15.4.1 General Description

This command performs an HMAC on the supplied data using the indicated hash algorithm.
The caller shall provide proper authorization for use of handle.
If the sign attribute is not SET in the key referenced by handle then the TPM shall return
TPM_RC_ATTRIBUTES. If the key type is not TPM_ALG_KEYEDHASH then the TPM shall return
TPM_RC_TYPE. If the key referenced by handle has the restricted attribute SET, the TPM shall return
TPM_RC_ATTRIBUTES.
If the default scheme of the key referenced by handle is not TPM_ALG_NULL, then the hashAlg
parameter is required to be either the same as the key’s default or TPM_ALG_NULL (TPM_RC_VALUE).
If the default scheme of the key is TPM_ALG_NULL, then hashAlg is required to be a valid hash and not
TPM_ALG_NULL (TPM_RC_VALUE). (See hash selection matrix in Table 66.)

NOTE            A key may only have both sign and decrypt SET if the key is unrestricted. When both sign and
                decrypt are set, there is no default scheme for the ke y and the hash algorithm must be specified.


Family “2.0”                                  TCG Published                                           Page 125
Level 00 Revision 01.16               Copyright © TCG 2006-2014                              October 30, 2014
Part 3: Commands                                                  Trusted Platform Module Library


15.4.2 Command and Response

                         Table 60 — TPM2_HMAC Command
Type                   Name                  Description

TPMI_ST_COMMAND_TAG    tag                   TPM_ST_SESSIONS
UINT32                 commandSize
TPM_CC                 commandCode           TPM_CC_HMAC

                                             handle for the symmetric signing key providing the
                                             HMAC key
TPMI_DH_OBJECT         @handle
                                             Auth Index: 1
                                             Auth Role: USER

TPM2B_MAX_BUFFER       buffer                HMAC data
TPMI_ALG_HASH+         hashAlg               algorithm to use for HMAC


                         Table 61 — TPM2_HMAC Response
Type                   Name                  Description

TPM_ST                 tag                   see clause 6
UINT32                 responseSize
TPM_RC                 responseCode

TPM2B_DIGEST           outHMAC               the returned HMAC in a sized buffer


Page 126                              TCG Published                                    Family “2.0”
October 30, 2014                Copyright © TCG 2006-2014                Level 00 Revision 01.16
     Trusted Platform Module Library                                                                 Part 3: Commands


     15.4.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "HMAC_fp.h"
3    #ifdef TPM_CC_HMAC // Conditional expansion of this file


     Error Returns                     Meaning

     TPM_RC_ATTRIBUTES                 key referenced by handle is not a signing key or is a restricted key
     TPM_RC_TYPE                       key referenced by handle is not an HMAC key
     TPM_RC_VALUE                      hashAlg is not compatible with the hash algorithm of the scheme of
                                       the object referenced by handle

 4   TPM_RC
 5   TPM2_HMAC(
 6       HMAC_In           *in,                 // IN: input parameter list
 7       HMAC_Out          *out                 // OUT: output parameter list
 8       )
 9   {
10       HMAC_STATE                 hmacState;
11       OBJECT                    *hmacObject;
12       TPMI_ALG_HASH              hashAlg;
13       TPMT_PUBLIC               *publicArea;
14
15   // Input Validation
16
17       // Get HMAC key object and public area pointers
18       hmacObject = ObjectGet(in->handle);
19       publicArea = &hmacObject->publicArea;
20
21       // Make sure that the key is an HMAC key
22       if(publicArea->type != TPM_ALG_KEYEDHASH)
23           return TPM_RCS_TYPE + RC_HMAC_handle;
24
25       // and that it is unrestricted
26       if(publicArea->objectAttributes.restricted == SET)
27           return TPM_RCS_ATTRIBUTES + RC_HMAC_handle;
28
29       // and that it is a signing key
30       if(publicArea->objectAttributes.sign != SET)
31           return TPM_RCS_KEY + RC_HMAC_handle;
32
33       // See if the key has a default
34       if(publicArea->parameters.keyedHashDetail.scheme.scheme == TPM_ALG_NULL)
35           // it doesn't so use the input value
36           hashAlg = in->hashAlg;
37       else
38       {
39           // key has a default so use it
40           hashAlg
41               = publicArea->parameters.keyedHashDetail.scheme.details.hmac.hashAlg;
42           // and verify that the input was either the TPM_ALG_NULL or the default
43           if(in->hashAlg != TPM_ALG_NULL && in->hashAlg != hashAlg)
44               hashAlg = TPM_ALG_NULL;
45       }
46       // if we ended up without a hash algorith then return an error
47       if(hashAlg == TPM_ALG_NULL)
48           return TPM_RCS_VALUE + RC_HMAC_hashAlg;
49
50   // Command Output
51

     Family “2.0”                                   TCG Published                                             Page 127
     Level 00 Revision 01.16               Copyright © TCG 2006-2014                                 October 30, 2014
     Part 3: Commands                                               Trusted Platform Module Library

52      // Start HMAC stack
53      out->outHMAC.t.size = CryptStartHMAC2B(hashAlg,
54                                             &hmacObject->sensitive.sensitive.bits.b,
55                                             &hmacState);
56      // Adding HMAC data
57      CryptUpdateDigest2B(&hmacState, &in->buffer.b);
58
59      // Complete HMAC
60      CryptCompleteHMAC2B(&hmacState, &out->outHMAC.b);
61
62       return TPM_RC_SUCCESS;
63   }
64   #endif // CC_HMAC


     Page 128                              TCG Published                              Family “2.0”
     October 30, 2014               Copyright © TCG 2006-2014             Level 00 Revision 01.16
Trusted Platform Module Library                                                           Part 3: Commands


16     Random Number Generator

16.1     TPM2_GetRandom

16.1.1 General Description

This command returns the next bytesRequested octets from the random number generator (RNG).

NOTE 1         It is recommended that a TPM implement the RNG in a manner that would allow it to return RNG
               octets such that, as long as the value of bytesRequested is not greater than the maximum digest
               size, the frequency of bytesRequested being more than the number of octets available is an
               infrequent occurrence.

If bytesRequested is more than will fit into a TPM2B_DIGEST on the TPM, no error is returned but the
TPM will only return as much data as will fit into a TPM2B_DIGEST buffer for the TPM.

NOTE 2         TPM2B_DIGEST is large enough to hold the largest dig est that may be produced by the TPM.
               Because that digest size changes according to the implemented hashes, the maximum amount of
               data returned by this command is TPM implementation-dependent.


Family “2.0”                                TCG Published                                          Page 129
Level 00 Revision 01.16             Copyright © TCG 2006-2014                             October 30, 2014
Part 3: Commands                                                  Trusted Platform Module Library


16.1.2 Command and Response

                      Table 62 — TPM2_GetRandom Command
Type                   Name                  Description

                                             TPM_ST_SESSIONS if an audit or encrypt session is
TPMI_ST_COMMAND_TAG    tag
                                             present; otherwise, TPM_ST_NO_SESSIONS
UINT32                 commandSize
TPM_CC                 commandCode           TPM_CC_GetRandom

UINT16                 bytesRequested        number of octets to return


                      Table 63 — TPM2_GetRandom Response
Type                   Name                  Description

TPM_ST                 tag                   see clause 6
UINT32                 responseSize
TPM_RC                 responseCode

TPM2B_DIGEST           randomBytes           the random octets


Page 130                              TCG Published                                  Family “2.0”
October 30, 2014             Copyright © TCG 2006-2014                    Level 00 Revision 01.16
     Trusted Platform Module Library                                                Part 3: Commands


     16.1.3 Detailed Actions

 1   #include "InternalRoutines.h"
 2   #include "GetRandom_fp.h"
 3   #ifdef TPM_CC_GetRandom // Conditional expansion of this file
 4   TPM_RC
 5   TPM2_GetRandom(
 6       GetRandom_In     *in,            // IN: input parameter list
 7       GetRandom_Out    *out            // OUT: output parameter list
 8       )
 9   {
10   // Command Output
11
12       // if the requested bytes exceed the output buffer size, generates the
13       // maximum bytes that the output buffer allows
14       if(in->bytesRequested > sizeof(TPMU_HA))
15           out->randomBytes.t.size = sizeof(TPMU_HA);
16       else
17           out->randomBytes.t.size = in->bytesRequested;
18
19       CryptGenerateRandom(out->randomBytes.t.size, out->randomBytes.t.buffer);
20
21       return TPM_RC_SUCCESS;
22   }
23   #endif // CC_GetRandom


     Family “2.0”                            TCG Published                                 Page 131
     Level 00 Revision 01.16           Copyright © TCG 2006-2014                    October 30, 2014
Part 3: Commands                                                           Trusted Platform Module Library


16.2   TPM2_StirRandom

16.2.1 General Description

This command is used to add "additional information" to the RNG state.

NOTE           The "additional information" is as defined in SP800 -90A.

The inData parameter may not be larger than 128 octets.


Page 132                                      TCG Published                                  Family “2.0”
October 30, 2014                      Copyright © TCG 2006-2014                 Level 00 Revision 01.16
Trusted Platform Module Library                                                      Part 3: Commands


16.2.2 Command and Response

                             Table 64 — TPM2_StirRandom Command
Type                          Name                  Description

                                                    TPM_ST_SESSIONS if an audit or decrypt session is
TPMI_ST_COMMAND_TAG           tag
                                                    present; otherwise, TPM_ST_NO_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode           TPM_CC_StirRandom {NV}

TPM2B_SENSITIVE_DATA          inData                additional information


                             Table 65 — TPM2_StirRandom Response
Type                          Name                  Description

TPM_ST                        tag                   see clause 6
UINT32                        responseSize
TPM_RC                        responseCode


Family “2.0”                                 TCG Published                                   Page 133
Level 00 Revision 01.16             Copyright © TCG 2006-2014                        October 30, 2014
     Part 3: Commands                                                 Trusted Platform Module Library


     16.2.3 Detailed Actions

 1   #include "InternalRoutines.h"
 2   #include "StirRandom_fp.h"
 3   #ifdef TPM_CC_StirRandom // Conditional expansion of this file
 4   TPM_RC
 5   TPM2_StirRandom(
 6       StirRandom_In   *in            // IN: input parameter list
 7       )
 8   {
 9   // Internal Data Update
10       CryptStirRandom(in->inData.t.size, in->inData.t.buffer);
11
12       return TPM_RC_SUCCESS;
13   }
14   #endif // CC_StirRandom


     Page 134                               TCG Published                               Family “2.0”
     October 30, 2014                Copyright © TCG 2006-2014             Level 00 Revision 01.16
Trusted Platform Module Library                                                                 Part 3: Commands


17     Hash/HMAC/Event Sequences

17.1     Introduction

All of the commands in this group are to support sequences for which an intermediate state must be
maintained. For a description of sequences, see “Hash, HMAC, and Event Sequences” in TPM 2.0 Part 1.

17.2     TPM2_HMAC_Start

17.2.1 General Description

This command starts an HMAC sequence. The TPM will create and initialize an HMAC sequence
structure, assign a handle to the sequence, and set the authValue of the sequence object to the value in
auth.

NOTE                The structure of a sequence object is vendor -dependent.

The caller shall provide proper authorization for use of handle.
If the sign attribute is not SET in the key referenced by handle then the TPM shall return
TPM_RC_ATTRIBUTES. If the key type is not TPM_ALG_KEYEDHASH then the TPM shall return
TPM_RC_TYPE. If the key referenced by handle has the restricted attribute SET, the TPM shall return
TPM_RC_ATTRIBUTES.
If the default scheme of the key referenced by handle is not TPM_ALG_NULL, then the hashAlg
parameter is required to be either the same as the key’s default or TPM_ALG_NULL (TPM_RC_VALUE).
If the default scheme of the key is TPM_ALG_NULL, then hashAlg is required to be a valid hash and not
TPM_ALG_NULL (TPM_RC_VALUE).

                                          Table 66 — Hash Selection Matrix
 handle→restricted          handle→scheme
 (key's restricted          (hash algorithm
 attribute)                 from key's scheme)          hashAlg                   hash used
                                                (1)                                       (1)
 CLEAR (unrestricted)       TPM_ALG_NULL                TPM_ALG_NULL              error         (TPM_RC_VALUE)
 CLEAR                      TPM_ALG_NULL                valid hash                hashAlg
 CLEAR                      valid hash                  TPM_ALG_NULL or same as   handle→scheme
                                                        handle→scheme
 SET (restricted)           don't care                  don't care                TPM_RC_ATTRIBUTES
 NOTES:
 1)    A hash algorithm is required for the HMAC.


Family “2.0”                                          TCG Published                                    Page 135
Level 00 Revision 01.16                      Copyright © TCG 2006-2014                          October 30, 2014
Part 3: Commands                                                 Trusted Platform Module Library


17.2.2 Command and Response

                      Table 67 — TPM2_HMAC_Start Command
Type                   Name                  Description

TPMI_ST_COMMAND_TAG    tag                   TPM_ST_SESSIONS
UINT32                 commandSize
TPM_CC                 commandCode           TPM_CC_HMAC_Start

                                             handle of an HMAC key
TPMI_DH_OBJECT         @handle               Auth Index: 1
                                             Auth Role: USER

TPM2B_AUTH             auth                  authorization value for subsequent use of the sequence
TPMI_ALG_HASH+         hashAlg               the hash algorithm to use for the HMAC


                      Table 68 — TPM2_HMAC_Start Response
Type                   Name                  Description

TPM_ST                 tag                   see clause 6
UINT32                 responseSize
TPM_RC                 responseCode

TPMI_DH_OBJECT         sequenceHandle        a handle to reference the sequence


Page 136                              TCG Published                                   Family “2.0”
October 30, 2014              Copyright © TCG 2006-2014                 Level 00 Revision 01.16
     Trusted Platform Module Library                                                                    Part 3: Commands


     17.2.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "HMAC_Start_fp.h"
3    #ifdef TPM_CC_HMAC_Start // Conditional expansion of this file


     Error Returns                     Meaning

     TPM_RC_ATTRIBUTES                 key referenced by handle is not a signing key or is restricted
     TPM_RC_OBJECT_MEMORY              no space to create an internal object
     TPM_RC_KEY                        key referenced by handle is not an HMAC key
     TPM_RC_VALUE                      hashAlg is not compatible with the hash algorithm of the scheme of
                                       the object referenced by handle

 4   TPM_RC
 5   TPM2_HMAC_Start(
 6       HMAC_Start_In     *in,                 // IN: input parameter list
 7       HMAC_Start_Out    *out                 // OUT: output parameter list
 8       )
 9   {
10       OBJECT                    *hmacObject;
11       TPMT_PUBLIC               *publicArea;
12       TPM_ALG_ID                 hashAlg;
13
14   // Input Validation
15
16       // Get HMAC key object and public area pointers
17       hmacObject = ObjectGet(in->handle);
18       publicArea = &hmacObject->publicArea;
19
20       // Make sure that the key is an HMAC key
21       if(publicArea->type != TPM_ALG_KEYEDHASH)
22           return TPM_RCS_TYPE + RC_HMAC_Start_handle;
23
24       // and that it is unrestricted
25       if(publicArea->objectAttributes.restricted == SET)
26           return TPM_RCS_ATTRIBUTES + RC_HMAC_Start_handle;
27
28       // and that it is a signing key
29       if(publicArea->objectAttributes.sign != SET)
30           return TPM_RCS_KEY + RC_HMAC_Start_handle;
31
32       // See if the key has a default
33       if(publicArea->parameters.keyedHashDetail.scheme.scheme == TPM_ALG_NULL)
34           // it doesn't so use the input value
35           hashAlg = in->hashAlg;
36       else
37       {
38           // key has a default so use it
39           hashAlg
40               = publicArea->parameters.keyedHashDetail.scheme.details.hmac.hashAlg;
41           // and verify that the input was either the TPM_ALG_NULL or the default
42           if(in->hashAlg != TPM_ALG_NULL && in->hashAlg != hashAlg)
43               hashAlg = TPM_ALG_NULL;
44       }
45       // if we ended up without a hash algorith then return an error
46       if(hashAlg == TPM_ALG_NULL)
47           return TPM_RCS_VALUE + RC_HMAC_Start_hashAlg;
48
49   // Internal Data Update
50

     Family “2.0”                                   TCG Published                                              Page 137
     Level 00 Revision 01.16               Copyright © TCG 2006-2014                                    October 30, 2014
     Part 3: Commands                                               Trusted Platform Module Library

51      // Create a HMAC sequence object. A TPM_RC_OBJECT_MEMORY error may be
52      // returned at this point
53      return ObjectCreateHMACSequence(hashAlg,
54                                      in->handle,
55                                      &in->auth,
56                                      &out->sequenceHandle);
57   }
58   #endif // CC_HMAC_Start


     Page 138                              TCG Published                              Family “2.0”
     October 30, 2014               Copyright © TCG 2006-2014             Level 00 Revision 01.16
Trusted Platform Module Library                                                        Part 3: Commands


17.3   TPM2_HashSequenceStart

17.3.1 General Description

This command starts a hash or an Event Sequence. If hashAlg is an implemented hash, then a hash
sequence is started. If hashAlg is TPM_ALG_NULL, then an Event Sequence is started. If hashAlg is
neither an implemented algorithm nor TPM_ALG_NULL, then the TPM shall return TPM_RC_HASH.
Depending on hashAlg, the TPM will create and initialize a Hash Sequence context or an Event
Sequence context. Additionally, it will assign a handle to the context and set the authValue of the context
to the value in auth. A sequence context for an Event (hashAlg = TPM_ALG_NULL) contains a hash
context for each of the PCR banks implemented on the TPM.


Family “2.0”                                TCG Published                                       Page 139
Level 00 Revision 01.16              Copyright © TCG 2006-2014                         October 30, 2014
Part 3: Commands                                                    Trusted Platform Module Library


17.3.2 Command and Response

                      Table 69 — TPM2_HashSequenceStart Command
Type                      Name                  Description

                                                TPM_ST_SESSIONS if an audit or decrypt session is
TPMI_ST_COMMAND_TAG       tag
                                                present; otherwise, TPM_ST_NO_SESSIONS
UINT32                    commandSize
TPM_CC                    commandCode           TPM_CC_HashSequenceStart

TPM2B_AUTH                auth                  authorization value for subsequent use of the sequence
                                                the hash algorithm to use for the hash sequence
TPMI_ALG_HASH+            hashAlg
                                                An Event Sequence starts if this is TPM_ALG_NULL.


                      Table 70 — TPM2_HashSequenceStart Response
Type                      Name                  Description

TPM_ST                    tag                   see clause 6
UINT32                    responseSize
TPM_RC                    responseCode

TPMI_DH_OBJECT            sequenceHandle        a handle to reference the sequence


Page 140                                 TCG Published                                   Family “2.0”
October 30, 2014                 Copyright © TCG 2006-2014                 Level 00 Revision 01.16
     Trusted Platform Module Library                                                      Part 3: Commands


     17.3.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "HashSequenceStart_fp.h"
3    #ifdef TPM_CC_HashSequenceStart // Conditional expansion of this file


     Error Returns                     Meaning

     TPM_RC_OBJECT_MEMORY              no space to create an internal object

 4   TPM_RC
 5   TPM2_HashSequenceStart(
 6       HashSequenceStart_In      *in,                   // IN: input parameter list
 7       HashSequenceStart_Out     *out                   // OUT: output parameter list
 8       )
 9   {
10   // Internal Data Update
11
12       if(in->hashAlg == TPM_ALG_NULL)
13           // Start a event sequence. A TPM_RC_OBJECT_MEMORY error may be
14           // returned at this point
15           return ObjectCreateEventSequence(&in->auth, &out->sequenceHandle);
16
17       // Start a hash sequence. A TPM_RC_OBJECT_MEMORY error may be
18       // returned at this point
19       return ObjectCreateHashSequence(in->hashAlg, &in->auth, &out->sequenceHandle);
20   }
21   #endif // CC_HashSequenceStart


     Family “2.0”                                   TCG Published                                Page 141
     Level 00 Revision 01.16               Copyright © TCG 2006-2014                      October 30, 2014
Part 3: Commands                                                              Trusted Platform Module Library


17.4     TPM2_SequenceUpdate

17.4.1 General Description

This command is used to add data to a hash or HMAC sequence. The amount of data in buffer may be
any size up to the limits of the TPM.

NOTE 1          In all TPM, a buffer size of 1,024 octets is allowed.

Proper authorization for the sequence object associated with sequenceHandle is required. If an
authorization or audit of this command requires computation of a cpHash and an rpHash, the Name
associated with sequenceHandle will be the Empty Buffer.
If the command does not return TPM_RC_SUCCESS, the state of the sequence is unmodified.
If the sequence is intended to produce a digest that will be signed by a restricted signing key, then the
first block of data shall contain sizeof(TPM_GENERATED) octets and the first octets shall not be
TPM_GENERATED_VALUE.

NOTE 2          This requirement allows the TPM to validate that the first block is safe to sign without having to
                accumulate octets over multiple calls.


Page 142                                        TCG Published                                       Family “2.0”
October 30, 2014                        Copyright © TCG 2006-2014                    Level 00 Revision 01.16
Trusted Platform Module Library                                                      Part 3: Commands


17.4.2 Command and Response

                          Table 71 — TPM2_SequenceUpdate Command
Type                          Name                  Description

TPMI_ST_COMMAND_TAG           tag                   TPM_ST_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode           TPM_CC_SequenceUpdate

                                                    handle for the sequence object
TPMI_DH_OBJECT                @sequenceHandle       Auth Index: 1
                                                    Auth Role: USER

TPM2B_MAX_BUFFER              buffer                data to be added to hash


                          Table 72 — TPM2_SequenceUpdate Response
Type                          Name                  Description

TPM_ST                        tag                   see clause 6
UINT32                        responseSize
TPM_RC                        responseCode


Family “2.0”                                 TCG Published                                  Page 143
Level 00 Revision 01.16                Copyright © TCG 2006-2014                     October 30, 2014
     Part 3: Commands                                                        Trusted Platform Module Library


     17.4.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "SequenceUpdate_fp.h"
3    #ifdef TPM_CC_SequenceUpdate // Conditional expansion of this file


     Error Returns                   Meaning

     TPM_RC_MODE                     sequenceHandle does not reference a hash or HMAC sequence
                                     object

 4   TPM_RC
 5   TPM2_SequenceUpdate(
 6       SequenceUpdate_In     *in               // IN: input parameter list
 7       )
 8   {
 9       OBJECT                      *object;
10
11   // Input Validation
12
13       // Get sequence object pointer
14       object = ObjectGet(in->sequenceHandle);
15
16       // Check that referenced object is a sequence object.
17       if(!ObjectIsSequence(object))
18           return TPM_RC_MODE + RC_SequenceUpdate_sequenceHandle;
19
20   // Internal Data Update
21
22       if(object->attributes.eventSeq == SET)
23       {
24           // Update event sequence object
25           UINT32           i;
26           HASH_OBJECT     *hashObject = (HASH_OBJECT *)object;
27           for(i = 0; i < HASH_COUNT; i++)
28           {
29               // Update sequence object
30               CryptUpdateDigest2B(&hashObject->state.hashState[i], &in->buffer.b);
31           }
32       }
33       else
34       {
35           HASH_OBJECT     *hashObject = (HASH_OBJECT *)object;
36
37           // Update hash/HMAC sequence object
38           if(hashObject->attributes.hashSeq == SET)
39           {
40               // Is this the first block of the sequence
41               if(hashObject->attributes.firstBlock == CLEAR)
42               {
43                   // If so, indicate that first block was received
44                   hashObject->attributes.firstBlock = SET;
45
46                    // Check the first block to see if the first block can contain
47                    // the TPM_GENERATED_VALUE. If it does, it is not safe for
48                    // a ticket.
49                    if(TicketIsSafe(&in->buffer.b))
50                        hashObject->attributes.ticketSafe = SET;
51                }
52                // Update sequence object hash/HMAC stack
53                CryptUpdateDigest2B(&hashObject->state.hashState[0], &in->buffer.b);
54
55           }

     Page 144                                   TCG Published                                    Family “2.0”
     October 30, 2014                    Copyright © TCG 2006-2014                 Level 00 Revision 01.16
     Trusted Platform Module Library                                              Part 3: Commands

56           else if(object->attributes.hmacSeq == SET)
57           {
58               HASH_OBJECT     *hashObject = (HASH_OBJECT *)object;
59
60                // Update sequence object hash/HMAC stack
61                CryptUpdateDigest2B(&hashObject->state.hmacState, &in->buffer.b);
62           }
63       }
64
65       return TPM_RC_SUCCESS;
66   }
67   #endif // CC_SequenceUpdate


     Family “2.0”                            TCG Published                               Page 145
     Level 00 Revision 01.16           Copyright © TCG 2006-2014                  October 30, 2014
Part 3: Commands                                                                Trusted Platform Module Library


17.5     TPM2_SequenceComplete

17.5.1 General Description

This command adds the last part of data, if any, to a hash/HMAC sequence and returns the result.

NOTE 1          This command is not used to complete an Event Sequence. TPM2_EventSequenceComplete() is
                used for that purpose.

For a hash sequence, if the results of the hash will be used in a signing operation that uses a restricted
signing key, then the ticket returned by this command can indicate that the hash is safe to sign.
If the digest is not safe to sign, then validation will be a TPMT_TK_HASHCHECK with the hierarchy set to
TPM_RH_NULL and digest set to the Empty Buffer.

NOTE 2          Regardless of the contents of the first octets of the hashed message, if the first buffer sent to the
                TPM had fewer than sizeof(TPM_GENERATED) octets, then the TPM will operate as if digest is not
                safe to sign.

NOTE 3          The ticket is only required for a signing operation that uses a restricted signing key. It is always
                returned, but can be ignored if not needed.

If sequenceHandle references an Event Sequence, then the TPM shall return TPM_RC_MODE.
Proper authorization for the sequence object associated with sequenceHandle is required. If an
authorization or audit of this command requires computation of a cpHash and an rpHash, the Name
associated with sequenceHandle will be the Empty Buffer.
If this command completes successfully, the sequenceHandle object will be flushed.


Page 146                                       TCG Published                                          Family “2.0”
October 30, 2014                       Copyright © TCG 2006-2014                       Level 00 Revision 01.16
Trusted Platform Module Library                                                          Part 3: Commands


17.5.2 Command and Response

                          Table 73 — TPM2_SequenceComplete Command
Type                          Name                  Description

TPMI_ST_COMMAND_TAG           tag                   TPM_ST_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode           TPM_CC_SequenceComplete {F}

                                                    authorization for the sequence
TPMI_DH_OBJECT                @sequenceHandle       Auth Index: 1
                                                    Auth Role: USER

TPM2B_MAX_BUFFER              buffer                data to be added to the hash/HMAC
TPMI_RH_HIERARCHY+            hierarchy             hierarchy of the ticket for a hash


                          Table 74 — TPM2_SequenceComplete Response
Type                          Name                  Description

TPM_ST                        tag                   see clause 6
UINT32                        responseSize
TPM_RC                        responseCode

TPM2B_DIGEST                  result                the returned HMAC or digest in a sized buffer
                                                    ticket indicating that the sequence of octets used to
                                                    compute outDigest did not start with
TPMT_TK_HASHCHECK             validation            TPM_GENERATED_VALUE
                                                    This is a NULL Ticket when the sequence is HMAC.


Family “2.0”                                 TCG Published                                          Page 147
Level 00 Revision 01.16                Copyright © TCG 2006-2014                         October 30, 2014
     Part 3: Commands                                                    Trusted Platform Module Library


     17.5.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "SequenceComplete_fp.h"
3    #ifdef TPM_CC_SequenceComplete // Conditional expansion of this file
4    #include <Platform.h>


     Error Returns               Meaning

     TPM_RC_TYPE                 sequenceHandle does not reference a hash or HMAC sequence
                                 object

 5   TPM_RC
 6   TPM2_SequenceComplete(
 7       SequenceComplete_In    *in,               // IN: input parameter list
 8       SequenceComplete_Out   *out               // OUT: output parameter list
 9       )
10   {
11       OBJECT                     *object;
12
13   // Input validation
14
15       // Get hash object pointer
16       object = ObjectGet(in->sequenceHandle);
17
18       // input handle must be a hash or HMAC sequence object.
19       if(   object->attributes.hashSeq == CLEAR
20          && object->attributes.hmacSeq == CLEAR)
21           return TPM_RC_MODE + RC_SequenceComplete_sequenceHandle;
22
23   // Command Output
24
25       if(object->attributes.hashSeq == SET)           // sequence object for hash
26       {
27           // Update last piece of data
28           HASH_OBJECT     *hashObject = (HASH_OBJECT *)object;
29
30          // Get the hash algorithm before the algorithm is lost in CryptCompleteHash
31           TPM_ALG_ID       hashAlg = hashObject->state.hashState[0].state.hashAlg;
32
33           CryptUpdateDigest2B(&hashObject->state.hashState[0], &in->buffer.b);
34
35           // Complete hash
36           out->result.t.size
37               = CryptGetHashDigestSize(
38                     CryptGetContextAlg(&hashObject->state.hashState[0]));
39
40           CryptCompleteHash2B(&hashObject->state.hashState[0], &out->result.b);
41
42           // Check if the first block of the sequence has been received
43           if(hashObject->attributes.firstBlock == CLEAR)
44           {
45               // If not, then this is the first block so see if it is 'safe'
46               // to sign.
47               if(TicketIsSafe(&in->buffer.b))
48                   hashObject->attributes.ticketSafe = SET;
49           }
50
51           // Output ticket
52           out->validation.tag = TPM_ST_HASHCHECK;
53           out->validation.hierarchy = in->hierarchy;
54
55           if(in->hierarchy == TPM_RH_NULL)

     Page 148                               TCG Published                                    Family “2.0”
     October 30, 2014                  Copyright © TCG 2006-2014               Level 00 Revision 01.16
     Trusted Platform Module Library                                                Part 3: Commands

56           {
57                // Ticket is not required
58                out->validation.digest.t.size = 0;
59           }
60           else if(object->attributes.ticketSafe == CLEAR)
61           {
62               // Ticket is not safe to generate
63               out->validation.hierarchy = TPM_RH_NULL;
64               out->validation.digest.t.size = 0;
65           }
66           else
67           {
68               // Compute ticket
69               TicketComputeHashCheck(out->validation.hierarchy, hashAlg,
70                                      &out->result, &out->validation);
71           }
72       }
73       else
74       {
75           HASH_OBJECT       *hashObject = (HASH_OBJECT *)object;
76
77           //   Update last piece of data
78           CryptUpdateDigest2B(&hashObject->state.hmacState, &in->buffer.b);
79           // Complete hash/HMAC
80           out->result.t.size =
81               CryptGetHashDigestSize(
82                   CryptGetContextAlg(&hashObject->state.hmacState.hashState));
83           CryptCompleteHMAC2B(&(hashObject->state.hmacState), &out->result.b);
84
85           // No ticket is generated for HMAC sequence
86           out->validation.tag = TPM_ST_HASHCHECK;
87           out->validation.hierarchy = TPM_RH_NULL;
88           out->validation.digest.t.size = 0;
89       }
90
91   // Internal Data Update
92
93       // mark sequence object as evict so it will be flushed on the way out
94       object->attributes.evict = SET;
95
96       return TPM_RC_SUCCESS;
97   }
98   #endif // CC_SequenceComplete


     Family “2.0”                             TCG Published                                Page 149
     Level 00 Revision 01.16           Copyright © TCG 2006-2014                    October 30, 2014
Part 3: Commands                                                        Trusted Platform Module Library


17.6   TPM2_EventSequenceComplete

17.6.1 General Description

This command adds the last part of data, if any, to an Event Sequence and returns the result in a digest
list. If pcrHandle references a PCR and not TPM_RH_NULL, then the returned digest list is processed in
the same manner as the digest list input parameter to TPM2_PCR_Extend() with the pcrHandle in each
bank extended with the associated digest value.
If sequenceHandle references a hash or HMAC sequence, the TPM shall return TPM_RC_MODE.
Proper authorization for the sequence object associated with sequenceHandle is required. If an
authorization or audit of this command requires computation of a cpHash and an rpHash, the Name
associated with sequenceHandle will be the Empty Buffer.
If this command completes successfully, the sequenceHandle object will be flushed.


Page 150                                   TCG Published                                   Family “2.0”
October 30, 2014                    Copyright © TCG 2006-2014                 Level 00 Revision 01.16
Trusted Platform Module Library                                                            Part 3: Commands


17.6.2 Command and Response

                      Table 75 — TPM2_EventSequenceComplete Command
Type                          Name                  Description

TPMI_ST_COMMAND_TAG           tag                   TPM_ST_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode           TPM_CC_EventSequenceComplete {NV F}

                                                    PCR to be extended with the Event data
TPMI_DH_PCR+                  @ pcrHandle           Auth Index: 1
                                                    Auth Role: USER
                                                    authorization for the sequence
TPMI_DH_OBJECT                @sequenceHandle       Auth Index: 2
                                                    Auth Role: USER

TPM2B_MAX_BUFFER              buffer                data to be added to the Event


                      Table 76 — TPM2_EventSequenceComplete Response
Type                          Name                  Description

TPM_ST                        tag                   see clause 6
UINT32                        responseSize
TPM_RC                        responseCode

TPML_DIGEST_VALUES            results               list of digests computed for the PCR


Family “2.0”                                 TCG Published                                        Page 151
Level 00 Revision 01.16                Copyright © TCG 2006-2014                           October 30, 2014
     Part 3: Commands                                                            Trusted Platform Module Library


     17.6.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "EventSequenceComplete_fp.h"
3    #ifdef TPM_CC_EventSequenceComplete // Conditional expansion of this file


     Error Returns                 Meaning

     TPM_RC_LOCALITY               PCR extension is not allowed at the current locality
     TPM_RC_MODE                   input handle is not a valid event sequence object

 4   TPM_RC
 5   TPM2_EventSequenceComplete(
 6       EventSequenceComplete_In      *in,                // IN: input parameter list
 7       EventSequenceComplete_Out     *out                // OUT: output parameter list
 8       )
 9   {
10       TPM_RC              result;
11       HASH_OBJECT        *hashObject;
12       UINT32              i;
13       TPM_ALG_ID          hashAlg;
14
15   // Input validation
16
17       // get the event sequence object pointer
18       hashObject = (HASH_OBJECT *)ObjectGet(in->sequenceHandle);
19
20       // input handle must reference an event sequence object
21       if(hashObject->attributes.eventSeq != SET)
22           return TPM_RC_MODE + RC_EventSequenceComplete_sequenceHandle;
23
24       // see if a PCR extend is requested in call
25       if(in->pcrHandle != TPM_RH_NULL)
26       {
27           // see if extend of the PCR is allowed at the locality of the command,
28           if(!PCRIsExtendAllowed(in->pcrHandle))
29               return TPM_RC_LOCALITY;
30           // if an extend is going to take place, then check to see if there has
31           // been an orderly shutdown. If so, and the selected PCR is one of the
32           // state saved PCR, then the orderly state has to change. The orderly state
33           // does not change for PCR that are not preserved.
34           // NOTE: This doesn't just check for Shutdown(STATE) because the orderly
35           // state will have to change if this is a state-saved PCR regardless
36           // of the current state. This is because a subsequent Shutdown(STATE) will
37           // check to see if there was an orderly shutdown and not do anything if
38           // there was. So, this must indicate that a future Shutdown(STATE) has
39           // something to do.
40           if(gp.orderlyState != SHUTDOWN_NONE && PCRIsStateSaved(in->pcrHandle))
41           {
42               result = NvIsAvailable();
43               if(result != TPM_RC_SUCCESS) return result;
44               g_clearOrderly = TRUE;
45           }
46       }
47
48   // Command Output
49
50       out->results.count = 0;
51
52       for(i = 0; i < HASH_COUNT; i++)
53       {
54           hashAlg = CryptGetHashAlgByIndex(i);

     Page 152                                   TCG Published                                        Family “2.0”
     October 30, 2014                  Copyright © TCG 2006-2014                          Level 00 Revision 01.16
     Trusted Platform Module Library                                             Part 3: Commands

55           // Update last piece of data
56           CryptUpdateDigest2B(&hashObject->state.hashState[i], &in->buffer.b);
57           // Complete hash
58           out->results.digests[out->results.count].hashAlg = hashAlg;
59           CryptCompleteHash(&hashObject->state.hashState[i],
60                           CryptGetHashDigestSize(hashAlg),
61                           (BYTE *) &out->results.digests[out->results.count].digest);
62
63           // Extend PCR
64           if(in->pcrHandle != TPM_RH_NULL)
65               PCRExtend(in->pcrHandle, hashAlg,
66                         CryptGetHashDigestSize(hashAlg),
67                         (BYTE *) &out->results.digests[out->results.count].digest);
68           out->results.count++;
69       }
70
71   // Internal Data Update
72
73       // mark sequence object as evict so it will be flushed on the way out
74       hashObject->attributes.evict = SET;
75
76       return TPM_RC_SUCCESS;
77   }
78   #endif // CC_EventSequenceComplete


     Family “2.0”                           TCG Published                                  Page 153
     Level 00 Revision 01.16           Copyright © TCG 2006-2014                 October 30, 2014
Part 3: Commands                                                                 Trusted Platform Module Library


18     Attestation Commands

18.1     Introduction

The attestation commands cause the TPM to sign an internally generated data structure. The contents of
the data structure vary according to the command.
All signing commands include a parameter (typically inScheme) for the caller to specify a scheme to be
used for the signing operation. This scheme will be applied only if the scheme of the key is
TPM_ALG_NULL or the key handle is TPM_RH_NULL. If the scheme for signHandle is not
TPM_ALG_NULL, then inScheme.scheme shall be TPM_ALG_NULL or the same as scheme in the
public area of the key. If the scheme for signHandle is TPM_ALG_NULL or the key handle is
TPM_RH_NULL, then inScheme will be used for the signing operation and may not be TPM_ALG_NULL.
The TPM shall return TPM_RC_SCHEME to indicate that the scheme is not appropriate.
For a signing key that is not restricted, the caller may specify the scheme to be used as long as the
scheme is compatible with the family of the key (for example, TPM_ALG_RSAPSS cannot be selected for
an ECC key). If the caller sets scheme to TPM_ALG_NULL, then the default scheme of the key is used.
For a restricted signing key, the key's scheme cannot be TPM_ALG_NULL and cannot be overridden.
If the handle for the signing key (signHandle) is TPM_RH_NULL, then all of the actions of the command
are performed and the attestation block is “signed” with the NULL Signature.

NOTE 1          This mechanism is provided so that additional commands are not required to access the data that
                might be in an attestation structure.

NOTE 2          When signHandle is TPM_RH_NULL, scheme is still required to be a valid signing scheme (may be
                TPM_ALG_NULL), but the scheme will have no effect on the format of the signature. It will always
                be the NULL Signature.

TPM2_NV_Certify() is an attestation command that is documented in 1. The remaining attestation
commands are collected in the remainder of this clause.
Each of the attestation structures contains a TPMS_CLOCK_INFO structure and a firmware version
number. These values may be considered privacy-sensitive, because they would aid in the correlation of
attestations by different keys. To provide improved privacy, the resetCount, restartCount, and
firmwareVersion numbers are obfuscated when the signing key is not in the Endorsement or Platform
hierarchies.
The obfuscation value is computed by:
     obfuscation ≔ KDFa(signHandle→nameAlg, shProof, “OBFUSCATE”, signHandle→QN, 0, 128) (3)
Of the returned 128 bits, 64 bits are added to the versionNumber field of the attestation structure; 32 bits
are added to the clockInfo.resetCount and 32 bits are added to the clockInfo.restartCount. The order in
which the bits are added is implementation-dependent.

NOTE 3          The obfuscation value for each signing key will be unique to that key in a specific location. That is,
                each version of a duplicated signing key will have a different obfuscation value.

When the signing key is TPM_RH_NULL, the data structure is produced but not signed; and the values in
the signed data structure are obfuscated. When computing the obfuscation value for TPM_RH_NULL, the
hash used for context integrity is used.

NOTE 4          The QN for TPM_RH_NULL is TPM_RH_NULL.

If the signing scheme of signHandle is an anonymous scheme, then the attestation blocks will not contain
the Qualified Name of the signHandle.
Each of the attestation structures allows the caller to provide some qualifying data (qualifyingData). For
most signing schemes, this value will be placed in the TPMS_ATTEST.extraData parameter that is then

Page 154                                       TCG Published                                           Family “2.0”
October 30, 2014                       Copyright © TCG 2006-2014                        Level 00 Revision 01.16
Trusted Platform Module Library                                           Part 3: Commands

hashed and signed. However, for some schemes such as ECDAA, the qualifyingData is used in a
different manner (for details, see “ECDAA” in TPM 2.0 Part 1).


Family “2.0”                           TCG Published                              Page 155
Level 00 Revision 01.16           Copyright © TCG 2006-2014               October 30, 2014
Part 3: Commands                                                                  Trusted Platform Module Library


18.2     TPM2_Certify

18.2.1 General Description

The purpose of this command is to prove that an object with a specific Name is loaded in the TPM. By
certifying that the object is loaded, the TPM warrants that a public area with a given Name is self-
consistent and associated with a valid sensitive area. If a relying party has a public area that has the
same Name as a Name certified with this command, then the values in that public area are correct.

NOTE 1          See 18.1 for description of how the signing scheme is selected.

Authorization for objectHandle requires ADMIN role authorization. If performed with a policy session, the
session shall have a policySession→commandCode set to TPM_CC_Certify. This indicates that the
policy that is being used is a policy that is for certification, and not a policy that would approve another
use. That is, authority to use an object does not grant authority to certify the object.
The object may be any object that is loaded with TPM2_Load() or TPM2_CreatePrimary(). An object that
only has its public area loaded cannot be certified.

NOTE 2          The restriction occurs because the Name is used to identify the object being certified. If the TPM
                has not validated that the public area is associated with a mat ched sensitive area, then the public
                area may not represent a valid object and cannot be certified.

The certification includes the Name and Qualified Name of the certified object as well as the Name and
the Qualified Name of the certifying object.

NOTE 2          If signHandle is TPM_RH_NULL, the TPMS_ATTEST structure is returned and signature is a NULL
                Signature.


Page 156                                       TCG Published                                         Family “2.0”
October 30, 2014                       Copyright © TCG 2006-2014                       Level 00 Revision 01.16
Trusted Platform Module Library                                                            Part 3: Commands


18.2.2 Command and Response

                                  Table 77 — TPM2_Certify Command
Type                          Name                  Description

TPMI_ST_COMMAND_TAG           tag                   TPM_ST_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode           TPM_CC_Certify

                                                    handle of the object to be certified
TPMI_DH_OBJECT                @objectHandle         Auth Index: 1
                                                    Auth Role: ADMIN
                                                    handle of the key used to sign the attestation structure
TPMI_DH_OBJECT+               @signHandle           Auth Index: 2
                                                    Auth Role: USER

TPM2B_DATA                    qualifyingData        user provided qualifying data
                                                    signing scheme to use if the scheme for signHandle is
TPMT_SIG_SCHEME+              inScheme
                                                    TPM_ALG_NULL


                                  Table 78 — TPM2_Certify Response
Type                          Name                  Description

TPM_ST                        tag                   see clause 6
UINT32                        responseSize
TPM_RC                        responseCode          .

TPM2B_ATTEST                  certifyInfo           the structure that was signed
                                                    the asymmetric signature over certifyInfo using the key
TPMT_SIGNATURE                signature
                                                    referenced by signHandle


Family “2.0”                                 TCG Published                                         Page 157
Level 00 Revision 01.16             Copyright © TCG 2006-2014                              October 30, 2014
     Part 3: Commands                                                           Trusted Platform Module Library


     18.2.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "Attest_spt_fp.h"
3    #include "Certify_fp.h"
4    #ifdef TPM_CC_Certify // Conditional expansion of this file


     Error Returns               Meaning

     TPM_RC_KEY                  key referenced by signHandle is not a signing key
     TPM_RC_SCHEME               inScheme is not compatible with signHandle
     TPM_RC_VALUE                digest generated for inScheme is greater or has larger size than the
                                 modulus of signHandle, or the buffer for the result in signature is too
                                 small (for an RSA key); invalid commit status (for an ECC key with a
                                 split scheme).

 5   TPM_RC
 6   TPM2_Certify(
 7       Certify_In      *in,             // IN: input parameter list
 8       Certify_Out     *out             // OUT: output parameter list
 9       )
10   {
11       TPM_RC                 result;
12       TPMS_ATTEST            certifyInfo;
13
14   // Command Output
15
16       // Filling in attest information
17       // Common fields
18       result = FillInAttestInfo(in->signHandle,
19                                 &in->inScheme,
20                                 &in->qualifyingData,
21                                 &certifyInfo);
22       if(result != TPM_RC_SUCCESS)
23       {
24           if(result == TPM_RC_KEY)
25               return TPM_RC_KEY + RC_Certify_signHandle;
26           else
27               return RcSafeAddToResult(result, RC_Certify_inScheme);
28       }
29       // Certify specific fields
30       // Attestation type
31       certifyInfo.type = TPM_ST_ATTEST_CERTIFY;
32       // Certified object name
33       certifyInfo.attested.certify.name.t.size =
34           ObjectGetName(in->objectHandle,
35                         &certifyInfo.attested.certify.name.t.name);
36       // Certified object qualified name
37       ObjectGetQualifiedName(in->objectHandle,
38                              &certifyInfo.attested.certify.qualifiedName);
39
40       // Sign attestation structure. A NULL signature will be returned if
41       // signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE,
42       // TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned
43       // by SignAttestInfo()
44       result = SignAttestInfo(in->signHandle,
45                               &in->inScheme,
46                               &certifyInfo,
47                               &in->qualifyingData,
48                               &out->certifyInfo,
49                               &out->signature);

     Page 158                                 TCG Published                                           Family “2.0”
     October 30, 2014                Copyright © TCG 2006-2014                         Level 00 Revision 01.16
     Trusted Platform Module Library                                             Part 3: Commands

50
51       // TPM_RC_ATTRIBUTES cannot be returned here as FillInAttestInfo would already
52       // have returned TPM_RC_KEY
53       pAssert(result != TPM_RC_ATTRIBUTES);
54
55       if(result != TPM_RC_SUCCESS)
56           return result;
57
58       // orderly state should be cleared because of the reporting of clock info
59       // if signing happens
60       if(in->signHandle != TPM_RH_NULL)
61           g_clearOrderly = TRUE;
62
63       return TPM_RC_SUCCESS;
64   }
65   #endif // CC_Certify


     Family “2.0”                            TCG Published                                Page 159
     Level 00 Revision 01.16            Copyright © TCG 2006-2014                October 30, 2014
Part 3: Commands                                                                  Trusted Platform Module Library


18.3     TPM2_CertifyCreation

18.3.1 General Description

This command is used to prove the association between an object and its creation data. The TPM will
validate that the ticket was produced by the TPM and that the ticket validates the association between a
loaded public area and the provided hash of the creation data (creationHash).

NOTE 1          See 18.1 for description of how the signing scheme is selected.

The TPM will create a test ticket using the Name associated with objectHandle and creationHash as:
             HMAC(proof, (TPM_ST_CREATION || objectHandle→Name || creationHash))                              (4)
This ticket is then compared to creation ticket. If the tickets are not the same, the TPM shall return
TPM_RC_TICKET.
If the ticket is valid, then the TPM will create a TPMS_ATTEST structure and place creationHash of the
command in the creationHash field of the structure. The Name associated with objectHandle will be
included in the attestation data that is then signed using the key associated with signHandle.

NOTE 2          If signHandle is TPM_RH_NULL, the TPMS_ATTEST structure is returned and signature is a NULL
                Signature.

ObjectHandle may be any object that is loaded with TPM2_Load() or TPM2_CreatePrimary().


Page 160                                       TCG Published                                        Family “2.0”
October 30, 2014                       Copyright © TCG 2006-2014                       Level 00 Revision 01.16
Trusted Platform Module Library                                                           Part 3: Commands


18.3.2 Command and Response

                           Table 79 — TPM2_CertifyCreation Command
Type                          Name                  Description

TPMI_ST_COMMAND_TAG           tag                   TPM_ST_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode           TPM_CC_CertifyCreation

                                                    handle of the key that will sign the attestation block
TPMI_DH_OBJECT+               @signHandle           Auth Index: 1
                                                    Auth Role: USER
                                                    the object associated with the creation data
TPMI_DH_OBJECT                objectHandle
                                                    Auth Index: None

TPM2B_DATA                    qualifyingData        user-provided qualifying data
                                                    hash of the creation data produced by TPM2_Create()
TPM2B_DIGEST                  creationHash
                                                    or TPM2_CreatePrimary()
                                                    signing scheme to use if the scheme for signHandle is
TPMT_SIG_SCHEME+              inScheme
                                                    TPM_ALG_NULL
                                                    ticket produced by TPM2_Create() or
TPMT_TK_CREATION              creationTicket
                                                    TPM2_CreatePrimary()


                           Table 80 — TPM2_CertifyCreation Response
Type                          Name                  Description

TPM_ST                        tag                   see clause 6
UINT32                        responseSize
TPM_RC                        responseCode

TPM2B_ATTEST                  certifyInfo           the structure that was signed
TPMT_SIGNATURE                signature             the signature over certifyInfo


Family “2.0”                                 TCG Published                                          Page 161
Level 00 Revision 01.16             Copyright © TCG 2006-2014                             October 30, 2014
     Part 3: Commands                                                           Trusted Platform Module Library


     18.3.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "Attest_spt_fp.h"
3    #include "CertifyCreation_fp.h"
4    #ifdef TPM_CC_CertifyCreation // Conditional expansion of this file


     Error Returns               Meaning

     TPM_RC_KEY                  key referenced by signHandle is not a signing key
     TPM_RC_SCHEME               inScheme is not compatible with signHandle
     TPM_RC_TICKET               creationTicket does not match objectHandle
     TPM_RC_VALUE                digest generated for inScheme is greater or has larger size than the
                                 modulus of signHandle, or the buffer for the result in signature is too
                                 small (for an RSA key); invalid commit status (for an ECC key with a
                                 split scheme).

 5   TPM_RC
 6   TPM2_CertifyCreation(
 7       CertifyCreation_In     *in,                // IN: input parameter list
 8       CertifyCreation_Out    *out                // OUT: output parameter list
 9       )
10   {
11       TPM_RC                 result;
12       TPM2B_NAME             name;
13       TPMT_TK_CREATION       ticket;
14       TPMS_ATTEST            certifyInfo;
15
16   // Input Validation
17
18       // CertifyCreation specific input validation
19       // Get certified object name
20       name.t.size = ObjectGetName(in->objectHandle, &name.t.name);
21       // Re-compute ticket
22       TicketComputeCreation(in->creationTicket.hierarchy, &name,
23                             &in->creationHash, &ticket);
24       // Compare ticket
25       if(!Memory2BEqual(&ticket.digest.b, &in->creationTicket.digest.b))
26           return TPM_RC_TICKET + RC_CertifyCreation_creationTicket;
27
28   // Command Output
29       // Common fields
30       result = FillInAttestInfo(in->signHandle, &in->inScheme, &in->qualifyingData,
31                                 &certifyInfo);
32       if(result != TPM_RC_SUCCESS)
33       {
34           if(result == TPM_RC_KEY)
35               return TPM_RC_KEY + RC_CertifyCreation_signHandle;
36           else
37               return RcSafeAddToResult(result, RC_CertifyCreation_inScheme);
38       }
39
40       // CertifyCreation specific fields
41       // Attestation type
42       certifyInfo.type = TPM_ST_ATTEST_CREATION;
43       certifyInfo.attested.creation.objectName = name;
44
45       // Copy the creationHash
46       certifyInfo.attested.creation.creationHash = in->creationHash;
47
48       // Sign attestation structure.   A NULL signature will be returned if

     Page 162                                 TCG Published                                           Family “2.0”
     October 30, 2014                  Copyright © TCG 2006-2014                       Level 00 Revision 01.16
     Trusted Platform Module Library                                             Part 3: Commands

49       // signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE,
50       // TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned at
51       // this point
52       result = SignAttestInfo(in->signHandle,
53                               &in->inScheme,
54                               &certifyInfo,
55                               &in->qualifyingData,
56                               &out->certifyInfo,
57                               &out->signature);
58
59       // TPM_RC_ATTRIBUTES cannot be returned here as FillInAttestInfo would already
60       // have returned TPM_RC_KEY
61       pAssert(result != TPM_RC_ATTRIBUTES);
62
63       if(result != TPM_RC_SUCCESS)
64           return result;
65
66       // orderly state should be cleared because of the reporting of clock info
67       // if signing happens
68       if(in->signHandle != TPM_RH_NULL)
69           g_clearOrderly = TRUE;
70
71       return TPM_RC_SUCCESS;
72   }
73   #endif // CC_CertifyCreation


     Family “2.0”                            TCG Published                                Page 163
     Level 00 Revision 01.16            Copyright © TCG 2006-2014                October 30, 2014
Part 3: Commands                                                                  Trusted Platform Module Library


18.4     TPM2_Quote

18.4.1 General Description

This command is used to quote PCR values.

NOTE            See 18.1 for description of how the signing scheme is selected.

The TPM will hash the list of PCR selected by PCRselect using the hash algorithm associated with
signHandle (this is the hash algorithm of the signing scheme, not the nameAlg of signHandle).
The digest is computed as the hash of the concatenation of all of the digest values of the selected PCR.
The concatenation of PCR is described in TPM 2.0 Part 1, Selecting Multiple PCR.

NOTE 2          If signHandle is TPM_RH_NULL, the TPMS_ATTEST structure is returned and signature is a NULL
                Signature.


Page 164                                       TCG Published                                        Family “2.0”
October 30, 2014                       Copyright © TCG 2006-2014                       Level 00 Revision 01.16
Trusted Platform Module Library                                                          Part 3: Commands


18.4.2 Command and Response

                                  Table 81 — TPM2_Quote Command
Type                          Name                  Description

TPMI_ST_COMMAND_TAG           tag                   TPM_ST_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode           TPM_CC_Quote

                                                    handle of key that will perform signature
TPMI_DH_OBJECT+               @signHandle           Auth Index: 1
                                                    Auth Role: USER

TPM2B_DATA                    qualifyingData        data supplied by the caller
                                                    signing scheme to use if the scheme for signHandle is
TPMT_SIG_SCHEME+              inScheme
                                                    TPM_ALG_NULL
TPML_PCR_SELECTION            PCRselect             PCR set to quote


                                  Table 82 — TPM2_Quote Response
Type                          Name                  Description

TPM_ST                        tag                   see clause 6
UINT32                        responseSize
TPM_RC                        responseCode

TPM2B_ATTEST                  quoted                the quoted information
TPMT_SIGNATURE                signature             the signature over quoted


Family “2.0”                                 TCG Published                                      Page 165
Level 00 Revision 01.16             Copyright © TCG 2006-2014                            October 30, 2014
     Part 3: Commands                                                           Trusted Platform Module Library


     18.4.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "Attest_spt_fp.h"
3    #include "Quote_fp.h"
4    #ifdef TPM_CC_Quote // Conditional expansion of this file


     Error Returns               Meaning

     TPM_RC_KEY                  signHandle does not reference a signing key;
     TPM_RC_SCHEME               the scheme is not compatible with sign key type, or input scheme is
                                 not compatible with default scheme, or the chosen scheme is not a
                                 valid sign scheme

 5   TPM_RC
 6   TPM2_Quote(
 7       Quote_In        *in,             // IN: input parameter list
 8       Quote_Out       *out             // OUT: output parameter list
 9       )
10   {
11       TPM_RC                  result;
12       TPMI_ALG_HASH           hashAlg;
13       TPMS_ATTEST             quoted;
14
15   // Command Output
16
17       // Filling in attest information
18       // Common fields
19       // FillInAttestInfo may return TPM_RC_SCHEME or TPM_RC_KEY
20       result = FillInAttestInfo(in->signHandle,
21                                 &in->inScheme,
22                                 &in->qualifyingData,
23                                 &quoted);
24       if(result != TPM_RC_SUCCESS)
25       {
26           if(result == TPM_RC_KEY)
27               return TPM_RC_KEY + RC_Quote_signHandle;
28           else
29               return RcSafeAddToResult(result, RC_Quote_inScheme);
30       }
31
32       // Quote specific fields
33       // Attestation type
34       quoted.type = TPM_ST_ATTEST_QUOTE;
35
36       // Get hash algorithm in sign scheme. This hash algorithm is used to
37       // compute PCR digest. If there is no algorithm, then the PCR cannot
38       // be digested and this command returns TPM_RC_SCHEME
39       hashAlg = in->inScheme.details.any.hashAlg;
40
41       if(hashAlg == TPM_ALG_NULL)
42           return TPM_RC_SCHEME + RC_Quote_inScheme;
43
44       // Compute PCR digest
45       PCRComputeCurrentDigest(hashAlg,
46                               &in->PCRselect,
47                               &quoted.attested.quote.pcrDigest);
48
49       // Copy PCR select. "PCRselect" is modified in PCRComputeCurrentDigest
50       // function
51       quoted.attested.quote.pcrSelect = in->PCRselect;
52

     Page 166                                 TCG Published                                        Family “2.0”
     October 30, 2014                Copyright © TCG 2006-2014                       Level 00 Revision 01.16
     Trusted Platform Module Library                                             Part 3: Commands

53       // Sign attestation structure. A NULL signature will be returned if
54       // signHandle is TPM_RH_NULL. TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES
55       // error may be returned by SignAttestInfo.
56       // NOTE: TPM_RC_ATTRIBUTES means that the key is not a signing key but that
57       // was checked above and TPM_RC_KEY was returned. TPM_RC_VALUE means that the
58       // value to sign is too large but that means that the digest is too big and
59       // that can't happen.
60       result = SignAttestInfo(in->signHandle,
61                               &in->inScheme,
62                               &quoted,
63                               &in->qualifyingData,
64                               &out->quoted,
65                               &out->signature);
66       if(result != TPM_RC_SUCCESS)
67           return result;
68
69       // orderly state should be cleared because of the reporting of clock info
70       // if signing happens
71       if(in->signHandle != TPM_RH_NULL)
72           g_clearOrderly = TRUE;
73
74       return TPM_RC_SUCCESS;
75   }
76   #endif // CC_Quote


     Family “2.0”                           TCG Published                                 Page 167
     Level 00 Revision 01.16           Copyright © TCG 2006-2014                 October 30, 2014
Part 3: Commands                                                                  Trusted Platform Module Library


18.5     TPM2_GetSessionAuditDigest

18.5.1 General Description

This command returns a digital signature of the audit session digest.

NOTE 1          See 18.1 for description of how the signing scheme is selected.

If sessionHandle is not an audit session, the TPM shall return TPM_RC_TYPE.

NOTE 2          A session does not become an audit session until the successful completion of the command in
                which the session is first used as an audit session.

This command requires authorization from the privacy administrator of the TPM (expressed with
Endorsement Authorization) as well as authorization to use the key associated with signHandle.
If this command is audited, then the audit digest that is signed will not include the digest of this command
because the audit digest is only updated when the command completes successfully.
This command does not cause the audit session to be closed and does not reset the digest value.

NOTE 3          If sessionHandle is used as an audit session for this command, the command is audited in the same
                manner as any other command.

NOTE 4          If signHandle is TPM_RH_NULL, the TPMS_ATTEST structure is returned and signature is a NULL
                Signature.


Page 168                                       TCG Published                                        Family “2.0”
October 30, 2014                       Copyright © TCG 2006-2014                       Level 00 Revision 01.16
Trusted Platform Module Library                                                           Part 3: Commands


18.5.2 Command and Response

                       Table 83 — TPM2_GetSessionAuditDigest Command
Type                          Name                  Description

TPMI_ST_COMMAND_TAG           tag                   TPM_ST_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode           TPM_CC_GetSessionAuditDigest

                                                    handle of the privacy administrator
                                                    (TPM_RH_ENDORSEMENT)
TPMI_RH_ENDORSEMENT           @privacyAdminHandle
                                                    Auth Index: 1
                                                    Auth Role: USER
                                                    handle of the signing key
TPMI_DH_OBJECT+               @signHandle           Auth Index: 2
                                                    Auth Role: USER
                                                    handle of the audit session
TPMI_SH_HMAC                  sessionHandle
                                                    Auth Index: None

TPM2B_DATA                    qualifyingData        user-provided qualifying data – may be zero-length
                                                    signing scheme to use if the scheme for signHandle is
TPMT_SIG_SCHEME+              inScheme
                                                    TPM_ALG_NULL


                       Table 84 — TPM2_GetSessionAuditDigest Response
Type                          Name                  Description

TPM_ST                        tag                   see clause 6
UINT32                        responseSize
TPM_RC                        responseCode

TPM2B_ATTEST                  auditInfo             the audit information that was signed
TPMT_SIGNATURE                signature             the signature over auditInfo


Family “2.0”                                 TCG Published                                       Page 169
Level 00 Revision 01.16             Copyright © TCG 2006-2014                             October 30, 2014
     Part 3: Commands                                                            Trusted Platform Module Library


     18.5.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "Attest_spt_fp.h"
3    #include "GetSessionAuditDigest_fp.h"
4    #ifdef TPM_CC_GetSessionAuditDigest // Conditional expansion of this file


     Error Returns                 Meaning

     TPM_RC_KEY                    key referenced by signHandle is not a signing key
     TPM_RC_SCHEME                 inScheme is incompatible with signHandle type; or both scheme and
                                   key's default scheme are empty; or scheme is empty while key's
                                   default scheme requires explicit input scheme (split signing); or non-
                                   empty default key scheme differs from scheme
     TPM_RC_TYPE                   sessionHandle does not reference an audit session
     TPM_RC_VALUE                  digest generated for the given scheme is greater than the modulus of
                                   signHandle (for an RSA key); invalid commit status or failed to
                                   generate r value (for an ECC key)

 5   TPM_RC
 6   TPM2_GetSessionAuditDigest(
 7       GetSessionAuditDigest_In      *in,                // IN: input parameter list
 8       GetSessionAuditDigest_Out     *out                // OUT: output parameter list
 9       )
10   {
11       TPM_RC                  result;
12       SESSION                *session;
13       TPMS_ATTEST             auditInfo;
14
15   // Input Validation
16
17       // SessionAuditDigest specific input validation
18       // Get session pointer
19       session = SessionGet(in->sessionHandle);
20
21       // session must be an audit session
22       if(session->attributes.isAudit == CLEAR)
23           return TPM_RC_TYPE + RC_GetSessionAuditDigest_sessionHandle;
24
25   // Command Output
26
27       // Filling in attest information
28       // Common fields
29       result = FillInAttestInfo(in->signHandle,
30                                 &in->inScheme,
31                                 &in->qualifyingData,
32                                 &auditInfo);
33       if(result != TPM_RC_SUCCESS)
34       {
35           if(result == TPM_RC_KEY)
36               return TPM_RC_KEY + RC_GetSessionAuditDigest_signHandle;
37           else
38               return RcSafeAddToResult(result, RC_GetSessionAuditDigest_inScheme);
39       }
40
41       // SessionAuditDigest specific fields
42       // Attestation type
43       auditInfo.type = TPM_ST_ATTEST_SESSION_AUDIT;
44
45       // Copy digest
46       auditInfo.attested.sessionAudit.sessionDigest = session->u2.auditDigest;

     Page 170                                   TCG Published                                          Family “2.0”
     October 30, 2014                  Copyright © TCG 2006-2014                        Level 00 Revision 01.16
     Trusted Platform Module Library                                             Part 3: Commands

47
48       // Exclusive audit session
49       if(g_exclusiveAuditSession == in->sessionHandle)
50           auditInfo.attested.sessionAudit.exclusiveSession = TRUE;
51       else
52           auditInfo.attested.sessionAudit.exclusiveSession = FALSE;
53
54       // Sign attestation structure. A NULL signature will be returned if
55       // signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE,
56       // TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned at
57       // this point
58       result = SignAttestInfo(in->signHandle,
59                               &in->inScheme,
60                               &auditInfo,
61                               &in->qualifyingData,
62                               &out->auditInfo,
63                               &out->signature);
64       if(result != TPM_RC_SUCCESS)
65           return result;
66
67       // orderly state should be cleared because of the reporting of clock info
68       // if signing happens
69       if(in->signHandle != TPM_RH_NULL)
70           g_clearOrderly = TRUE;
71
72       return TPM_RC_SUCCESS;
73   }
74   #endif // CC_GetSessionAuditDigest


     Family “2.0”                           TCG Published                               Page 171
     Level 00 Revision 01.16           Copyright © TCG 2006-2014                 October 30, 2014
Part 3: Commands                                                                  Trusted Platform Module Library


18.6     TPM2_GetCommandAuditDigest

18.6.1 General Description

This command returns the current value of the command audit digest, a digest of the commands being
audited, and the audit hash algorithm. These values are placed in an attestation structure and signed with
the key referenced by signHandle.

NOTE 1          See 18.1 for description of how the signing scheme is selected.

When this command completes successfully, and signHandle is not TPM_RH_NULL, the audit digest is
cleared. If signHandle is TPM_RH_NULL, signature is the Empty Buffer and the audit digest is not
cleared.

NOTE 2          The way that the TPM tracks that the digest is clear is vendor-dependent. The reference
                implementation resets the size of the digest to zero.

If this command is being audited, then the signed digest produced by the command will not include the
command. At the end of this command, the audit digest will be extended with cpHash and the rpHash of
the command which would change the command audit digest signed by the next invocation of this
command.
This command requires authorization from the privacy administrator of the TPM (expressed with
Endorsement Authorization) as well as authorization to use the key associated with signHandle.


Page 172                                       TCG Published                                        Family “2.0”
October 30, 2014                       Copyright © TCG 2006-2014                       Level 00 Revision 01.16
Trusted Platform Module Library                                                            Part 3: Commands


18.6.2 Command and Response

                      Table 85 — TPM2_GetCommandAuditDigest Command
 Type                         Name                   Description

 TPMI_ST_COMMAND_TAG          tag                    TPM_ST_SESSIONS
 UINT32                       commandSize
 TPM_CC                       commandCode            TPM_CC_GetCommandAuditDigest {NV}

                                                     handle of the privacy administrator
                                                     (TPM_RH_ENDORSEMENT)
 TPMI_RH_ENDORSEMENT          @privacyHandle
                                                     Auth Index: 1
                                                     Auth Role: USER
                                                     the handle of the signing key
 TPMI_DH_OBJECT+              @signHandle            Auth Index: 2
                                                     Auth Role: USER

 TPM2B_DATA                   qualifyingData         other data to associate with this audit digest
                                                     signing scheme to use if the scheme for signHandle is
 TPMT_SIG_SCHEME+             inScheme
                                                     TPM_ALG_NULL


                      Table 86 — TPM2_GetCommandAuditDigest Response
Type                          Name                  Description

TPM_ST                        tag                   see clause 6
UINT32                        responseSize
TPM_RC                        responseCode

TPM2B_ATTEST                  auditInfo             the auditInfo that was signed
TPMT_SIGNATURE                signature             the signature over auditInfo


Family “2.0”                                 TCG Published                                            Page 173
Level 00 Revision 01.16             Copyright © TCG 2006-2014                              October 30, 2014
     Part 3: Commands                                                            Trusted Platform Module Library


     18.6.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "Attest_spt_fp.h"
3    #include "GetCommandAuditDigest_fp.h"
4    #ifdef TPM_CC_GetCommandAuditDigest // Conditional expansion of this file


     Error Returns                 Meaning

     TPM_RC_KEY                    key referenced by signHandle is not a signing key
     TPM_RC_SCHEME                 inScheme is incompatible with signHandle type; or both scheme and
                                   key's default scheme are empty; or scheme is empty while key's
                                   default scheme requires explicit input scheme (split signing); or non-
                                   empty default key scheme differs from scheme
     TPM_RC_VALUE                  digest generated for the given scheme is greater than the modulus of
                                   signHandle (for an RSA key); invalid commit status or failed to
                                   generate r value (for an ECC key)

 5   TPM_RC
 6   TPM2_GetCommandAuditDigest(
 7       GetCommandAuditDigest_In      *in,                // IN: input parameter list
 8       GetCommandAuditDigest_Out     *out                // OUT: output parameter list
 9       )
10   {
11       TPM_RC                   result;
12       TPMS_ATTEST              auditInfo;
13
14   // Command Output
15
16       // Filling in attest information
17       // Common fields
18       result = FillInAttestInfo(in->signHandle,
19                                 &in->inScheme,
20                                 &in->qualifyingData,
21                                 &auditInfo);
22       if(result != TPM_RC_SUCCESS)
23       {
24           if(result == TPM_RC_KEY)
25               return TPM_RC_KEY + RC_GetCommandAuditDigest_signHandle;
26           else
27               return RcSafeAddToResult(result, RC_GetCommandAuditDigest_inScheme);
28       }
29
30       // CommandAuditDigest specific fields
31       // Attestation type
32       auditInfo.type = TPM_ST_ATTEST_COMMAND_AUDIT;
33
34       // Copy audit hash algorithm
35       auditInfo.attested.commandAudit.digestAlg = gp.auditHashAlg;
36
37       // Copy counter value
38       auditInfo.attested.commandAudit.auditCounter = gp.auditCounter;
39
40       // Copy command audit log
41       auditInfo.attested.commandAudit.auditDigest = gr.commandAuditDigest;
42       CommandAuditGetDigest(&auditInfo.attested.commandAudit.commandDigest);
43
44       //   Sign attestation structure. A NULL signature will be returned if
45       //   signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE,
46       //   TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned at
47       //   this point

     Page 174                                   TCG Published                                          Family “2.0”
     October 30, 2014                  Copyright © TCG 2006-2014                        Level 00 Revision 01.16
     Trusted Platform Module Library                                         Part 3: Commands

48       result = SignAttestInfo(in->signHandle,
49                               &in->inScheme,
50                               &auditInfo,
51                               &in->qualifyingData,
52                               &out->auditInfo,
53                               &out->signature);
54
55       if(result != TPM_RC_SUCCESS)
56           return result;
57
58   // Internal Data Update
59
60       if(in->signHandle != TPM_RH_NULL)
61       {
62           // Reset log
63           gr.commandAuditDigest.t.size = 0;
64
65           // orderly state should be cleared because of the update in
66           // commandAuditDigest, as well as the reporting of clock info
67           g_clearOrderly = TRUE;
68       }
69
70       return TPM_RC_SUCCESS;
71   }
72   #endif // CC_GetCommandAuditDigest


     Family “2.0”                            TCG Published                          Page 175
     Level 00 Revision 01.16            Copyright © TCG 2006-2014            October 30, 2014
Part 3: Commands                                                                  Trusted Platform Module Library


18.7     TPM2_GetTime

18.7.1 General Description

This command returns the current values of Time and Clock.

NOTE 1          See 18.1 for description of how the signing scheme is selected.

The values of Clock, resetCount and restartCount appear in two places in timeInfo: once in
TPMS_ATTEST.clockInfo and again in TPMS_ATTEST.attested.time.clockInfo. The firmware version
number       also      appears       in      two    places     (TPMS_ATTEST.firmwareVersion             and
TPMS_ATTEST.attested.time.firmwareVersion). If signHandle is in the endorsement or platform
hierarchies, both copies of the data will be the same. However, if signHandle is in the storage hierarchy or
is TPM_RH_NULL, the values in TPMS_ATTEST.clockInfo and TPMS_ATTEST.firmwareVersion are
obfuscated but the values in TPMS_ATTEST.attested.time are not.

NOTE 2          The purpose of this duplication is to allow an entity who is trusted by the privacy Administrator to
                correlate the obfuscated values with the clear-text values. This command requires Endorsement
                Authorization.

NOTE 3          If signHandle is TPM_RH_NULL, the TPMS_ATTEST structure is returned and signature is a NULL
                Signature.


Page 176                                       TCG Published                                         Family “2.0”
October 30, 2014                       Copyright © TCG 2006-2014                       Level 00 Revision 01.16
Trusted Platform Module Library                                                           Part 3: Commands


18.7.2 Command and Response

                                  Table 87 — TPM2_GetTime Command
Type                          Name                  Description

TPMI_ST_COMMAND_TAG           tag                   TPM_ST_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode           TPM_CC_GetTime

                                                    handle of the privacy administrator
                                                    (TPM_RH_ENDORSEMENT)
TPMI_RH_ENDORSEMENT           @privacyAdminHandle
                                                    Auth Index: 1
                                                    Auth Role: USER
                                                    the keyHandle identifier of a loaded key that can
                                                    perform digital signatures
TPMI_DH_OBJECT+               @signHandle
                                                    Auth Index: 2
                                                    Auth Role: USER

TPM2B_DATA                    qualifyingData        data to tick stamp
                                                    signing scheme to use if the scheme for signHandle is
TPMT_SIG_SCHEME+              inScheme
                                                    TPM_ALG_NULL


                                  Table 88 — TPM2_GetTime Response
Type                          Name                  Description

TPM_ST                        tag                   see clause 6
UINT32                        responseSize
TPM_RC                        responseCode          .

TPM2B_ATTEST                  timeInfo              standard TPM-generated attestation block
TPMT_SIGNATURE                signature             the signature over timeInfo


Family “2.0”                                 TCG Published                                        Page 177
Level 00 Revision 01.16              Copyright © TCG 2006-2014                            October 30, 2014
     Part 3: Commands                                                          Trusted Platform Module Library


     18.7.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "Attest_spt_fp.h"
3    #include "GetTime_fp.h"
4    #ifdef TPM_CC_GetTime // Conditional expansion of this file


     Error Returns               Meaning

     TPM_RC_KEY                  key referenced by signHandle is not a signing key
     TPM_RC_SCHEME               inScheme is incompatible with signHandle type; or both scheme and
                                 key's default scheme are empty; or scheme is empty while key's
                                 default scheme requires explicit input scheme (split signing); or non-
                                 empty default key scheme differs from scheme
     TPM_RC_VALUE                digest generated for the given scheme is greater than the modulus of
                                 signHandle (for an RSA key); invalid commit status or failed to
                                 generate r value (for an ECC key)

 5   TPM_RC
 6   TPM2_GetTime(
 7       GetTime_In      *in,             // IN: input parameter list
 8       GetTime_Out     *out             // OUT: output parameter list
 9       )
10   {
11       TPM_RC                 result;
12       TPMS_ATTEST            timeInfo;
13
14   // Command Output
15
16       // Filling in attest information
17       // Common fields
18       result = FillInAttestInfo(in->signHandle,
19                                 &in->inScheme,
20                                 &in->qualifyingData,
21                                 &timeInfo);
22       if(result != TPM_RC_SUCCESS)
23       {
24           if(result == TPM_RC_KEY)
25               return TPM_RC_KEY + RC_GetTime_signHandle;
26           else
27               return RcSafeAddToResult(result, RC_GetTime_inScheme);
28       }
29
30       // GetClock specific fields
31       // Attestation type
32       timeInfo.type = TPM_ST_ATTEST_TIME;
33
34       // current clock in plain text
35       timeInfo.attested.time.time.time = g_time;
36       TimeFillInfo(&timeInfo.attested.time.time.clockInfo);
37
38       // Firmware version in plain text
39       timeInfo.attested.time.firmwareVersion
40           = ((UINT64) gp.firmwareV1) << 32;
41       timeInfo.attested.time.firmwareVersion += gp.firmwareV2;
42
43       // Sign attestation structure. A NULL signature will be returned if
44       // signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE,
45       // TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned at
46       // this point
47       result = SignAttestInfo(in->signHandle,

     Page 178                                  TCG Published                                         Family “2.0”
     October 30, 2014                Copyright © TCG 2006-2014                        Level 00 Revision 01.16
     Trusted Platform Module Library                                             Part 3: Commands

48                               &in->inScheme,
49                               &timeInfo,
50                               &in->qualifyingData,
51                               &out->timeInfo,
52                               &out->signature);
53       if(result != TPM_RC_SUCCESS)
54           return result;
55
56       // orderly state should be cleared because of the reporting of clock info
57       // if signing happens
58       if(in->signHandle != TPM_RH_NULL)
59           g_clearOrderly = TRUE;
60
61       return TPM_RC_SUCCESS;
62   }
63   #endif // CC_GetTime


     Family “2.0”                           TCG Published                               Page 179
     Level 00 Revision 01.16           Copyright © TCG 2006-2014                 October 30, 2014
Part 3: Commands                                                              Trusted Platform Module Library


19     Ephemeral EC Keys

19.1    Introduction

The TPM generates keys that have different lifetimes. TPM keys in a hierarchy can be persistent for as
long as the seed of the hierarchy is unchanged and these keys may be used multiple times. Other TPM-
generated keys are only useful for a single operation. Some of these single-use keys are used in the
command in which they are created. Examples of this use are TPM2_Duplicate() where an ephemeral
key is created for a single pass key exchange with another TPM. However, there are other cases, such
as anonymous attestation, where the protocol requires two passes where the public part of the ephemeral
key is used outside of the TPM before the final command "consumes" the ephemeral key.
For these uses, TPM2_Commit() or TPM2_EC_Ephemeral() may be used to have the TPM create an
ephemeral EC key and return the public part of the key for external use. Then in a subsequent command,
the caller provides a reference to the ephemeral key so that the TPM can retrieve or recreate the
associated private key.
When an ephemeral EC key is created, it is assigned a number and that number is returned to the caller
as the identifier for the key. This number is not a handle. A handle is assigned to a key that may be
context saved but these ephemeral EC keys may not be saved and do not have a full key context. When
a subsequent command uses the ephemeral key, the caller provides the number of the ephemeral key.
The TPM uses that number to either look up or recompute the associated private key. After the key is
used, the TPM records the fact that the key has been used so that it cannot be used again.
As mentioned, the TPM can keep each assigned private ephemeral key in memory until it is used.
However, this could consume a large amount of memory. To limit the memory size, the TPM is allowed to
restrict the number of pending private keys – keys that have been allocated but not used.

NOTE            The minimum number of ephemeral keys is determined by a platform specific specification

To further reduce the memory requirements for the ephemeral private keys, the TPM is allowed to use
pseudo-random values for the ephemeral keys. Instead of keeping the full value of the key in memory, the
TPM can use a counter as input to a KDF. Incrementing the counter will cause the TPM to generate a
new pseudo-random value.
Using the counter to generate pseudo-random private ephemeral keys greatly simplifies tracking of key
usage. When a counter value is used to create a key, a bit in an array may be set to indicate that the key
use is pending. When the ephemeral key is consumed, the bit is cleared. This prevents the key from
being used more than once.
Since the TPM is allowed to restrict the number of pending ephemeral keys, the array size can be limited.
For example, a 128 bit array would allow 128 keys to be "pending".
The management of the array is described in greater detail in the Split Operations clause in Annex C of
TPM 2.0 Part 1.


Page 180                                      TCG Published                                        Family “2.0”
October 30, 2014                      Copyright © TCG 2006-2014                     Level 00 Revision 01.16
Trusted Platform Module Library                                                            Part 3: Commands


19.2   TPM2_Commit

19.2.1 General Description

TPM2_Commit() performs the first part of an ECC anonymous signing operation. The TPM will perform
the point multiplications on the provided points and return intermediate signing values. The signHandle
parameter shall refer to an ECC key with the sign attribute (TPM_RC_ATTRIBUTES) and the signing
scheme must be anonymous (TPM_RC_SCHEME). Currently, TPM_ALG_ECDAA is the only defined
anonymous scheme.

NOTE           This command cannot be used with a sign+decrypt key because that type of key is req uired to have
               a scheme of TPM_ALG_NULL.

For this command, p1, s2 and y2 are optional parameters. If s2 is an Empty Buffer, then the TPM shall
return TPM_RC_SIZE if y2 is not an Empty Buffer.
The algorithm is specified in the TPM 2.0 Part 1 Annex for ECC, TPM2_Commit().


Family “2.0”                                 TCG Published                                          Page 181
Level 00 Revision 01.16              Copyright © TCG 2006-2014                             October 30, 2014
Part 3: Commands                                                 Trusted Platform Module Library


19.2.2 Command and Response

                        Table 89 — TPM2_Commit Command
Type                    Name                Description

TPMI_ST_COMMAND_TAG     tag                 TPM_ST_SESSIONS

UINT32                  commandSize

TPM_CC                  commandCode         TPM_CC_Commit

                                            handle of the key that will be used in the signing
                                            operation
TPMI_DH_OBJECT          @signHandle
                                            Auth Index: 1
                                            Auth Role: USER

TPM2B_ECC_POINT         P1                  a point (M) on the curve used by signHandle

TPM2B_SENSITIVE_DATA    s2                  octet array used to derive x-coordinate of a base point

TPM2B_ECC_PARAMETER     y2                  y coordinate of the point associated with s2


                        Table 90 — TPM2_Commit Response
Type                    Name                Description

TPM_ST                  tag                 see 6

UINT32                  responseSize

TPM_RC                  responseCode

TPM2B_ECC_POINT         K                   ECC point K ≔ [ds](x2, y2)

TPM2B_ECC_POINT         L                   ECC point L ≔ [r](x2, y2)

TPM2B_ECC_POINT         E                   ECC point E ≔ [r]P1

UINT16                  counter             least-significant 16 bits of commitCount


Page 182                           TCG Published                                        Family “2.0”
October 30, 2014              Copyright © TCG 2006-2014                  Level 00 Revision 01.16
     Trusted Platform Module Library                                                                      Part 3: Commands


     19.2.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "Commit_fp.h"
3    #ifdef TPM_CC_Commit // Conditional expansion of this file
4    #ifdef TPM_ALG_ECC


     Error Returns                     Meaning

     TPM_RC_ATTRIBUTES                 keyHandle references a restricted key that is not a signing key
     TPM_RC_ECC_POINT                  either P1 or the point derived from s2 is not on the curve of
                                       keyHandle
     TPM_RC_HASH                       invalid name algorithm in keyHandle
     TPM_RC_KEY                        keyHandle does not reference an ECC key
     TPM_RC_SCHEME                     the scheme of keyHandle is not an anonymous scheme
     TPM_RC_NO_RESULT                  K, L or E was a point at infinity; or failed to generate r value
     TPM_RC_SIZE                       s2 is empty but y2 is not or s2 provided but y2 is not

 5   TPM_RC
 6   TPM2_Commit(
 7       Commit_In         *in,                 // IN: input parameter list
 8       Commit_Out        *out                 // OUT: output parameter list
 9       )
10   {
11       OBJECT                    *eccKey;
12       TPMS_ECC_POINT             P2;
13       TPMS_ECC_POINT            *pP2 = NULL;
14       TPMS_ECC_POINT            *pP1 = NULL;
15       TPM2B_ECC_PARAMETER        r;
16       TPM2B                     *p;
17       TPM_RC                     result;
18       TPMS_ECC_PARMS            *parms;
19
20   // Input Validation
21
22       eccKey = ObjectGet(in->signHandle);
23       parms = & eccKey->publicArea.parameters.eccDetail;
24
25       // Input key must be an ECC key
26       if(eccKey->publicArea.type != TPM_ALG_ECC)
27           return TPM_RC_KEY + RC_Commit_signHandle;
28
29        // This command may only be used with a sign-only key using an anonymous
30        // scheme.
31        // NOTE: a sign + decrypt key has no scheme so it will not be an anonymous one
32        // and an unrestricted sign key might no have a signing scheme but it can't
33        // be use in Commit()
34       if(!CryptIsSchemeAnonymous(parms->scheme.scheme))
35                return TPM_RC_SCHEME + RC_Commit_signHandle;
36
37       // Make sure that both parts of P2 are present if either is present
38       if((in->s2.t.size == 0) != (in->y2.t.size == 0))
39           return TPM_RC_SIZE + RC_Commit_y2;
40
41       // Get prime modulus for the curve. This is needed later but getting this now
42       // allows confirmation that the curve exists
43       p = (TPM2B *)CryptEccGetParameter('p', parms->curveID);
44
45       // if no p, then the curve ID is bad


     Family “2.0”                                    TCG Published                                               Page 183
     Level 00 Revision 01.16                Copyright © TCG 2006-2014                                     October 30, 2014
      Part 3: Commands                                                  Trusted Platform Module Library

 46      // NOTE: This should never occur if the input unmarshaling code is working
 47      // correctly
 48      pAssert(p != NULL);
 49
 50      // Get the random value that will be used in the point multiplications
 51      // Note: this does not commit the count.
 52      if(!CryptGenerateR(&r, NULL, parms->curveID, &eccKey->name))
 53          return TPM_RC_NO_RESULT;
 54
 55      // Set up P2 if s2 and Y2 are provided
 56      if(in->s2.t.size != 0)
 57      {
 58          pP2 = &P2;
 59
 60          // copy y2 for P2
 61          MemoryCopy2B(&P2.y.b, &in->y2.b, sizeof(P2.y.t.buffer));
 62          // Compute x2 HnameAlg(s2) mod p
 63
 64          //      do the hash operation on s2 with the size of curve 'p'
 65          P2.x.t.size = CryptHashBlock(eccKey->publicArea.nameAlg,
 66                                       in->s2.t.size,
 67                                       in->s2.t.buffer,
 68                                       p->size,
 69                                       P2.x.t.buffer);
 70
 71          // If there were error returns in the hash routine, indicate a problem
 72          // with the hash in
 73          if(P2.x.t.size == 0)
 74              return TPM_RC_HASH + RC_Commit_signHandle;
 75
 76          // set p2.x = hash(s2) mod p
 77          if(CryptDivide(&P2.x.b, p, NULL, &P2.x.b) != TPM_RC_SUCCESS)
 78              return TPM_RC_NO_RESULT;
 79
 80          if(!CryptEccIsPointOnCurve(parms->curveID, pP2))
 81              return TPM_RC_ECC_POINT + RC_Commit_s2;
 82
 83          if(eccKey->attributes.publicOnly == SET)
 84              return TPM_RC_KEY + RC_Commit_signHandle;
 85
 86      }
 87      // If there is a P1, make sure that it is on the curve
 88      // NOTE: an "empty" point has two UINT16 values which are the size values
 89      // for each of the coordinates.
 90      if(in->P1.t.size > 4)
 91      {
 92          pP1 = &in->P1.t.point;
 93          if(!CryptEccIsPointOnCurve(parms->curveID, pP1))
 94              return TPM_RC_ECC_POINT + RC_Commit_P1;
 95      }
 96
 97      // Pass the parameters to CryptCommit.
 98      // The work is not done in-line because it does several point multiplies
 99      // with the same curve. There is significant optimization by not
100      // having to reload the curve parameters multiple times.
101      result = CryptCommitCompute(&out->K.t.point,
102                                  &out->L.t.point,
103                                  &out->E.t.point,
104                                  parms->curveID,
105                                  pP1,
106                                  pP2,
107                                  &eccKey->sensitive.sensitive.ecc,
108                                  &r);
109      if(result != TPM_RC_SUCCESS)
110          return result;
111

      Page 184                              TCG Published                                 Family “2.0”
      October 30, 2014               Copyright © TCG 2006-2014                Level 00 Revision 01.16
      Trusted Platform Module Library                                             Part 3: Commands

112       out->K.t.size = TPMS_ECC_POINT_Marshal(&out->K.t.point, NULL, NULL);
113       out->L.t.size = TPMS_ECC_POINT_Marshal(&out->L.t.point, NULL, NULL);
114       out->E.t.size = TPMS_ECC_POINT_Marshal(&out->E.t.point, NULL, NULL);
115
116       // The commit computation was successful so complete the commit by setting
117       // the bit
118       out->counter = CryptCommit();
119
120       return TPM_RC_SUCCESS;
121   }
122   #endif
123   #endif // CC_Commit


      Family “2.0”                           TCG Published                               Page 185
      Level 00 Revision 01.16           Copyright © TCG 2006-2014                 October 30, 2014
Part 3: Commands                                                   Trusted Platform Module Library


19.3   TPM2_EC_Ephemeral

19.3.1 General Description

TPM2_EC_Ephemeral() creates an ephemeral key for use in a two-phase key exchange protocol.
The TPM will use the commit mechanism to assign an ephemeral key r and compute a public point Q ≔
[r]G where G is the generator point associated with curveID.


Page 186                                TCG Published                                Family “2.0”
October 30, 2014                  Copyright © TCG 2006-2014              Level 00 Revision 01.16
Trusted Platform Module Library                                                           Part 3: Commands


19.3.2 Command and Response

                            Table 91 — TPM2_EC_Ephemeral Command
Type                              Name                Description

                                                      TPM_ST_SESSIONS if an audit or encrypt session is
TPMI_ST_COMMAND_TAG               tag
                                                      present; otherwise, TPM_ST_NO_SESSIONS

UINT32                            commandSize

TPM_CC                            commandCode         TPM_CC_EC_Ephemeral

TPMI_ECC_CURVE                    curveID             The curve for the computed ephemeral point


                            Table 92 — TPM2_EC_Ephemeral Response
Type                              Name                Description

TPM_ST                            tag                 see 6

UINT32                            responseSize

TPM_RC                            responseCode

TPM2B_ECC_POINT                   Q                   ephemeral public key Q ≔ [r]G

UINT16                            counter             least-significant 16 bits of commitCount


Family “2.0”                                 TCG Published                                         Page 187
Level 00 Revision 01.16                 Copyright © TCG 2006-2014                         October 30, 2014
     Part 3: Commands                                                     Trusted Platform Module Library


     19.3.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "EC_Ephemeral_fp.h"
3    #ifdef TPM_CC_EC_Ephemeral // Conditional expansion of this file
4    #ifdef TPM_ALG_ECC


     Error Returns                    Meaning

     none                             ...

 5   TPM_RC
 6   TPM2_EC_Ephemeral(
 7       EC_Ephemeral_In       *in,               // IN: input parameter list
 8       EC_Ephemeral_Out      *out               // OUT: output parameter list
 9       )
10   {
11       TPM2B_ECC_PARAMETER          r;
12
13       // Get the random value that will be used in the point multiplications
14       // Note: this does not commit the count.
15       if(!CryptGenerateR(&r,
16                          NULL,
17                          in->curveID,
18                          NULL))
19           return TPM_RC_NO_RESULT;
20
21       CryptEccPointMultiply(&out->Q.t.point, in->curveID, &r, NULL);
22
23       // commit the count value
24       out->counter = CryptCommit();
25
26       return TPM_RC_SUCCESS;
27   }
28   #endif
29   #endif // CC_EC_Ephemeral


     Page 188                                    TCG Published                               Family “2.0”
     October 30, 2014                       Copyright © TCG 2006-2014             Level 00 Revision 01.16
Trusted Platform Module Library                                                           Part 3: Commands


20     Signing and Signature Verification

20.1     TPM2_VerifySignature

20.1.1 General Description

This command uses loaded keys to validate a signature on a message with the message digest passed
to the TPM.
If the signature check succeeds, then the TPM will produce a TPMT_TK_VERIFIED. Otherwise, the TPM
shall return TPM_RC_SIGNATURE.

NOTE 1          A valid ticket may be used in subsequent commands to provide proof to the TPM that the TPM has
                validated the signature over the message using the key referenced by keyHandle.

If keyHandle references an asymmetric key, only the public portion of the key needs to be loaded. If
keyHandle references a symmetric key, both the public and private portions need to be loaded.

NOTE 2          The sensitive area of the symmetric object is required to allow verification of the symmetric
                signature (the HMAC).


Family “2.0”                                 TCG Published                                         Page 189
Level 00 Revision 01.16              Copyright © TCG 2006-2014                            October 30, 2014
Part 3: Commands                                                    Trusted Platform Module Library


20.1.2 Command and Response

                      Table 93 — TPM2_VerifySignature Command
Type                    Name                  Description

                                              TPM_ST_SESSIONS if an audit or encrypt session is
TPMI_ST_COMMAND_TAG     tag
                                              present; otherwise, TPM_ST_NO_SESSIONS
UINT32                  commandSize
TPM_CC                  commandCode           TPM_CC_VerifySignature

                                              handle of public key that will be used in the validation
TPMI_DH_OBJECT          keyHandle
                                              Auth Index: None

TPM2B_DIGEST            digest                digest of the signed message
TPMT_SIGNATURE          signature             signature to be tested


                      Table 94 — TPM2_VerifySignature Response
Type                    Name                  Description

TPM_ST                  tag                   see clause 6
UINT32                  responseSize
TPM_RC                  responseCode

TPMT_TK_VERIFIED        validation


Page 190                               TCG Published                                      Family “2.0”
October 30, 2014              Copyright © TCG 2006-2014                    Level 00 Revision 01.16
     Trusted Platform Module Library                                                               Part 3: Commands


     20.1.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "VerifySignature_fp.h"
3    #ifdef TPM_CC_VerifySignature // Conditional expansion of this file


     Error Returns                     Meaning

     TPM_RC_ATTRIBUTES                 keyHandle does not reference a signing key
     TPM_RC_SIGNATURE                  signature is not genuine
     TPM_RC_SCHEME                     CryptVerifySignature()
     TPM_RC_HANDLE                     the input handle is references an HMAC key but the private portion is
                                       not loaded

 4   TPM_RC
 5   TPM2_VerifySignature(
 6       VerifySignature_In        *in,                   // IN: input parameter list
 7       VerifySignature_Out       *out                   // OUT: output parameter list
 8       )
 9   {
10       TPM_RC                     result;
11       TPM2B_NAME                 name;
12       OBJECT                    *signObject;
13       TPMI_RH_HIERARCHY          hierarchy;
14
15   // Input Validation
16
17       // Get sign object pointer
18       signObject = ObjectGet(in->keyHandle);
19
20       // The object to validate the signature must be a signing key.
21       if(signObject->publicArea.objectAttributes.sign != SET)
22           return TPM_RC_ATTRIBUTES + RC_VerifySignature_keyHandle;
23
24       // Validate Signature. TPM_RC_SCHEME, TPM_RC_HANDLE or TPM_RC_SIGNATURE
25       // error may be returned by CryptCVerifySignatrue()
26       result = CryptVerifySignature(in->keyHandle, &in->digest, &in->signature);
27       if(result != TPM_RC_SUCCESS)
28           return RcSafeAddToResult(result, RC_VerifySignature_signature);
29
30   // Command Output
31
32       hierarchy = ObjectGetHierarchy(in->keyHandle);
33       if(   hierarchy == TPM_RH_NULL
34          || signObject->publicArea.nameAlg == TPM_ALG_NULL)
35       {
36           // produce empty ticket if hierarchy is TPM_RH_NULL or nameAlg is
37           // TPM_ALG_NULL
38           out->validation.tag = TPM_ST_VERIFIED;
39           out->validation.hierarchy = TPM_RH_NULL;
40           out->validation.digest.t.size = 0;
41       }
42       else
43       {
44           // Get object name that verifies the signature
45           name.t.size = ObjectGetName(in->keyHandle, &name.t.name);
46           // Compute ticket
47           TicketComputeVerified(hierarchy, &in->digest, &name, &out->validation);
48       }
49
50       return TPM_RC_SUCCESS;

     Family “2.0”                                  TCG Published                                               Page 191
     Level 00 Revision 01.16               Copyright © TCG 2006-2014                               October 30, 2014
     Part 3: Commands                                           Trusted Platform Module Library

51   }
52   #endif // CC_VerifySignature


     Page 192                            TCG Published                            Family “2.0”
     October 30, 2014               Copyright © TCG 2006-2014        Level 00 Revision 01.16
Trusted Platform Module Library                                                                Part 3: Commands


20.2     TPM2_Sign

20.2.1 General Description

This command causes the TPM to sign an externally provided hash with the specified symmetric or
asymmetric signing key.

NOTE 1          Symmetric “signing” is done with the TPM HMAC commands.

If keyHandle references a restricted signing key, then validation shall be provided, indicating that the TPM
performed the hash of the data and validation shall indicate that hashed data did not start with
TPM_GENERATED_VALUE.

NOTE 2          If the hashed data did start with TPM_GENERATED_VALUE, then the validation will be a NULL
                ticket.

If the scheme of keyHandle is not TPM_ALG_NULL, then inScheme shall either be the same scheme as
keyHandle or TPM_ALG_NULL.
If the scheme of keyHandle is TPM_ALG_NULL, the TPM will sign using inScheme; otherwise, it will sign
using the scheme of keyHandle.

NOTE 3          When the signing scheme uses a hash algorithm, the algorithm is defined in the qualifying data of
                the scheme. This is the same algorithm that is required to be used in producing digest. The size of
                digest must match that of the hash algorithm in the scheme.

If inScheme is not a valid signing scheme for the type of keyHandle (or TPM_ALG_NULL), then the TPM
shall return TPM_RC_SCHEME.
If the scheme of keyHandle is an anonymous scheme, then inScheme shall have the same scheme
algorithm as keyHandle and inScheme will contain a counter value that will be used in the signing
process.
If validation is provided, then the hash algorithm used in computing the digest is required to be the hash
algorithm specified in the scheme of keyHandle (TPM_RC_TICKET).
If the validation parameter is not the Empty Buffer, then it will be checked even if the key referenced by
keyHandle is not a restricted signing key.

NOTE 4          If keyHandle is both a sign and decrypt key, keyHandle will have an scheme of TPM_ALG_NULL. If
                validation is provided, then it must be a NULL validation ticket or the ticket validation will fail.


Family “2.0”                                   TCG Published                                            Page 193
Level 00 Revision 01.16                Copyright © TCG 2006-2014                               October 30, 2014
Part 3: Commands                                                   Trusted Platform Module Library


20.2.2 Command and Response

                             Table 95 — TPM2_Sign Command
Type                   Name                  Description

TPMI_ST_COMMAND_TAG    tag                   TPM_ST_SESSIONS
UINT32                 commandSize
TPM_CC                 commandCode           TPM_CC_Sign

                                             Handle of key that will perform signing
TPMI_DH_OBJECT         @keyHandle            Auth Index: 1
                                             Auth Role: USER

TPM2B_DIGEST           digest                digest to be signed
                                             signing scheme to use if the scheme for keyHandle is
TPMT_SIG_SCHEME+       inScheme
                                             TPM_ALG_NULL
                                             proof that digest was created by the TPM
TPMT_TK_HASHCHECK      validation            If keyHandle is not a restricted signing key, then this
                                             may be a NULL Ticket with tag =
                                             TPM_ST_CHECKHASH.


                             Table 96 — TPM2_Sign Response
Type                   Name                  Description

TPM_ST                 tag                   see clause 6
UINT32                 responseSize
TPM_RC                 responseCode

TPMT_SIGNATURE         signature             the signature


Page 194                              TCG Published                                       Family “2.0”
October 30, 2014              Copyright © TCG 2006-2014                   Level 00 Revision 01.16
     Trusted Platform Module Library                                                                 Part 3: Commands


     20.2.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "Sign_fp.h"
3    #ifdef TPM_CC_Sign // Conditional expansion of this file
4    #include "Attest_spt_fp.h"


     Error Returns                     Meaning

     TPM_RC_BINDING                    The public and private portions of the key are not properly bound.
     TPM_RC_KEY                        signHandle does not reference a signing key;
     TPM_RC_SCHEME                     the scheme is not compatible with sign key type, or input scheme is
                                       not compatible with default scheme, or the chosen scheme is not a
                                       valid sign scheme
     TPM_RC_TICKET                     validation is not a valid ticket
     TPM_RC_VALUE                      the value to sign is larger than allowed for the type of keyHandle

 5   TPM_RC
 6   TPM2_Sign(
 7       Sign_In          *in,                   // IN: input parameter list
 8       Sign_Out         *out                   // OUT: output parameter list
 9       )
10   {
11       TPM_RC                     result;
12       TPMT_TK_HASHCHECK          ticket;
13       OBJECT                    *signKey;
14
15   // Input Validation
16       // Get sign key pointer
17       signKey = ObjectGet(in->keyHandle);
18
19       // pick a scheme for sign. If the input sign scheme is not compatible with
20       // the default scheme, return an error.
21       result = CryptSelectSignScheme(in->keyHandle, &in->inScheme);
22       if(result != TPM_RC_SUCCESS)
23       {
24           if(result == TPM_RC_KEY)
25               return TPM_RC_KEY + RC_Sign_keyHandle;
26           else
27               return RcSafeAddToResult(result, RC_Sign_inScheme);
28       }
29
30       // If validation is provided, or the key is restricted, check the ticket
31       if(   in->validation.digest.t.size != 0
32          || signKey->publicArea.objectAttributes.restricted == SET)
33       {
34           // Compute and compare ticket
35           TicketComputeHashCheck(in->validation.hierarchy,
36                                  in->inScheme.details.any.hashAlg,
37                                  &in->digest, &ticket);
38
39           if(!Memory2BEqual(&in->validation.digest.b, &ticket.digest.b))
40               return TPM_RC_TICKET + RC_Sign_validation;
41       }
42       else
43       // If we don't have a ticket, at least verify that the provided 'digest'
44       // is the size of the scheme hashAlg digest.
45       // NOTE: this does not guarantee that the 'digest' is actually produced using
46       // the indicated hash algorithm, but at least it might be.
47       {

     Family “2.0”                                    TCG Published                                           Page 195
     Level 00 Revision 01.16                Copyright © TCG 2006-2014                                October 30, 2014
     Part 3: Commands                                                  Trusted Platform Module Library

48           if(       in->digest.t.size
49                 != CryptGetHashDigestSize(in->inScheme.details.any.hashAlg))
50                 return TPM_RCS_SIZE + RC_Sign_digest;
51       }
52
53   // Command Output
54       // Sign the hash. A TPM_RC_VALUE or TPM_RC_SCHEME
55       // error may be returned at this point
56       result = CryptSign(in->keyHandle, &in->inScheme, &in->digest, &out->signature);
57
58       return result;
59   }
60   #endif // CC_Sign


     Page 196                                TCG Published                               Family “2.0”
     October 30, 2014                  Copyright © TCG 2006-2014            Level 00 Revision 01.16
Trusted Platform Module Library                                                       Part 3: Commands


21     Command Audit

21.1    Introduction

If a command has been selected for command audit, the command audit status will be updated when that
command completes successfully. The digest is updated as:
             commandAuditDigestnew ≔ HauditAlg(commandAuditDigestold || cpHash || rpHash)           (5)
where
         HauditAlg                       hash function using the algorithm of the audit sequence
         commandAuditDigest              accumulated digest
         cpHash                          the command parameter hash
         rpHash                          the response parameter hash

auditAlg, the hash algorithm, is set using TPM2_SetCommandCodeAuditStatus.


TPM2_Shutdown() cannot be audited but TPM2_Startup() can be audited. If the cpHash of the
TPM2_Startup() is TPM_SU_STATE, that would indicate that a TPM2_Shutdown() had been successfully
executed.
TPM2_SetCommandCodeAuditStatus() is always audited.
If the TPM is in Failure mode, command audit is not functional.


Family “2.0”                                TCG Published                                      Page 197
Level 00 Revision 01.16              Copyright © TCG 2006-2014                        October 30, 2014
Part 3: Commands                                                               Trusted Platform Module Library


21.2     TPM2_SetCommandCodeAuditStatus

21.2.1 General Description

This command may be used by the Privacy Administrator or platform to change the audit status of a
command or to set the hash algorithm used for the audit digest, but not both at the same time.
If the auditAlg parameter is a supported hash algorithm and not the same as the current algorithm, then
the TPM will check both setList and clearList are empty (zero length). If so, then the algorithm is changed,
and the audit digest is cleared. If auditAlg is TPM_ALG_NULL or the same as the current algorithm, then
the algorithm and audit digest are unchanged and the setList and clearList will be processed.

NOTE 1          Because the audit digest is cleared, the audit counter will increment the next time that an audited
                command is executed.

Use of TPM2_SetCommandCodeAuditStatus() to change the list of audited commands is an audited
event. If TPM_CC_SetCommandCodeAuditStatus is in clearList, the fact that it is in clearList is ignored.

NOTE 2          Use of this command to change the audit hash algorithm is not audited and the digest is reset when
                the command completes. The change in the audit hash algorith m is the evidence that this command
                was used to change the algorithm.

The commands in setList indicate the commands to be added to the list of audited commands and the
commands in clearList indicate the commands that will no longer be audited. It is not an error if a
command in setList is already audited or is not implemented. It is not an error if a command in clearList is
not currently being audited or is not implemented.
If a command code is in both setList and clearList, then it will not be audited (that is, setList shall be
processed first).


Page 198                                      TCG Published                                         Family “2.0”
October 30, 2014                      Copyright © TCG 2006-2014                       Level 00 Revision 01.16
Trusted Platform Module Library                                                       Part 3: Commands


21.2.2 Command and Response

                   Table 97 — TPM2_SetCommandCodeAuditStatus Command
 Type                         Name                Description

 TPMI_ST_COMMAND_TAG          tag                 TPM_ST_SESSIONS
 UINT32                       commandSize
 TPM_CC                       commandCode         TPM_CC_SetCommandCodeAuditStatus {NV}

                                                  TPM_RH_OWNER or TPM_RH_PLATFORM+{PP}
 TPMI_RH_PROVISION            @auth               Auth Index: 1
                                                  Auth Role: USER

                                                  hash algorithm for the audit digest; if
 TPMI_ALG_HASH+               auditAlg
                                                  TPM_ALG_NULL, then the hash is not changed
                                                  list of commands that will be added to those that will
 TPML_CC                      setList
                                                  be audited
 TPML_CC                      clearList           list of commands that will no longer be audited


                   Table 98 — TPM2_SetCommandCodeAuditStatus Response
 Type                         Name                Description

 TPM_ST                       tag                 see clause 6
 UINT32                       responseSize
 TPM_RC                       responseCode


Family “2.0”                              TCG Published                                         Page 199
Level 00 Revision 01.16             Copyright © TCG 2006-2014                         October 30, 2014
     Part 3: Commands                                                  Trusted Platform Module Library


     21.2.3 Detailed Actions

 1   #include "InternalRoutines.h"
 2   #include "SetCommandCodeAuditStatus_fp.h"
 3   #ifdef TPM_CC_SetCommandCodeAuditStatus // Conditional expansion of this file
 4   TPM_RC
 5   TPM2_SetCommandCodeAuditStatus(
 6       SetCommandCodeAuditStatus_In      *in             // IN: input parameter list
 7       )
 8   {
 9       TPM_RC          result;
10       UINT32          i;
11       BOOL            changed = FALSE;
12
13       // The command needs NV update. Check if NV is available.
14       // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
15       // this point
16       result = NvIsAvailable();
17       if(result != TPM_RC_SUCCESS)
18           return result;
19
20   // Internal Data Update
21
22       // Update hash algorithm
23       if(   in->auditAlg != TPM_ALG_NULL
24          && in->auditAlg != gp.auditHashAlg)
25       {
26           // Can't change the algorithm and command list at the same time
27           if(in->setList.count != 0 || in->clearList.count != 0)
28               return TPM_RC_VALUE + RC_SetCommandCodeAuditStatus_auditAlg;
29
30           // Change the hash algorithm for audit
31           gp.auditHashAlg = in->auditAlg;
32
33           // Set the digest size to a unique value that indicates that the digest
34           // algorithm has been changed. The size will be cleared to zero in the
35           // command audit processing on exit.
36           gr.commandAuditDigest.t.size = 1;
37
38           // Save the change of command audit data (this sets g_updateNV so that NV
39           // will be updated on exit.)
40           NvWriteReserved(NV_AUDIT_HASH_ALG, &gp.auditHashAlg);
41
42       } else {
43
44           // Process set list
45           for(i = 0; i < in->setList.count; i++)
46
47                // If change is made in CommandAuditSet, set changed flag
48                if(CommandAuditSet(in->setList.commandCodes[i]))
49                    changed = TRUE;
50
51           // Process clear list
52           for(i = 0; i < in->clearList.count; i++)
53               // If change is made in CommandAuditClear, set changed flag
54               if(CommandAuditClear(in->clearList.commandCodes[i]))
55                   changed = TRUE;
56
57           // if change was made to command list, update NV
58           if(changed)
59               // this sets g_updateNV so that NV will be updated on exit.
60               NvWriteReserved(NV_AUDIT_COMMANDS, &gp.auditComands);
61       }
62

     Page 200                                    TCG Published                           Family “2.0”
     October 30, 2014                   Copyright © TCG 2006-2014             Level 00 Revision 01.16
     Trusted Platform Module Library                               Part 3: Commands

63       return TPM_RC_SUCCESS;
64   }
65   #endif // CC_SetCommandCodeAuditStatus


     Family “2.0”                             TCG Published               Page 201
     Level 00 Revision 01.16           Copyright © TCG 2006-2014   October 30, 2014
Part 3: Commands                                                             Trusted Platform Module Library


22     Integrity Collection (PCR)

22.1     Introduction

In TPM 1.2, an Event was hashed using SHA-1 and then the 20-octet digest was extended to a PCR
using TPM_Extend(). This specification allows the use of multiple PCR at a given Index, each using a
different hash algorithm. Rather than require that the external software generate multiple hashes of the
Event with each being extended to a different PCR, the Event data may be sent to the TPM for hashing.
This ensures that the resulting digests will properly reflect the algorithms chosen for the PCR even if the
calling software is unable to implement the hash algorithm.

NOTE 1          There is continued support for software hashing of events with TPM2_PCR_Extend().

To support recording of an Event that is larger than the TPM input buffer, the caller may use the
command sequence described in clause 1.
Change to a PCR requires authorization. The authorization may be with either an authorization value or
an authorization policy. The platform-specific specifications determine which PCR may be controlled by
policy. All other PCR are controlled by authorization.
If a PCR may be associated with a policy, then the algorithm ID of that policy determines whether the
policy is to be applied. If the algorithm ID is not TPM_ALG_NULL, then the policy digest associated with
the PCR must match the policySession→policyDigest in a policy session. If the algorithm ID is
TPM_ALG_NULL, then no policy is present and the authorization requires an EmptyAuth.
If a platform-specific specification indicates that PCR are grouped, then all the PCR in the group use the
same authorization policy or authorization value.
PcrUpdateCounter counter will be incremented on the successful completion of any command that
modifies (Extends or resets) a PCR unless the platform-specific specification explicitly excludes the PCR
from being counted.

NOTE 2          If a command causes PCR in multiple banks to change, the PCR Update Counter may be
                incremented either once or once for each bank.

A platform-specific specification may designate a set of PCR that are under control of the TCB. These
PCR may not be modified without the proper authorization. Updates of these PCR shall not cause the
PCR Update Counter to increment.

EXAMPLE         Updates of the TCB PCR will not cause the PCR update counter to increment because these PCR
                are changed at the whim of the TCB and may not represent the trust state of the platform.


Page 202                                      TCG Published                                         Family “2.0”
October 30, 2014                      Copyright © TCG 2006-2014                     Level 00 Revision 01.16
Trusted Platform Module Library                                                                    Part 3: Commands


22.2     TPM2_PCR_Extend

22.2.1 General Description

This command is used to cause an update to the indicated PCR. The digests parameter contains one or
more tagged digest values identified by an algorithm ID. For each digest, the PCR associated with
pcrHandle is Extended into the bank identified by the tag (hashAlg).

EXAMPLE           A SHA1 digest would be Extended i nto the SHA1 bank and a SHA256 digest would be Extended into
                  the SHA256 bank.

For each list entry, the TPM will check to see if pcrNum is implemented for that algorithm. If so, the TPM
shall perform the following operation:
          PCR.digestnew [pcrNum][alg] ≔ Halg(PCR.digestold [pcrNum][alg] || data[alg].buffer))                       (6)
where
         Halg()                               hash function using the hash algorithm associated with the PCR
                                              instance
         PCR.digest                           the digest value in a PCR
         pcrNum                               the PCR numeric selector (pcrHandle)
         alg                                  the PCR algorithm selector for the digest
         data[alg].buffer                     the bank-specific data to be extended


If no digest value is specified for a bank, then the PCR in that bank is not modified.

NOTE 1            This allows consistent operation of the digests list for all of the Event recording commands.

If a digest is present and the PCR in that bank is not implemented, the digest value is not used.

NOTE 2            If the caller includes digests for algorithms that are not implemented, then the TPM will fail the call
                  because the unmarshalling of digests will fail. Each of the entries in the list is a TPMT_HA, which is
                  a hash algorithm followed by a digest. If the algorithm is not implemented, unmarshalling of the
                  hashAlg will fail and the TPM will return TPM_RC_HASH.

If the TPM unmarshals the hashAlg of a list entry and the unmarshaled value is not a hash algorithm
implemented on the TPM, the TPM shall return TPM_RC_HASH.
The pcrHandle parameter is allowed to reference TPM_RH_NULL. If so, the input parameters are
processed but no action is taken by the TPM. This permits the caller to probe for implemented hash
algorithms as an alternative to TPM2_GetCapability.

NOTE 3            This command allows a list of digests so that PCR in all banks may be updated in a single
                  command. While the semantics of this command allow multiple extends to a single PCR bank, this is
                  not the preferred use and the limit on the number of entries in the list make this use somewhat
                  impractical.


Family “2.0”                                      TCG Published                                              Page 203
Level 00 Revision 01.16                  Copyright © TCG 2006-2014                                 October 30, 2014
Part 3: Commands                                                  Trusted Platform Module Library


22.2.2 Command and Response

                      Table 99 — TPM2_PCR_Extend Command
Type                   Name                  Description

TPMI_ST_COMMAND_TAG    tag                   TPM_ST_SESSIONS
UINT32                 commandSize
TPM_CC                 commandCode           TPM_CC_PCR_Extend {NV}

                                             handle of the PCR
TPMI_DH_PCR+           @pcrHandle            Auth Handle: 1
                                             Auth Role: USER

TPML_DIGEST_VALUES     digests               list of tagged digest values to be extended


                      Table 100 — TPM2_PCR_Extend Response
Type                   Name                  Description

TPM_ST                 tag                   see clause 6
UINT32                 responseSize
TPM_RC                 responseCode          .


Page 204                              TCG Published                                        Family “2.0”
October 30, 2014             Copyright © TCG 2006-2014                   Level 00 Revision 01.16
     Trusted Platform Module Library                                                               Part 3: Commands


     22.2.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "PCR_Extend_fp.h"
3    #ifdef TPM_CC_PCR_Extend // Conditional expansion of this file


     Error Returns                     Meaning

     TPM_RC_LOCALITY                   current command locality is not allowed to extend the PCR
                                       referenced by pcrHandle

 4   TPM_RC
 5   TPM2_PCR_Extend(
 6       PCR_Extend_In     *in                 // IN: input parameter list
 7       )
 8   {
 9       TPM_RC                  result;
10       UINT32                  i;
11
12   // Input Validation
13
14       //   NOTE: This function assumes that the unmarshaling function for 'digests' will
15       //   have validated that all of the indicated hash algorithms are valid. If the
16       //   hash algorithms are correct, the unmarshaling code will unmarshal a digest
17       //   of the size indicated by the hash algorithm. If the overall size is not
18       //   consistent, the unmarshaling code will run out of input data or have input
19       //   data left over. In either case, it will cause an unmarshaling error and this
20       //   function will not be called.
21
22       // For NULL handle, do nothing and return success
23       if(in->pcrHandle == TPM_RH_NULL)
24           return TPM_RC_SUCCESS;
25
26       // Check if the extend operation is allowed by the current command locality
27       if(!PCRIsExtendAllowed(in->pcrHandle))
28           return TPM_RC_LOCALITY;
29
30       // If PCR is state saved and we need to update orderlyState, check NV
31       // availability
32       if(PCRIsStateSaved(in->pcrHandle) && gp.orderlyState != SHUTDOWN_NONE)
33       {
34           result = NvIsAvailable();
35           if(result != TPM_RC_SUCCESS) return result;
36           g_clearOrderly = TRUE;
37       }
38
39   // Internal Data Update
40
41       // Iterate input digest list to extend
42       for(i = 0; i < in->digests.count; i++)
43       {
44           PCRExtend(in->pcrHandle, in->digests.digests[i].hashAlg,
45                     CryptGetHashDigestSize(in->digests.digests[i].hashAlg),
46                     (BYTE *) &in->digests.digests[i].digest);
47       }
48
49       return TPM_RC_SUCCESS;
50   }
51   #endif // CC_PCR_Extend


     Family “2.0”                                  TCG Published                                          Page 205
     Level 00 Revision 01.16               Copyright © TCG 2006-2014                               October 30, 2014
Part 3: Commands                                                             Trusted Platform Module Library


22.3   TPM2_PCR_Event

22.3.1 General Description

This command is used to cause an update to the indicated PCR.
The data in eventData is hashed using the hash algorithm associated with each bank in which the
indicated PCR has been allocated. After the data is hashed, the digests list is returned. If the pcrHandle
references an implemented PCR and not TPM_ALG_NULL, the digests list is processed as in
TPM2_PCR_Extend().
A TPM shall support an Event.size of zero through 1,024 inclusive (Event.size is an octet count). An
Event.size of zero indicates that there is no data but the indicated operations will still occur,

EXAMPLE 1       If the command implements PCR[2] in a SHA1 bank and a SHA256 bank, then an extend to PCR[2]
                will cause eventData to be hashed twice, once with SHA1 and once with SHA256. The SHA1 hash of
                eventData will be Extended to PCR[2] in the SHA1 bank and the SHA256 hash of eventData will be
                Extended to PCR[2] of the SHA256 bank.

On successful command completion, digests will contain the list of tagged digests of eventData that was
computed in preparation for extending the data into the PCR. At the option of the TPM, the list may
contain a digest for each bank, or it may only contain a digest for each bank in which pcrHandle is extant.
If pcrHandle is TPM_RH_NULL, the TPM may return either an empty list or a digest for each bank.

EXAMPLE 2       Assume a TPM that implements a SHA1 bank and a SHA256 bank and that PCR[22] is only
                implemented in the SHA1 bank. If pcrHandle references PCR[22], then digests may contain either a
                SHA1 and a SHA256 digest or just a SHA1 digest.


Page 206                                      TCG Published                                       Family “2.0”
October 30, 2014                      Copyright © TCG 2006-2014                    Level 00 Revision 01.16
Trusted Platform Module Library                                                  Part 3: Commands


22.3.2 Command and Response

                             Table 101 — TPM2_PCR_Event Command
Type                          Name                  Description

TPMI_ST_COMMAND_TAG           tag                   TPM_ST_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode           TPM_CC_PCR_Event {NV}

                                                    Handle of the PCR
TPMI_DH_PCR+                  @pcrHandle            Auth Handle: 1
                                                    Auth Role: USER

TPM2B_EVENT                   eventData             Event data in sized buffer


                             Table 102 — TPM2_PCR_Event Response
Type                          Name                  Description

TPM_ST                        tag                   see clause 6
UINT32                        responseSize
TPM_RC                        responseCode          .

TPML_DIGEST_VALUES            digests


Family “2.0”                                 TCG Published                              Page 207
Level 00 Revision 01.16             Copyright © TCG 2006-2014                    October 30, 2014
     Part 3: Commands                                                          Trusted Platform Module Library


     22.3.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "PCR_Event_fp.h"
3    #ifdef TPM_CC_PCR_Event // Conditional expansion of this file


     Error Returns                 Meaning

     TPM_RC_LOCALITY               current command locality is not allowed to extend the PCR
                                   referenced by pcrHandle

 4   TPM_RC
 5   TPM2_PCR_Event(
 6       PCR_Event_In      *in,             // IN: input parameter list
 7       PCR_Event_Out     *out             // OUT: output parameter list
 8       )
 9   {
10       TPM_RC                result;
11       HASH_STATE            hashState;
12       UINT32                i;
13       UINT16                size;
14
15   // Input Validation
16
17       // If a PCR extend is required
18       if(in->pcrHandle != TPM_RH_NULL)
19       {
20           // If the PCR is not allow to extend, return error
21           if(!PCRIsExtendAllowed(in->pcrHandle))
22               return TPM_RC_LOCALITY;
23
24           // If PCR is state saved and we need to update orderlyState, check NV
25           // availability
26           if(PCRIsStateSaved(in->pcrHandle) && gp.orderlyState != SHUTDOWN_NONE)
27           {
28               result = NvIsAvailable();
29               if(result != TPM_RC_SUCCESS) return result;
30               g_clearOrderly = TRUE;
31           }
32       }
33
34   // Internal Data Update
35
36       out->digests.count = HASH_COUNT;
37
38       // Iterate supported PCR bank algorithms to extend
39       for(i = 0; i < HASH_COUNT; i++)
40       {
41           TPM_ALG_ID hash = CryptGetHashAlgByIndex(i);
42           out->digests.digests[i].hashAlg = hash;
43           size = CryptStartHash(hash, &hashState);
44           CryptUpdateDigest2B(&hashState, &in->eventData.b);
45           CryptCompleteHash(&hashState, size,
46                             (BYTE *) &out->digests.digests[i].digest);
47           if(in->pcrHandle != TPM_RH_NULL)
48               PCRExtend(in->pcrHandle, hash, size,
49                         (BYTE *) &out->digests.digests[i].digest);
50       }
51
52       return TPM_RC_SUCCESS;
53   }
54   #endif // CC_PCR_Event


     Page 208                                  TCG Published                                     Family “2.0”
     October 30, 2014                  Copyright © TCG 2006-2014                     Level 00 Revision 01.16
Trusted Platform Module Library                                                                 Part 3: Commands


22.4   TPM2_PCR_Read

22.4.1 General Description

This command returns the values of all PCR specified in pcrSelectionIn.
The TPM will process the list of TPMS_PCR_SELECTION in pcrSelectionIn in order. Within each
TPMS_PCR_SELECTION, the TPM will process the bits in the pcrSelect array in ascending PCR order
(see TPM 2.0 Part 2 for definition of the PCR order). If a bit is SET, and the indicated PCR is present,
then the TPM will add the digest of the PCR to the list of values to be returned in pcrValues.
The TPM will continue processing bits until all have been processed or until pcrValues would be too large
to fit into the output buffer if additional values were added.
The returned pcrSelectionOut will have a bit SET in its pcrSelect structures for each value present in
pcrValues.
The current value of the PCR Update Counter is returned in pcrUpdateCounter.
The returned list may be empty if none of the selected PCR are implemented.

NOTE            If no PCR are returned from a bank, the selector for the bank will be present in pcrSelectionOut.

No authorization is required to read a PCR and any implemented PCR may be read from any locality.


Family “2.0”                                   TCG Published                                              Page 209
Level 00 Revision 01.16                Copyright © TCG 2006-2014                                October 30, 2014
Part 3: Commands                                                  Trusted Platform Module Library


22.4.2 Command and Response

                      Table 103 — TPM2_PCR_Read Command
Type                   Name                  Description

                                             TPM_ST_SESSIONS if an audit session is present;
TPMI_ST_COMMAND_TAG    tag
                                             otherwise, TPM_ST_NO_SESSIONS
UINT32                 commandSize
TPM_CC                 commandCode           TPM_CC_PCR_Read

TPML_PCR_SELECTION     pcrSelectionIn        The selection of PCR to read


                      Table 104 — TPM2_PCR_Read Response
Type                   Name                  Description

TPM_ST                 tag                   see clause 6
UINT32                 responseSize
TPM_RC                 responseCode

UINT32                 pcrUpdateCounter      the current value of the PCR update counter
TPML_PCR_SELECTION     pcrSelectionOut       the PCR in the returned list
                                             the contents of the PCR indicated in pcrSelect as
TPML_DIGEST            pcrValues
                                             tagged digests


Page 210                              TCG Published                                    Family “2.0”
October 30, 2014             Copyright © TCG 2006-2014                      Level 00 Revision 01.16
     Trusted Platform Module Library                                            Part 3: Commands


     22.4.3 Detailed Actions

 1   #include "InternalRoutines.h"
 2   #include "PCR_Read_fp.h"
 3   #ifdef TPM_CC_PCR_Read // Conditional expansion of this file
 4   TPM_RC
 5   TPM2_PCR_Read(
 6       PCR_Read_In      *in,            // IN: input parameter list
 7       PCR_Read_Out     *out            // OUT: output parameter list
 8       )
 9   {
10   // Command Output
11
12       // Call PCR read function. input pcrSelectionIn parameter could be changed
13       // to reflect the actual PCR being returned
14       PCRRead(&in->pcrSelectionIn, &out->pcrValues, &out->pcrUpdateCounter);
15
16       out->pcrSelectionOut = in->pcrSelectionIn;
17
18       return TPM_RC_SUCCESS;
19   }
20   #endif // CC_PCR_Read


     Family “2.0”                            TCG Published                             Page 211
     Level 00 Revision 01.16           Copyright © TCG 2006-2014                October 30, 2014
Part 3: Commands                                                              Trusted Platform Module Library


22.5     TPM2_PCR_Allocate

22.5.1 General Description

This command is used to set the desired PCR allocation of PCR and algorithms. This command requires
Platform Authorization.
The TPM will evaluate the request and, if sufficient memory is available for the requested allocation, the
TPM will store the allocation request for use during the next TPM2_Startup(TPM_SU_CLEAR) operation.
The PCR allocation in place when this command is executed will be retained until the next
TPM2_Startup(TPM_SU_CLEAR).              If this command is received multiple times before a
TPM2_Startup(TPM_SU_CLEAR), each one overwrites the previous stored allocation.
This command will only change the allocations of banks that are listed in pcrAllocation.
EXAMPLE      If a TPM supports SHA1 and SHA256, then it maintains an allocation for two banks (one of which could
             be empty). If a TPM_PCR_ALLOCATE() only has a selector for the SHA1 bank, then only the allocation
             of the SHA1 bank will be changed and the SHA256 bank will re main unchanged. To change the
             allocation of a TPM from 24 SHA1 PCR and no SHA256 PCR to 24 SHA256 PCR and no SHA1 PCR, the
             pcrAllocation would have to have two selections: one for the empty SHA1 bank and one for the SHA256
             bank with 24 PCR.


If a bank is listed more than once, then the last selection in the pcrAllocation list is the one that the TPM
will attempt to allocate.
This command shall not allocate more PCR in any bank than there are PCR attribute definitions. The
PCR attribute definitions indicate how a PCR is to be managed – if it is resettable, the locality for update,
etc. In the response to this command, the TPM returns the maximum number of PCR allowed for any
bank.
When PCR are allocated, if DRTM_PCR is defined, the resulting allocation must have at least one bank
with the D-RTM PCR allocated. If HCRTM_PCR is defined, the resulting allocation must have at least
one bank with the HCRTM_PCR allocated. If not, the TPM returns TPM_RC_PCR.
The TPM may return TPM_RC_SUCCESS even though the request fails. This is to allow the TPM to
return information about the size needed for the requested allocation and the size available. If the
sizeNeeded parameter in the return is less than or equal to the sizeAvailable parameter, then the
allocationSuccess parameter will be YES. Alternatively, if the request fails, The TPM may return
TPM_RC_NO_RESULT.

NOTE 1          An example for this type of failure is a TPM that can only support one bank at a time and cannot
                support arbitrary distribution of PCR among banks.

After this command, TPM2_Shutdown() is only allowed to have a startupType equal to TPM_SU_CLEAR.

NOTE 2          Even if this command does not cause the PCR allocation to change, the TPM cannot have its state
                saved. This is done in order to simplify the implementat ion. There is no need to optimize this
                command as it is not expected to be used more than once in the lifetime of the TPM (it can be used
                any number of times but there is no justification for optimization).


Page 212                                      TCG Published                                        Family “2.0”
October 30, 2014                      Copyright © TCG 2006-2014                      Level 00 Revision 01.16
Trusted Platform Module Library                                                          Part 3: Commands


22.5.2 Command and Response

                           Table 105 — TPM2_PCR_Allocate Command
Type                          Name                   Description

TPMI_ST_COMMAND_TAG           tag                    TPM_ST_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode            TPM_CC_PCR_Allocate {NV}

                                                     TPM_RH_PLATFORM+{PP}
TPMI_RH_PLATFORM              @authHandle            Auth Index: 1
                                                     Auth Role: USER

TPML_PCR_SELECTION            pcrAllocation          the requested allocation


                            Table 106 — TPM2_PCR_Allocate Response
Type                          Name                   Description

TPM_ST                        tag                    see clause 6
UINT32                        responseSize
TPM_RC                        responseCode

TPMI_YES_NO                   allocationSuccess      YES if the allocation succeeded
UINT32                        maxPCR                 maximum number of PCR that may be in a bank
UINT32                        sizeNeeded             number of octets required to satisfy the request
                                                     Number of octets available. Computed before the
UINT32                        sizeAvailable
                                                     allocation.


Family “2.0”                                  TCG Published                                        Page 213
Level 00 Revision 01.16             Copyright © TCG 2006-2014                            October 30, 2014
     Part 3: Commands                                                            Trusted Platform Module Library


     22.5.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "PCR_Allocate_fp.h"
3    #ifdef TPM_CC_PCR_Allocate // Conditional expansion of this file


     Error Returns                    Meaning

     TPM_RC_PCR                       the allocation did not have required PCR
     TPM_RC_NV_UNAVAILABLE            NV is not accessible
     TPM_RC_NV_RATE                   NV is in a rate-limiting mode

 4   TPM_RC
 5   TPM2_PCR_Allocate(
 6       PCR_Allocate_In       *in,                 // IN: input parameter list
 7       PCR_Allocate_Out      *out                 // OUT: output parameter list
 8       )
 9   {
10       TPM_RC      result;
11
12       // The command needs NV update. Check if NV is available.
13       // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
14       // this point.
15       // Note: These codes are not listed in the return values above because it is
16       // an implementation choice to check in this routine rather than in a common
17       // function that is called before these actions are called. These return values
18       // are described in the Response Code section of Part 3.
19       result = NvIsAvailable();
20       if(result != TPM_RC_SUCCESS)
21           return result;
22
23   // Command Output
24
25       // Call PCR Allocation function.
26       result = PCRAllocate(&in->pcrAllocation, &out->maxPCR,
27                                            &out->sizeNeeded, &out->sizeAvailable);
28       if(result == TPM_RC_PCR)
29           return result;
30
31       //
32       out->allocationSuccess = (result == TPM_RC_SUCCESS);
33
34       // if re-configuration succeeds, set the flag to indicate PCR configuration is
35       // going to be changed in next boot
36       if(out->allocationSuccess == YES)
37           g_pcrReConfig = TRUE;
38
39       return TPM_RC_SUCCESS;
40   }
41   #endif // CC_PCR_Allocate


     Page 214                                      TCG Published                                   Family “2.0”
     October 30, 2014                     Copyright © TCG 2006-2014                   Level 00 Revision 01.16
Trusted Platform Module Library                                                               Part 3: Commands


22.6     TPM2_PCR_SetAuthPolicy

22.6.1 General Description

This command is used to associate a policy with a PCR or group of PCR. The policy determines the
conditions under which a PCR may be extended or reset.
A policy may only be associated with a PCR that has been defined by a platform-specific specification as
allowing a policy. If the TPM implementation does not allow a policy for pcrNum, the TPM shall return
TPM_RC_VALUE.
A platform-specific specification may group PCR so that they share a common policy. In such case, a
pcrNum that selects any of the PCR in the group will change the policy for all PCR in the group.
The policy setting is persistent and may only be changed by TPM2_PCR_SetAuthPolicy() or by
TPM2_ChangePPS().
Before this command is first executed on a TPM or after TPM2_ChangePPS(), the access control on the
PCR will be set to the default value defined in the platform-specific specification.

NOTE 1          It is expected that the typical default will be with the policy hash set to TPM_ALG_NULL and an
                Empty Buffer for the authPolicy value. This will allow an EmptyAuth to be used as the authorization
                value.

If the size of the data buffer in authPolicy is not the size of a digest produced by hashAlg, the TPM shall
return TPM_RC_SIZE.

NOTE 2          If hashAlg is TPM_ALG_NULL, then the size is required to be zero.

This command requires platformAuth/platformPolicy.

NOTE 3          If the PCR is in multiple policy sets, the policy will be changed in only one set. The set that is
                changed will be implementation dependent.


Family “2.0”                                  TCG Published                                            Page 215
Level 00 Revision 01.16               Copyright © TCG 2006-2014                               October 30, 2014
Part 3: Commands                                                  Trusted Platform Module Library


22.6.2 Command and Response

                   Table 107 — TPM2_PCR_SetAuthPolicy Command
Type                   Name                  Description

TPMI_ST_COMMAND_TAG    tag                   TPM_ST_SESSIONS
UINT32                 commandSize
TPM_CC                 commandCode           TPM_CC_PCR_SetAuthPolicy {NV}

                                             TPM_RH_PLATFORM+{PP}
TPMI_RH_PLATFORM       @authHandle           Auth Index: 1
                                             Auth Role: USER

TPM2B_DIGEST           authPolicy            the desired authPolicy
TPMI_ALG_HASH+         hashAlg               the hash algorithm of the policy
TPMI_DH_PCR            pcrNum                the PCR for which the policy is to be set


                   Table 108 — TPM2_PCR_SetAuthPolicy Response
Type                   Name                  Description

TPM_ST                 tag                   see clause 6
UINT32                 responseSize
TPM_RC                 responseCode


Page 216                              TCG Published                                      Family “2.0”
October 30, 2014             Copyright © TCG 2006-2014                   Level 00 Revision 01.16
     Trusted Platform Module Library                                                                 Part 3: Commands


     22.6.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "PCR_SetAuthPolicy_fp.h"
3    #ifdef TPM_CC_PCR_SetAuthPolicy // Conditional expansion of this file


     Error Returns                     Meaning

     TPM_RC_SIZE                       size of authPolicy is not the size of a digest produced by policyDigest
     TPM_RC_VALUE                      PCR referenced by pcrNum is not a member of a PCR policy group

 4   TPM_RC
 5   TPM2_PCR_SetAuthPolicy(
 6       PCR_SetAuthPolicy_In       *in                   // IN: input parameter list
 7       )
 8   {
 9       UINT32       groupIndex;
10
11       TPM_RC       result;
12
13       // The command needs NV update. Check if NV is available.
14       // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
15       // this point
16       result = NvIsAvailable();
17       if(result != TPM_RC_SUCCESS) return result;
18
19   // Input Validation:
20
21       // Check the authPolicy consistent with hash algorithm
22       if(in->authPolicy.t.size != CryptGetHashDigestSize(in->hashAlg))
23           return TPM_RC_SIZE + RC_PCR_SetAuthPolicy_authPolicy;
24
25       // If PCR does not belong to a policy group, return TPM_RC_VALUE
26       if(!PCRBelongsPolicyGroup(in->pcrNum, &groupIndex))
27           return TPM_RC_VALUE + RC_PCR_SetAuthPolicy_pcrNum;
28
29   // Internal Data Update
30
31       // Set PCR policy
32       gp.pcrPolicies.hashAlg[groupIndex] = in->hashAlg;
33       gp.pcrPolicies.policy[groupIndex] = in->authPolicy;
34
35       // Save new policy to NV
36       NvWriteReserved(NV_PCR_POLICIES, &gp.pcrPolicies);
37
38       return TPM_RC_SUCCESS;
39   }
40   #endif // CC_PCR_SetAuthPolicy


     Family “2.0”                                   TCG Published                                                Page 217
     Level 00 Revision 01.16               Copyright © TCG 2006-2014                                 October 30, 2014
Part 3: Commands                                                      Trusted Platform Module Library


22.7   TPM2_PCR_SetAuthValue

22.7.1 General Description

This command changes the authValue of a PCR or group of PCR.
An authValue may only be associated with a PCR that has been defined by a platform-specific
specification as allowing an authorization value. If the TPM implementation does not allow an
authorization for pcrNum, the TPM shall return TPM_RC_VALUE. A platform-specific specification may
group PCR so that they share a common authorization value. In such case, a pcrNum that selects any of
the PCR in the group will change the authValue value for all PCR in the group.
The authorization setting is set to EmptyAuth on each STARTUP(CLEAR) or by TPM2_Clear(). The
authorization setting is preserved by SHUTDOWN(STATE).


Page 218                                  TCG Published                                 Family “2.0”
October 30, 2014                   Copyright © TCG 2006-2014               Level 00 Revision 01.16
Trusted Platform Module Library                                                       Part 3: Commands


22.7.2 Command and Response

                          Table 109 — TPM2_PCR_SetAuthValue Command
Type                          Name                  Description

TPMI_ST_COMMAND_TAG           tag                   TPM_ST_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode           TPM_CC_PCR_SetAuthValue

                                                    handle for a PCR that may have an authorization value
                                                    set
TPMI_DH_PCR                   @pcrHandle
                                                    Auth Index: 1
                                                    Auth Role: USER

TPM2B_DIGEST                  auth                  the desired authorization value


                          Table 110 — TPM2_PCR_SetAuthValue Response
Type                          Name                  Description

TPM_ST                        tag                   see clause 6
UINT32                        responseSize
TPM_RC                        responseCode


Family “2.0”                                 TCG Published                                      Page 219
Level 00 Revision 01.16              Copyright © TCG 2006-2014                        October 30, 2014
     Part 3: Commands                                                       Trusted Platform Module Library


     22.7.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "PCR_SetAuthValue_fp.h"
3    #ifdef TPM_CC_PCR_SetAuthValue // Conditional expansion of this file


     Error Returns                 Meaning

     TPM_RC_VALUE                  PCR referenced by pcrHandle is not a member of a PCR
                                   authorization group

 4   TPM_RC
 5   TPM2_PCR_SetAuthValue(
 6       PCR_SetAuthValue_In       *in              // IN: input parameter list
 7       )
 8   {
 9       UINT32      groupIndex;
10       TPM_RC      result;
11
12   // Input Validation:
13
14       // If PCR does not belong to an auth group, return TPM_RC_VALUE
15       if(!PCRBelongsAuthGroup(in->pcrHandle, &groupIndex))
16           return TPM_RC_VALUE;
17
18       // The command may cause the orderlyState to be cleared due to the update of
19       // state clear data. If this is the case, Check if NV is available.
20       // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
21       // this point
22       if(gp.orderlyState != SHUTDOWN_NONE)
23       {
24           result = NvIsAvailable();
25           if(result != TPM_RC_SUCCESS) return result;
26           g_clearOrderly = TRUE;
27       }
28
29   // Internal Data Update
30
31       // Set PCR authValue
32       gc.pcrAuthValues.auth[groupIndex] = in->auth;
33
34       return TPM_RC_SUCCESS;
35   }
36   #endif // CC_PCR_SetAuthValue


     Page 220                                 TCG Published                                   Family “2.0”
     October 30, 2014                    Copyright © TCG 2006-2014                Level 00 Revision 01.16
Trusted Platform Module Library                                                             Part 3: Commands


22.8     TPM2_PCR_Reset

22.8.1 General Description

If the attribute of a PCR allows the PCR to be reset and proper authorization is provided, then this
command may be used to set the PCR to zero. The attributes of the PCR may restrict the locality that can
perform the reset operation.

NOTE 1         The definition of TPMI_DH_PCR in TPM 2.0 Part 2 indicates that if pcrHandle is out of the allowed
               range for PCR, then the appropriate return value is TPM_RC_VALUE.

If pcrHandle references a PCR that cannot be reset, the TPM shall return TPM_RC_LOCALITY.

NOTE 2         TPM_RC_LOCALITY is returned because the reset attributes are defined on a per -locality basis.


Family “2.0”                                 TCG Published                                            Page 221
Level 00 Revision 01.16              Copyright © TCG 2006-2014                              October 30, 2014
Part 3: Commands                                                Trusted Platform Module Library


22.8.2 Command and Response

                      Table 111 — TPM2_PCR_Reset Command
Type                   Name                  Description

TPMI_ST_COMMAND_TAG    tag                   TPM_ST_SESSIONS
UINT32                 commandSize
TPM_CC                 commandCode           TPM_CC_PCR_Reset {NV}

                                             the PCR to reset
TPMI_DH_PCR            @pcrHandle            Auth Index: 1
                                             Auth Role: USER


                      Table 112 — TPM2_PCR_Reset Response
Type                   Name                  Description

TPM_ST                 tag                   see clause 6
UINT32                 responseSize
TPM_RC                 responseCode


Page 222                              TCG Published                               Family “2.0”
October 30, 2014             Copyright © TCG 2006-2014               Level 00 Revision 01.16
     Trusted Platform Module Library                                                              Part 3: Commands


     22.8.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "PCR_Reset_fp.h"
3    #ifdef TPM_CC_PCR_Reset // Conditional expansion of this file


     Error Returns                     Meaning

     TPM_RC_LOCALITY                   current command locality is not allowed to reset the PCR referenced
                                       by pcrHandle

 4   TPM_RC
 5   TPM2_PCR_Reset(
 6       PCR_Reset_In      *in                 // IN: input parameter list
 7       )
 8   {
 9       TPM_RC        result;
10
11   // Input Validation
12
13       // Check if the reset operation is allowed by the current command locality
14       if(!PCRIsResetAllowed(in->pcrHandle))
15           return TPM_RC_LOCALITY;
16
17       // If PCR is state saved and we need to update orderlyState, check NV
18       // availability
19       if(PCRIsStateSaved(in->pcrHandle) && gp.orderlyState != SHUTDOWN_NONE)
20       {
21           result = NvIsAvailable();
22           if(result != TPM_RC_SUCCESS)
23               return result;
24           g_clearOrderly = TRUE;
25       }
26
27   // Internal Data Update
28
29       // Reset selected PCR in all banks to 0
30       PCRSetValue(in->pcrHandle, 0);
31
32       // Indicate that the PCR changed so that pcrCounter will be incremented if
33       // necessary.
34       PCRChanged(in->pcrHandle);
35
36       return TPM_RC_SUCCESS;
37   }
38   #endif // CC_PCR_Reset


     Family “2.0”                                  TCG Published                                             Page 223
     Level 00 Revision 01.16               Copyright © TCG 2006-2014                              October 30, 2014
Part 3: Commands                                                                  Trusted Platform Module Library


22.9   _TPM_Hash_Start

22.9.1 Description

This indication from the TPM interface indicates the start of an H-CRTM measurement sequence. On
receipt of this indication, the TPM will initialize an H-CRTM Event Sequence context.
If no object memory is available for creation of the sequence context, the TPM will flush the context of an
object so that creation of the sequence context will always succeed.
A platform-specific specification may allow this indication before TPM2_Startup().

NOTE            If this indication occurs after TPM2_Startup(), i t is the responsibility of software to ensure that an
                object context slot is available or to deal with the consequences of having the TPM select an
                arbitrary object to be flushed. If this indication occurs before TPM2_Startup() then all context slots
                are available.


Page 224                                        TCG Published                                           Family “2.0”
October 30, 2014                       Copyright © TCG 2006-2014                         Level 00 Revision 01.16
     Trusted Platform Module Library                                                Part 3: Commands


     22.9.2 Detailed Actions

1    #include "InternalRoutines.h"

     This function is called to process a _TPM_Hash_Start() indication.

 2   void
 3   _TPM_Hash_Start(
 4       void
 5       )
 6   {
 7       TPM_RC                 result;
 8       TPMI_DH_OBJECT         handle;
 9
10       // If a DRTM sequence object exists, free it up
11       if(g_DRTMHandle != TPM_RH_UNASSIGNED)
12       {
13           ObjectFlush(g_DRTMHandle);
14           g_DRTMHandle = TPM_RH_UNASSIGNED;
15       }
16
17       // Create an event sequence object and store the handle in global
18       // g_DRTMHandle. A TPM_RC_OBJECT_MEMORY error may be returned at this point
19       // The null value for the 'auth' parameter will cause the sequence structure to
20       // be allocated without being set as present. This keeps the sequence from
21       // being left behind if the sequence is terminated early.
22       result = ObjectCreateEventSequence(NULL, &g_DRTMHandle);
23
24       // If a free slot was not available, then free up a slot.
25       if(result != TPM_RC_SUCCESS)
26       {
27           // An implementation does not need to have a fixed relationship between
28           // slot numbers and handle numbers. To handle the general case, scan for
29           // a handle that is assigned and free it for the DRTM sequence.
30           // In the reference implementation, the relationship between handles and
31           // slots is fixed. So, if the call to ObjectCreateEvenSequence()
32           // failed indicating that all slots are occupied, then the first handle we
33           // are going to check (TRANSIENT_FIRST) will be occupied. It will be freed
34           // so that it can be assigned for use as the DRTM sequence object.
35           for(handle = TRANSIENT_FIRST; handle < TRANSIENT_LAST; handle++)
36           {
37               // try to flush the first object
38               if(ObjectIsPresent(handle))
39                   break;
40           }
41           // If the first call to find a slot fails but none of the slots is occupied
42           // then there's a big problem
43           pAssert(handle < TRANSIENT_LAST);
44
45            // Free the slot
46            ObjectFlush(handle);
47
48            // Try to create an event sequence object again. This time, we must
49            // succeed.
50            result = ObjectCreateEventSequence(NULL, &g_DRTMHandle);
51            pAssert(result == TPM_RC_SUCCESS);
52       }
53
54       return;
55   }


     Family “2.0”                                TCG Published                             Page 225
     Level 00 Revision 01.16              Copyright © TCG 2006-2014                 October 30, 2014
Part 3: Commands                                                      Trusted Platform Module Library


22.10 _TPM_Hash_Data

22.10.1    Description

This indication from the TPM interface indicates arrival of one or more octets of data that are to be
included in the H-CRTM Event Sequence sequence context created by the _TPM_Hash_Start indication.
The context holds data for each hash algorithm for each PCR bank implemented on the TPM.
If no H-CRTM Event Sequence context exists, this indication is discarded and no other action is
performed.


Page 226                                  TCG Published                                 Family “2.0”
October 30, 2014                   Copyright © TCG 2006-2014                Level 00 Revision 01.16
     Trusted Platform Module Library                                               Part 3: Commands


     22.10.2      Detailed Actions

1    #include "InternalRoutines.h"
2    #include "Platform.h"
3    #include "PCR_fp.h"

     This function is called to process a _TPM_Hash_Data() indication.

 4   void
 5   _TPM_Hash_Data(
 6       UINT32             dataSize,        // IN: size of data to be extend
 7       BYTE              *data             // IN: data buffer
 8       )
 9   {
10       UINT32             i;
11       HASH_OBJECT       *hashObject;
12       TPMI_DH_PCR        pcrHandle = TPMIsStarted()
13                                     ? PCR_FIRST + DRTM_PCR : PCR_FIRST + HCRTM_PCR;
14
15       // If there is no DRTM sequence object, then _TPM_Hash_Start
16       // was not called so this function returns without doing
17       // anything.
18       if(g_DRTMHandle == TPM_RH_UNASSIGNED)
19           return;
20
21       hashObject = (HASH_OBJECT *)ObjectGet(g_DRTMHandle);
22       pAssert(hashObject->attributes.eventSeq);
23
24       // For each of the implemented hash algorithms, update the digest with the
25       // data provided.
26       for(i = 0; i < HASH_COUNT; i++)
27       {
28           // make sure that the PCR is implemented for this algorithm
29           if(PcrIsAllocated(pcrHandle,
30                               hashObject->state.hashState[i].state.hashAlg))
31               // Update sequence object
32               CryptUpdateDigest(&hashObject->state.hashState[i], dataSize, data);
33       }
34
35       return;
36   }


     Family “2.0”                               TCG Published                             Page 227
     Level 00 Revision 01.16             Copyright © TCG 2006-2014                 October 30, 2014
Part 3: Commands                                                                   Trusted Platform Module Library


22.11 _TPM_Hash_End

22.11.1       Description

This indication from the TPM interface indicates the end of the H-CRTM measurement. This indication is
discarded and no other action performed if the TPM does not contain an H-CRTM Event Sequence
context.

NOTE 1              An H-CRTM Event Sequence context is created by _TPM_Hash_Start().

If the H-CRTM Event Sequence occurs after TPM2_Startup(), the TPM will set all of the PCR designated
in the platform-specific specifications as resettable by this event to the value indicated in the platform
specific specification, and increment restartCount. The TPM will then Extend the Event Sequence
digest/digests into the designated D-RTM PCR (PCR[17]).
                       PCR[17][hashAlg] ≔ HhashAlg (initial_value || HhashAlg (hash_data))                          (7)
where
          hashAlg                             hash algorithm associated with a bank of PCR
          initial_value                       initialization value specified in the platform-specific specification
                                              (should be 0…0)
          hash_data                           all the octets of data received in _TPM_Hash_Data indications
A _TPM_Hash_End indication that occurs after TPM2_Startup() will increment pcrUpdateCounter unless
a platform-specific specification excludes modifications of PCR[DRTM] from causing an increment.
A platform-specific specification may allow an H-CRTM Event Sequence before TPM2_Startup(). If so,
_TPM_Hash_End will complete the digest, initialize PCR[0] with a digest-size value of 4, and then extend
the H-CRTM Event Sequence data into PCR[0].
                            PCR[0][hashAlg] ≔ HhashAlg (0…04 || HhashAlg (hash_data))                               (8)

NOTE 2              The entire sequence of _TPM_Hash_Start, _TPM_Hash_Data, and _TPM_Hash_End are required to
                    complete before TPM2_Startup() or the sequence will have no effect on the TPM.

NOTE 3              PCR[0] does not need to be updated according to (8) until the end of TPM2_Startup().


Page 228                                          TCG Published                                            Family “2.0”
October 30, 2014                          Copyright © TCG 2006-2014                      Level 00 Revision 01.16
     Trusted Platform Module Library                                                Part 3: Commands


     22.11.2       Detailed Actions

1    #include "InternalRoutines.h"

     This function is called to process a _TPM_Hash_End() indication.

 2   void
 3   _TPM_Hash_End(
 4       void
 5       )
 6   {
 7
 8       UINT32            i;
 9       TPM2B_DIGEST      digest;
10       HASH_OBJECT      *hashObject;
11       TPMI_DH_PCR       pcrHandle;
12
13       // If the DRTM handle is not being used, then either _TPM_Hash_Start has not
14       // been called, _TPM_Hash_End was previously called, or some other command
15       // was executed and the sequence was aborted.
16       if(g_DRTMHandle == TPM_RH_UNASSIGNED)
17           return;
18
19       // Get DRTM sequence object
20       hashObject = (HASH_OBJECT *)ObjectGet(g_DRTMHandle);
21
22       // Is this _TPM_Hash_End after Startup or before
23       if(TPMIsStarted())
24       {
25           // After
26
27             // Reset the DRTM PCR
28             PCRResetDynamics();
29
30             // Extend the DRTM_PCR.
31             pcrHandle = PCR_FIRST + DRTM_PCR;
32
33             // DRTM sequence increments restartCount
34             gr.restartCount++;
35       }
36       else
37       {
38           pcrHandle = PCR_FIRST + HCRTM_PCR;
39       }
40
41       // Complete hash and extend PCR, or if this is an HCRTM, complete
42       // the hash, reset the H-CRTM register (PCR[0]) to 0...04, and then
43       // extend the H-CRTM data
44       for(i = 0; i < HASH_COUNT; i++)
45       {
46           TPMI_ALG_HASH       hash = CryptGetHashAlgByIndex(i);
47           // make sure that the PCR is implemented for this algorithm
48           if(PcrIsAllocated(pcrHandle,
49                               hashObject->state.hashState[i].state.hashAlg))
50           {
51               // Complete hash
52               digest.t.size = CryptGetHashDigestSize(hash);
53               CryptCompleteHash2B(&hashObject->state.hashState[i], &digest.b);
54
55                  PcrDrtm(pcrHandle, hash, &digest);
56             }
57       }
58
59       // Flush sequence object.


     Family “2.0”                               TCG Published                              Page 229
     Level 00 Revision 01.16             Copyright © TCG 2006-2014                  October 30, 2014
     Part 3: Commands                                             Trusted Platform Module Library

60       ObjectFlush(g_DRTMHandle);
61
62       g_DRTMHandle = TPM_RH_UNASSIGNED;
63
64       g_DrtmPreStartup = TRUE;
65
66       return;
67   }


     Page 230                                TCG Published                          Family “2.0”
     October 30, 2014                 Copyright © TCG 2006-2014        Level 00 Revision 01.16
Trusted Platform Module Library                                                                Part 3: Commands


23     Enhanced Authorization (EA) Commands

23.1     Introduction

The commands in this clause 1 are used for policy evaluation. When successful, each command will
update the policySession→policyDigest in a policy session context in order to establish that the
authorizations required to use an object have been provided. Many of the commands will also modify
other parts of a policy context so that the caller may constrain the scope of the authorization that is
provided.

NOTE 1          Many of the terms used in this clause are described in detail in TPM 2.0 Part 1 and are not redefined
                in this clause.

The policySession parameter of the command is the handle of the policy session context to be modified
by the command.
If the policySession parameter indicates a trial policy session, then the policySession→policyDigest will
be updated and the indicated validations are not performed.

NOTE 2          A policy session is set to a trial policy by TPM2_StartAuthSession(sessionType = TPM_SE_TRIAL).

NOTE 3          Unless there is an unmarshaling error in the parameters of the command, these commands will
                return TPM_RC_SUCCESS when policySession references a trial session.

NOTE 4          Policy context other than the policySession→policyDigest may be updated for a trial policy but it is
                not required.


Family “2.0”                                   TCG Published                                             Page 231
Level 00 Revision 01.16                Copyright © TCG 2006-2014                               October 30, 2014
Part 3: Commands                                                              Trusted Platform Module Library


23.2   Signed Authorization Actions

23.2.1 Introduction

The TPM2_PolicySigned, TPM_PolicySecret, and TPM2_PolicyTicket commands use many of the same
functions. This clause consolidates those functions to simplify the document and to ensure uniformity of
the operations.

23.2.2 Policy Parameter Checks

These parameter checks will be performed when indicated in the description of each of the commands:
a) nonceTPM – If this parameter is not the Empty Buffer, and it does not match
   policySession→nonceTPM, then the TPM shall return TPM_RC_VALUE. This parameter is required
   to be present if expiration is non-zero (TPM_RC_EXPIRED).
b) expiration – If this parameter is not zero, then its absolute value is compared to the time in seconds
   since the policySession→nonceTPM was generated. If more time has passed than indicated in
   expiration, the TPM shall return TPM_RC_EXPIRED. If nonceTPM is the Empty buffer, and expiration
   is non-zero, then the TPM shall return TPM_RC_EXPIRED.
    If policySession→timeout is greater than policySession→startTime plus the absolute value of
    expiration, then policySession→timeout is set to policySession→startTime plus the absolute value of
    expiration. That is, policySession→timeout can only be changed to a smaller value.
c) timeout – This parameter is compared to the current TPM time. If policySession→timeout is in the
   past, then the TPM shall return TPM_RC_EXPIRED.

    NOTE 1          The expiration parameter is present in the TPM2_PolicySigned and TPM2_PolicySecret
                    command and timeout is the analogous parameter in the TPM2_PolicyTicket command.

d) cpHashA – If this parameter is not an Empty Buffer

    NOTE 2          CpHashA is the hash of the command to be executed using this policy session in the
                    authorization. The algorithm used to compute this hash is required to be the algorithm of the
                    policy session.

    1) the TPM shall return TPM_RC_CPHASH if policySession→cpHash is set and the contents of
       policySession→cpHash are not the same as cpHashA; or

        NOTE 3          cpHash is the expected cpHash value held in the policy session context.

    2) the TPM shall return TPM_RC_SIZE                    if   cpHashA     is   not     the   same    size   as
       policySession→policyDigest.

        NOTE 4          policySession→policyDigest is the size of the digest produced by the hash algorithm used
                        to compute policyDigest.


Page 232                                      TCG Published                                       Family “2.0”
October 30, 2014                      Copyright © TCG 2006-2014                        Level 00 Revision 01.16
Trusted Platform Module Library                                                                  Part 3: Commands


23.2.3 Policy Digest Update Function (PolicyUpdate())

This is the update process for policySession→policyDigest used by TPM2_PolicySigned(),
TPM2_PolicySecret(), TPM2_PolicyTicket(), and TPM2_PolicyAuthorize(). The function prototype for the
update function is:
                                   PolicyUpdate(commandCode, arg2, arg3)                                           (9)
where
         arg2                                 a TPM2B_NAME
         arg3                                 a TPM2B
These parameters are used to update policySession→policyDigest by
                 policyDigestnew ≔ HpolicyAlg(policyDigestold || commandCode || arg2.name)                       (10)
followed by
                          policyDigestnew+1 ≔ HpolicyAlg(policyDigestnew || arg3.buffer)                         (11)
where
         HpolicyAlg()                         the hash algorithm chosen when the policy session was started

NOTE 1             If arg3 is a TPM2B_NAME, then arg3.buffer will actually be an arg3.name.

NOTE 2             The arg2.size and arg3.size fields are not included in the hashes.

NOTE 3             PolicyUpdate() uses two hash operations because arg2 and arg3 are variable-sized and the
                   concatenation of arg2 and arg3 in a single hash could produce the same digest even though arg2
                   and arg3 are different. For example, arg2 = 1 2 3 and arg3 = 4 5 6 would produce the same digest
                   as arg2 = 1 2 and arg3 = 3 4 5 6. Processing of the arguments separately in different Extend
                   operation insures that the digest produced by PolicyUpdate() will be different if arg2 and arg3 are
                   different.


Family “2.0”                                      TCG Published                                           Page 233
Level 00 Revision 01.16                   Copyright © TCG 2006-2014                              October 30, 2014
Part 3: Commands                                                               Trusted Platform Module Library


23.2.4 Policy Context Updates

When a policy command modifies some part of the policy session context other than the
policySession→policyDigest, the following rules apply.
        cpHash – this parameter may only be changed if it contains its initialization value (an Empty
         String). If cpHash is not the Empty String when a policy command attempts to update it, the TPM
         will return an error (TPM_RC_CPHASH) if the current and update values are not the same.
        timeOut – this parameter may only be changed to a smaller value. If a command attempts to
         update this value with a larger value (longer into the future), the TPM will discard the update
         value. This is not an error condition.
        commandCode – once set by a policy command, this value may not be changed except by
         TPM2_PolicyRestart(). If a policy command tries to change this to a different value, an error is
         returned (TPM_RC_POLICY_CC).
        pcrUpdateCounter – this parameter is updated by TPM2_PolicyPCR(). This value may only be
         set once during a policy. Each time TPM2_PolicyPCR() executes, it checks to see if
         policySession→pcrUpdateCounter has its default state, indicating that this is the first
         TPM2_PolicyPCR(). If it has its default value, then policySession→pcrUpdateCounter is set to the
         current value of pcrUpdateCounter. If policySession→pcrUpdateCounter does not have its default
         value and its value is not the same as pcrUpdateCounter, the TPM shall return
         TPM_RC_PCR_CHANGED.

   NOTE 1            If this parameter and pcrUpdateCounter are not the same, it indicates that PCR have changed
                     since checked by the previous TPM2_PolicyPCR(). Since they have changed, the previous PCR
                     validation is no longer valid.

        commandLocality – this parameter is the logical AND of all enabled localities. All localities are
         enabled for a policy when the policy session is created. TPM2_PolicyLocalities() selectively
         disables localities. Once use of a policy for a locality has been disabled, it cannot be enabled
         except by TPM2_PolicyRestart().
        isPPRequired – once SET, this parameter may only be CLEARed by TPM2_PolicyRestart().
        isAuthValueNeeded – once SET, this parameter may only be CLEARed by
         TPM2_PolicyPassword() or TPM2_PolicyRestart().
        isPasswordNeeded – once SET, this parameter may only be CLEARed by
         TPM2_PolicyAuthValue() or TPM2_PolicyRestart(),

NOTE 2           Both TPM2_PolicyAuthValue() and TPM2_PolicyPassword() change policySession→policyDigest in
                 the same way. The different commands simply indicate to the TPM the format used for the authValue
                 (HMAC or clear text). Both commands could be in the same policy. The final instance of these
                 commands determines the format.


Page 234                                       TCG Published                                       Family “2.0”
October 30, 2014                       Copyright © TCG 2006-2014                     Level 00 Revision 01.16
Trusted Platform Module Library                                                                Part 3: Commands


23.2.5 Policy Ticket Creation

If, for TPM2_PolicySigned() or TPM2_PolicySecret(), the caller specified a negative value for expiration,
and the nonceTPM matches policySession->nonceTPM, then the TPM will return a ticket that includes a
value indicating when the authorization expires. If expiration is non-negative, then the TPM will return a
NULL ticket.
The required computation for the digest in the authorization ticket is:
        HMAC(proof, HpolicyAlg(ticketType || timeout || cpHashA || policyRef || authObject→Name)) (12)
where
         proof                             secret associated with the storage primary seed (SPS) of the
                                           TPM
         HpolicyAlg                        hash function using the hash algorithm associated with the policy
                                           session
         ticketType                        either TPM_ST_AUTH_SECRET or TPM_ST_AUTH_SIGNED,
                                           used to indicate type of the ticket

         NOTE 1          If the  ticket is produced   by   TPM2_PolicySecret () then   ticketType  is
                         TPM_ST_AUTH_SECRET and if produced by TPM2_PolicySigned() then ticketType is
                         TPM_ST_AUTH_SIGNED.


         timeout                           implementation-specific representation of the expiration time of
                                           the ticket; required to be the implementation equivalent of
                                           policySession→startTime plus the absolute value of expiration

         NOTE 2          timeout is not the same as expiration. The expiration value in the aHash is a relative time,
                         using the creation time of the authorization session (TPM2_StartAuthSession()) as its
                         reference. The timeout parameter is an absolute time, using TPM Clock as the reference.


         cpHashA                           the command parameter digest for the command being
                                           authorized; computed using the hash algorithm of the policy
                                           session
         policyRef                         the commands that use this function have a policyRef parameter
                                           and the value of that parameter is used here
         authObject→Name                   Name associated with the authObject parameter


Family “2.0”                                   TCG Published                                             Page 235
Level 00 Revision 01.16                Copyright © TCG 2006-2014                               October 30, 2014
Part 3: Commands                                                                 Trusted Platform Module Library

23.3    TPM2_PolicySigned

23.3.1 General Description

This command includes a signed authorization in a policy. The command ties the policy to a signing key
by including the Name of the signing key in the policyDigest
If policySession is a trial session, the TPM will not check the signature and will update
policySession→policyDigest as described in 23.2.3 as if a properly signed authorization was received, but
no ticket will be produced.
If policySession is not a trial session, the TPM will validate auth and only perform the update if it is a valid
signature over the fields of the command.
The authorizing entity will sign a digest of the authorization qualifiers: nonceTPM, expiration, cpHashA,
and policyRef. The digest is computed as:
                     aHash ≔ HauthAlg(nonceTPM || expiration || cpHashA || policyRef)                       (13)
where
        HauthAlg()                           the hash associated with the auth parameter of this command

        NOTE 1            Each signature and key combination indicates the scheme and each scheme has an
                          associated hash.


        nonceTPM                             the nonceTPM parameter from the TPM2_StartAuthSession()
                                             response. If the authorization is not limited to this session, the
                                             size of this value is zero.

        NOTE 2            This parameter must be present if expiration is non-zero.


        expiration                           time limit on authorization set by authorizing object. This 32-bit
                                             value is set to zero if the expiration time is not being set.
        cpHashA                              digest of the command parameters for the command being
                                             approved using the hash algorithm of the policy session. Set to
                                             an EmptyAuth if the authorization is not limited to a specific
                                             command.

        NOTE 3            This is not the cpHash of this TPM2_PolicySigned() command.


        policyRef                            an opaque value determined by the authorizing entity. Set to the
                                             Empty Buffer if no value is present.

EXAMPLE          The computation for an aHash if there are no restrictions is:


                                       aHash ≔ HauthAlg(00 00 00 0016)
                 which is the hash of an expiration time of zero.

The aHash is signed by the key associated with a key whose handle is authObject. The signature and
signing parameters are combined to create the auth parameter.
The TPM will perform the parameter checks listed in 23.2.2
If the parameter checks succeed, the TPM will construct a test digest (tHash) over the provided
parameters using the same formulation as shown in equation (13) above.
If tHash does not match the digest of the signed aHash, then the authorization fails and the TPM shall
return TPM_RC_POLICY_FAIL and make no change to policySession→policyDigest.


Page 236                                         TCG Published                                     Family “2.0”
October 30, 2014                        Copyright © TCG 2006-2014                     Level 00 Revision 01.16
Trusted Platform Module Library                                                       Part 3: Commands

When all validations have succeeded, policySession→policyDigest is updated by PolicyUpdate() (see
23.2.3).
                 PolicyUpdate(TPM_CC_PolicySigned, authObject→Name, policyRef)                       (14)
policySession is updated as described in 23.2.4. The TPM will optionally produce a ticket as described in
23.2.5.
Authorization to use authObject is not required.


Family “2.0”                                 TCG Published                                    Page 237
Level 00 Revision 01.16              Copyright © TCG 2006-2014                        October 30, 2014
Part 3: Commands                                                     Trusted Platform Module Library


23.3.2 Command and Response

                      Table 113 — TPM2_PolicySigned Command
Type                   Name                   Description

                                              TPM_ST_SESSIONS if an audit, encrypt, or decrypt
TPMI_ST_COMMAND_TAG    tag                    session is present; otherwise,
                                              TPM_ST_NO_SESSIONS
UINT32                 commandSize
TPM_CC                 commandCode            TPM_CC_PolicySigned

                                              handle for a key that will validate the signature
TPMI_DH_OBJECT         authObject
                                              Auth Index: None
                                              handle for the policy session being extended
TPMI_SH_POLICY         policySession
                                              Auth Index: None

                                              the policy nonce for the session
TPM2B_NONCE            nonceTPM
                                              This can be the Empty Buffer.
                                              digest of the command parameters to which this
                                              authorization is limited
TPM2B_DIGEST           cpHashA                This is not the cpHash for this command but the cpHash
                                              for the command to which this policy session will be
                                              applied. If it is not limited, the parameter will be the
                                              Empty Buffer.
                                              a reference to a policy relating to the authorization –
                                              may be the Empty Buffer
TPM2B_NONCE            policyRef
                                              Size is limited to be no larger than the nonce size
                                              supported on the TPM.
                                              time when authorization will expire, measured in
                                              seconds from the time that nonceTPM was generated
INT32                  expiration
                                              If expiration is non-negative, a NULL Ticket is returned.
                                              See 23.2.5.
TPMT_SIGNATURE         auth                   signed authorization (not optional)


                      Table 114 — TPM2_PolicySigned Response
Type                   Name                   Description

TPM_ST                 tag                    see clause 6
UINT32                 responseSize
TPM_RC                 responseCode

                                              implementation-specific time value, used to indicate to
                                              the TPM when the ticket expires
TPM2B_TIMEOUT          timeout
                                              NOTE        If policyTicket is a NULL Ticket, then this shall be
                                                          the Empty Buffer.

                                              produced if the command succeeds and expiration in
TPMT_TK_AUTH           policyTicket           the command was non-zero; this ticket will use the
                                              TPMT_ST_AUTH_SIGNED structure tag. See 23.2.5


Page 238                               TCG Published                                           Family “2.0”
October 30, 2014              Copyright © TCG 2006-2014                      Level 00 Revision 01.16
     Trusted Platform Module Library                                                                  Part 3: Commands


     23.3.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "Policy_spt_fp.h"
3    #include "PolicySigned_fp.h"
4    #ifdef TPM_CC_PolicySigned // Conditional expansion of this file


     Error Returns                     Meaning

     TPM_RC_CPHASH                     cpHash was previously set to a different value
     TPM_RC_EXPIRED                    expiration indicates a time in the past or expiration is non-zero but no
                                       nonceTPM is present
     TPM_RC_HANDLE                     authObject need to have sensitive portion loaded
     TPM_RC_KEY                        authObject is not a signing scheme
     TPM_RC_NONCE                      nonceTPM is not the nonce associated with the policySession
     TPM_RC_SCHEME                     the signing scheme of auth is not supported by the TPM
     TPM_RC_SIGNATURE                  the signature is not genuine
     TPM_RC_SIZE                       input cpHash has wrong size
     TPM_RC_VALUE                      input policyID or expiration does not match the internal data in policy
                                       session

 5   TPM_RC
 6   TPM2_PolicySigned(
 7       PolicySigned_In       *in,                  // IN: input parameter list
 8       PolicySigned_Out      *out                  // OUT: output parameter list
 9       )
10   {
11       TPM_RC                     result = TPM_RC_SUCCESS;
12       SESSION                   *session;
13       TPM2B_NAME                 entityName;
14       TPM2B_DIGEST               authHash;
15       HASH_STATE                 hashState;
16       UINT32                     expiration = (in->expiration < 0)
17                                               ? -(in->expiration) : in->expiration;
18       UINT64                     authTimeout = 0;
19
20   // Input Validation
21
22       // Set up local pointers
23       session = SessionGet(in->policySession);               // the session structure
24
25       // Only do input validation if this is not a trial policy session
26       if(session->attributes.isTrialPolicy == CLEAR)
27       {
28           if(expiration != 0)
29               authTimeout = expiration * 1000 + session->startTime;
30
31           result = PolicyParameterChecks(session, authTimeout,
32                                           &in->cpHashA, &in->nonceTPM,
33                                           RC_PolicySigned_nonceTPM,
34                                           RC_PolicySigned_cpHashA,
35                                           RC_PolicySigned_expiration);
36           if(result != TPM_RC_SUCCESS)
37               return result;
38
39           // Re-compute the digest being signed
40           /*(See part 3 specification)

     Family “2.0”                                   TCG Published                                                 Page 239
     Level 00 Revision 01.16                Copyright © TCG 2006-2014                                October 30, 2014
      Part 3: Commands                                                Trusted Platform Module Library

 41           // The digest is computed as:
 42           //     aHash := hash ( nonceTPM | expiration | cpHashA | policyRef)
 43           // where:
 44           //      hash()      the hash associated with the signed auth
 45           //      nonceTPM    the nonceTPM value from the TPM2_StartAuthSession .
 46           //                  response If the authorization is not limited to this
 47           //                  session, the size of this value is zero.
 48           //      expiration time limit on authorization set by authorizing object.
 49           //                  This 32-bit value is set to zero if the expiration
 50           //                  time is not being set.
 51           //      cpHashA     hash of the command parameters for the command being
 52           //                  approved using the hash algorithm of the PSAP session.
 53           //                  Set to NULLauth if the authorization is not limited
 54           //                  to a specific command.
 55           //      policyRef   hash of an opaque value determined by the authorizing
 56           //                  object. Set to the NULLdigest if no hash is present.
 57           */
 58           // Start hash
 59           authHash.t.size = CryptStartHash(CryptGetSignHashAlg(&in->auth),
 60                                            &hashState);
 61
 62           // add nonceTPM
 63           CryptUpdateDigest2B(&hashState, &in->nonceTPM.b);
 64
 65           // add expiration
 66           CryptUpdateDigestInt(&hashState, sizeof(UINT32), (BYTE*) &in->expiration);
 67
 68           // add cpHashA
 69           CryptUpdateDigest2B(&hashState, &in->cpHashA.b);
 70
 71           // add policyRef
 72           CryptUpdateDigest2B(&hashState, &in->policyRef.b);
 73
 74           // Complete digest
 75           CryptCompleteHash2B(&hashState, &authHash.b);
 76
 77           // Validate Signature. A TPM_RC_SCHEME, TPM_RC_HANDLE or TPM_RC_SIGNATURE
 78           // error may be returned at this point
 79           result = CryptVerifySignature(in->authObject, &authHash, &in->auth);
 80           if(result != TPM_RC_SUCCESS)
 81               return RcSafeAddToResult(result, RC_PolicySigned_auth);
 82       }
 83   // Internal Data Update
 84       // Need the Name of the signing entity
 85       entityName.t.size = EntityGetName(in->authObject, &entityName.t.name);
 86
 87       // Update policy with input policyRef and name of auth key
 88       // These values are updated even if the session is a trial session
 89       PolicyContextUpdate(TPM_CC_PolicySigned, &entityName, &in->policyRef,
 90                           &in->cpHashA, authTimeout, session);
 91
 92   // Command Output
 93
 94       // Create ticket and timeout buffer if in->expiration < 0 and this is not
 95       // a trial session.
 96       // NOTE: PolicyParameterChecks() makes sure that nonceTPM is present
 97       // when expiration is non-zero.
 98       if(   in->expiration < 0
 99          && session->attributes.isTrialPolicy == CLEAR
100         )
101       {
102           // Generate timeout buffer. The format of output timeout buffer is
103           // TPM-specific.
104           // Note: can't do a direct copy because the output buffer is a byte
105           // array and it may not be aligned to accept a 64-bit value. The method
106           // used has the side-effect of making the returned value a big-endian,

      Page 240                               TCG Published                              Family “2.0”
      October 30, 2014                Copyright © TCG 2006-2014             Level 00 Revision 01.16
      Trusted Platform Module Library                                             Part 3: Commands

107           // 64-bit value that is byte aligned.
108           out->timeout.t.size = sizeof(UINT64);
109           UINT64_TO_BYTE_ARRAY(authTimeout, out->timeout.t.buffer);
110
111           // Compute policy ticket
112           TicketComputeAuth(TPM_ST_AUTH_SIGNED, EntityGetHierarchy(in->authObject),
113                             authTimeout, &in->cpHashA, &in->policyRef, &entityName,
114                             &out->policyTicket);
115       }
116       else
117       {
118           // Generate a null ticket.
119           // timeout buffer is null
120           out->timeout.t.size = 0;
121
122           // auth ticket is null
123           out->policyTicket.tag = TPM_ST_AUTH_SIGNED;
124           out->policyTicket.hierarchy = TPM_RH_NULL;
125           out->policyTicket.digest.t.size = 0;
126       }
127
128       return TPM_RC_SUCCESS;
129   }
130   #endif // CC_PolicySigned


      Family “2.0”                           TCG Published                                Page 241
      Level 00 Revision 01.16           Copyright © TCG 2006-2014                 October 30, 2014
Part 3: Commands                                                                 Trusted Platform Module Library


23.4     TPM2_PolicySecret

23.4.1 General Description

This command includes a secret-based authorization to a policy. The caller proves knowledge of the
secret value using an authorization session using the authValue associated with authHandle. A password
session, an HMAC session, or a policy session containing TPM2_PolicyAuthValue() or
TPM2_PolicyPassword() will satisfy this requirement.
If a policy session is used and use of the authValue of authHandle is not required, the TPM will return
TPM_RC_MODE.
The secret is the authValue of the entity whose handle is authHandle, which may be any TPM entity with
a handle and an associated authValue. This includes the reserved handles (for example, Platform,
Storage, and Endorsement), NV Indexes, and loaded objects.

NOTE 1           The authorization value for a hierarchy cannot be used in this command if the hierarchy is disabled.

If the authorization check fails, then the normal dictionary attack logic is invoked.
If the authorization provided by the authorization session is valid, the command parameters are checked
as described in 23.2.2.
nonceTPM must be present if expiration is non-zero.
When all validations have succeeded, policySession→policyDigest is updated by PolicyUpdate() (see
23.2.3).
                  PolicyUpdate(TPM_CC_PolicySecret, authObject→Name, policyRef)                                   (15)
policySession is updated as described in 23.2.4. The TPM will optionally produce a ticket as described in
23.2.5.
If the session is a trial session, policySession→policyDigest is updated as if the authorization is valid but
no check is performed.

NOTE 2           If an HMAC is used to convey the authorization, a separate session is needed for the authorization.
                 Because the HMAC in that authorization will include a nonce that prevents replay of the
                 authorization, the value of the nonceTPM parameter in this command is limited. It is retained mostly
                 to provide processing consistency with TPM2_PolicySigned().


Page 242                                        TCG Published                                          Family “2.0”
October 30, 2014                        Copyright © TCG 2006-2014                       Level 00 Revision 01.16
Trusted Platform Module Library                                                            Part 3: Commands


23.4.2 Command and Response

                            Table 115 — TPM2_PolicySecret Command
Type                          Name                   Description

TPMI_ST_COMMAND_TAG           tag                    TPM_ST_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode            TPM_CC_PolicySecret

                                                     handle for an entity providing the authorization
TPMI_DH_ENTITY                @authHandle            Auth Index: 1
                                                     Auth Role: USER
                                                     handle for the policy session being extended
TPMI_SH_POLICY                policySession
                                                     Auth Index: None

                                                     the policy nonce for the session
TPM2B_NONCE                   nonceTPM
                                                     This can be the Empty Buffer.
                                                     digest of the command parameters to which this
                                                     authorization is limited
TPM2B_DIGEST                  cpHashA                This not the cpHash for this command but the cpHash
                                                     for the command to which this policy session will be
                                                     applied. If it is not limited, the parameter will be the
                                                     Empty Buffer.
                                                     a reference to a policy relating to the authorization –
                                                     may be the Empty Buffer
TPM2B_NONCE                   policyRef
                                                     Size is limited to be no larger than the nonce size
                                                     supported on the TPM.
                                                     time when authorization will expire, measured in
                                                     seconds from the time that nonceTPM was generated
INT32                         expiration
                                                     If expiration is non-negative, a NULL Ticket is returned.
                                                     See 23.2.5.


                            Table 116 — TPM2_PolicySecret Response
Type                          Name                   Description

TPM_ST                        tag                    see clause 6
UINT32                        responseSize
TPM_RC                        responseCode

                                                     implementation-specific time value used to indicate to
TPM2B_TIMEOUT                 timeout                the TPM when the ticket expires; this ticket will use the
                                                     TPMT_ST_AUTH_SECRET structure tag
                                                     produced if the command succeeds and expiration in
TPMT_TK_AUTH                  policyTicket
                                                     the command was non-zero. See 23.2.5


Family “2.0”                                  TCG Published                                          Page 243
Level 00 Revision 01.16             Copyright © TCG 2006-2014                              October 30, 2014
     Part 3: Commands                                                             Trusted Platform Module Library


     23.4.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "PolicySecret_fp.h"
3    #ifdef TPM_CC_PolicySecret // Conditional expansion of this file
4    #include "Policy_spt_fp.h"


     Error Returns                 Meaning

     TPM_RC_CPHASH                 cpHash for policy was previously set to a value that is not the same
                                   as cpHashA
     TPM_RC_EXPIRED                expiration indicates a time in the past
     TPM_RC_NONCE                  nonceTPM does not match the nonce associated with policySession
     TPM_RC_SIZE                   cpHashA is not the size of a digest for the hash associated with
                                   policySession
     TPM_RC_VALUE                  input policyID or expiration does not match the internal data in policy
                                   session

 5   TPM_RC
 6   TPM2_PolicySecret(
 7       PolicySecret_In    *in,                 // IN: input parameter list
 8       PolicySecret_Out   *out                 // OUT: output parameter list
 9       )
10   {
11       TPM_RC                  result;
12       SESSION                *session;
13       TPM2B_NAME              entityName;
14       UINT32                  expiration = (in->expiration < 0)
15                                            ? -(in->expiration) : in->expiration;
16       UINT64                  authTimeout = 0;
17
18   // Input Validation
19
20       // Get pointer to the session structure
21       session = SessionGet(in->policySession);
22
23       //Only do input validation if this is not a trial policy session
24       if(session->attributes.isTrialPolicy == CLEAR)
25       {
26
27           if(expiration != 0)
28               authTimeout = expiration * 1000 + session->startTime;
29
30           result = PolicyParameterChecks(session, authTimeout,
31                                           &in->cpHashA, &in->nonceTPM,
32                                           RC_PolicySecret_nonceTPM,
33                                           RC_PolicySecret_cpHashA,
34                                           RC_PolicySecret_expiration);
35           if(result != TPM_RC_SUCCESS)
36               return result;
37       }
38
39   // Internal Data Update
40       // Need the name of the authorizing entity
41       entityName.t.size = EntityGetName(in->authHandle, &entityName.t.name);
42
43       // Update policy context with input policyRef and name of auth key
44       // This value is computed even for trial sessions. Possibly update the cpHash
45       PolicyContextUpdate(TPM_CC_PolicySecret, &entityName, &in->policyRef,
46                           &in->cpHashA, authTimeout, session);

     Page 244                                   TCG Published                                           Family “2.0”
     October 30, 2014                   Copyright © TCG 2006-2014                        Level 00 Revision 01.16
     Trusted Platform Module Library                                             Part 3: Commands

47
48   // Command Output
49
50       // Create ticket and timeout buffer if in->expiration < 0 and this is not
51       // a trial session.
52       // NOTE: PolicyParameterChecks() makes sure that nonceTPM is present
53       // when expiration is non-zero.
54       if(   in->expiration < 0
55          && session->attributes.isTrialPolicy == CLEAR
56         )
57       {
58           // Generate timeout buffer. The format of output timeout buffer is
59           // TPM-specific.
60           // Note: can't do a direct copy because the output buffer is a byte
61           // array and it may not be aligned to accept a 64-bit value. The method
62           // used has the side-effect of making the returned value a big-endian,
63           // 64-bit value that is byte aligned.
64           out->timeout.t.size = sizeof(UINT64);
65           UINT64_TO_BYTE_ARRAY(authTimeout, out->timeout.t.buffer);
66
67           // Compute policy ticket
68           TicketComputeAuth(TPM_ST_AUTH_SECRET, EntityGetHierarchy(in->authHandle),
69                             authTimeout, &in->cpHashA, &in->policyRef,
70                             &entityName, &out->policyTicket);
71       }
72       else
73       {
74           // timeout buffer is null
75           out->timeout.t.size = 0;
76
77           // auth ticket is null
78           out->policyTicket.tag = TPM_ST_AUTH_SECRET;
79           out->policyTicket.hierarchy = TPM_RH_NULL;
80           out->policyTicket.digest.t.size = 0;
81       }
82
83       return TPM_RC_SUCCESS;
84   }
85   #endif // CC_PolicySecret


     Family “2.0”                           TCG Published                                Page 245
     Level 00 Revision 01.16           Copyright © TCG 2006-2014                 October 30, 2014
Part 3: Commands                                                         Trusted Platform Module Library


23.5   TPM2_PolicyTicket

23.5.1 General Description

This command is similar to TPM2_PolicySigned() except that it takes a ticket instead of a signed
authorization. The ticket represents a validated authorization that had an expiration time associated with
it.
The parameters of this command are checked as described in 23.2.2.
If the checks succeed, the TPM uses the timeout, cpHashA, policyRef, and authName to construct a
ticket to compare with the value in ticket. If these tickets match, then the TPM will create a TPM2B_NAME
(objectName) using authName and update the context of policySession by PolicyUpdate() (see 23.2.3).
                         PolicyUpdate(commandCode, authName, policyRef)                               (16)
If the structure tag of ticket is TPM_ST_AUTH_SECRET, then commandCode will be
TPM_CC_PolicySecret. If the structure tag of ticket is TPM_ST_AUTH_SIGNED, then commandCode will
be TPM_CC_PolicySIgned.
policySession is updated as described in 23.2.4.


Page 246                                    TCG Published                                    Family “2.0”
October 30, 2014                    Copyright © TCG 2006-2014                  Level 00 Revision 01.16
Trusted Platform Module Library                                                            Part 3: Commands


23.5.2 Command and Response

                            Table 117 — TPM2_PolicyTicket Command
Type                          Name                   Description

                                                     TPM_ST_SESSIONS if an audit or decrypt session is
TPMI_ST_COMMAND_TAG           tag
                                                     present; otherwise, TPM_ST_NO_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode            TPM_CC_PolicyTicket

                                                     handle for the policy session being extended
TPMI_SH_POLICY                policySession
                                                     Auth Index: None

                                                     time when authorization will expire
TPM2B_TIMEOUT                 timeout                The contents are TPM specific. This shall be the value
                                                     returned when ticket was produced.
                                                     digest of the command parameters to which this
                                                     authorization is limited
TPM2B_DIGEST                  cpHashA
                                                     If it is not limited, the parameter will be the Empty
                                                     Buffer.
                                                     reference to a qualifier for the policy – may be the
TPM2B_NONCE                   policyRef
                                                     Empty Buffer
TPM2B_NAME                    authName               name of the object that provided the authorization
                                                     an authorization ticket returned by the TPM in response
TPMT_TK_AUTH                  ticket
                                                     to a TPM2_PolicySigned() or TPM2_PolicySecret()


                            Table 118 — TPM2_PolicyTicket Response
Type                          Name                   Description

TPM_ST                        tag                    see clause 6
UINT32                        responseSize
TPM_RC                        responseCode


Family “2.0”                                  TCG Published                                           Page 247
Level 00 Revision 01.16                Copyright © TCG 2006-2014                           October 30, 2014
     Part 3: Commands                                                             Trusted Platform Module Library


     23.5.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "PolicyTicket_fp.h"
3    #ifdef TPM_CC_PolicyTicket // Conditional expansion of this file
4    #include "Policy_spt_fp.h"


     Error Returns                Meaning

     TPM_RC_CPHASH                policy's cpHash was previously set to a different value
     TPM_RC_EXPIRED               timeout value in the ticket is in the past and the ticket has expired
     TPM_RC_SIZE                  timeout or cpHash has invalid size for the
     TPM_RC_TICKET                ticket is not valid

 5   TPM_RC
 6   TPM2_PolicyTicket(
 7       PolicyTicket_In    *in                   // IN: input parameter list
 8       )
 9   {
10       TPM_RC                    result;
11       SESSION                  *session;
12       UINT64                    timeout;
13       TPMT_TK_AUTH              ticketToCompare;
14       TPM_CC                    commandCode = TPM_CC_PolicySecret;
15
16   // Input Validation
17
18       // Get pointer to the session structure
19       session = SessionGet(in->policySession);
20
21       // NOTE: A trial policy session is not allowed to use this command.
22       // A ticket is used in place of a previously given authorization. Since
23       // a trial policy doesn't actually authenticate, the validated
24       // ticket is not necessary and, in place of using a ticket, one
25       // should use the intended authorization for which the ticket
26       // would be a substitute.
27       if(session->attributes.isTrialPolicy)
28           return TPM_RCS_ATTRIBUTES + RC_PolicyTicket_policySession;
29
30       // Restore timeout data. The format of timeout buffer is TPM-specific.
31       // In this implementation, we simply copy the value of timeout to the
32       // buffer.
33       if(in->timeout.t.size != sizeof(UINT64))
34           return TPM_RC_SIZE + RC_PolicyTicket_timeout;
35       timeout = BYTE_ARRAY_TO_UINT64(in->timeout.t.buffer);
36
37       // Do the normal checks on the cpHashA and timeout values
38       result = PolicyParameterChecks(session, timeout,
39                                      &in->cpHashA, NULL,
40                                      0,                       // no bad nonce return
41                                      RC_PolicyTicket_cpHashA,
42                                      RC_PolicyTicket_timeout);
43       if(result != TPM_RC_SUCCESS)
44           return result;
45
46       // Validate Ticket
47       // Re-generate policy ticket by input parameters
48       TicketComputeAuth(in->ticket.tag, in->ticket.hierarchy, timeout, &in->cpHashA,
49                         &in->policyRef, &in->authName, &ticketToCompare);
50
51       // Compare generated digest with input ticket digest

     Page 248                                   TCG Published                                             Family “2.0”
     October 30, 2014                  Copyright © TCG 2006-2014                         Level 00 Revision 01.16
     Trusted Platform Module Library                                            Part 3: Commands

52       if(!Memory2BEqual(&in->ticket.digest.b, &ticketToCompare.digest.b))
53           return TPM_RC_TICKET + RC_PolicyTicket_ticket;
54
55   // Internal Data Update
56
57       // Is this ticket to take the place of a TPM2_PolicySigned() or
58       // a TPM2_PolicySecret()?
59       if(in->ticket.tag == TPM_ST_AUTH_SIGNED)
60           commandCode = TPM_CC_PolicySigned;
61       else if(in->ticket.tag == TPM_ST_AUTH_SECRET)
62           commandCode = TPM_CC_PolicySecret;
63       else
64           // There could only be two possible tag values. Any other value should
65           // be caught by the ticket validation process.
66           pAssert(FALSE);
67
68       // Update policy context
69       PolicyContextUpdate(commandCode, &in->authName, &in->policyRef,
70                           &in->cpHashA, timeout, session);
71
72       return TPM_RC_SUCCESS;
73   }
74   #endif // CC_PolicyTicket


     Family “2.0”                           TCG Published                              Page 249
     Level 00 Revision 01.16           Copyright © TCG 2006-2014                October 30, 2014
Part 3: Commands                                                                  Trusted Platform Module Library


23.6     TPM2_PolicyOR

23.6.1 General Description

This command allows options in authorizations without requiring that the TPM evaluate all of the options.
If a policy may be satisfied by different sets of conditions, the TPM need only evaluate one set that
satisfies the policy. This command will indicate that one of the required sets of conditions has been
satisfied.
PolicySession→policyDigest is compared against the list of provided values. If the current
policySession→policyDigest does not match any value in the list, the TPM shall return TPM_RC_VALUE.
Otherwise, it will replace policySession→policyDigest with the digest of the concatenation of all of the
digests and return TPM_RC_SUCCESS.
If policySession is a trial session, the TPM will assume that policySession→policyDigest matches one of
the list entries and compute the new value of policyDigest.
The algorithm for computing the new value for policyDigest of policySession is:
a) Concatenate all the digest values in pHashList:
                digests ≔ pHashList.digests[1].buffer || … || pHashList.digests[n].buffer                         (17)

    NOTE 1           The TPM will not return an error if the size of an entry is not the same as the size of the digest
                     of the policy. However, that entry cannot match policyDigest.

b) Reset policyDigest to a Zero Digest.
c) Extend the command code and the hashes computed in step a) above:
               policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyOR || digests)                        (18)

    NOTE 2           The computation in b) and c) above is equivalent to:
                          policyDigestnew ≔ HpolicyAlg(0…0 || TPM_CC_PolicyOR || digests)

A TPM shall support a list with at least eight tagged digest values.

NOTE 3          If policies are to be portable between TPMs, then they should not use more than eight values.


Page 250                                        TCG Published                                           Family “2.0”
October 30, 2014                       Copyright © TCG 2006-2014                         Level 00 Revision 01.16
Trusted Platform Module Library                                                           Part 3: Commands


23.6.2 Command and Response

                              Table 119 — TPM2_PolicyOR Command
Type                          Name                   Description

                                                     TPM_ST_SESSIONS if an audit session is present;
TPMI_ST_COMMAND_TAG           tag
                                                     otherwise, TPM_ST_NO_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode            TPM_CC_PolicyOR.

                                                     handle for the policy session being extended
TPMI_SH_POLICY                policySession
                                                     Auth Index: None

TPML_DIGEST                   pHashList              the list of hashes to check for a match


                              Table 120 — TPM2_PolicyOR Response
Type                          Name                   Description

TPM_ST                        tag                    see clause 6
UINT32                        responseSize
TPM_RC                        responseCode


Family “2.0”                                  TCG Published                                         Page 251
Level 00 Revision 01.16             Copyright © TCG 2006-2014                             October 30, 2014
     Part 3: Commands                                                           Trusted Platform Module Library


     23.6.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "PolicyOR_fp.h"
3    #ifdef TPM_CC_PolicyOR // Conditional expansion of this file
4    #include "Policy_spt_fp.h"


     Error Returns                 Meaning

     TPM_RC_VALUE                  no digest in pHashList matched the current value of policyDigest for
                                   policySession

 5   TPM_RC
 6   TPM2_PolicyOR(
 7       PolicyOR_In      *in               // IN: input parameter list
 8       )
 9   {
10       SESSION       *session;
11       UINT32         i;
12
13   // Input Validation and Update
14
15       // Get pointer to the session structure
16       session = SessionGet(in->policySession);
17
18       // Compare and Update Internal Session policy if match
19       for(i = 0; i < in->pHashList.count; i++)
20       {
21           if(   session->attributes.isTrialPolicy == SET
22              || (Memory2BEqual(&session->u2.policyDigest.b,
23                                &in->pHashList.digests[i].b))
24             )
25           {
26               // Found a match
27               HASH_STATE      hashState;
28               TPM_CC          commandCode = TPM_CC_PolicyOR;
29
30                 // Start hash
31                 session->u2.policyDigest.t.size = CryptStartHash(session->authHashAlg,
32                                                                &hashState);
33                 // Set policyDigest to 0 string and add it to hash
34                 MemorySet(session->u2.policyDigest.t.buffer, 0,
35                           session->u2.policyDigest.t.size);
36                 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b);
37
38                 // add command code
39                 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode);
40
41                 // Add each of the hashes in the list
42                 for(i = 0; i < in->pHashList.count; i++)
43                 {
44                     // Extend policyDigest
45                     CryptUpdateDigest2B(&hashState, &in->pHashList.digests[i].b);
46                 }
47                 // Complete digest
48                 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b);
49
50                 return TPM_RC_SUCCESS;
51           }
52       }
53       // None of the values in the list matched the current policyDigest
54       return TPM_RC_VALUE + RC_PolicyOR_pHashList;
55   }

     Page 252                                   TCG Published                                         Family “2.0”
     October 30, 2014                  Copyright © TCG 2006-2014                       Level 00 Revision 01.16
     Trusted Platform Module Library                               Part 3: Commands

56   #endif // CC_PolicyOR


     Family “2.0”                           TCG Published                 Page 253
     Level 00 Revision 01.16           Copyright © TCG 2006-2014   October 30, 2014
Part 3: Commands                                                                   Trusted Platform Module Library


23.7     TPM2_PolicyPCR

23.7.1 General Description

This command is used to cause conditional gating of a policy based on PCR. This command together
with TPM2_PolicyOR() allows one group of authorizations to occur when PCR are in one state and a
different set of authorizations when the PCR are in a different state. If this command is used for a trial
policySession, policySession→policyDigest will be updated using the values from the command rather
than the values from digest of the TPM PCR.
The TPM will modify the pcrs parameter so that bits that correspond to unimplemented PCR are CLEAR.
If policySession is not a trial policy session, the TPM will use the modified value of pcrs to select PCR
values to hash according to TPM 2.0 Part 1, Selecting Multiple PCR. The hash algorithm of the policy
session is used to compute a digest (digestTPM) of the selected PCR. If pcrDigest does not have a length
of zero, then it is compared to digestTPM; and if the values do not match, the TPM shall return
TPM_RC_VALUE and make no change to policySession→policyDigest. If the values match, or if the
length of pcrDigest is zero, then policySession→policyDigest is extended by:
          policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyPCR || pcrs || digestTPM)                    (19)
where
         pcrs                                the pcrs parameter with bits corresponding to unimplemented
                                             PCR set to 0
         digestTPM                           the digest of the selected PCR using the hash algorithm of the
                                             policy session

NOTE 1            If the caller provides the expected PCR value, the intention is that the policy evaluation stop at that
                 point if the PCR do not match. If the caller does not provide the expected PCR value, then the
                 validity of the settings will not be determined until an attempt is made to use the policy for
                 authorization. If the policy is constructed such that the PCR check comes before user authorization
                 checks, this early termination would allow software to avoid unnecessary prompts for user input to
                 satisfy a policy that would fail later due to incorrect PCR values.

After this command completes successfully, the TPM shall return TPM_RC_PCR_CHANGED if the policy
session is used for authorization and the PCR are not known to be correct.
The TPM uses a “generation” number (pcrUpdateCounter) that is incremented each time PCR are
updated (unless the PCR being changed is specified not to cause a change to this counter). The value of
this counter is stored in the policy session context (policySession→pcrUpdateCounter) when this
command is executed. When the policy is used for authorization, the current value of the counter is
compared to the value in the policy session context and the authorization will fail if the values are not the
same.
When this command is executed, policySession→pcrUpdateCounter is checked to see if it has been
previously set (in the reference implementation, it has a value of zero if not previously set). If it has been
set, it will be compared with the current value of pcrUpdateCounter to determine if any PCR changes
have occurred. If the values are different, the TPM shall return TPM_RC_PCR_CHANGED.

NOTE 2           Since the pcrUpdateCounter is updated if any PCR is extended (except those specified not to do
                 so), this means that the command will fail even if a PCR not specified in the policy is updated. This
                 is an optimization for the purposes of conserving internal TPM memory. This would be a rare
                 occurrence. and, if this should occur, the policy could be reset using the TPM2_PolicyRestart
                 command and rerun.

If policySession→pcrUpdateCounter has not been set, then it is set to the current value of
pcrUpdateCounter.


Page 254                                         TCG Published                                            Family “2.0”
October 30, 2014                        Copyright © TCG 2006-2014                         Level 00 Revision 01.16
Trusted Platform Module Library                                                              Part 3: Commands

If policySession is a trial policy session, the TPM will not check any PCR and will compute:
         policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyPCR || pcrs || pcrDigest)              (20)
In this computation, pcrs is the input parameter without modification.

NOTE 3          The pcrs parameter is expected to match the configuration of the TPM for which the policy is being
                computed which may not be the same as the TPM on which the trial policy is being computed.

NOTE 4          Although no PCR are checked in a trial policy session, pcrDigest is expected to correspond to some
                useful PCR values. It is legal, but pointless, to have the TP M aid in calculating a policyDigest
                corresponding to PCR values that are not useful in practice.


Family “2.0”                                  TCG Published                                           Page 255
Level 00 Revision 01.16               Copyright © TCG 2006-2014                              October 30, 2014
Part 3: Commands                                                   Trusted Platform Module Library


23.7.2 Command and Response

                      Table 121 — TPM2_PolicyPCR Command
Type                   Name                   Description

                                              TPM_ST_SESSIONS if an audit or decrypt session is
TPMI_ST_COMMAND_TAG    tag
                                              present; otherwise, TPM_ST_NO_SESSIONS
UINT32                 commandSize
TPM_CC                 commandCode            TPM_CC_PolicyPCR

                                              handle for the policy session being extended
TPMI_SH_POLICY         policySession
                                              Auth Index: None

                                              expected digest value of the selected PCR using the
TPM2B_DIGEST           pcrDigest
                                              hash algorithm of the session; may be zero length
TPML_PCR_SELECTION     pcrs                   the PCR to include in the check digest


                      Table 122 — TPM2_PolicyPCR Response
Type                   Name                   Description

TPM_ST                 tag                    see clause 6
UINT32                 responseSize
TPM_RC                 responseCode


Page 256                               TCG Published                                    Family “2.0”
October 30, 2014              Copyright © TCG 2006-2014                  Level 00 Revision 01.16
     Trusted Platform Module Library                                                              Part 3: Commands


     23.7.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "PolicyPCR_fp.h"
3    #ifdef TPM_CC_PolicyPCR // Conditional expansion of this file


     Error Returns                     Meaning

     TPM_RC_VALUE                      if provided, pcrDigest does not match the current PCR settings
     TPM_RC_PCR_CHANGED                a previous TPM2_PolicyPCR() set pcrCounter and it has changed

 4   TPM_RC
 5   TPM2_PolicyPCR(
 6       PolicyPCR_In      *in                 // IN: input parameter list
 7       )
 8   {
 9       SESSION           *session;
10       TPM2B_DIGEST       pcrDigest;
11       BYTE               pcrs[sizeof(TPML_PCR_SELECTION)];
12       UINT32             pcrSize;
13       BYTE              *buffer;
14       TPM_CC             commandCode = TPM_CC_PolicyPCR;
15       HASH_STATE         hashState;
16
17   // Input Validation
18
19       // Get pointer to the session structure
20       session = SessionGet(in->policySession);
21
22       // Do validation for non trial session
23       if(session->attributes.isTrialPolicy == CLEAR)
24       {
25           // Make sure that this is not going to invalidate a previous PCR check
26           if(session->pcrCounter != 0 && session->pcrCounter != gr.pcrCounter)
27               return TPM_RC_PCR_CHANGED;
28
29           // Compute current PCR digest
30           PCRComputeCurrentDigest(session->authHashAlg, &in->pcrs, &pcrDigest);
31
32           // If the caller specified the PCR digest and it does not
33           // match the current PCR settings, return an error..
34           if(in->pcrDigest.t.size != 0)
35           {
36               if(!Memory2BEqual(&in->pcrDigest.b, &pcrDigest.b))
37                   return TPM_RC_VALUE + RC_PolicyPCR_pcrDigest;
38           }
39       }
40       else
41       {
42           // For trial session, just use the input PCR digest
43           pcrDigest = in->pcrDigest;
44       }
45   // Internal Data Update
46
47       // Update policy hash
48       // policyDigestnew = hash(   policyDigestold || TPM_CC_PolicyPCR
49       //                      || pcrs || pcrDigest)
50       // Start hash
51       CryptStartHash(session->authHashAlg, &hashState);
52
53       // add old digest
54       CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b);

     Family “2.0”                                  TCG Published                                         Page 257
     Level 00 Revision 01.16               Copyright © TCG 2006-2014                              October 30, 2014
     Part 3: Commands                                               Trusted Platform Module Library

55
56      // add commandCode
57      CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode);
58
59      // add PCRS
60      buffer = pcrs;
61      pcrSize = TPML_PCR_SELECTION_Marshal(&in->pcrs, &buffer, NULL);
62      CryptUpdateDigest(&hashState, pcrSize, pcrs);
63
64      // add PCR digest
65      CryptUpdateDigest2B(&hashState, &pcrDigest.b);
66
67      // complete the hash and get the results
68      CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b);
69
70      // update pcrCounter in session context for non trial session
71      if(session->attributes.isTrialPolicy == CLEAR)
72      {
73          session->pcrCounter = gr.pcrCounter;
74      }
75
76       return TPM_RC_SUCCESS;
77   }
78   #endif // CC_PolicyPCR


     Page 258                              TCG Published                              Family “2.0”
     October 30, 2014               Copyright © TCG 2006-2014             Level 00 Revision 01.16
Trusted Platform Module Library                                                           Part 3: Commands


23.8   TPM2_PolicyLocality

23.8.1 General Description

This command indicates that the authorization will be limited to a specific locality.
policySession→commandLocality is a parameter kept in the session context. When the policy session is
started, this parameter is initialized to a value that allows the policy to apply to any locality.
If locality has a value greater than 31, then an extended locality is indicated. For an extended locality, the
TPM will validate that policySession→commandLocality has not previously been set or that the current
value of policySession→commandLocality is the same as locality (TPM_RC_RANGE).
When locality is not an extended locality, the TPM will validate that the policySession→commandLocality
is not set to an extended locality value (TPM_RC_RANGE). If not the TPM will disable any locality not
SET in the locality parameter. If the result of disabling localities results in no locality being enabled, the
TPM will return TPM_RC_RANGE.
If no error occurred in the validation of locality, policySession→policyDigest is extended with
             policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyLocality || locality)          (21)
Then policySession→commandLocality is updated to indicate which localities are still allowed after
execution of TPM2_PolicyLocality().
When the policy session is used to authorize a command, the authorization will fail if the locality used for
the command is not one of the enabled localities in policySession→commandLocality.


Family “2.0”                                  TCG Published                                        Page 259
Level 00 Revision 01.16               Copyright © TCG 2006-2014                           October 30, 2014
Part 3: Commands                                                      Trusted Platform Module Library


23.8.2 Command and Response

                      Table 123 — TPM2_PolicyLocality Command
Type                    Name                   Description

                                               TPM_ST_SESSIONS if an audit session is present;
TPMI_ST_COMMAND_TAG     tag
                                               otherwise, TPM_ST_NO_SESSIONS
UINT32                  commandSize
TPM_CC                  commandCode            TPM_CC_PolicyLocality

                                               handle for the policy session being extended
TPMI_SH_POLICY          policySession
                                               Auth Index: None

TPMA_LOCALITY           locality               the allowed localities for the policy


                      Table 124 — TPM2_PolicyLocality Response
Type                    Name                   Description

TPM_ST                  tag                    see clause 6
UINT32                  responseSize
TPM_RC                  responseCode


Page 260                                TCG Published                                    Family “2.0”
October 30, 2014              Copyright © TCG 2006-2014                      Level 00 Revision 01.16
     Trusted Platform Module Library                                                                   Part 3: Commands


     23.8.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "PolicyLocality_fp.h"
3    #ifdef TPM_CC_PolicyLocality // Conditional expansion of this file

     Limit a policy to a specific locality

     Error Returns                       Meaning

     TPM_RC_RANGE                        all the locality values selected by locality have been disabled by
                                         previous TPM2_PolicyLocality() calls.

 4   TPM_RC
 5   TPM2_PolicyLocality(
 6        PolicyLocality_In        *in                 // IN: input parameter list
 7        )
 8   {
 9        SESSION        *session;
10        BYTE            marshalBuffer[sizeof(TPMA_LOCALITY)];
11        BYTE            prevSetting[sizeof(TPMA_LOCALITY)];
12        UINT32          marshalSize;
13        BYTE           *buffer;
14        TPM_CC          commandCode = TPM_CC_PolicyLocality;
15        HASH_STATE      hashState;
16
17   // Input Validation
18
19        // Get pointer to the session structure
20        session = SessionGet(in->policySession);
21
22        // Get new locality setting in canonical form
23        buffer = marshalBuffer;
24        marshalSize = TPMA_LOCALITY_Marshal(&in->locality, &buffer, NULL);
25
26        // Its an error if the locality parameter is zero
27        if(marshalBuffer[0] == 0)
28            return TPM_RC_RANGE + RC_PolicyLocality_locality;
29
30        // Get existing locality setting in canonical form
31        buffer = prevSetting;
32        TPMA_LOCALITY_Marshal(&session->commandLocality, &buffer, NULL);
33
34        // If the locality has previously been set
35        if(    prevSetting[0] != 0
36            // then the current locality setting and the requested have to be the same
37            // type (that is, either both normal or both extended
38            && ((prevSetting[0] < 32) != (marshalBuffer[0] < 32)))
39            return TPM_RC_RANGE + RC_PolicyLocality_locality;
40
41        // See if the input is a regular or extended locality
42        if(marshalBuffer[0] < 32)
43        {
44            // if there was no previous setting, start with all normal localities
45            // enabled
46            if(prevSetting[0] == 0)
47                prevSetting[0] = 0x1F;
48
49             // AND the new setting with the previous setting and store it in prevSetting
50             prevSetting[0] &= marshalBuffer[0];
51
52             // The result setting can not be 0
53             if(prevSetting[0] == 0)

     Family “2.0”                                     TCG Published                                           Page 261
     Level 00 Revision 01.16                 Copyright © TCG 2006-2014                                 October 30, 2014
     Part 3: Commands                                                Trusted Platform Module Library

54              return TPM_RC_RANGE + RC_PolicyLocality_locality;
55      }
56      else
57      {
58          // for extended locality
59          // if the locality has already been set, then it must match the
60          if(prevSetting[0] != 0 && prevSetting[0] != marshalBuffer[0])
61              return TPM_RC_RANGE + RC_PolicyLocality_locality;
62
63          // Setting is OK
64          prevSetting[0] = marshalBuffer[0];
65
66      }
67
68   // Internal Data Update
69
70      // Update policy hash
71      // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyLocality || locality)
72      // Start hash
73      CryptStartHash(session->authHashAlg, &hashState);
74
75      // add old digest
76      CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b);
77
78      // add commandCode
79      CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode);
80
81      // add input locality
82      CryptUpdateDigest(&hashState, marshalSize, marshalBuffer);
83
84      // complete the digest
85      CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b);
86
87      // update session locality by unmarshal function. The function must succeed
88      // because both input and existing locality setting have been validated.
89      buffer = prevSetting;
90      TPMA_LOCALITY_Unmarshal(&session->commandLocality, &buffer,
91                              (INT32 *) &marshalSize);
92
93       return TPM_RC_SUCCESS;
94   }
95   #endif // CC_PolicyLocality


     Page 262                              TCG Published                               Family “2.0”
     October 30, 2014               Copyright © TCG 2006-2014             Level 00 Revision 01.16
Trusted Platform Module Library                                                            Part 3: Commands


23.9    TPM2_PolicyNV

23.9.1 General Description

This command is used to cause conditional gating of a policy based on the contents of an NV Index.
If policySession is a trial policy session, the TPM will update policySession→policyDigest as shown in
equations (22) and (23) below and return TPM_RC_SUCCESS. It will not perform any validation. The
remainder of this general description would apply only if policySession is not a trial policy session.
An authorization session providing authorization to read the NV Index shall be provided.

NOTE               If read access is controlled by policy, the policy should include a branch that authorizes a
                   TPM2_PolicyNV().

If TPMA_NV_WRITTEN is not SET in the NV Index, the TPM shall return TPM_RC_NV_UNINITIALIZED.
The TPM will validate that the size of operandB plus offset is not greater than the size of the NV Index. If
it is, the TPM shall return TPM_RC_SIZE.
operandA begins at offest into the NV index contents and has a size equal to the size of operandB. The
TPM will perform the indicated arithmetic check using operandA and operandB. . If the check fails, the
TPM shall return TPM_RC_POLICY and not change policySession→policyDigest. If the check succeeds,
the TPM will hash the arguments:
                           args ≔ HpolicyAlg(operandB.buffer || offset || operation)                       (22)
where
         HpolicyAlg()                       hash function using the algorithm of the policy session
         operandB                           the value used for the comparison
         offset                             offset from the start of the NV Index data to start the comparison
         operation                          the operation parameter indicating the comparison being
                                            performed


The value of args and the Name of the NV Index are extended to policySession→policyDigest by
        policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyNV || args || nvIndex→Name)           (23)
where
         HpolicyAlg()                       hash function using the algorithm of the policy session
         args                               value computed in equation (22)
         nvIndex→Name                       the Name of the NV Index


The signed arithmetic operations are performed using twos-compliment.
Magnitude comparisons assume that the octet at offset zero in the referenced NV location and in
operandB contain the most significant octet of the data.


Family “2.0”                                   TCG Published                                          Page 263
Level 00 Revision 01.16                 Copyright © TCG 2006-2014                          October 30, 2014
Part 3: Commands                                                    Trusted Platform Module Library


23.9.2 Command and Response

                       Table 125 — TPM2_PolicyNV Command
Type                   Name                   Description

TPMI_ST_COMMAND_TAG    tag                    TPM_ST_SESSIONS
UINT32                 commandSize
TPM_CC                 commandCode            TPM_CC_PolicyNV

                                              handle indicating the source of the authorization value
TPMI_RH_NV_AUTH        @authHandle            Auth Index: 1
                                              Auth Role: USER
                                              the NV Index of the area to read
TPMI_RH_NV_INDEX       nvIndex
                                              Auth Index: None
                                              handle for the policy session being extended
TPMI_SH_POLICY         policySession
                                              Auth Index: None

TPM2B_OPERAND          operandB               the second operand
UINT16                 offset                 the offset in the NV Index for the start of operand A
TPM_EO                 operation              the comparison to make


                       Table 126 — TPM2_PolicyNV Response
Type                   Name                   Description

TPM_ST                 tag                    see clause 6
UINT32                 responseSize
TPM_RC                 responseCode


Page 264                               TCG Published                                      Family “2.0”
October 30, 2014                Copyright © TCG 2006-2014                  Level 00 Revision 01.16
     Trusted Platform Module Library                                                                   Part 3: Commands


     23.9.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "PolicyNV_fp.h"
3    #ifdef TPM_CC_PolicyNV // Conditional expansion of this file
4    #include "Policy_spt_fp.h"
5    #include "NV_spt_fp.h"         // Include NV support routine for read access check


     Error Returns                     Meaning

     TPM_RC_AUTH_TYPE                  NV index authorization type is not correct
     TPM_RC_NV_LOCKED                  NV index read locked
     TPM_RC_NV_UNINITIALIZED           the NV index has not been initialized
     TPM_RC_POLICY                     the comparison to the NV contents failed
     TPM_RC_SIZE                       the size of nvIndex data starting at offset is less than the size of
                                       operandB

 6   TPM_RC
 7   TPM2_PolicyNV(
 8       PolicyNV_In       *in                  // IN: input parameter list
 9       )
10   {
11       TPM_RC                   result;
12       SESSION                 *session;
13       NV_INDEX                 nvIndex;
14           BYTE                 nvBuffer[sizeof(in->operandB.t.buffer)];
15       TPM2B_NAME               nvName;
16       TPM_CC                   commandCode = TPM_CC_PolicyNV;
17       HASH_STATE               hashState;
18       TPM2B_DIGEST             argHash;
19
20   // Input Validation
21
22       // Get NV index information
23       NvGetIndexInfo(in->nvIndex, &nvIndex);
24
25       // Get pointer to the session structure
26       session = SessionGet(in->policySession);
27
28       //If this is a trial policy, skip all validations and the operation
29       if(session->attributes.isTrialPolicy == CLEAR)
30       {
31           // NV Read access check. NV index should be allowed for read. A
32           // TPM_RC_AUTH_TYPE or TPM_RC_NV_LOCKED error may be return at this
33           // point
34           result = NvReadAccessChecks(in->authHandle, in->nvIndex);
35           if(result != TPM_RC_SUCCESS) return result;
36
37           // Valid NV data size should not be smaller than input operandB size
38           if((nvIndex.publicArea.dataSize - in->offset) < in->operandB.t.size)
39               return TPM_RC_SIZE + RC_PolicyNV_operandB;
40
41           // Arithmetic Comparison
42
43           // Get NV data. The size of NV data equals the input operand B size
44           NvGetIndexData(in->nvIndex, &nvIndex, in->offset,
45                          in->operandB.t.size, nvBuffer);
46
47           switch(in->operation)
48           {

     Family “2.0”                                   TCG Published                                             Page 265
     Level 00 Revision 01.16                Copyright © TCG 2006-2014                                  October 30, 2014
      Part 3: Commands                                               Trusted Platform Module Library

 49              case TPM_EO_EQ:
 50                  // compare A = B
 51                  if(CryptCompare(in->operandB.t.size, nvBuffer,
 52                                  in->operandB.t.size, in->operandB.t.buffer)   != 0)
 53                      return TPM_RC_POLICY;
 54                  break;
 55              case TPM_EO_NEQ:
 56                  // compare A != B
 57                  if(CryptCompare(in->operandB.t.size, nvBuffer,
 58                                  in->operandB.t.size, in->operandB.t.buffer)   == 0)
 59                      return TPM_RC_POLICY;
 60                  break;
 61              case TPM_EO_SIGNED_GT:
 62                  // compare A > B signed
 63                  if(CryptCompareSigned(in->operandB.t.size, nvBuffer,
 64                                  in->operandB.t.size, in->operandB.t.buffer)   <= 0)
 65                      return TPM_RC_POLICY;
 66                  break;
 67              case TPM_EO_UNSIGNED_GT:
 68                  // compare A > B unsigned
 69                  if(CryptCompare(in->operandB.t.size, nvBuffer,
 70                                  in->operandB.t.size, in->operandB.t.buffer)   <= 0)
 71                      return TPM_RC_POLICY;
 72                  break;
 73              case TPM_EO_SIGNED_LT:
 74                  // compare A < B signed
 75                  if(CryptCompareSigned(in->operandB.t.size, nvBuffer,
 76                                  in->operandB.t.size, in->operandB.t.buffer)   >= 0)
 77                      return TPM_RC_POLICY;
 78                  break;
 79              case TPM_EO_UNSIGNED_LT:
 80                  // compare A < B unsigned
 81                  if(CryptCompare(in->operandB.t.size, nvBuffer,
 82                                  in->operandB.t.size, in->operandB.t.buffer)   >= 0)
 83                      return TPM_RC_POLICY;
 84                  break;
 85              case TPM_EO_SIGNED_GE:
 86                  // compare A >= B signed
 87                  if(CryptCompareSigned(in->operandB.t.size, nvBuffer,
 88                                  in->operandB.t.size, in->operandB.t.buffer)   < 0)
 89                      return TPM_RC_POLICY;
 90                  break;
 91              case TPM_EO_UNSIGNED_GE:
 92                  // compare A >= B unsigned
 93                  if(CryptCompare(in->operandB.t.size, nvBuffer,
 94                                  in->operandB.t.size, in->operandB.t.buffer)   < 0)
 95                      return TPM_RC_POLICY;
 96                  break;
 97              case TPM_EO_SIGNED_LE:
 98                  // compare A <= B signed
 99                  if(CryptCompareSigned(in->operandB.t.size, nvBuffer,
100                                  in->operandB.t.size, in->operandB.t.buffer)   > 0)
101                      return TPM_RC_POLICY;
102                  break;
103              case TPM_EO_UNSIGNED_LE:
104                  // compare A <= B unsigned
105                  if(CryptCompare(in->operandB.t.size, nvBuffer,
106                                  in->operandB.t.size, in->operandB.t.buffer)   > 0)
107                      return TPM_RC_POLICY;
108                  break;
109              case TPM_EO_BITSET:
110                  // All bits SET in B are SET in A. ((A&B)=B)
111              {
112                  UINT32 i;
113                  for (i = 0; i < in->operandB.t.size; i++)
114                      if((nvBuffer[i] & in->operandB.t.buffer[i])

      Page 266                              TCG Published                                  Family “2.0”
      October 30, 2014               Copyright © TCG 2006-2014             Level 00 Revision 01.16
      Trusted Platform Module Library                                          Part 3: Commands

115                                 != in->operandB.t.buffer[i])
116                             return TPM_RC_POLICY;
117                }
118                break;
119                case TPM_EO_BITCLEAR:
120                    // All bits SET in B are CLEAR in A. ((A&B)=0)
121                {
122                    UINT32 i;
123                    for (i = 0; i < in->operandB.t.size; i++)
124                        if((nvBuffer[i] & in->operandB.t.buffer[i]) != 0)
125                            return TPM_RC_POLICY;
126                }
127                break;
128                default:
129                    pAssert(FALSE);
130                    break;
131           }
132       }
133
134   // Internal Data Update
135
136       // Start argument hash
137       argHash.t.size = CryptStartHash(session->authHashAlg, &hashState);
138
139       // add operandB
140       CryptUpdateDigest2B(&hashState, &in->operandB.b);
141
142       // add offset
143       CryptUpdateDigestInt(&hashState, sizeof(UINT16), &in->offset);
144
145       // add operation
146       CryptUpdateDigestInt(&hashState, sizeof(TPM_EO), &in->operation);
147
148       // complete argument digest
149       CryptCompleteHash2B(&hashState, &argHash.b);
150
151       // Update policyDigest
152       // Start digest
153       CryptStartHash(session->authHashAlg, &hashState);
154
155       // add old digest
156       CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b);
157
158       // add commandCode
159       CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode);
160
161       // add argument digest
162       CryptUpdateDigest2B(&hashState, &argHash.b);
163
164       // Adding nvName
165       nvName.t.size = EntityGetName(in->nvIndex, &nvName.t.name);
166       CryptUpdateDigest2B(&hashState, &nvName.b);
167
168       // complete the digest
169       CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b);
170
171       return TPM_RC_SUCCESS;
172   }
173   #endif // CC_PolicyNV


      Family “2.0”                             TCG Published                          Page 267
      Level 00 Revision 01.16           Copyright © TCG 2006-2014              October 30, 2014
Part 3: Commands                                                            Trusted Platform Module Library


23.10 TPM2_PolicyCounterTimer

23.10.1        General Description

This command is used to cause conditional gating of a policy based on the contents of the
TPMS_TIME_INFO structure.
If policySession is a trial policy session, the TPM will update policySession→policyDigest as shown in
equations (24) and (25) below and return TPM_RC_SUCCESS. It will not perform any validation. The
remainder of this general description would apply only if policySession is not a trial policy session.
The TPM will perform the indicated arithmetic check on the indicated portion of the TPMS_TIME_INFO
structure. If the check fails, the TPM shall return TPM_RC_POLICY and not change
policySession→policyDigest. If the check succeeds, the TPM will hash the arguments:
                          args ≔ HpolicyAlg(operandB.buffer || offset || operation)                    (24)
where
          HpolicyAlg()                    hash function using the algorithm of the policy session
          operandB.buffer                 the value used for the comparison
          offset                          offset from the start of the TPMS_TIME_INFO structure at which
                                          the comparison starts
          operation                       the operation parameter indicating the comparison being
                                          performed


The value of args is extended to policySession→policyDigest by
             policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyCounterTimer || args)        (25)
where
          HpolicyAlg()                    hash function using the algorithm of the policy session
          args                            value computed in equation (24)


The signed arithmetic operations are performed using twos-compliment. The indicated portion of the
TPMS_TIME_INFO structure begins at offset and has a length of operandB.size. If the octets to be
compared overflows the TPMS_TIME_INFO structure, the TPM returns TPM_RC_RANGE. The structure
is marshaled into its canonical form with no padding. The TPM does not check for alignment of the offset
with a TPMS_TIME_INFO structure member.
Magnitude comparisons assume that the octet at offset zero in the referenced location and in operandB
contain the most significant octet of the data.


Page 268                                     TCG Published                                    Family “2.0”
October 30, 2014                      Copyright © TCG 2006-2014                  Level 00 Revision 01.16
Trusted Platform Module Library                                                         Part 3: Commands


23.10.2    Command and Response

                        Table 127 — TPM2_PolicyCounterTimer Command
Type                          Name                   Description

                                                     TPM_ST_SESSIONS if an audit or decrypt session is
TPMI_ST_COMMAND_TAG           tag
                                                     present; otherwise, TPM_ST_NO_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode            TPM_CC_PolicyCounterTimer

                                                     handle for the policy session being extended
TPMI_SH_POLICY                policySession
                                                     Auth Index: None

TPM2B_OPERAND                 operandB               the second operand
                                                     the offset in TPMS_TIME_INFO structure for the start of
UINT16                        offset
                                                     operand A
TPM_EO                        operation              the comparison to make


                        Table 128 — TPM2_PolicyCounterTimer Response
Type                          Name                   Description

TPM_ST                        tag                    see clause 6
UINT32                        responseSize
TPM_RC                        responseCode


Family “2.0”                                  TCG Published                                         Page 269
Level 00 Revision 01.16                Copyright © TCG 2006-2014                        October 30, 2014
     Part 3: Commands                                                         Trusted Platform Module Library


     23.10.3     Detailed Actions

1    #include "InternalRoutines.h"
2    #include "PolicyCounterTimer_fp.h"
3    #ifdef TPM_CC_PolicyCounterTimer // Conditional expansion of this file
4    #include "Policy_spt_fp.h"


     Error Returns                  Meaning

     TPM_RC_POLICY                  the comparison of the selected portion of the TPMS_TIME_INFO with
                                    operandB failed
     TPM_RC_RANGE                   offset + size exceed size of TPMS_TIME_INFO structure

 5   TPM_RC
 6   TPM2_PolicyCounterTimer(
 7       PolicyCounterTimer_In      *in              // IN: input parameter list
 8       )
 9   {
10       TPM_RC                result;
11       SESSION              *session;
12       TIME_INFO             infoData;      // data buffer of TPMS_TIME_INFO
13       TPM_CC                commandCode = TPM_CC_PolicyCounterTimer;
14       HASH_STATE            hashState;
15       TPM2B_DIGEST          argHash;
16
17   // Input Validation
18
19       // If the command is going to use any part of the counter or timer, need
20       // to verify that time is advancing.
21       // The time and clock vales are the first two 64-bit values in the clock
22       if(in->offset < sizeof(UINT64) + sizeof(UINT64))
23       {
24           // Using Clock or Time so see if clock is running. Clock doesn't run while
25           // NV is unavailable.
26           // TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned here.
27           result = NvIsAvailable();
28           if(result != TPM_RC_SUCCESS)
29               return result;
30       }
31       // Get pointer to the session structure
32       session = SessionGet(in->policySession);
33
34       //If this is a trial policy, skip all validations and the operation
35       if(session->attributes.isTrialPolicy == CLEAR)
36       {
37           // Get time data info. The size of time info data equals the input
38           // operand B size. A TPM_RC_RANGE error may be returned at this point
39           result = TimeGetRange(in->offset, in->operandB.t.size, &infoData);
40           if(result != TPM_RC_SUCCESS) return result;
41
42             // Arithmetic Comparison
43             switch(in->operation)
44             {
45                 case TPM_EO_EQ:
46                     // compare A = B
47                     if(CryptCompare(in->operandB.t.size, infoData,
48                                     in->operandB.t.size, in->operandB.t.buffer) != 0)
49                         return TPM_RC_POLICY;
50                     break;
51                 case TPM_EO_NEQ:
52                     // compare A != B
53                     if(CryptCompare(in->operandB.t.size, infoData,

     Page 270                                   TCG Published                                     Family “2.0”
     October 30, 2014                     Copyright © TCG 2006-2014                 Level 00 Revision 01.16
      Trusted Platform Module Library                                                Part 3: Commands

 54                                    in->operandB.t.size, in->operandB.t.buffer)   == 0)
 55                        return TPM_RC_POLICY;
 56                    break;
 57                case TPM_EO_SIGNED_GT:
 58                    // compare A > B signed
 59                    if(CryptCompareSigned(in->operandB.t.size, infoData,
 60                                    in->operandB.t.size, in->operandB.t.buffer)   <= 0)
 61                        return TPM_RC_POLICY;
 62                    break;
 63                case TPM_EO_UNSIGNED_GT:
 64                    // compare A > B unsigned
 65                    if(CryptCompare(in->operandB.t.size, infoData,
 66                                    in->operandB.t.size, in->operandB.t.buffer)   <= 0)
 67                        return TPM_RC_POLICY;
 68                    break;
 69                case TPM_EO_SIGNED_LT:
 70                    // compare A < B signed
 71                    if(CryptCompareSigned(in->operandB.t.size, infoData,
 72                                    in->operandB.t.size, in->operandB.t.buffer)   >= 0)
 73                        return TPM_RC_POLICY;
 74                    break;
 75                case TPM_EO_UNSIGNED_LT:
 76                    // compare A < B unsigned
 77                    if(CryptCompare(in->operandB.t.size, infoData,
 78                                    in->operandB.t.size, in->operandB.t.buffer)   >= 0)
 79                        return TPM_RC_POLICY;
 80                    break;
 81                case TPM_EO_SIGNED_GE:
 82                    // compare A >= B signed
 83                    if(CryptCompareSigned(in->operandB.t.size, infoData,
 84                                    in->operandB.t.size, in->operandB.t.buffer)   < 0)
 85                        return TPM_RC_POLICY;
 86                    break;
 87                case TPM_EO_UNSIGNED_GE:
 88                    // compare A >= B unsigned
 89                    if(CryptCompare(in->operandB.t.size, infoData,
 90                                    in->operandB.t.size, in->operandB.t.buffer)   < 0)
 91                        return TPM_RC_POLICY;
 92                    break;
 93                case TPM_EO_SIGNED_LE:
 94                    // compare A <= B signed
 95                    if(CryptCompareSigned(in->operandB.t.size, infoData,
 96                                    in->operandB.t.size, in->operandB.t.buffer)   > 0)
 97                        return TPM_RC_POLICY;
 98                    break;
 99                case TPM_EO_UNSIGNED_LE:
100                    // compare A <= B unsigned
101                    if(CryptCompare(in->operandB.t.size, infoData,
102                                    in->operandB.t.size, in->operandB.t.buffer)   > 0)
103                        return TPM_RC_POLICY;
104                    break;
105                case TPM_EO_BITSET:
106                    // All bits SET in B are SET in A. ((A&B)=B)
107                {
108                    UINT32 i;
109                    for (i = 0; i < in->operandB.t.size; i++)
110                        if(   (infoData[i] & in->operandB.t.buffer[i])
111                           != in->operandB.t.buffer[i])
112                            return TPM_RC_POLICY;
113                }
114                break;
115                case TPM_EO_BITCLEAR:
116                    // All bits SET in B are CLEAR in A. ((A&B)=0)
117                {
118                    UINT32 i;
119                    for (i = 0; i < in->operandB.t.size; i++)

      Family “2.0”                            TCG Published                                  Page 271
      Level 00 Revision 01.16           Copyright © TCG 2006-2014                    October 30, 2014
      Part 3: Commands                                               Trusted Platform Module Library

120                      if((infoData[i] & in->operandB.t.buffer[i]) != 0)
121                          return TPM_RC_POLICY;
122              }
123              break;
124              default:
125                  pAssert(FALSE);
126                  break;
127          }
128      }
129
130   // Internal Data Update
131
132      // Start argument list hash
133      argHash.t.size = CryptStartHash(session->authHashAlg, &hashState);
134      // add operandB
135      CryptUpdateDigest2B(&hashState, &in->operandB.b);
136      // add offset
137      CryptUpdateDigestInt(&hashState, sizeof(UINT16), &in->offset);
138      // add operation
139      CryptUpdateDigestInt(&hashState, sizeof(TPM_EO), &in->operation);
140      // complete argument hash
141      CryptCompleteHash2B(&hashState, &argHash.b);
142
143      // update policyDigest
144      // start hash
145      CryptStartHash(session->authHashAlg, &hashState);
146
147      // add old digest
148      CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b);
149
150      // add commandCode
151      CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode);
152
153      // add argument digest
154      CryptUpdateDigest2B(&hashState, &argHash.b);
155
156      // complete the digest
157      CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b);
158
159       return TPM_RC_SUCCESS;
160   }
161   #endif // CC_PolicyCounterTimer


      Page 272                               TCG Published                               Family “2.0”
      October 30, 2014                  Copyright © TCG 2006-2014             Level 00 Revision 01.16
Trusted Platform Module Library                                                             Part 3: Commands


23.11 TPM2_PolicyCommandCode

23.11.1     General Description

This command indicates that the authorization will be limited to a specific command code.
If policySession→commandCode has its default value, then it will be set to code. If
policySession→commandCode does not have its default value, then the TPM will return
TPM_RC_VALUE if the two values are not the same.
If code is not implemented, the TPM will return TPM_RC_POLICY_CC.
If the TPM does not return an error, it will update policySession→policyDigest by
          policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyCommandCode || code)                   (26)

NOTE 1          If a previous TPM2_PolicyCommandCode() had been executed, then it is probable that the policy
                expression is improperly formed but the TPM does not return an error.

NOTE 2          A TPM2_PolicyOR() would be used to allow an authorization to be used for multiple commands.

When the policy session is used to authorize a command, the TPM will fail the command if the
commandCode of that command does not match policySession→commandCode.
This command, or TPM2_PolicyDuplicationSelect(), is required to enable the policy to be used for ADMIN
role authorization.

EXAMPLE         Before TPM2_Certify() can     be   executed,   TPM2_PolicyCommandCode()     with   code   set   to
                TPM_CC_Certify is required.


Family “2.0”                                  TCG Published                                          Page 273
Level 00 Revision 01.16               Copyright © TCG 2006-2014                             October 30, 2014
Part 3: Commands                                                    Trusted Platform Module Library


23.11.2    Command and Response

                   Table 129 — TPM2_PolicyCommandCode Command
Type                    Name                   Description

                                               TPM_ST_SESSIONS if an audit session is present;
TPMI_ST_COMMAND_TAG     tag
                                               otherwise, TPM_ST_NO_SESSIONS
UINT32                  commandSize
TPM_CC                  commandCode            TPM_CC_PolicyCommandCode

                                               handle for the policy session being extended
TPMI_SH_POLICY          policySession
                                               Auth Index: None

TPM_CC                  code                   the allowed commandCode


                   Table 130 — TPM2_PolicyCommandCode Response
Type                    Name                   Description

TPM_ST                  tag                    see clause 6
UINT32                  responseSize
TPM_RC                  responseCode


Page 274                                TCG Published                                    Family “2.0”
October 30, 2014               Copyright © TCG 2006-2014                  Level 00 Revision 01.16
     Trusted Platform Module Library                                                             Part 3: Commands


     23.11.3    Detailed Actions

1    #include "InternalRoutines.h"
2    #include "PolicyCommandCode_fp.h"
3    #ifdef TPM_CC_PolicyCommandCode // Conditional expansion of this file


     Error Returns                     Meaning

     TPM_RC_VALUE                      commandCode of policySession previously set to a different value

 4   TPM_RC
 5   TPM2_PolicyCommandCode(
 6       PolicyCommandCode_In      *in                   // IN: input parameter list
 7       )
 8   {
 9       SESSION      *session;
10       TPM_CC       commandCode = TPM_CC_PolicyCommandCode;
11       HASH_STATE   hashState;
12
13   // Input validation
14
15       // Get pointer to the session structure
16       session = SessionGet(in->policySession);
17
18       if(session->commandCode != 0 && session->commandCode != in->code)
19           return TPM_RC_VALUE + RC_PolicyCommandCode_code;
20       if(!CommandIsImplemented(in->code))
21           return TPM_RC_POLICY_CC + RC_PolicyCommandCode_code;
22
23   // Internal Data Update
24       // Update policy hash
25       // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyCommandCode || code)
26       // Start hash
27       CryptStartHash(session->authHashAlg, &hashState);
28
29       // add old digest
30       CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b);
31
32       // add commandCode
33       CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode);
34
35       // add input commandCode
36       CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &in->code);
37
38       // complete the hash and get the results
39       CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b);
40
41       // update commandCode value in session context
42       session->commandCode = in->code;
43
44       return TPM_RC_SUCCESS;
45   }
46   #endif // CC_PolicyCommandCode


     Family “2.0”                                  TCG Published                                          Page 275
     Level 00 Revision 01.16               Copyright © TCG 2006-2014                             October 30, 2014
Part 3: Commands                                                        Trusted Platform Module Library


23.12 TPM2_PolicyPhysicalPresence

23.12.1     General Description

This command indicates that physical presence will need to be asserted at the time the authorization is
performed.
If this command is successful, policySession→isPPRequired will be SET to indicate that this check is
required when the policy is used for authorization. Additionally, policySession→policyDigest is extended
with
            policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyPhysicalPresence)          (27)


Page 276                                   TCG Published                                   Family “2.0”
October 30, 2014                    Copyright © TCG 2006-2014                 Level 00 Revision 01.16
Trusted Platform Module Library                                                         Part 3: Commands


23.12.2    Command and Response

                      Table 131 — TPM2_PolicyPhysicalPresence Command
Type                          Name                   Description

                                                     TPM_ST_SESSIONS if an audit session is present;
TPMI_ST_COMMAND_TAG           tag
                                                     otherwise, TPM_ST_NO_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode            TPM_CC_PolicyPhysicalPresence

                                                     handle for the policy session being extended
TPMI_SH_POLICY                policySession
                                                     Auth Index: None


                      Table 132 — TPM2_PolicyPhysicalPresence Response
Type                          Name                   Description

TPM_ST                        tag                    see clause 6
UINT32                        responseSize
TPM_RC                        responseCode


Family “2.0”                                  TCG Published                                         Page 277
Level 00 Revision 01.16             Copyright © TCG 2006-2014                           October 30, 2014
     Part 3: Commands                                                Trusted Platform Module Library


     23.12.3    Detailed Actions

 1   #include "InternalRoutines.h"
 2   #include "PolicyPhysicalPresence_fp.h"
 3   #ifdef TPM_CC_PolicyPhysicalPresence // Conditional expansion of this file
 4   TPM_RC
 5   TPM2_PolicyPhysicalPresence(
 6       PolicyPhysicalPresence_In   *in             // IN: input parameter list
 7       )
 8   {
 9       SESSION      *session;
10       TPM_CC       commandCode = TPM_CC_PolicyPhysicalPresence;
11       HASH_STATE   hashState;
12
13   // Internal Data Update
14
15       // Get pointer to the session structure
16       session = SessionGet(in->policySession);
17
18       // Update policy hash
19       // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyPhysicalPresence)
20       // Start hash
21       CryptStartHash(session->authHashAlg, &hashState);
22
23       // add old digest
24       CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b);
25
26       // add commandCode
27       CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode);
28
29       // complete the digest
30       CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b);
31
32       // update session attribute
33       session->attributes.isPPRequired = SET;
34
35       return TPM_RC_SUCCESS;
36   }
37   #endif // CC_PolicyPhysicalPresence


     Page 278                                TCG Published                             Family “2.0”
     October 30, 2014                 Copyright © TCG 2006-2014            Level 00 Revision 01.16
Trusted Platform Module Library                                                      Part 3: Commands


23.13 TPM2_PolicyCpHash

23.13.1    General Description

This command is used to allow a policy to be bound to a specific command and command parameters.
TPM2_PolicySigned(), TPM2_PolicySecret(), and TPM2_PolicyTIcket() are designed to allow an
authorizing entity to execute an arbitrary command as the cpHashA parameter of those commands is not
included in policySession→policyDigest. TPM2_PolicyCommandCode() allows the policy to be bound to a
specific Command Code so that only certain entities may authorize specific command codes. This
command allows the policy to be restricted such that an entity may only authorize a command with a
specific set of parameters.
If policySession→cpHash is already set and not the same as cpHashA, then the TPM shall return
TPM_RC_VALUE. If cpHashA does not have the size of the policySession→policyDigest, the TPM shall
return TPM_RC_SIZE.
If the cpHashA checks succeed, policySession→cpHash                  is   set   to     cpHashA    and
policySession→policyDigest is updated with
           policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyCpHash || cpHashA)       (28)


Family “2.0”                              TCG Published                                      Page 279
Level 00 Revision 01.16            Copyright © TCG 2006-2014                         October 30, 2014
Part 3: Commands                                                   Trusted Platform Module Library


23.13.2    Command and Response

                      Table 133 — TPM2_PolicyCpHash Command
Type                    Name                   Description

                                               TPM_ST_SESSIONS if an audit or decrypt session is
TPMI_ST_COMMAND_TAG     tag
                                               present; otherwise, TPM_ST_NO_SESSIONS
UINT32                  commandSize
TPM_CC                  commandCode            TPM_CC_PolicyCpHash

                                               handle for the policy session being extended
TPMI_SH_POLICY          policySession
                                               Auth Index: None

TPM2B_DIGEST            cpHashA                the cpHash added to the policy


                      Table 134 — TPM2_PolicyCpHash Response
Type                    Name                   Description

TPM_ST                  tag                    see clause 6
UINT32                  responseSize
TPM_RC                  responseCode


Page 280                                TCG Published                                    Family “2.0”
October 30, 2014              Copyright © TCG 2006-2014                   Level 00 Revision 01.16
     Trusted Platform Module Library                                                               Part 3: Commands


     23.13.3    Detailed Actions

1    #include "InternalRoutines.h"
2    #include "PolicyCpHash_fp.h"
3    #ifdef TPM_CC_PolicyCpHash // Conditional expansion of this file


     Error Returns                     Meaning

     TPM_RC_CPHASH                     cpHash of policySession has previously been set to a different value
     TPM_RC_SIZE                       cpHashA is not the size of a digest produced by the hash algorithm
                                       associated with policySession

 4   TPM_RC
 5   TPM2_PolicyCpHash(
 6       PolicyCpHash_In       *in                   // IN: input parameter list
 7       )
 8   {
 9       SESSION      *session;
10       TPM_CC       commandCode = TPM_CC_PolicyCpHash;
11       HASH_STATE   hashState;
12
13   // Input Validation
14
15       // Get pointer to the session structure
16       session = SessionGet(in->policySession);
17
18       // A new cpHash is given in input parameter, but cpHash in session context
19       // is not empty, or is not the same as the new cpHash
20       if(    in->cpHashA.t.size != 0
21           && session->u1.cpHash.t.size != 0
22           && !Memory2BEqual(&in->cpHashA.b, &session->u1.cpHash.b)
23          )
24           return TPM_RC_CPHASH;
25
26       // A valid cpHash must have the same size as session hash digest
27       if(in->cpHashA.t.size != CryptGetHashDigestSize(session->authHashAlg))
28           return TPM_RC_SIZE + RC_PolicyCpHash_cpHashA;
29
30   // Internal Data Update
31
32       // Update policy hash
33       // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyCpHash || cpHashA)
34       // Start hash
35       CryptStartHash(session->authHashAlg, &hashState);
36
37       // add old digest
38       CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b);
39
40       // add commandCode
41       CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode);
42
43       // add cpHashA
44       CryptUpdateDigest2B(&hashState, &in->cpHashA.b);
45
46       // complete the digest and get the results
47       CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b);
48
49       // update cpHash in session context
50       session->u1.cpHash = in->cpHashA;
51       session->attributes.iscpHashDefined = SET;
52
53       return TPM_RC_SUCCESS;

     Family “2.0”                                  TCG Published                                              Page 281
     Level 00 Revision 01.16               Copyright © TCG 2006-2014                               October 30, 2014
     Part 3: Commands                                        Trusted Platform Module Library

54   }
55   #endif // CC_PolicyCpHash


     Page 282                         TCG Published                            Family “2.0”
     October 30, 2014            Copyright © TCG 2006-2014        Level 00 Revision 01.16
Trusted Platform Module Library                                                            Part 3: Commands


23.14 TPM2_PolicyNameHash

23.14.1     General Description

This command allows a policy to be bound to a specific set of TPM entities without being bound to the
parameters of the command. This is most useful for commands such as TPM2_Duplicate() and for
TPM2_PCR_Event() when the referenced PCR requires a policy.
The nameHash parameter should contain the digest of the Names associated with the handles to be used
in the authorized command.

EXAMPLE         For the TPM2_Duplicate() command, two han dles are provided. One is the handle of the object
                being duplicated and the other is the handle of the new parent. For that command, nameHash would
                contain:
                   nameHash ≔ H policyAlg (objectHandle→Name || newParentHandle→Name)

If policySession→cpHash is already set, the TPM shall return TPM_RC_VALUE. If the size of nameHash
is not the size of policySession→policyDigest, the TPM shall return TPM_RC_SIZE. Otherwise,
policySession→cpHash is set to nameHash.
If this command completes successfully, the cpHash of the authorized command will not be used for
validation. Only the digest of the Names associated with the handles in the command will be used.

NOTE 1          This allows the space normally       used   to   hold   policySession→cpHash   to   be    used    for
                policySession→nameHash instead.

The policySession→policyDigest will be updated with
          policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyNameHash || nameHash)                     (29)

NOTE 2          This command will often be used with TPM2_PolicyAuthorize() where the owner of the object being
                duplicated provides approval for their object to be migrated to a specific new parent.


Family “2.0”                                 TCG Published                                               Page 283
Level 00 Revision 01.16               Copyright © TCG 2006-2014                            October 30, 2014
Part 3: Commands                                                     Trusted Platform Module Library


23.14.2    Command and Response

                      Table 135 — TPM2_PolicyNameHash Command
Type                     Name                   Description

                                                TPM_ST_SESSIONS if an audit or decrypt session is
TPMI_ST_COMMAND_TAG      tag
                                                present; otherwise, TPM_ST_NO_SESSIONS
UINT32                   commandSize
TPM_CC                   commandCode            TPM_CC_PolicyNameHash

                                                handle for the policy session being extended
TPMI_SH_POLICY           policySession
                                                Auth Index: None

TPM2B_DIGEST             nameHash               the digest to be added to the policy


                      Table 136 — TPM2_PolicyNameHash Response
Type                     Name                   Description

TPM_ST                   tag                    see clause 6
UINT32                   responseSize
TPM_RC                   responseCode


Page 284                                 TCG Published                                    Family “2.0”
October 30, 2014               Copyright © TCG 2006-2014                    Level 00 Revision 01.16
     Trusted Platform Module Library                                                             Part 3: Commands


     23.14.3    Detailed Actions

1    #include "InternalRoutines.h"
2    #include "PolicyNameHash_fp.h"
3    #ifdef TPM_CC_PolicyNameHash // Conditional expansion of this file


     Error Returns                     Meaning

     TPM_RC_CPHASH                     nameHash has been previously set to a different value
     TPM_RC_SIZE                       nameHash is not the size of the digest produced by the hash
                                       algorithm associated with policySession

 4   TPM_RC
 5   TPM2_PolicyNameHash(
 6       PolicyNameHash_In     *in                  // IN: input parameter list
 7       )
 8   {
 9       SESSION               *session;
10       TPM_CC                 commandCode = TPM_CC_PolicyNameHash;
11       HASH_STATE             hashState;
12
13   // Input Validation
14
15       // Get pointer to the session structure
16       session = SessionGet(in->policySession);
17
18       // A new nameHash is given in input parameter, but cpHash in session context
19       // is not empty
20       if(in->nameHash.t.size != 0 && session->u1.cpHash.t.size != 0)
21           return TPM_RC_CPHASH;
22
23       // A valid nameHash must have the same size as session hash digest
24       if(in->nameHash.t.size != CryptGetHashDigestSize(session->authHashAlg))
25           return TPM_RC_SIZE + RC_PolicyNameHash_nameHash;
26
27   // Internal Data Update
28
29       // Update policy hash
30       // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyNameHash || nameHash)
31       // Start hash
32       CryptStartHash(session->authHashAlg, &hashState);
33
34       // add old digest
35       CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b);
36
37       // add commandCode
38       CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode);
39
40       // add nameHash
41       CryptUpdateDigest2B(&hashState, &in->nameHash.b);
42
43       // complete the digest
44       CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b);
45
46       // clear iscpHashDefined bit to indicate now this field contains a nameHash
47       session->attributes.iscpHashDefined = CLEAR;
48
49       // update nameHash in session context
50       session->u1.cpHash = in->nameHash;
51
52       return TPM_RC_SUCCESS;
53   }

     Family “2.0”                                  TCG Published                                        Page 285
     Level 00 Revision 01.16               Copyright © TCG 2006-2014                             October 30, 2014
     Part 3: Commands                                          Trusted Platform Module Library

54   #endif // CC_PolicyNameHash


     Page 286                           TCG Published                            Family “2.0”
     October 30, 2014              Copyright © TCG 2006-2014        Level 00 Revision 01.16
Trusted Platform Module Library                                                                    Part 3: Commands


23.15 TPM2_PolicyDuplicationSelect

23.15.1       General Description

This command allows qualification of duplication to allow duplication to a selected new parent.
If this command not used in conjunction with TPM2_PolicyAuthorize(), then only the new parent is
selected.

EXAMPLE           When an object is created when the list of allowed duplication targets is known, the policy would be
                  created with includeObject CLEAR.

NOTE 1            Only the new parent may be selected because, without TPM2_PolicyAuthorize(), the Name of the
                  Object to be duplicated would need to be known at the time that Object's policy is created. However,
                  since the Name of the Object includes its policy, the Name is not known.

If used in conjunction with TPM2_PolicyAuthorize(), then the authorizer of the new policy has the option
of selecting just the new parent or of selecting both the new parent and the duplication Object..

NOTE 2            If the authorizing entity for an TPM2_PolicyAuthorize() only specifies the new parent, t hen that
                  authorization may be applied to the duplication of any number of other Objects. If the authorizing
                  entity specifies both a new parent and the duplicated Object, then the authorization only applies to
                  that pairing of Object and new parent.

If either policySession→cpHash or policySession→nameHash has been previously set, the TPM shall
return TPM_RC_CPHASH. Otherwise, policySession→nameHash will be set to:
                           nameHash ≔ HpolicyAlg(objectName || newParentName)                                       (30)

NOTE 3            It is allowed that policySesion→nameHash and policySession→cpHash share the same memory
                  space.

The policySession→policyDigest will be updated according to the setting of includeObject. If equal to
YES, policySession→policyDigest is updated by:
          policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyDuplicationSelect ||
                                  objectName || newParentName || includeObject)                                     (31)
If includeObject is NO, policySession→policyDigest is updated by:
          policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyDuplicationSelect ||
                                  newParentName || includeObject)                                                   (32)

NOTE 4            policySession→cpHash receives the digest of both Names so that the check performed in
                  TPM2_Duplicate() may be the same regardless of which Names are included in
                  policySession→policyDigest. This means that, when TPM2_PolicyDuplicationSelect() is executed, it
                  is only valid for a specific pair of duplication object and new parent.

If the command succeeds, policySession→commandCode is set to TPM_CC_Duplicate.

NOTE 5            The normal use of this command is before a TPM2_PolicyAuthorize(). An authorized entity would
                  approve a policyDigest that allowed duplication to a specific new parent. The authorizing entity may
                  want to limit the authorization so that the approval allows on ly a specific object to be duplicated to
                  the new parent. In that case, the authorizing entity would approve the policyDigest of equation (31).


Family “2.0”                                      TCG Published                                              Page 287
Level 00 Revision 01.16                  Copyright © TCG 2006-2014                                 October 30, 2014
Part 3: Commands                                                     Trusted Platform Module Library


23.15.2    Command and Response

                   Table 137 — TPM2_PolicyDuplicationSelect Command
Type                     Name                   Description

                                                TPM_ST_SESSIONS if an audit or decrypt session is
TPMI_ST_COMMAND_TAG      tag
                                                present; otherwise, TPM_ST_NO_SESSIONS
UINT32                   commandSize
TPM_CC                   commandCode            TPM_CC_PolicyDuplicationSelect

                                                handle for the policy session being extended
TPMI_SH_POLICY           policySession
                                                Auth Index: None

TPM2B_NAME               objectName             the Name of the object to be duplicated
TPM2B_NAME               newParentName          the Name of the new parent
                                                if YES, the objectName will be included in the value in
TPMI_YES_NO              includeObject
                                                policySession→policyDigest


                   Table 138 — TPM2_PolicyDuplicationSelect Response
Type                     Name                   Description

TPM_ST                   tag                    see clause 6
UINT32                   responseSize
TPM_RC                   responseCode


Page 288                                 TCG Published                                     Family “2.0”
October 30, 2014               Copyright © TCG 2006-2014                     Level 00 Revision 01.16
     Trusted Platform Module Library                                                        Part 3: Commands


     23.15.3    Detailed Actions

1    #include "InternalRoutines.h"
2    #include "PolicyDuplicationSelect_fp.h"
3    #ifdef TPM_CC_PolicyDuplicationSelect // Conditional expansion of this file


     Error Returns                     Meaning

     TPM_RC_COMMAND_CODE               commandCode of 'policySession; is not empty
     TPM_RC_CPHASH                     cpHash of policySession is not empty

 4   TPM_RC
 5   TPM2_PolicyDuplicationSelect(
 6       PolicyDuplicationSelect_In       *in                 // IN: input parameter list
 7       )
 8   {
 9       SESSION           *session;
10       HASH_STATE        hashState;
11       TPM_CC            commandCode = TPM_CC_PolicyDuplicationSelect;
12
13   // Input Validation
14
15       // Get pointer to the session structure
16       session = SessionGet(in->policySession);
17
18       // cpHash in session context must be empty
19       if(session->u1.cpHash.t.size != 0)
20           return TPM_RC_CPHASH;
21
22       // commandCode in session context must be empty
23       if(session->commandCode != 0)
24           return TPM_RC_COMMAND_CODE;
25
26   // Internal Data Update
27
28       // Update name hash
29       session->u1.cpHash.t.size = CryptStartHash(session->authHashAlg, &hashState);
30
31       // add objectName
32       CryptUpdateDigest2B(&hashState, &in->objectName.b);
33
34       // add new parent name
35       CryptUpdateDigest2B(&hashState, &in->newParentName.b);
36
37       // complete hash
38       CryptCompleteHash2B(&hashState, &session->u1.cpHash.b);
39
40       // update policy hash
41       // Old policyDigest size should be the same as the new policyDigest size since
42       // they are using the same hash algorithm
43       session->u2.policyDigest.t.size
44               = CryptStartHash(session->authHashAlg, &hashState);
45
46       // add old policy
47       CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b);
48
49       // add command code
50       CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode);
51
52       // add objectName
53       if(in->includeObject == YES)
54           CryptUpdateDigest2B(&hashState, &in->objectName.b);

     Family “2.0”                                  TCG Published                                   Page 289
     Level 00 Revision 01.16               Copyright © TCG 2006-2014                        October 30, 2014
     Part 3: Commands                                               Trusted Platform Module Library

55
56      // add new parent name
57      CryptUpdateDigest2B(&hashState, &in->newParentName.b);
58
59      // add includeObject
60      CryptUpdateDigestInt(&hashState, sizeof(TPMI_YES_NO), &in->includeObject);
61
62      // complete digest
63      CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b);
64
65      // clear iscpHashDefined bit to indicate now this field contains a nameHash
66      session->attributes.iscpHashDefined = CLEAR;
67
68      // set commandCode in session context
69      session->commandCode = TPM_CC_Duplicate;
70
71       return TPM_RC_SUCCESS;
72   }
73   #endif // CC_PolicyDuplicationSelect


     Page 290                               TCG Published                             Family “2.0”
     October 30, 2014                Copyright © TCG 2006-2014            Level 00 Revision 01.16
Trusted Platform Module Library                                                                  Part 3: Commands


23.16 TPM2_PolicyAuthorize

23.16.1     General Description

This command allows policies to change. If a policy were static, then it would be difficult to add users to a
policy. This command lets a policy authority sign a new policy so that it may be used in an existing policy.
The authorizing entity signs a structure that contains
                              aHash ≔ HaHashAlg(approvedPolicy || policyRef)                                      (33)
The aHashAlg is required to be the nameAlg of the key used to sign the aHash. The aHash value is then
signed (symmetric or asymmetric) by keySign. That signature is then checked by the TPM in
TPM2_VerifySignature() which produces a ticket by
                    HMAC(proof, (TPM_ST_VERIFIED || aHash || keySign→Name))                                       (34)

NOTE 1          The reason for the validation is because of the expectation that the policy will be used multiple times
                and it is more efficient to check a ticket than to load an object each time to check a signature.

The ticket is then used in TPM2_PolicyAuthorize() to validate the parameters.
The keySign parameter is required to be a valid object name using nameAlg other than TPM_ALG_NULL.
If the first two octets of keySign are not a valid hash algorithm, the TPM shall return TPM_RC_HASH. If
the remainder of the Name is not the size of the indicated digest, the TPM shall return TPM_RC_SIZE.
The TPM validates that the approvedPolicy matches the current value of policySession→policyDigest and
if not, shall return TPM_RC_VALUE.
The TPM then validates that the parameters to TPM2_PolicyAuthorize() match the values used to
generate the ticket. If so, the TPM will reset policySession→policyDigest to a Zero Digest. Then it will
update policySession→policyDigest with PolicyUpdate() (see 23.2.3).
                      PolicyUpdate(TPM_CC_PolicyAuthorize, keySign, policyRef)                                    (35)
If the ticket is not valid, the TPM shall return TPM_RC_POLICY.
If policySession is a trial session, policySession→policyDigest is extended as if the ticket is valid without
actual verification.

NOTE 2          The unmarshaling process requires that a proper TPMT_TK_VERIFIED be provided for checkTicket
                but it may be a NULL Ticket. A NULL ticket is useful in a trial policy, where the caller uses the TPM
                to perform policy calculations but does not have a valid authorization ticket.


Family “2.0”                                    TCG Published                                              Page 291
Level 00 Revision 01.16                Copyright © TCG 2006-2014                                 October 30, 2014
Part 3: Commands                                                    Trusted Platform Module Library


23.16.2    Command and Response

                      Table 139 — TPM2_PolicyAuthorize Command
Type                    Name                   Description

                                               TPM_ST_SESSIONS if an audit or decrypt session is
TPMI_ST_COMMAND_TAG     tag
                                               present; otherwise, TPM_ST_NO_SESSIONS
UINT32                  commandSize
TPM_CC                  commandCode            TPM_CC_PolicyAuthorize

                                               handle for the policy session being extended
TPMI_SH_POLICY          policySession
                                               Auth Index: None

TPM2B_DIGEST            approvedPolicy         digest of the policy being approved
TPM2B_NONCE             policyRef              a policy qualifier
TPM2B_NAME              keySign                Name of a key that can sign a policy addition
                                               ticket validating that approvedPolicy and policyRef were
TPMT_TK_VERIFIED        checkTicket
                                               signed by keySign


                      Table 140 — TPM2_PolicyAuthorize Response
Type                    Name                   Description

TPM_ST                  tag                    see clause 6
UINT32                  responseSize
TPM_RC                  responseCode


Page 292                                TCG Published                                    Family “2.0”
October 30, 2014              Copyright © TCG 2006-2014                    Level 00 Revision 01.16
     Trusted Platform Module Library                                                             Part 3: Commands


     23.16.3     Detailed Actions

1    #include "InternalRoutines.h"
2    #include "PolicyAuthorize_fp.h"
3    #ifdef TPM_CC_PolicyAuthorize // Conditional expansion of this file
4    #include "Policy_spt_fp.h"


     Error Returns                     Meaning

     TPM_RC_HASH                       hash algorithm in keyName is not supported
     TPM_RC_SIZE                       keyName is not the correct size for its hash algorithm
     TPM_RC_VALUE                      the current policyDigest of policySession does not match
                                       approvedPolicy; or checkTicket doesn't match the provided values

 5   TPM_RC
 6   TPM2_PolicyAuthorize(
 7       PolicyAuthorize_In    *in                   // IN: input parameter list
 8       )
 9   {
10       SESSION                     *session;
11       TPM2B_DIGEST                 authHash;
12       HASH_STATE                   hashState;
13       TPMT_TK_VERIFIED             ticket;
14       TPM_ALG_ID                   hashAlg;
15       UINT16                       digestSize;
16
17   // Input Validation
18
19       // Get pointer to the session structure
20       session = SessionGet(in->policySession);
21
22       // Extract from the Name of the key, the algorithm used to compute it's Name
23       hashAlg = BYTE_ARRAY_TO_UINT16(in->keySign.t.name);
24
25       // 'keySign' parameter needs to use a supported hash algorithm, otherwise
26       // can't tell how large the digest should be
27       digestSize = CryptGetHashDigestSize(hashAlg);
28       if(digestSize == 0)
29           return TPM_RC_HASH + RC_PolicyAuthorize_keySign;
30
31       if(digestSize != (in->keySign.t.size - 2))
32           return TPM_RC_SIZE + RC_PolicyAuthorize_keySign;
33
34       //If this is a trial policy, skip all validations
35       if(session->attributes.isTrialPolicy == CLEAR)
36       {
37           // Check that "approvedPolicy" matches the current value of the
38           // policyDigest in policy session
39           if(!Memory2BEqual(&session->u2.policyDigest.b,
40                             &in->approvedPolicy.b))
41               return TPM_RC_VALUE + RC_PolicyAuthorize_approvedPolicy;
42
43             // Validate ticket TPMT_TK_VERIFIED
44             // Compute aHash. The authorizing object sign a digest
45             // aHash := hash(approvedPolicy || policyRef).
46             // Start hash
47             authHash.t.size = CryptStartHash(hashAlg, &hashState);
48
49             // add approvedPolicy
50             CryptUpdateDigest2B(&hashState, &in->approvedPolicy.b);
51

     Family “2.0”                                   TCG Published                                         Page 293
     Level 00 Revision 01.16               Copyright © TCG 2006-2014                             October 30, 2014
     Part 3: Commands                                               Trusted Platform Module Library

52          // add policyRef
53          CryptUpdateDigest2B(&hashState, &in->policyRef.b);
54
55          // complete hash
56          CryptCompleteHash2B(&hashState, &authHash.b);
57
58          // re-compute TPMT_TK_VERIFIED
59          TicketComputeVerified(in->checkTicket.hierarchy, &authHash,
60                                &in->keySign, &ticket);
61
62          // Compare ticket digest. If not match, return error
63          if(!Memory2BEqual(&in->checkTicket.digest.b, &ticket.digest.b))
64              return TPM_RC_VALUE+ RC_PolicyAuthorize_checkTicket;
65      }
66
67   // Internal Data Update
68
69      // Set policyDigest to zero digest
70      MemorySet(session->u2.policyDigest.t.buffer, 0,
71                session->u2.policyDigest.t.size);
72
73      // Update policyDigest
74      PolicyContextUpdate(TPM_CC_PolicyAuthorize, &in->keySign, &in->policyRef,
75                          NULL, 0, session);
76
77      return TPM_RC_SUCCESS;
78
79   }
80   #endif // CC_PolicyAuthorize


     Page 294                              TCG Published                              Family “2.0”
     October 30, 2014               Copyright © TCG 2006-2014             Level 00 Revision 01.16
Trusted Platform Module Library                                                          Part 3: Commands


23.17 TPM2_PolicyAuthValue

23.17.1     General Description

This command allows a policy to be bound to the authorization value of the authorized object.
When this command completes successfully, policySession→isAuthValueNeeded is SET to indicate that
the authValue will be included in hmacKey when the authorization HMAC is computed for the command
being authorized using this session. Additionally, policySession→isPasswordNeeded will be CLEAR.

NOTE            If a policy does not use this command, then the hmacKey for the authorized command would only
                use sessionKey. If sessionKey is not present, then the hmacKey is an Empty Buffer and no HMAC
                would be computed.

If successful, policySession→policyDigest will be updated with
                policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyAuthValue)                 (36)


Family “2.0”                                 TCG Published                                        Page 295
Level 00 Revision 01.16              Copyright © TCG 2006-2014                           October 30, 2014
Part 3: Commands                                                     Trusted Platform Module Library


23.17.2    Command and Response

                      Table 141 — TPM2_PolicyAuthValue Command
Type                     Name                   Description

                                                TPM_ST_SESSIONS if an audit session is present;
TPMI_ST_COMMAND_TAG      tag
                                                otherwise, TPM_ST_NO_SESSIONS
UINT32                   commandSize
TPM_CC                   commandCode            TPM_CC_PolicyAuthValue

                                                handle for the policy session being extended
TPMI_SH_POLICY           policySession
                                                Auth Index: None


                      Table 142 — TPM2_PolicyAuthValue Response
Type                     Name                   Description

TPM_ST                   tag                    see clause 6
UINT32                   responseSize
TPM_RC                   responseCode


Page 296                                 TCG Published                                    Family “2.0”
October 30, 2014               Copyright © TCG 2006-2014                   Level 00 Revision 01.16
     Trusted Platform Module Library                                            Part 3: Commands


     23.17.3    Detailed Actions

 1   #include "InternalRoutines.h"
 2   #include "PolicyAuthValue_fp.h"
 3   #ifdef TPM_CC_PolicyAuthValue // Conditional expansion of this file
 4   #include "Policy_spt_fp.h"
 5   TPM_RC
 6   TPM2_PolicyAuthValue(
 7       PolicyAuthValue_In    *in            // IN: input parameter list
 8       )
 9   {
10       SESSION               *session;
11       TPM_CC                 commandCode = TPM_CC_PolicyAuthValue;
12       HASH_STATE             hashState;
13
14   // Internal Data Update
15
16       // Get pointer to the session structure
17       session = SessionGet(in->policySession);
18
19       // Update policy hash
20       // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyAuthValue)
21       //   Start hash
22       CryptStartHash(session->authHashAlg, &hashState);
23
24       // add old digest
25       CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b);
26
27       // add commandCode
28       CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode);
29
30       // complete the hash and get the results
31       CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b);
32
33       // update isAuthValueNeeded bit in the session context
34       session->attributes.isAuthValueNeeded = SET;
35       session->attributes.isPasswordNeeded = CLEAR;
36
37       return TPM_RC_SUCCESS;
38   }
39   #endif // CC_PolicyAuthValue


     Family “2.0”                             TCG Published                            Page 297
     Level 00 Revision 01.16           Copyright © TCG 2006-2014                October 30, 2014
Part 3: Commands                                                                 Trusted Platform Module Library


23.18 TPM2_PolicyPassword

23.18.1     General Description

This command allows a policy to be bound to the authorization value of the authorized object.
When this command completes successfully, policySession→isPasswordNeeded is SET to indicate that
authValue of the authorized object will be checked when the session is used for authorization. The caller
will provide the authValue in clear text in the hmac parameter of the authorization. The comparison of
hmac to authValue is performed as if the authorization is a password.

NOTE 1          The parameter field in the policy session where the authorization value is provided is called hmac. If
                TPM2_PolicyPassword() is part of the sequence, then the field will c ontain a password and not an
                HMAC.

If successful, policySession→policyDigest will be updated with
                policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyAuthValue)                          (37)

NOTE 2          This is the same extend value as used with TPM2_PolicyAuthValue so that the evaluation may be
                done using either an HMAC or a password with no change to the authPolicy of the object. The
                reason that two commands are present is to indicate to the TPM if the hmac field in the authorization
                will contain an HMAC or a password value.

When this command is successful, policySession→isAuthValueNeeded will be CLEAR.


Page 298                                       TCG Published                                           Family “2.0”
October 30, 2014                       Copyright © TCG 2006-2014                        Level 00 Revision 01.16
Trusted Platform Module Library                                                         Part 3: Commands


23.18.2    Command and Response

                          Table 143 — TPM2_PolicyPassword Command
Type                          Name                   Description

                                                     TPM_ST_SESSIONS if an audit session is present;
TPMI_ST_COMMAND_TAG           tag
                                                     otherwise, TPM_ST_NO_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode            TPM_CC_PolicyPassword

                                                     handle for the policy session being extended
TPMI_SH_POLICY                policySession
                                                     Auth Index: None


                          Table 144 — TPM2_PolicyPassword Response
Type                          Name                   Description

TPM_ST                        tag                    see clause 6
UINT32                        responseSize
TPM_RC                        responseCode


Family “2.0”                                  TCG Published                                         Page 299
Level 00 Revision 01.16             Copyright © TCG 2006-2014                           October 30, 2014
     Part 3: Commands                                                   Trusted Platform Module Library


     23.18.3    Detailed Actions

 1   #include "InternalRoutines.h"
 2   #include "PolicyPassword_fp.h"
 3   #ifdef TPM_CC_PolicyPassword // Conditional expansion of this file
 4   #include "Policy_spt_fp.h"
 5   TPM_RC
 6   TPM2_PolicyPassword(
 7       PolicyPassword_In     *in            // IN: input parameter list
 8       )
 9   {
10       SESSION               *session;
11       TPM_CC                 commandCode = TPM_CC_PolicyAuthValue;
12       HASH_STATE             hashState;
13
14   // Internal Data Update
15
16       // Get pointer to the session structure
17       session = SessionGet(in->policySession);
18
19       // Update policy hash
20       // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyAuthValue)
21       // Start hash
22       CryptStartHash(session->authHashAlg, &hashState);
23
24       // add old digest
25       CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b);
26
27       // add commandCode
28       CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode);
29
30       // complete the digest
31       CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b);
32
33       // Update isPasswordNeeded bit
34       session->attributes.isPasswordNeeded = SET;
35       session->attributes.isAuthValueNeeded = CLEAR;
36
37       return TPM_RC_SUCCESS;
38   }
39   #endif // CC_PolicyPassword


     Page 300                                 TCG Published                               Family “2.0”
     October 30, 2014                  Copyright © TCG 2006-2014             Level 00 Revision 01.16
Trusted Platform Module Library                                                   Part 3: Commands


23.19 TPM2_PolicyGetDigest

23.19.1    General Description

This command returns the current policyDigest of the session. This command allows the TPM to be used
to perform the actions required to pre-compute the authPolicy for an object.


Family “2.0”                             TCG Published                                    Page 301
Level 00 Revision 01.16           Copyright © TCG 2006-2014                       October 30, 2014
Part 3: Commands                                                    Trusted Platform Module Library


23.19.2    Command and Response

                      Table 145 — TPM2_PolicyGetDigest Command
Type                    Name                   Description

                                               TPM_ST_SESSIONS if an audit or encrypt session is
TPMI_ST_COMMAND_TAG     tag
                                               present; otherwise, TPM_ST_NO_SESSIONS
UINT32                  commandSize
TPM_CC                  commandCode            TPM_CC_PolicyGetDigest

                                               handle for the policy session
TPMI_SH_POLICY          policySession
                                               Auth Index: None


                      Table 146 — TPM2_PolicyGetDigest Response
Type                    Name                   Description

TPM_ST                  tag                    see clause 6
UINT32                  responseSize
TPM_RC                  responseCode

TPM2B_DIGEST            policyDigest           the current value of the policySession→policyDigest


Page 302                                TCG Published                                   Family “2.0”
October 30, 2014              Copyright © TCG 2006-2014                    Level 00 Revision 01.16
     Trusted Platform Module Library                                                Part 3: Commands


     23.19.3    Detailed Actions

 1   #include "InternalRoutines.h"
 2   #include "PolicyGetDigest_fp.h"
 3   #ifdef TPM_CC_PolicyGetDigest // Conditional expansion of this file
 4   TPM_RC
 5   TPM2_PolicyGetDigest(
 6       PolicyGetDigest_In        *in,             // IN: input parameter list
 7       PolicyGetDigest_Out       *out             // OUT: output parameter list
 8       )
 9   {
10       SESSION      *session;
11
12   // Command Output
13
14       // Get pointer to the session structure
15       session = SessionGet(in->policySession);
16
17       out->policyDigest = session->u2.policyDigest;
18
19       return TPM_RC_SUCCESS;
20   }
21   #endif // CC_PolicyGetDigest


     Family “2.0”                              TCG Published                               Page 303
     Level 00 Revision 01.16              Copyright © TCG 2006-2014                 October 30, 2014
Part 3: Commands                                                                 Trusted Platform Module Library


23.20 TPM2_PolicyNvWritten

23.20.1     General Description

This command allows a policy to be bound to the TPMA_NV_WRITTEN attributes. This is a deferred
assertion. Values are stored in the policy session context and checked when the policy is used for
authorization.
If policySession→checkNVWritten is CLEAR, it is SET and policySession→nvWrittenState is set to
writtenSet.   If policySession→checkNVWritten is SET, the TPM will return TPM_RC_VALUE if
policySession→nvWrittenState and writtenSet are not the same.
If the TPM does not return an error, it will update policySession→policyDigest by
          policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyNvWritten || writtenSet)                  (38)
When the policy session is used to authorize a command, the TPM will fail the command if
policySession→checkNVWritten is SET and nvIndex→attributes→TPMA_NV_WRITTEN does not match
policySession→nvWrittenState.

NOTE 1          A typical use case is a simple policy for the first write during manufacturing provisioning that would
                require TPMA_NV_WRITTEN CLEAR and a more complex policy for later use that would require
                TPMA_NV_WRITTEN SET.

NOTE 2          When an Index is written, it has a different authorization name than an Index that has not been
                written. It is possible to use this change in the NV Index to create a write-once Index.


Page 304                                       TCG Published                                           Family “2.0”
October 30, 2014                       Copyright © TCG 2006-2014                        Level 00 Revision 01.16
Trusted Platform Module Library                                                          Part 3: Commands


23.20.2    Command and Response

                          Table 147 — TPM2_PolicyNvWritten Command
Type                          Name                   Description

                                                     TPM_ST_SESSIONS if an audit session is present;
TPMI_ST_COMMAND_TAG           tag
                                                     otherwise, TPM_ST_NO_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode            TPM_CC_PolicyNVWritten

                                                     handle for the policy session being extended
TPMI_SH_POLICY                policySession
                                                     Auth Index: None

                                                     YES if NV Index is required to have been written
TPMI_YES_NO                   writtenSet
                                                     NO if NV Index is required not to have been written


                          Table 148 — TPM2_PolicyNvWritten Response
Type                          Name                   Description

TPM_ST                        tag                    see clause 6
UINT32                        responseSize
TPM_RC                        responseCode


Family “2.0”                                  TCG Published                                         Page 305
Level 00 Revision 01.16             Copyright © TCG 2006-2014                            October 30, 2014
     Part 3: Commands                                                              Trusted Platform Module Library


     23.20.3    Detailed Actions

1    #include "InternalRoutines.h"
2    #include "PolicyNvWritten_fp.h"
3    #ifdef TPM_CC_PolicyNvWritten // Conditional expansion of this file

     Make an NV Index policy dependent on the state of the TPMA_NV_WRITTEN attribute of the index.

     Error Returns                   Meaning

     TPM_RC_VALUE                    a conflicting request for the attribute has already been processed

 4   TPM_RC
 5   TPM2_PolicyNvWritten(
 6       PolicyNvWritten_In    *in                 // IN: input parameter list
 7       )
 8   {
 9       SESSION      *session;
10       TPM_CC        commandCode = TPM_CC_PolicyNvWritten;
11       HASH_STATE    hashState;
12
13   // Input Validation
14
15       // Get pointer to the session structure
16       session = SessionGet(in->policySession);
17
18       // If already set is this a duplicate (the same setting)? If it
19       // is a conflicting setting, it is an error
20       if(session->attributes.checkNvWritten == SET)
21       {
22           if((    (session->attributes.nvWrittenState == SET)
23               != (in->writtenSet == YES)))
24               return TPM_RC_VALUE + RC_PolicyNvWritten_writtenSet;
25       }
26
27   // Internal Data Update
28
29       // Set session attributes so that the NV Index needs to be checked
30       session->attributes.checkNvWritten = SET;
31       session->attributes.nvWrittenState = (in->writtenSet == YES);
32
33       // Update policy hash
34       // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyNvWritten
35       //                          || writtenSet)
36       // Start hash
37       CryptStartHash(session->authHashAlg, &hashState);
38
39       // add old digest
40       CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b);
41
42       // add commandCode
43       CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode);
44
45       // add the byte of writtenState
46       CryptUpdateDigestInt(&hashState, sizeof(TPMI_YES_NO), &in->writtenSet);
47
48       // complete the digest
49       CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b);
50
51       return TPM_RC_SUCCESS;
52   }
53   #endif // CC_PolicyNvWritten


     Page 306                                     TCG Published                                           Family “2.0”
     October 30, 2014                    Copyright © TCG 2006-2014                        Level 00 Revision 01.16
Trusted Platform Module Library                               Part 3: Commands


Family “2.0”                           TCG Published                 Page 307
Level 00 Revision 01.16           Copyright © TCG 2006-2014   October 30, 2014
Part 3: Commands                                                           Trusted Platform Module Library


24     Hierarchy Commands

24.1     TPM2_CreatePrimary

24.1.1 General Description

This command is used to create a Primary Object under one of the Primary Seeds or a Temporary Object
under TPM_RH_NULL. The command uses a TPM2B_PUBLIC as a template for the object to be created.
The command will create and load a Primary Object. The sensitive area is not returned.

NOTE 1:         Since the sensitive data is not returned, the key cannot be reloaded.   It can either be made
                persistent or it can be recreated.

Any type of object and attributes combination that is allowed by TPM2_Create() may be created by this
command. The constraints on templates and parameters are the same as TPM2_Create() except that a
Primary Storage Key and a Temporary Storage Key are not constrained to use the algorithms of their
parents.
For setting of the attributes of the created object, fixedParent, fixedTPM, decrypt, and restricted are
implied to be SET in the parent (a Permanent Handle). The remaining attributes are implied to be CLEAR.
The TPM will derive the object from the Primary Seed indicated in primaryHandle using an approved
KDF. All of the bits of the template are used in the creation of the Primary Key. Methods for creating a
Primary Object from a Primary Seed are described in TPM 2.0 Part 1 and implemented in TPM 2.0 Part 4.
If this command is called multiple times with the same inPublic parameter, inSensitive.data, and Primary
Seed, the TPM shall produce the same Primary Object.

NOTE 2          If the Primary Seed is changed, the Primary Objects generated with the new seed shall be
                statistically unique even if the parameters of the call are the same.

This command requires authorization. Authorization for a Primary Object attached to the Platform Primary
Seed (PPS) shall be provided by platformAuth or platformPolicy. Authorization for a Primary Object
attached to the Storage Primary Seed (SPS) shall be provided by ownerAuth or ownerPolicy.
Authorization for a Primary Key attached to the Endorsement Primary Seed (EPS) shall be provided by
endorsementAuth or endorsementPolicy.


Page 308                                     TCG Published                                      Family “2.0”
October 30, 2014                     Copyright © TCG 2006-2014                    Level 00 Revision 01.16
Trusted Platform Module Library                                                          Part 3: Commands


24.1.2 Command and Response

                           Table 149 — TPM2_CreatePrimary Command
Type                          Name                  Description

TPMI_ST_COMMAND_TAG           tag                   TPM_ST_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode           TPM_CC_CreatePrimary

                                                    TPM_RH_ENDORSEMENT, TPM_RH_OWNER,
                                                    TPM_RH_PLATFORM+{PP}, or TPM_RH_NULL
TPMI_RH_HIERARCHY+            @primaryHandle
                                                    Auth Index: 1
                                                    Auth Role: USER

TPM2B_SENSITIVE_CREATE        inSensitive           the sensitive data, see TPM 2.0 Part 1 Sensitive Values
TPM2B_PUBLIC                  inPublic              the public template
                                                    data that will be included in the creation data for this
TPM2B_DATA                    outsideInfo           object to provide permanent, verifiable linkage between
                                                    this object and some object owner data
TPML_PCR_SELECTION            creationPCR           PCR that will be used in creation data


                           Table 150 — TPM2_CreatePrimary Response
Type                          Name                  Description

TPM_ST                        tag                   see clause 6
UINT32                        responseSize
TPM_RC                        responseCode

                                                    handle of type TPM_HT_TRANSIENT for created
TPM_HANDLE                    objectHandle
                                                    Primary Object

TPM2B_PUBLIC                  outPublic             the public portion of the created object
TPM2B_CREATION_DATA           creationData          contains a TPMT_CREATION_DATA
TPM2B_DIGEST                  creationHash          digest of creationData using nameAlg of outPublic
                                                    ticket used by TPM2_CertifyCreation() to validate that
TPMT_TK_CREATION              creationTicket
                                                    the creation data was produced by the TPM
TPM2B_NAME                    name                  the name of the created object


Family “2.0”                                 TCG Published                                        Page 309
Level 00 Revision 01.16              Copyright © TCG 2006-2014                           October 30, 2014
     Part 3: Commands                                                               Trusted Platform Module Library


     24.1.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "CreatePrimary_fp.h"
3    #ifdef TPM_CC_CreatePrimary // Conditional expansion of this file
4    #include "Object_spt_fp.h"
5    #include <Platform.h>


     Error Returns                  Meaning

     TPM_RC_ATTRIBUTES              sensitiveDataOrigin is CLEAR when 'sensitive.data' is an Empty
                                    Buffer, or is SET when 'sensitive.data' is not empty; fixedTPM,
                                    fixedParent, or encryptedDuplication attributes are inconsistent
                                    between themselves or with those of the parent object; inconsistent
                                    restricted, decrypt and sign attributes; attempt to inject sensitive data
                                    for an asymmetric key; attempt to create a symmetric cipher key that
                                    is not a decryption key
     TPM_RC_KDF                     incorrect KDF specified for decrypting keyed hash object
     TPM_RC_OBJECT_MEMORY           there is no free slot for the object
     TPM_RC_SCHEME                  inconsistent attributes decrypt, sign, restricted and key's scheme ID;
                                    or hash algorithm is inconsistent with the scheme ID for keyed hash
                                    object
     TPM_RC_SIZE                    size of public auth policy or sensitive auth value does not match
                                    digest size of the name algorithm sensitive data size for the keyed
                                    hash object is larger than is allowed for the scheme
     TPM_RC_SYMMETRIC               a storage key with no symmetric algorithm specified; or non-storage
                                    key with symmetric algorithm different from TPM_ALG_NULL
     TPM_RC_TYPE                    unknown object type;

 6   TPM_RC
 7   TPM2_CreatePrimary(
 8       CreatePrimary_In    *in,                  // IN: input parameter list
 9       CreatePrimary_Out   *out                  // OUT: output parameter list
10       )
11   {
12   // Local variables
13       TPM_RC              result = TPM_RC_SUCCESS;
14       TPMT_SENSITIVE      sensitive;
15
16   // Input Validation
17       // The sensitiveDataOrigin attribute must be consistent with the setting of
18       // the size of the data object in inSensitive.
19       if(   (in->inPublic.t.publicArea.objectAttributes.sensitiveDataOrigin == SET)
20          != (in->inSensitive.t.sensitive.data.t.size == 0 ))
21           // Mismatch between the object attributes and the parameter.
22           return TPM_RC_ATTRIBUTES + RC_CreatePrimary_inSensitive;
23
24       // Check attributes in input public area. TPM_RC_ATTRIBUTES, TPM_RC_KDF,
25       // TPM_RC_SCHEME, TPM_RC_SIZE, TPM_RC_SYMMETRIC, or TPM_RC_TYPE error may
26       // be returned at this point.
27       result = PublicAttributesValidation(FALSE, in->primaryHandle,
28                                           &in->inPublic.t.publicArea);
29       if(result != TPM_RC_SUCCESS)
30           return RcSafeAddToResult(result, RC_CreatePrimary_inPublic);
31
32       // Validate the sensitive area values
33       if( MemoryRemoveTrailingZeros(&in->inSensitive.t.sensitive.userAuth)
34               > CryptGetHashDigestSize(in->inPublic.t.publicArea.nameAlg))


     Page 310                                     TCG Published                                            Family “2.0”
     October 30, 2014                    Copyright © TCG 2006-2014                         Level 00 Revision 01.16
     Trusted Platform Module Library                                                Part 3: Commands

35           return TPM_RC_SIZE + RC_CreatePrimary_inSensitive;
36
37   // Command output
38
39       // Generate Primary Object
40       // The primary key generation process uses the Name of the input public
41       // template to compute the key. The keys are generated from the template
42       // before anything in the template is allowed to be changed.
43       // A TPM_RC_KDF, TPM_RC_SIZE error may be returned at this point
44       result = CryptCreateObject(in->primaryHandle, &in->inPublic.t.publicArea,
45                                  &in->inSensitive.t.sensitive,&sensitive);
46       if(result != TPM_RC_SUCCESS)
47           return result;
48
49       // Fill in creation data
50       FillInCreationData(in->primaryHandle, in->inPublic.t.publicArea.nameAlg,
51                          &in->creationPCR, &in->outsideInfo, &out->creationData,
52                          &out->creationHash);
53
54       // Copy public area
55       out->outPublic = in->inPublic;
56
57       // Fill in private area for output
58       ObjectComputeName(&(out->outPublic.t.publicArea), &out->name);
59
60       // Compute creation ticket
61       TicketComputeCreation(EntityGetHierarchy(in->primaryHandle), &out->name,
62                             &out->creationHash, &out->creationTicket);
63
64       // Create a internal object. A TPM_RC_OBJECT_MEMORY error may be returned
65       // at this point.
66       result = ObjectLoad(in->primaryHandle, &in->inPublic.t.publicArea, &sensitive,
67                           &out->name, in->primaryHandle, TRUE, &out->objectHandle);
68
69       return result;
70   }
71   #endif // CC_CreatePrimary


     Family “2.0”                           TCG Published                                  Page 311
     Level 00 Revision 01.16           Copyright © TCG 2006-2014                    October 30, 2014
Part 3: Commands                                                           Trusted Platform Module Library


24.2   TPM2_HierarchyControl

24.2.1 General Description

This command enables and disables use of a hierarchy and its associated NV storage. The command
allows phEnable, phEnableNV, shEnable, and ehEnable to be changed when the proper authorization is
provided.
This command may be used to CLEAR phEnable and phEnableNV if platformAuth/platformPolicy is
provided. phEnable may not be SET using this command.
This command may be used to CLEAR shEnable if either platformAuth/platformPolicy                          or
ownerAuth/ownerPolicy is provided. shEnable may be SET if platformAuth/platformPolicy is provided.
This command may be used to CLEAR ehEnable if either platformAuth/platformPolicy or
endorsementAuth/endorsementPolicy is provided. ehEnable may be SET if platformAuth/platformPolicy is
provided.
When this command is used to CLEAR phEnable, shEnable, or ehEnable, the TPM will disable use of
any persistent entity associated with the disabled hierarchy and will flush any transient objects associated
with the disabled hierarchy.
When this command is used to CLEAR shEnable, the TPM will disable access to any NV index that has
TPMA_NV_PLATFORMCREATE CLEAR (indicating that the NV Index was defined using Owner
Authorization). As long as shEnable is CLEAR, the TPM will return an error in response to any command
that attempts to operate upon an NV index that has TPMA_NV_PLATFORMCREATE CLEAR.
When this command is used to CLEAR phEnableNV, the TPM will disable access to any NV index that
has TPMA_NV_PLATFORMCREATE SET (indicating that the NV Index was defined using Platform
Authorization). As long as phEnableNV is CLEAR, the TPM will return an error in response to any
command that attempts to operate upon an NV index that has TPMA_NV_PLATFORMCREATE SET.


Page 312                                     TCG Published                                    Family “2.0”
October 30, 2014                     Copyright © TCG 2006-2014                   Level 00 Revision 01.16
Trusted Platform Module Library                                                        Part 3: Commands


24.2.2 Command and Response

                          Table 151 — TPM2_HierarchyControl Command
Type                          Name                  Description

TPMI_ST_COMMAND_TAG           tag                   TPM_ST_SESSIONS

UINT32                        commandSize

TPM_CC                        commandCode           TPM_CC_HierarchyControl {NV E}

                                                    TPM_RH_ENDORSEMENT, TPM_RH_OWNER or
                                                    TPM_RH_PLATFORM+{PP}
TPMI_RH_HIERARCHY             @authHandle
                                                    Auth Index: 1
                                                    Auth Role: USER

                                                    the enable being modified
TPMI_RH_ENABLES               enable                TPM_RH_ENDORSEMENT, TPM_RH_OWNER,
                                                    TPM_RH_PLATFORM, or TPM_RH_PLATFORM_NV
                                                    YES if the enable should be SET, NO if the enable
TPMI_YES_NO                   state
                                                    should be CLEAR


                          Table 152 — TPM2_HierarchyControl Response
Type                          Name                  Description

TPM_ST                        tag                   see clause 6

UINT32                        responseSize

TPM_RC                        responseCode


Family “2.0”                                 TCG Published                                      Page 313
Level 00 Revision 01.16               Copyright © TCG 2006-2014                        October 30, 2014
     Part 3: Commands                                                           Trusted Platform Module Library


     24.2.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "HierarchyControl_fp.h"
3    #ifdef TPM_CC_HierarchyControl // Conditional expansion of this file


     Error Returns               Meaning

     TPM_RC_AUTH_TYPE            authHandle is not applicable to hierarchy in its current state

 4   TPM_RC
 5   TPM2_HierarchyControl(
 6       HierarchyControl_In    *in                 // IN: input parameter list
 7       )
 8   {
 9       TPM_RC      result;
10       BOOL        select = (in->state == YES);
11       BOOL        *selected = NULL;
12
13   // Input Validation
14       switch(in->enable)
15       {
16           // Platform hierarchy has to be disabled by platform auth
17           // If the platform hierarchy has already been disabled, only a reboot
18           // can enable it again
19           case TPM_RH_PLATFORM:
20           case TPM_RH_PLATFORM_NV:
21               if(in->authHandle != TPM_RH_PLATFORM)
22                   return TPM_RC_AUTH_TYPE;
23               break;
24
25           // ShEnable may be disabled if PlatformAuth/PlatformPolicy or
26           // OwnerAuth/OwnerPolicy is provided. If ShEnable is disabled, then it
27           // may only be enabled if PlatformAuth/PlatformPolicy is provided.
28           case TPM_RH_OWNER:
29               if(   in->authHandle != TPM_RH_PLATFORM
30                  && in->authHandle != TPM_RH_OWNER)
31                   return TPM_RC_AUTH_TYPE;
32               if(   gc.shEnable == FALSE && in->state == YES
33                  && in->authHandle != TPM_RH_PLATFORM)
34                   return TPM_RC_AUTH_TYPE;
35               break;
36
37           // EhEnable may be disabled if either PlatformAuth/PlatformPolicy or
38           // EndosementAuth/EndorsementPolicy is provided. If EhEnable is disabled,
39           // then it may only be enabled if PlatformAuth/PlatformPolicy is
40           // provided.
41           case TPM_RH_ENDORSEMENT:
42               if(   in->authHandle != TPM_RH_PLATFORM
43                  && in->authHandle != TPM_RH_ENDORSEMENT)
44                   return TPM_RC_AUTH_TYPE;
45               if(   gc.ehEnable == FALSE && in->state == YES
46                  && in->authHandle != TPM_RH_PLATFORM)
47                   return TPM_RC_AUTH_TYPE;
48               break;
49           default:
50               pAssert(FALSE);
51               break;
52       }
53
54   // Internal Data Update
55
56       // Enable or disable the selected hierarchy

     Page 314                                 TCG Published                                       Family “2.0”
     October 30, 2014                 Copyright © TCG 2006-2014                        Level 00 Revision 01.16
      Trusted Platform Module Library                                             Part 3: Commands

 57       // Note: the authorization processing for this command may keep these
 58       // command actions from being executed. For example, if phEnable is
 59       // CLEAR, then platformAuth cannot be used for authorization. This
 60       // means that would not be possible to use platformAuth to change the
 61       // state of phEnable from CLEAR to SET.
 62       // If it is decided that platformPolicy can still be used when phEnable
 63       // is CLEAR, then this code could SET phEnable when proper platform
 64       // policy is provided.
 65       switch(in->enable)
 66       {
 67           case TPM_RH_OWNER:
 68               selected = &gc.shEnable;
 69               break;
 70           case TPM_RH_ENDORSEMENT:
 71               selected = &gc.ehEnable;
 72               break;
 73           case TPM_RH_PLATFORM:
 74               selected = &g_phEnable;
 75               break;
 76           case TPM_RH_PLATFORM_NV:
 77               selected = &gc.phEnableNV;
 78               break;
 79           default:
 80               pAssert(FALSE);
 81               break;
 82       }
 83       if(selected != NULL && *selected != select)
 84       {
 85           // Before changing the internal state, make sure that NV is available.
 86           // Only need to update NV if changing the orderly state
 87           if(gp.orderlyState != SHUTDOWN_NONE)
 88           {
 89               // The command needs NV update. Check if NV is available.
 90               // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
 91               // this point
 92               result = NvIsAvailable();
 93               if(result != TPM_RC_SUCCESS)
 94                   return result;
 95           }
 96           // state is changing and NV is available so modify
 97           *selected = select;
 98           // If a hierarchy was just disabled, flush it
 99           if(select == CLEAR && in->enable != TPM_RH_PLATFORM_NV)
100           // Flush hierarchy
101               ObjectFlushHierarchy(in->enable);
102
103           // orderly state should be cleared because of the update to state clear data
104           // This gets processed in ExecuteCommand() on the way out.
105           g_clearOrderly = TRUE;
106       }
107       return TPM_RC_SUCCESS;
108   }
109   #endif // CC_HierarchyControl


      Family “2.0”                           TCG Published                                   Page 315
      Level 00 Revision 01.16           Copyright © TCG 2006-2014                 October 30, 2014
Part 3: Commands                                                        Trusted Platform Module Library


24.3   TPM2_SetPrimaryPolicy

24.3.1 General Description

This command allows setting of the authorization policy for the lockout (lockoutPolicy), the platform
hierarchy (platformPolicy), the storage hierarchy (ownerPolicy), and the endorsement hierarchy
(endorsementPolicy).
The command requires an authorization session. The session shall use the current authValue or satisfy
the current authPolicy for the referenced hierarchy.
The policy that is changed is the policy associated with authHandle.
If the enable associated with authHandle is not SET, then the associated authorization values (authValue
or authPolicy) may not be used.


Page 316                                    TCG Published                                  Family “2.0”
October 30, 2014                     Copyright © TCG 2006-2014                Level 00 Revision 01.16
Trusted Platform Module Library                                                           Part 3: Commands


24.3.2 Command and Response

                          Table 153 — TPM2_SetPrimaryPolicy Command
Type                          Name                  Description

TPMI_ST_COMMAND_TAG           tag                   TPM_ST_SESSIONS

UINT32                        commandSize

TPM_CC                        commandCode           TPM_CC_SetPrimaryPolicy {NV}

                                                    TPM_RH_LOCKOUT, TPM_RH_ENDORSEMENT,
                                                    TPM_RH_OWNER or TPM_RH_PLATFORM+{PP}
TPMI_RH_HIERARCHY_AUTH        @authHandle
                                                    Auth Index: 1
                                                    Auth Role: USER

                                                    an authorization policy digest; may be the Empty Buffer
TPM2B_DIGEST                  authPolicy            If hashAlg is TPM_ALG_NULL, then this shall be an
                                                    Empty Buffer.
                                                    the hash algorithm to use for the policy
TPMI_ALG_HASH+                hashAlg               If the authPolicy is an Empty Buffer, then this field shall
                                                    be TPM_ALG_NULL.


                          Table 154 — TPM2_SetPrimaryPolicy Response
Type                          Name                  Description

TPM_ST                        tag                   see clause 6

UINT32                        responseSize

TPM_RC                        responseCode


Family “2.0”                                 TCG Published                                          Page 317
Level 00 Revision 01.16             Copyright © TCG 2006-2014                             October 30, 2014
     Part 3: Commands                                                           Trusted Platform Module Library


     24.3.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "SetPrimaryPolicy_fp.h"
3    #ifdef TPM_CC_SetPrimaryPolicy // Conditional expansion of this file


     Error Returns               Meaning

     TPM_RC_SIZE                 size of input authPolicy is not consistent with input hash algorithm

 4   TPM_RC
 5   TPM2_SetPrimaryPolicy(
 6       SetPrimaryPolicy_In    *in                 // IN: input parameter list
 7       )
 8   {
 9       TPM_RC                  result;
10
11   // Input Validation
12
13       // Check the authPolicy consistent with hash algorithm. If the policy size is
14       // zero, then the algorithm is required to be TPM_ALG_NULL
15       if(in->authPolicy.t.size != CryptGetHashDigestSize(in->hashAlg))
16           return TPM_RC_SIZE + RC_SetPrimaryPolicy_authPolicy;
17
18       // The command need NV update for OWNER and ENDORSEMENT hierarchy, and
19       // might need orderlyState update for PLATFROM hierarchy.
20       // Check if NV is available. A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE
21       // error may be returned at this point
22       result = NvIsAvailable();
23       if(result != TPM_RC_SUCCESS)
24           return result;
25
26   // Internal Data Update
27
28       // Set hierarchy policy
29       switch(in->authHandle)
30       {
31           case TPM_RH_OWNER:
32               gp.ownerAlg = in->hashAlg;
33               gp.ownerPolicy = in->authPolicy;
34               NvWriteReserved(NV_OWNER_ALG, &gp.ownerAlg);
35               NvWriteReserved(NV_OWNER_POLICY, &gp.ownerPolicy);
36               break;
37           case TPM_RH_ENDORSEMENT:
38               gp.endorsementAlg = in->hashAlg;
39               gp.endorsementPolicy = in->authPolicy;
40               NvWriteReserved(NV_ENDORSEMENT_ALG, &gp.endorsementAlg);
41               NvWriteReserved(NV_ENDORSEMENT_POLICY, &gp.endorsementPolicy);
42               break;
43           case TPM_RH_PLATFORM:
44               gc.platformAlg = in->hashAlg;
45               gc.platformPolicy = in->authPolicy;
46               // need to update orderly state
47               g_clearOrderly = TRUE;
48               break;
49           case TPM_RH_LOCKOUT:
50               gp.lockoutAlg = in->hashAlg;
51               gp.lockoutPolicy = in->authPolicy;
52               NvWriteReserved(NV_LOCKOUT_ALG, &gp.lockoutAlg);
53               NvWriteReserved(NV_LOCKOUT_POLICY, &gp.lockoutPolicy);
54               break;
55
56           default:

     Page 318                                 TCG Published                                             Family “2.0”
     October 30, 2014                 Copyright © TCG 2006-2014                        Level 00 Revision 01.16
     Trusted Platform Module Library                               Part 3: Commands

57                pAssert(FALSE);
58                break;
59       }
60
61       return TPM_RC_SUCCESS;
62   }
63   #endif // CC_SetPrimaryPolicy


     Family “2.0”                           TCG Published                 Page 319
     Level 00 Revision 01.16           Copyright © TCG 2006-2014   October 30, 2014
Part 3: Commands                                                              Trusted Platform Module Library


24.4     TPM2_ChangePPS

24.4.1 General Description

This replaces the current PPS with a value from the RNG and sets platformPolicy to the default
initialization value (the Empty Buffer).

NOTE 1          A policy that is the Empty Buffer can match no policy.

NOTE 2          Platform Authorization is not changed.

All resident transient and persistent objects in the Platform hierarchy are flushed.
Saved contexts in the Platform hierarchy that were created under the old PPS will no longer be able to be
loaded.
The policy hash algorithm for PCR is reset to TPM_ALG_NULL.
This command does not clear any NV Index values.

NOTE 3          Index values belonging to the Platform are preserved because the indexes may have configuration
                information that will be the same after the PPS changes. The Platform may remove the indexes that
                are no longer needed using TPM2_NV_UndefineSpace().

This command requires Platform Authorization.


Page 320                                       TCG Published                                       Family “2.0”
October 30, 2014                       Copyright © TCG 2006-2014                    Level 00 Revision 01.16
Trusted Platform Module Library                                             Part 3: Commands


24.4.2 Command and Response

                            Table 155 — TPM2_ChangePPS Command
 Type                         Name                Description

 TPMI_ST_COMMAND_TAG          tag                 TPM_ST_SESSIONS
 UINT32                       commandSize
 TPM_CC                       commandCode         TPM_CC_ChangePPS {NV E}

                                                  TPM_RH_PLATFORM+{PP}
 TPMI_RH_PLATFORM             @authHandle         Auth Index: 1
                                                  Auth Role: USER


                             Table 156 — TPM2_ChangePPS Response
 Type                         Name                Description
 TPM_ST                       tag                 see clause 6
 UINT32                       responseSize
 TPM_RC                       responseCode


Family “2.0”                             TCG Published                             Page 321
Level 00 Revision 01.16             Copyright © TCG 2006-2014               October 30, 2014
     Part 3: Commands                                                  Trusted Platform Module Library


     24.4.3 Detailed Actions

 1   #include "InternalRoutines.h"
 2   #include "ChangePPS_fp.h"
 3   #ifdef TPM_CC_ChangePPS // Conditional expansion of this file
 4   TPM_RC
 5   TPM2_ChangePPS(
 6       ChangePPS_In   *in             // IN: input parameter list
 7       )
 8   {
 9       UINT32         i;
10       TPM_RC         result;
11
12       // Check if NV is available. A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE
13       // error may be returned at this point
14       result = NvIsAvailable();
15       if(result != TPM_RC_SUCCESS) return result;
16
17       // Input parameter is not reference in command action
18       in = NULL;
19
20   // Internal Data Update
21
22       // Reset platform hierarchy seed from RNG
23       CryptGenerateRandom(PRIMARY_SEED_SIZE, gp.PPSeed.t.buffer);
24
25       // Create a new phProof value from RNG to prevent the saved platform
26       // hierarchy contexts being loaded
27       CryptGenerateRandom(PROOF_SIZE, gp.phProof.t.buffer);
28
29       // Set platform authPolicy to null
30       gc.platformAlg = TPM_ALG_NULL;
31       gc.platformPolicy.t.size = 0;
32
33       // Flush loaded object in platform hierarchy
34       ObjectFlushHierarchy(TPM_RH_PLATFORM);
35
36       // Flush platform evict object and index in NV
37       NvFlushHierarchy(TPM_RH_PLATFORM);
38
39       // Save hierarchy changes to NV
40       NvWriteReserved(NV_PP_SEED, &gp.PPSeed);
41       NvWriteReserved(NV_PH_PROOF, &gp.phProof);
42
43       // Re-initialize PCR policies
44       for(i = 0; i < NUM_POLICY_PCR_GROUP; i++)
45       {
46           gp.pcrPolicies.hashAlg[i] = TPM_ALG_NULL;
47           gp.pcrPolicies.policy[i].t.size = 0;
48       }
49       NvWriteReserved(NV_PCR_POLICIES, &gp.pcrPolicies);
50
51       // orderly state should be cleared because of the update to state clear data
52       g_clearOrderly = TRUE;
53
54       return TPM_RC_SUCCESS;
55   }
56   #endif // CC_ChangePPS


     Page 322                                 TCG Published                              Family “2.0”
     October 30, 2014                Copyright © TCG 2006-2014              Level 00 Revision 01.16
Trusted Platform Module Library                                                                Part 3: Commands


24.5   TPM2_ChangeEPS

24.5.1 General Description

This replaces the current EPS with a value from the RNG and sets the Endorsement hierarchy controls to
their default initialization values: ehEnable is SET, endorsementAuth and endorsementPolicy both equal
to the Empty Buffer. It will flush any resident objects (transient or persistent) in the EPS hierarchy and not
allow objects in the hierarchy associated with the previous EPS to be loaded.

NOTE            In the reference implementation, ehProof is a non-volatile value from the RNG. It is allowed that the
                ehProof be generated by a KDF using both the EPS and SPS as inputs. If generated with a KDF, the
                ehProof can be generated on an as-needed basis or made a non-volatile value.

This command requires Platform Authorization.


Family “2.0”                                   TCG Published                                             Page 323
Level 00 Revision 01.16                Copyright © TCG 2006-2014                               October 30, 2014
Part 3: Commands                                           Trusted Platform Module Library


24.5.2 Command and Response

                       Table 157 — TPM2_ChangeEPS Command
 Type                   Name                Description

 TPMI_ST_COMMAND_TAG    tag                 TPM_ST_SESSIONS
 UINT32                 commandSize
 TPM_CC                 commandCode         TPM_CC_ChangeEPS {NV E}

                                            TPM_RH_PLATFORM+{PP}
 TPMI_RH_PLATFORM       @authHandle         Auth Handle: 1
                                            Auth Role: USER


                       Table 158 — TPM2_ChangeEPS Response
 Type                   Name                Description
 TPM_ST                 tag                 see clause 6
 UINT32                 responseSize
 TPM_RC                 responseCode


Page 324                           TCG Published                             Family “2.0”
October 30, 2014              Copyright © TCG 2006-2014         Level 00 Revision 01.16
     Trusted Platform Module Library                                             Part 3: Commands


     24.5.3 Detailed Actions

 1   #include "InternalRoutines.h"
 2   #include "ChangeEPS_fp.h"
 3   #ifdef TPM_CC_ChangeEPS // Conditional expansion of this file
 4   TPM_RC
 5   TPM2_ChangeEPS(
 6       ChangeEPS_In     *in              // IN: input parameter list
 7       )
 8   {
 9       TPM_RC           result;
10
11       // The command needs NV update. Check if NV is available.
12       // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
13       // this point
14       result = NvIsAvailable();
15       if(result != TPM_RC_SUCCESS) return result;
16
17       // Input parameter is not reference in command action
18       in = NULL;
19
20   // Internal Data Update
21
22       // Reset endorsement hierarchy seed from RNG
23       CryptGenerateRandom(PRIMARY_SEED_SIZE, gp.EPSeed.t.buffer);
24
25       // Create new ehProof value from RNG
26       CryptGenerateRandom(PROOF_SIZE, gp.ehProof.t.buffer);
27
28       // Enable endorsement hierarchy
29       gc.ehEnable = TRUE;
30
31       // set authValue buffer to zeros
32       MemorySet(gp.endorsementAuth.t.buffer, 0, gp.endorsementAuth.t.size);
33       // Set endorsement authValue to null
34       gp.endorsementAuth.t.size = 0;
35
36       // Set endorsement authPolicy to null
37       gp.endorsementAlg = TPM_ALG_NULL;
38       gp.endorsementPolicy.t.size = 0;
39
40       // Flush loaded object in endorsement hierarchy
41       ObjectFlushHierarchy(TPM_RH_ENDORSEMENT);
42
43       // Flush evict object of endorsement hierarchy stored in NV
44       NvFlushHierarchy(TPM_RH_ENDORSEMENT);
45
46       // Save hierarchy changes to NV
47       NvWriteReserved(NV_EP_SEED, &gp.EPSeed);
48       NvWriteReserved(NV_EH_PROOF, &gp.ehProof);
49       NvWriteReserved(NV_ENDORSEMENT_AUTH, &gp.endorsementAuth);
50       NvWriteReserved(NV_ENDORSEMENT_ALG, &gp.endorsementAlg);
51       NvWriteReserved(NV_ENDORSEMENT_POLICY, &gp.endorsementPolicy);
52
53       // orderly state should be cleared because of the update to state clear data
54       g_clearOrderly = TRUE;
55
56       return TPM_RC_SUCCESS;
57   }
58   #endif // CC_ChangeEPS


     Family “2.0”                             TCG Published                             Page 325
     Level 00 Revision 01.16           Copyright © TCG 2006-2014                 October 30, 2014
Part 3: Commands                                                              Trusted Platform Module Library


24.6    TPM2_Clear

24.6.1 General Description

This command removes all TPM context associated with a specific Owner.
The clear operation will:
       flush resident objects (persistent and volatile) in the Storage and Endorsement hierarchies;
       delete any NV Index with TPMA_NV_PLATFORMCREATE == CLEAR;
       change the SPS to a new value from the TPM’s random number generator (RNG),
       change shProof and ehProof,

    NOTE             The proof values may be set from the RNG or derived from the associated new Primary Seed. If
                     derived from the Primary Seeds, the derivation of ehProof shall use both the SPS and EPS. The
                     computation shall use the SPS as an HMAC key and the derived value may then be a parameter
                     in a second HMAC in which the EPS is the HMAC key. The reference design uses values from
                     the RNG.

       SET shEnable and ehEnable;
       set ownerAuth, endorsementAuth, and lockoutAuth to the Empty Buffer;
       set ownerPolicy, endorsementPolicy, and lockoutPolicy to the Empty Buffer;
       set Clock to zero;
       set resetCount to zero;
       set restartCount to zero; and
       set Safe to YES.
This command requires Platform Authorization or Lockout Authorization. If TPM2_ClearControl() has
disabled this command, the TPM shall return TPM_RC_DISABLED.
If this command is authorized using lockoutAuth, the HMAC in the response shall use the new
lockoutAuth value (that is, the Empty Buffer) when computing response HMAC.


Page 326                                       TCG Published                                       Family “2.0”
October 30, 2014                        Copyright © TCG 2006-2014                    Level 00 Revision 01.16
Trusted Platform Module Library                                             Part 3: Commands


24.6.2 Command and Response

                                  Table 159 — TPM2_Clear Command
 Type                         Name                 Description

 TPMI_ST_COMMAND_TAG          tag                  TPM_ST_SESSIONS
 UINT32                       commandSize
 TPM_CC                       commandCode          TPM_CC_Clear {NV E}

                                                   TPM_RH_LOCKOUT or TPM_RH_PLATFORM+{PP}
 TPMI_RH_CLEAR                @authHandle          Auth Handle: 1
                                                   Auth Role: USER


                                  Table 160 — TPM2_Clear Response
 Type                         Name                 Description
 TPM_ST                       tag                  see clause 6
 UINT32                       responseSize
 TPM_RC                       responseCode


Family “2.0”                              TCG Published                            Page 327
Level 00 Revision 01.16             Copyright © TCG 2006-2014               October 30, 2014
     Part 3: Commands                                                       Trusted Platform Module Library


     24.6.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "Clear_fp.h"
3    #ifdef TPM_CC_Clear // Conditional expansion of this file


     Error Returns                   Meaning

     TPM_RC_DISABLED                 Clear command has been disabled

 4   TPM_RC
 5   TPM2_Clear(
 6       Clear_In          *in                // IN: input parameter list
 7       )
 8   {
 9       TPM_RC                  result;
10
11       // Input parameter is not reference in command action
12       in = NULL;
13
14       // The command needs NV update. Check if NV is available.
15       // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
16       // this point
17       result = NvIsAvailable();
18       if(result != TPM_RC_SUCCESS) return result;
19
20   // Input Validation
21
22       // If Clear command is disabled, return an error
23       if(gp.disableClear)
24           return TPM_RC_DISABLED;
25
26   // Internal Data Update
27
28       // Reset storage hierarchy seed from RNG
29       CryptGenerateRandom(PRIMARY_SEED_SIZE, gp.SPSeed.t.buffer);
30
31       // Create new shProof and ehProof value from RNG
32       CryptGenerateRandom(PROOF_SIZE, gp.shProof.t.buffer);
33       CryptGenerateRandom(PROOF_SIZE, gp.ehProof.t.buffer);
34
35       // Enable storage and endorsement hierarchy
36       gc.shEnable = gc.ehEnable = TRUE;
37
38       // set the authValue buffers to zero
39       MemorySet(gp.ownerAuth.t.buffer, 0, gp.ownerAuth.t.size);
40       MemorySet(gp.endorsementAuth.t.buffer, 0, gp.endorsementAuth.t.size);
41       MemorySet(gp.lockoutAuth.t.buffer, 0, gp.lockoutAuth.t.size);
42       // Set storage, endorsement and lockout authValue to null
43       gp.ownerAuth.t.size = gp.endorsementAuth.t.size = gp.lockoutAuth.t.size = 0;
44
45       // Set storage, endorsement, and lockout authPolicy to null
46       gp.ownerAlg = gp.endorsementAlg = gp.lockoutAlg = TPM_ALG_NULL;
47       gp.ownerPolicy.t.size = 0;
48       gp.endorsementPolicy.t.size = 0;
49       gp.lockoutPolicy.t.size = 0;
50
51       // Flush loaded object in storage and endorsement hierarchy
52       ObjectFlushHierarchy(TPM_RH_OWNER);
53       ObjectFlushHierarchy(TPM_RH_ENDORSEMENT);
54
55       // Flush owner and endorsement object and owner index in NV
56       NvFlushHierarchy(TPM_RH_OWNER);

     Page 328                                    TCG Published                                Family “2.0”
     October 30, 2014                      Copyright © TCG 2006-2014             Level 00 Revision 01.16
     Trusted Platform Module Library                                             Part 3: Commands

57       NvFlushHierarchy(TPM_RH_ENDORSEMENT);
58
59       // Save hierarchy changes to NV
60       NvWriteReserved(NV_SP_SEED, &gp.SPSeed);
61       NvWriteReserved(NV_SH_PROOF, &gp.shProof);
62       NvWriteReserved(NV_EH_PROOF, &gp.ehProof);
63       NvWriteReserved(NV_OWNER_AUTH, &gp.ownerAuth);
64       NvWriteReserved(NV_ENDORSEMENT_AUTH, &gp.endorsementAuth);
65       NvWriteReserved(NV_LOCKOUT_AUTH, &gp.lockoutAuth);
66       NvWriteReserved(NV_OWNER_ALG, &gp.ownerAlg);
67       NvWriteReserved(NV_ENDORSEMENT_ALG, &gp.endorsementAlg);
68       NvWriteReserved(NV_LOCKOUT_ALG, &gp.lockoutAlg);
69       NvWriteReserved(NV_OWNER_POLICY, &gp.ownerPolicy);
70       NvWriteReserved(NV_ENDORSEMENT_POLICY, &gp.endorsementPolicy);
71       NvWriteReserved(NV_LOCKOUT_POLICY, &gp.lockoutPolicy);
72
73       // Initialize dictionary attack parameters
74       DAPreInstall_Init();
75
76       // Reset clock
77       go.clock = 0;
78       go.clockSafe = YES;
79       // Update the DRBG state whenever writing orderly state to NV
80       CryptDrbgGetPutState(GET_STATE);
81       NvWriteReserved(NV_ORDERLY_DATA, &go);
82
83       // Reset counters
84       gp.resetCount = gr.restartCount = gr.clearCount = 0;
85       gp.auditCounter = 0;
86       NvWriteReserved(NV_RESET_COUNT, &gp.resetCount);
87       NvWriteReserved(NV_AUDIT_COUNTER, &gp.auditCounter);
88
89       // orderly state should be cleared because of the update to state clear data
90       g_clearOrderly = TRUE;
91
92       return TPM_RC_SUCCESS;
93   }
94   #endif // CC_Clear


     Family “2.0”                           TCG Published                               Page 329
     Level 00 Revision 01.16           Copyright © TCG 2006-2014                 October 30, 2014
Part 3: Commands                                                           Trusted Platform Module Library


24.7   TPM2_ClearControl

24.7.1 General Description

TPM2_ClearControl() disables and enables the execution of TPM2_Clear().
The TPM will SET the TPM’s TPMA_PERMANENT.disableClear attribute if disable is YES and will
CLEAR the attribute if disable is NO. When the attribute is SET, TPM2_Clear() may not be executed.

NOTE           This is to simplify the logic of TPM2_Clear(). TPM2_ClearControl() can be called using Platform
               Authorization to CLEAR the disableClear attribute and then execute TPM2_Clear().

Lockout Authorization may be used to SET disableClear but not to CLEAR it.
Platform Authorization may be used to SET or CLEAR disableClear.


Page 330                                    TCG Published                                       Family “2.0”
October 30, 2014                    Copyright © TCG 2006-2014                     Level 00 Revision 01.16
Trusted Platform Module Library                                                      Part 3: Commands


24.7.2 Command and Response

                            Table 161 — TPM2_ClearControl Command
 Type                         Name                Description

 TPMI_ST_COMMAND_TAG          tag                 TPM_ST_SESSIONS
 UINT32                       commandSize
 TPM_CC                       commandCode         TPM_CC_ClearControl {NV}

                                                  TPM_RH_LOCKOUT or TPM_RH_PLATFORM+{PP}
 TPMI_RH_CLEAR                @auth               Auth Handle: 1
                                                  Auth Role: USER

                                                  YES if the disableOwnerClear flag is to be SET, NO if
 TPMI_YES_NO                  disable
                                                  the flag is to be CLEAR.


                            Table 162 — TPM2_ClearControl Response
 Type                         Name                Description

 TPM_ST                       tag                 see clause 6
 UINT32                       responseSize
 TPM_RC                       responseCode


Family “2.0”                             TCG Published                                        Page 331
Level 00 Revision 01.16             Copyright © TCG 2006-2014                        October 30, 2014
     Part 3: Commands                                                      Trusted Platform Module Library


     24.7.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "ClearControl_fp.h"
3    #ifdef TPM_CC_ClearControl // Conditional expansion of this file


     Error Returns                   Meaning

     TPM_RC_AUTH_FAIL                authorization is not properly given

 4   TPM_RC
 5   TPM2_ClearControl(
 6       ClearControl_In       *in                 // IN: input parameter list
 7       )
 8   {
 9       TPM_RC      result;
10
11       // The command needs NV update. Check if NV is available.
12       // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
13       // this point
14       result = NvIsAvailable();
15       if(result != TPM_RC_SUCCESS) return result;
16
17   // Input Validation
18
19       // LockoutAuth may be used to set disableLockoutClear to TRUE but not to FALSE
20       if(in->auth == TPM_RH_LOCKOUT && in->disable == NO)
21           return TPM_RC_AUTH_FAIL;
22
23   // Internal Data Update
24
25       if(in->disable == YES)
26           gp.disableClear = TRUE;
27       else
28           gp.disableClear = FALSE;
29
30       // Record the change to NV
31       NvWriteReserved(NV_DISABLE_CLEAR, &gp.disableClear);
32
33       return TPM_RC_SUCCESS;
34   }
35   #endif // CC_ClearControl


     Page 332                                     TCG Published                              Family “2.0”
     October 30, 2014                    Copyright © TCG 2006-2014               Level 00 Revision 01.16
Trusted Platform Module Library                                                             Part 3: Commands


24.8   TPM2_HierarchyChangeAuth

24.8.1 General Description

This command allows the authorization secret for a hierarchy or lockout to be changed using the current
authorization value as the command authorization.
If authHandle is TPM_RH_PLATFORM, then platformAuth is changed. If authHandle is
TPM_RH_OWNER, then ownerAuth is changed. If authHandle is TPM_RH_ENDORSEMENT, then
endorsementAuth is changed. If authHandle is TPM_RH_LOCKOUT, then lockoutAuth is changed.
If authHandle is TPM_RH_PLATFORM, then Physical Presence may need to be asserted for this
command to succeed (see 26.2, “TPM2_PP_Commands”).
The authorization value may be no larger than the digest produced by the hash algorithm used for context
integrity.

EXAMPLE         If SHA384 is used in the computation of the integrity values for saved contexts, then the largest
                authorization value is 48 octets.


Family “2.0”                                  TCG Published                                          Page 333
Level 00 Revision 01.16               Copyright © TCG 2006-2014                             October 30, 2014
Part 3: Commands                                                   Trusted Platform Module Library


24.8.2 Command and Response

                   Table 163 — TPM2_HierarchyChangeAuth Command
Type                     Name                  Description

TPMI_ST_COMMAND_TAG      tag                   TPM_ST_SESSIONS
UINT32                   commandSize
TPM_CC                   commandCode           TPM_CC_HierarchyChangeAuth {NV}

                                               TPM_RH_LOCKOUT, TPM_RH_ENDORSEMENT,
                                               TPM_RH_OWNER or TPM_RH_PLATFORM+{PP}
TPMI_RH_HIERARCHY_AUTH   @authHandle
                                               Auth Index: 1
                                               Auth Role: USER

TPM2B_AUTH               newAuth               new authorization value


                   Table 164 — TPM2_HierarchyChangeAuth Response
Type                     Name                  Description

TPM_ST                   tag                   see clause 6
UINT32                   responseSize
TPM_RC                   responseCode


Page 334                                TCG Published                                Family “2.0”
October 30, 2014               Copyright © TCG 2006-2014                 Level 00 Revision 01.16
     Trusted Platform Module Library                                                                Part 3: Commands


     24.8.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "HierarchyChangeAuth_fp.h"
3    #ifdef TPM_CC_HierarchyChangeAuth // Conditional expansion of this file
4    #include "Object_spt_fp.h"


     Error Returns                     Meaning

     TPM_RC_SIZE                       newAuth size is greater than that of integrity hash digest

 5   TPM_RC
 6   TPM2_HierarchyChangeAuth(
 7       HierarchyChangeAuth_In    *in                    // IN: input parameter list
 8       )
 9   {
10       TPM_RC       result;
11
12       // The command needs NV update. Check if NV is available.
13       // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
14       // this point
15       result = NvIsAvailable();
16       if(result != TPM_RC_SUCCESS) return result;
17
18       // Make sure the the auth value is a reasonable size (not larger than
19       // the size of the digest produced by the integrity hash. The integrity
20       // hash is assumed to produce the longest digest of any hash implemented
21       // on the TPM.
22       if( MemoryRemoveTrailingZeros(&in->newAuth)
23               > CryptGetHashDigestSize(CONTEXT_INTEGRITY_HASH_ALG))
24           return TPM_RC_SIZE + RC_HierarchyChangeAuth_newAuth;
25
26       // Set hierarchy authValue
27       switch(in->authHandle)
28       {
29       case TPM_RH_OWNER:
30           gp.ownerAuth = in->newAuth;
31           NvWriteReserved(NV_OWNER_AUTH, &gp.ownerAuth);
32           break;
33       case TPM_RH_ENDORSEMENT:
34           gp.endorsementAuth = in->newAuth;
35           NvWriteReserved(NV_ENDORSEMENT_AUTH, &gp.endorsementAuth);
36           break;
37       case TPM_RH_PLATFORM:
38           gc.platformAuth = in->newAuth;
39           // orderly state should be cleared
40           g_clearOrderly = TRUE;
41           break;
42       case TPM_RH_LOCKOUT:
43           gp.lockoutAuth = in->newAuth;
44           NvWriteReserved(NV_LOCKOUT_AUTH, &gp.lockoutAuth);
45           break;
46       default:
47           pAssert(FALSE);
48           break;
49       }
50
51       return TPM_RC_SUCCESS;
52   }
53   #endif // CC_HierarchyChangeAuth


     Family “2.0”                                   TCG Published                                          Page 335
     Level 00 Revision 01.16               Copyright © TCG 2006-2014                                October 30, 2014
Part 3: Commands                                                             Trusted Platform Module Library


25     Dictionary Attack Functions

25.1    Introduction

A TPM is required to have support for logic that will help prevent a dictionary attack on an authorization
value. The protection is provided by a counter that increments when a password authorization or an
HMAC authorization fails. When the counter reaches a predefined value, the TPM will not accept, for
some time interval, further requests that require authorization and the TPM is in Lockout mode. While the
TPM is in Lockout mode, the TPM will return TPM_RC_LOCKED if the command requires use of an
object’s or Index’s authValue unless the authorization applies to an entry in the Platform hierarchy.

NOTE            Authorizations for objects and NV Index values in the Platform hierarchy are never locked out.
                However, a command that requires multiple authorizations will not be accepted when the TPM is in
                Lockout mode unless all of the authorizations reference objects and indexes in the Platform
                hierarchy.

If the TPM is continuously powered for the duration of newRecoveryTime and no authorization failures
occur, the authorization failure counter will be decremented by one. This property is called “self-healing.”
Self-healing shall not cause the count of failed attempts to decrement below zero.
The count of failed attempts, the lockout interval, and self-healing interval are settable using
TPM2_DictionaryAttackParameters(). The lockout parameters and the current value of the lockout
counter can be read with TPM2_GetCapability().
Dictionary attack protection does not apply to an entity associated with a permanent handle (handle type
== TPM_HT_PERMANENT).

25.2    TPM2_DictionaryAttackLockReset

25.2.1 General Description

This command cancels the effect of a TPM lockout due to a number of successive authorization failures.
If this command is properly authorized, the lockout counter is set to zero.
Only one lockoutAuth authorization failure is allowed for this command during a lockoutRecovery interval
(set using TPM2_DictionaryAttackParameters().


Page 336                                     TCG Published                                        Family “2.0”
October 30, 2014                      Copyright © TCG 2006-2014                    Level 00 Revision 01.16
Trusted Platform Module Library                                                 Part 3: Commands


25.2.2 Command and Response

                    Table 165 — TPM2_DictionaryAttackLockReset Command
 Type                         Name                Description

 TPMI_ST_COMMAND_TAG          tag                 TPM_ST_SESSIONS
 UINT32                       commandSize
 TPM_CC                       commandCode         TPM_CC_DictionaryAttackLockReset {NV}

                                                  TPM_RH_LOCKOUT
 TPMI_RH_LOCKOUT              @lockHandle         Auth Index: 1
                                                  Auth Role: USER


                     Table 166 — TPM2_DictionaryAttackLockReset Response
 Type                         Name                Description
 TPM_ST                       tag                 see clause 6
 UINT32                       responseSize
 TPM_RC                       responseCode


Family “2.0”                             TCG Published                                    Page 337
Level 00 Revision 01.16             Copyright © TCG 2006-2014                   October 30, 2014
     Part 3: Commands                                                  Trusted Platform Module Library


     25.2.3 Detailed Actions

 1   #include "InternalRoutines.h"
 2   #include "DictionaryAttackLockReset_fp.h"
 3   #ifdef TPM_CC_DictionaryAttackLockReset // Conditional expansion of this file
 4   TPM_RC
 5   TPM2_DictionaryAttackLockReset(
 6       DictionaryAttackLockReset_In      *in             // IN: input parameter list
 7       )
 8   {
 9       TPM_RC         result;
10
11       // Input parameter is not reference in command action
12       in = NULL;
13
14       // The command needs NV update. Check if NV is available.
15       // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
16       // this point
17       result = NvIsAvailable();
18       if(result != TPM_RC_SUCCESS) return result;
19
20   // Internal Data Update
21
22       // Set failed tries to 0
23       gp.failedTries = 0;
24
25       // Record the changes to NV
26       NvWriteReserved(NV_FAILED_TRIES, &gp.failedTries);
27
28       return TPM_RC_SUCCESS;
29   }
30   #endif // CC_DictionaryAttackLockReset


     Page 338                                    TCG Published                           Family “2.0”
     October 30, 2014                   Copyright © TCG 2006-2014            Level 00 Revision 01.16
Trusted Platform Module Library                                                               Part 3: Commands


25.3   TPM2_DictionaryAttackParameters

25.3.1 General Description

This command changes the lockout parameters.
The command requires Lockout Authorization.
The timeout parameters (newRecoveryTime and lockoutRecovery) indicate values that are measured with
respect to the Time and not Clock.

NOTE            Use of Time means that the TPM shall be continuously powered for the duration of a timeout.

If newRecoveryTime is zero, then DA protection is disabled. Authorizations are checked but authorization
failures will not cause the TPM to enter lockout.
If newMaxTries is zero, the TPM will be in lockout and use of DA protected entities will be disabled.
If lockoutRecovery is zero, then the recovery interval is a boot cycle (_TPM_Init followed by
Startup(CLEAR).
This command will set the authorization failure count (failedTries) to zero.
Only one lockoutAuth authorization failure is allowed for this command during a lockoutRecovery interval.


Family “2.0”                                  TCG Published                                            Page 339
Level 00 Revision 01.16               Copyright © TCG 2006-2014                               October 30, 2014
Part 3: Commands                                                    Trusted Platform Module Library


25.3.2 Command and Response

                   Table 167 — TPM2_DictionaryAttackParameters Command
 Type                      Name                Description

 TPMI_ST_COMMAND_TAG       tag                 TPM_ST_SESSIONS
 UINT32                    commandSize
 TPM_CC                    commandCode         TPM_CC_DictionaryAttackParameters {NV}

                                               TPM_RH_LOCKOUT
 TPMI_RH_LOCKOUT           @lockHandle         Auth Index: 1
                                               Auth Role: USER

                                               count of authorization failures before the lockout is
 UINT32                    newMaxTries
                                               imposed
                                               time in seconds before the authorization failure count
                                               is automatically decremented
 UINT32                    newRecoveryTime
                                               A value of zero indicates that DA protection is
                                               disabled.
                                               time in seconds after a lockoutAuth failure before use
 UINT32                    lockoutRecovery     of lockoutAuth is allowed
                                               A value of zero indicates that a reboot is required.


                   Table 168 — TPM2_DictionaryAttackParameters Response
 Type                      Name                Description

 TPM_ST                    tag                 see clause 6
 UINT32                    responseSize
 TPM_RC                    responseCode


Page 340                              TCG Published                                        Family “2.0”
October 30, 2014                 Copyright © TCG 2006-2014                 Level 00 Revision 01.16
     Trusted Platform Module Library                                              Part 3: Commands


     25.3.3 Detailed Actions

 1   #include "InternalRoutines.h"
 2   #include "DictionaryAttackParameters_fp.h"
 3   #ifdef TPM_CC_DictionaryAttackParameters // Conditional expansion of this file
 4   TPM_RC
 5   TPM2_DictionaryAttackParameters(
 6       DictionaryAttackParameters_In    *in             // IN: input parameter list
 7       )
 8   {
 9       TPM_RC           result;
10
11       // The command needs NV update. Check if NV is available.
12       // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
13       // this point
14       result = NvIsAvailable();
15       if(result != TPM_RC_SUCCESS) return result;
16
17   // Internal Data Update
18
19       // Set dictionary attack parameters
20       gp.maxTries = in->newMaxTries;
21       gp.recoveryTime = in->newRecoveryTime;
22       gp.lockoutRecovery = in->lockoutRecovery;
23
24       // Set failed tries to 0
25       gp.failedTries = 0;
26
27       // Record the changes to NV
28       NvWriteReserved(NV_FAILED_TRIES, &gp.failedTries);
29       NvWriteReserved(NV_MAX_TRIES, &gp.maxTries);
30       NvWriteReserved(NV_RECOVERY_TIME, &gp.recoveryTime);
31       NvWriteReserved(NV_LOCKOUT_RECOVERY, &gp.lockoutRecovery);
32
33       return TPM_RC_SUCCESS;
34   }
35   #endif // CC_DictionaryAttackParameters


     Family “2.0”                               TCG Published                            Page 341
     Level 00 Revision 01.16           Copyright © TCG 2006-2014                  October 30, 2014
Part 3: Commands                                                             Trusted Platform Module Library


26     Miscellaneous Management Functions

26.1    Introduction

This clause contains commands that do not logically group with any other commands.

26.2    TPM2_PP_Commands

26.2.1 General Description

This command is used to determine which commands require assertion of Physical Presence (PP) in
addition to platformAuth/platformPolicy.
This command requires that auth is TPM_RH_PLATFORM and that Physical Presence be asserted.
After this command executes successfully, the commands listed in setList will be added to the list of
commands that require that Physical Presence be asserted when the handle associated with the
authorization is TPM_RH_PLATFORM. The commands in clearList will no longer require assertion of
Physical Presence in order to authorize a command.
If a command is not in either list, its state is not changed. If a command is in both lists, then it will no
longer require Physical Presence (for example, setList is processed first).
Only commands with               handle types of TPMI_RH_PLATFORM, TPMI_RH_PROVISION,
TPMI_RH_CLEAR, or TPMI_RH_HIERARCHY can be gated with Physical Presence. If any other
command is in either list, it is discarded.
When a command requires that Physical Presence be provided, then Physical Presence shall be
asserted for either an HMAC or a Policy authorization.

NOTE            Physical Presence may be made a requirement of any policy.

TPM2_PP_Commands() always requires assertion of Physical Presence.


Page 342                                     TCG Published                                     Family “2.0”
October 30, 2014                      Copyright © TCG 2006-2014                   Level 00 Revision 01.16
Trusted Platform Module Library                                                       Part 3: Commands


26.2.2 Command and Response

                           Table 169 — TPM2_PP_Commands Command
 Type                         Name                Description

 TPMI_ST_COMMAND_TAG          tag                 TPM_ST_SESSIONS
 UINT32                       commandSize
 TPM_CC                       commandCode         TPM_CC_PP_Commands {NV}

                                                  TPM_RH_PLATFORM+PP
 TPMI_RH_PLATFORM             @auth               Auth Index: 1
                                                  Auth Role: USER + Physical Presence

                                                  list of commands to be added to those that will require
 TPML_CC                      setList
                                                  that Physical Presence be asserted
                                                  list of commands that will no longer require that
 TPML_CC                      clearList
                                                  Physical Presence be asserted


                           Table 170 — TPM2_PP_Commands Response
 Type                         Name                Description

 TPM_ST                       tag                 see clause 6
 UINT32                       responseSize
 TPM_RC                       responseCode


Family “2.0”                              TCG Published                                         Page 343
Level 00 Revision 01.16             Copyright © TCG 2006-2014                         October 30, 2014
     Part 3: Commands                                                  Trusted Platform Module Library


     26.2.3 Detailed Actions

 1   #include "InternalRoutines.h"
 2   #include "PP_Commands_fp.h"
 3   #ifdef TPM_CC_PP_Commands // Conditional expansion of this file
 4   TPM_RC
 5   TPM2_PP_Commands(
 6       PP_Commands_In   *in           // IN: input parameter list
 7       )
 8   {
 9       UINT32           i;
10
11       TPM_RC      result;
12
13       // The command needs NV update. Check if NV is available.
14       // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
15       // this point
16       result = NvIsAvailable();
17       if(result != TPM_RC_SUCCESS) return result;
18
19   // Internal Data Update
20
21       // Process set list
22       for(i = 0; i < in->setList.count; i++)
23           // If command is implemented, set it as PP required. If the input
24           // command is not a PP command, it will be ignored at
25           // PhysicalPresenceCommandSet().
26           if(CommandIsImplemented(in->setList.commandCodes[i]))
27               PhysicalPresenceCommandSet(in->setList.commandCodes[i]);
28
29       // Process clear list
30       for(i = 0; i < in->clearList.count; i++)
31           // If command is implemented, clear it as PP required. If the input
32           // command is not a PP command, it will be ignored at
33           // PhysicalPresenceCommandClear(). If the input command is
34           // TPM2_PP_Commands, it will be ignored as well
35           if(CommandIsImplemented(in->clearList.commandCodes[i]))
36               PhysicalPresenceCommandClear(in->clearList.commandCodes[i]);
37
38       // Save the change of PP list
39       NvWriteReserved(NV_PP_LIST, &gp.ppList);
40
41       return TPM_RC_SUCCESS;
42   }
43   #endif // CC_PP_Commands


     Page 344                               TCG Published                                Family “2.0”
     October 30, 2014                Copyright © TCG 2006-2014              Level 00 Revision 01.16
Trusted Platform Module Library                                                            Part 3: Commands


26.3   TPM2_SetAlgorithmSet

26.3.1 General Description

This command allows the platform to change the set of algorithms that are used by the TPM. The
algorithmSet setting is a vendor-dependent value.
If the changing of the algorithm set results in a change of the algorithms of PCR banks, then the TPM will
need to be reset (_TPM_Init and TPM2_Startup(TPM_SU_CLEAR)) before the new PCR settings take
effect. After this command executes successfully, if startupType in the next TPM2_Startup() is not
TPM_SU_CLEAR, the TPM shall return TPM_RC_VALUE and enter Failure mode.
This command does not change the algorithms available to the platform.

NOTE            The reference implementation does not have support for this command. In particular, it does not
                support use of this command to selectively disable algorithms. Proper support would require
                modification of the unmarshaling code so that each time an algorithm is unmarshaled, it would be
                verified as being enabled.


Family “2.0”                                  TCG Published                                          Page 345
Level 00 Revision 01.16               Copyright © TCG 2006-2014                            October 30, 2014
Part 3: Commands                                                    Trusted Platform Module Library


26.3.2 Command and Response

                       Table 171 — TPM2_SetAlgorithmSet Command
 Type                     Name                   Description

 TPMI_ST_COMMAND_TAG      tag                    TPM_ST_SESSIONS
 UINT32                   commandSize
 TPM_CC                   commandCode            TPM_CC_SetAlgorithmSet {NV}

                                                 TPM_RH_PLATFORM
 TPMI_RH_PLATFORM         @authHandle            Auth Index: 1
                                                 Auth Role: USER

                                                 a TPM vendor-dependent value indicating the
 UINT32                   algorithmSet
                                                 algorithm set selection


                       Table 172 — TPM2_SetAlgorithmSet Response
 Type                     Name                   Description

 TPM_ST                   tag                    see clause 6
 UINT32                   responseSize
 TPM_RC                   responseCode


Page 346                                 TCG Published                                  Family “2.0”
October 30, 2014                Copyright © TCG 2006-2014                 Level 00 Revision 01.16
     Trusted Platform Module Library                                             Part 3: Commands


     26.3.3 Detailed Actions

 1   #include "InternalRoutines.h"
 2   #include "SetAlgorithmSet_fp.h"
 3   #ifdef TPM_CC_SetAlgorithmSet // Conditional expansion of this file
 4   TPM_RC
 5   TPM2_SetAlgorithmSet(
 6       SetAlgorithmSet_In     *in            // IN: input parameter list
 7       )
 8   {
 9       TPM_RC       result;
10
11       // The command needs NV update. Check if NV is available.
12       // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
13       // this point
14       result = NvIsAvailable();
15       if(result != TPM_RC_SUCCESS) return result;
16
17   // Internal Data Update
18       gp.algorithmSet = in->algorithmSet;
19
20       // Write the algorithm set changes to NV
21       NvWriteReserved(NV_ALGORITHM_SET, &gp.algorithmSet);
22
23       return TPM_RC_SUCCESS;
24   }
25   #endif // CC_SetAlgorithmSet


     Family “2.0”                              TCG Published                            Page 347
     Level 00 Revision 01.16           Copyright © TCG 2006-2014                 October 30, 2014
Part 3: Commands                                                                  Trusted Platform Module Library


27     Field Upgrade

27.1     Introduction

This clause contains the commands for managing field upgrade of the firmware in the TPM. The field
upgrade scheme may be used for replacement or augmentation of the firmware installed in the TPM.

EXAMPLE 1        If an algorithm is found to be flawed, a patch of that algori thm might be installed using the firmware
                 upgrade process. The patch might be a replacement of a portion of the code or a complete
                 replacement of the firmware.

EXAMPLE 2        If an additional set of ECC parameters is needed, the firmware process may be used to add the
                 parameters to the TPM data set.

The     field  upgrade    process     uses    two     commands       (TPM2_FieldUpgradeStart()  and
TPM2_FieldUpgradeData()). TPM2_FieldUpgradeStart() validates that a signature on the provided digest
is from the TPM manufacturer and that proper authorization is provided using platformPolicy.

NOTE 1           The platformPolicy for field upgraded is defined by the PM and may include requirements that the
                 upgrade be signed by the PM or the TPM owner and include any other constraints that are desired
                 by the PM.

If the proper authorization is given, the TPM will retain the signed digest and enter the Field Upgrade
mode (FUM). While in FUM, the TPM will accept TPM2_FieldUpgradeData() commands. It may accept
other commands if it is able to complete them using the previously installed firmware. Otherwise, it will
return TPM_RC_UPGRADE.
Each block of the field upgrade shall contain the digest of the next block of the field upgrade data. That
digest shall be included in the digest of the previous block. The digest of the first block is signed by the
TPM manufacturer. That signature and first block digest are the parameters for
TPM2_FieldUpgradeStart(). The digest is saved in the TPM as the required digest for the next field
upgrade data block and as the identifier of the field upgrade sequence.
For each field upgrade data block that is sent to the TPM by TPM2_FieldUpgradeData(), the TPM shall
validate that the digest matches the required digest and if not, shall return TPM_RC_VALUE. The TPM
shall extract the digest of the next expected block and return that value to the caller, along with the digest
of the first data block of the update sequence.
The system may attempt to abandon the firmware upgrade by using a zero-length buffer in
TPM2_FieldUpdateData(). If the TPM is able to resume operation using the firmware present when the
upgrade started, then the TPM will indicate that it has abandon the update by setting the digest of the
next block to the Empty Buffer. If the TPM cannot abandon the update, it will return the expected next
digest.
The system may also attempt to abandon the update because of a power interruption. If the TPM is able
to resume normal operations, then it will respond normally to TPM2_Startup(). If the TPM is not able to
resume normal operations, then it will respond to any command but TPM2_FieldUpgradeData() with
TPM_RC_FIELDUPGRADE.
After a _TPM_Init, system software may not be able to resume the field upgrade that was in process
when the power interruption occurred. In such case, the TPM firmware may be reset to one of two other
values:
        the original firmware that was installed at the factory (“initial firmware”); or
        the firmware that was in the TPM when the field upgrade process started (“previous firmware”).
The TPM retains the digest of the first block for these firmware images and checks to see if the first block
after _TPM_Init matches either of those digests. If so, the firmware update process restarts and the
original firmware may be loaded.


Page 348                                         TCG Published                                           Family “2.0”
October 30, 2014                        Copyright © TCG 2006-2014                        Level 00 Revision 01.16
Trusted Platform Module Library                                                                   Part 3: Commands

NOTE 2            The TPM is required to accept the previous firmware as either a vendor-provided update or as
                  recovered from the TPM using TPM2_FirmwareRead().

When the last block of the firmware upgrade is loaded into the TPM (indicated to the TPM by data in the
data block in a TPM vendor-specific manner), the TPM will complete the upgrade process. If the TPM is
able to resume normal operations without a reboot, it will set the hash algorithm of the next block to
TPM_ALG_NULL and return TPM_RC_SUCCESS. If a reboot is required, the TPM shall return
TPM_RC_REBOOT in response to the last TPM2_FieldUpgradeData() and all subsequent TPM
commands until a _TPM_Init is received.

NOTE 3            Because no additional data is allowed when the response code is not TPM_RC_SUCCESS, the TPM
                  returns TPM_RC_SUCCESS for all calls to TPM2_FieldUpgradeData() except the last. In this
                  manner, the TPM is able to indicate the digest of the next block. If a _TPM_Init occurs while the
                  TPM is in FUM, the next block may be the digest for the first block of the original firmware. If it is
                  not, then the TPM will not accept the original firmware until the next _TPM_Init when the TPM is in
                  FUM.

During the field upgrade process, either the one specified in this clause or a vendor proprietary field
upgrade process, the TPM shall preserve:
        Primary Seeds;
        Hierarchy authValue, authPolicy, and proof values;
        Lockout authValue and authorization failure count values;
        PCR authValue and authPolicy values;
        NV Index allocations and contents;
        Persistent object allocations and contents; and
        Clock.

NOTE 4            A platform manufacturer may provide a means to change preserved data to accommodate a case
                  where a field upgrade fixes a flaw that might have compromised TPM secrets.


Family “2.0”                                     TCG Published                                              Page 349
Level 00 Revision 01.16                  Copyright © TCG 2006-2014                                October 30, 2014
Part 3: Commands                                                               Trusted Platform Module Library


27.2   TPM2_FieldUpgradeStart

27.2.1 General Description

This command uses platformPolicy and a TPM Vendor Authorization Key to authorize a Field Upgrade
Manifest.
If the signature checks        succeed,     the   authorization   is   valid   and   the   TPM     will   accept
TPM2_FieldUpgradeData().
This signature is checked against the loaded key referenced by keyHandle. This key will have a Name
that is the same as a value that is part of the TPM firmware data. If the signature is not valid, the TPM
shall return TPM_RC_SIGNATURE.

NOTE            A loaded key is used rather than a hard -coded key to reduce the amount of memory needed for this
                key data in case more than one vendor key is needed.


Page 350                                      TCG Published                                        Family “2.0”
October 30, 2014                      Copyright © TCG 2006-2014                      Level 00 Revision 01.16
Trusted Platform Module Library                                                          Part 3: Commands


27.2.2 Command and Response

                          Table 173 — TPM2_FieldUpgradeStart Command
Type                          Name                  Description

TPMI_ST_COMMAND_TAG           tag                   TPM_ST_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode           TPM_CC_FieldUpgradeStart

                                                    TPM_RH_PLATFORM+{PP}
TPMI_RH_PLATFORM              @authorization        Auth Index:1
                                                    Auth Role: ADMIN
                                                    handle of a public area that contains the TPM Vendor
                                                    Authorization Key that will be used to validate
TPMI_DH_OBJECT                keyHandle             manifestSignature
                                                    Auth Index: None

TPM2B_DIGEST                  fuDigest              digest of the first block in the field upgrade sequence
                                                    signature over fuDigest using the key associated with
TPMT_SIGNATURE                manifestSignature
                                                    keyHandle (not optional)


                          Table 174 — TPM2_FieldUpgradeStart Response
Type                          Name                  Description

TPM_ST                        tag                   see clause 6
UINT32                        responseSize
TPM_RC                        responseCode


Family “2.0”                                 TCG Published                                         Page 351
Level 00 Revision 01.16             Copyright © TCG 2006-2014                            October 30, 2014
     Part 3: Commands                                                 Trusted Platform Module Library


     27.2.3 Detailed Actions

 1   #include "InternalRoutines.h"
 2   #include "FieldUpgradeStart_fp.h"
 3   #ifdef TPM_CC_FieldUpgradeStart // Conditional expansion of this file
 4   TPM_RC
 5   TPM2_FieldUpgradeStart(
 6       FieldUpgradeStart_In     *in             // IN: input parameter list
 7       )
 8   {
 9       // Not implemented
10       UNUSED_PARAMETER(in);
11       return TPM_RC_SUCCESS;
12   }
13   #endif


     Page 352                                TCG Published                              Family “2.0”
     October 30, 2014                   Copyright © TCG 2006-2014            Level 00 Revision 01.16
Trusted Platform Module Library                                                     Part 3: Commands


27.3   TPM2_FieldUpgradeData

27.3.1 General Description

This command will take the actual field upgrade image to be installed on the TPM. The exact format of
fuData is vendor-specific. This command is only possible following a successful
TPM2_FieldUpgradeStart().    If    the    TPM     has    not   received     a   properly  authorized
TPM2_FieldUpgradeStart(), then the TPM shall return TPM_RC_FIELDUPGRADE.
The TPM will validate that the digest of fuData matches an expected value. If so, the TPM may buffer or
immediately apply the update. If the digest of fuData does not match an expected value, the TPM shall
return TPM_RC_VALUE.


Family “2.0”                               TCG Published                                    Page 353
Level 00 Revision 01.16            Copyright © TCG 2006-2014                        October 30, 2014
Part 3: Commands                                                    Trusted Platform Module Library


27.3.2 Command and Response

                      Table 175 — TPM2_FieldUpgradeData Command
Type                     Name                  Description

                                               TPM_ST_SESSIONS if an audit or decrypt session is
TPMI_ST_COMMAND_TAG      tag
                                               present; otherwise, TPM_ST_NO_SESSIONS
UINT32                   commandSize
TPM_CC                   commandCode           TPM_CC_FieldUpgradeData {NV}

TPM2B_MAX_BUFFER         fuData                field upgrade image data


                      Table 176 — TPM2_FieldUpgradeData Response
Type                     Name                  Description

TPM_ST                   tag                   see clause 6
UINT32                   responseSize
TPM_RC                   responseCode

                                               tagged digest of the next block
TPMT_HA+                 nextDigest
                                               TPM_ALG_NULL if field update is complete
TPMT_HA                  firstDigest           tagged digest of the first block of the sequence


Page 354                                TCG Published                                     Family “2.0”
October 30, 2014               Copyright © TCG 2006-2014                   Level 00 Revision 01.16
     Trusted Platform Module Library                                                Part 3: Commands


     27.3.3 Detailed Actions

 1   #include "InternalRoutines.h"
 2   #include "FieldUpgradeData_fp.h"
 3   #ifdef TPM_CC_FieldUpgradeData // Conditional expansion of this file
 4   TPM_RC
 5   TPM2_FieldUpgradeData(
 6       FieldUpgradeData_In       *in,             // IN: input parameter list
 7       FieldUpgradeData_Out      *out             // OUT: output parameter list
 8       )
 9   {
10       // Not implemented
11       UNUSED_PARAMETER(in);
12       UNUSED_PARAMETER(out);
13       return TPM_RC_SUCCESS;
14   }
15   #endif


     Family “2.0”                              TCG Published                               Page 355
     Level 00 Revision 01.16              Copyright © TCG 2006-2014                 October 30, 2014
Part 3: Commands                                                              Trusted Platform Module Library


27.4     TPM2_FirmwareRead

27.4.1 General Description

This command is used to read a copy of the current firmware installed in the TPM.
The presumption is that the data will be returned in reverse order so that the last block in the sequence
would be the first block given to the TPM in case of a failure recovery. If the TPM2_FirmwareRead
sequence completes successfully, then the data provided from the TPM will be sufficient to allow the TPM
to recover from an abandoned upgrade of this firmware.
To start the sequence of retrieving the data, the caller sets sequenceNumber to zero. When the TPM has
returned all the firmware data, the TPM will return the Empty Buffer as fuData.
The contents of fuData are opaque to the caller.

NOTE 1          The caller should retain the ordering of the update blocks so that the blocks sent to the TPM have
                the same size and inverse order as the blocks returned by a sequence of calls to this command.

NOTE 2          Support for this command is optional even if the TPM implements TPM2_FieldUpgradeStart() a nd
                TPM2_FieldUpgradeData().


Page 356                                      TCG Published                                        Family “2.0”
October 30, 2014                      Copyright © TCG 2006-2014                      Level 00 Revision 01.16
Trusted Platform Module Library                                                         Part 3: Commands


27.4.2 Command and Response

                           Table 177 — TPM2_FirmwareRead Command
Type                          Name                  Description

                                                    TPM_ST_SESSIONS if an audit or encrypt session is
TPMI_ST_COMMAND_TAG           tag
                                                    present; otherwise, TPM_ST_NO_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode           TPM_CC_FirmwareRead

                                                    the number of previous calls to this command in this
UINT32                        sequenceNumber        sequence
                                                    set to 0 on the first call


                           Table 178 — TPM2_FirmwareRead Response
Type                          Name                  Description

TPM_ST                        tag                   see clause 6
UINT32                        responseSize
TPM_RC                        responseCode

TPM2B_MAX_BUFFER              fuData                field upgrade image data


Family “2.0”                                 TCG Published                                       Page 357
Level 00 Revision 01.16             Copyright © TCG 2006-2014                           October 30, 2014
     Part 3: Commands                                               Trusted Platform Module Library


     27.4.3 Detailed Actions

 1   #include "InternalRoutines.h"
 2   #include "FirmwareRead_fp.h"
 3   #ifdef TPM_CC_FirmwareRead // Conditional expansion of this file
 4   TPM_RC
 5   TPM2_FirmwareRead(
 6       FirmwareRead_In    *in,            // IN: input parameter list
 7       FirmwareRead_Out   *out            // OUT: output parameter list
 8       )
 9   {
10       // Not implemented
11       UNUSED_PARAMETER(in);
12       UNUSED_PARAMETER(out);
13       return TPM_RC_SUCCESS;
14   }
15   #endif // CC_FirmwareRead


     Page 358                              TCG Published                               Family “2.0”
     October 30, 2014                Copyright © TCG 2006-2014              Level 00 Revision 01.16
Trusted Platform Module Library                                                                Part 3: Commands


28     Context Management

28.1    Introduction

Three of the commands in this clause (TPM2_ContextSave(), TPM2_ContextLoad(), and
TPM2_FlushContext()) implement the resource management described in the "Context Management"
clause in TPM 2.0 Part 1.
The fourth command in this clause (TPM2_EvictControl()) is used to control the persistence of loadable
objects in TPM memory. Background for this command may be found in the "Owner and Platform Evict
Objects" clause in TPM 2.0 Part 1.

28.2    TPM2_ContextSave

28.2.1 General Description

This command saves a session context, object context, or sequence object context outside the TPM.
No authorization sessions of any type are allowed with this command and tag is required to be
TPM_ST_NO_SESSIONS.

NOTE            This preclusion avoids complex issues of dealing with the same session in handle and in the session
                area. While it might be possible to provide specificity, it would add unnecessary complexity to the
                TPM and, because this capability would provide no application benefit, use of authorization sessions
                for audit or encryption is prohibited.

The TPM shall encrypt and integrity protect the TPM2B_CONTEXT_SENSITIVE context as described in
the "Context Protection" clause in TPM 2.0 Part 1.
See the “Context Data” clause in TPM 2.0 Part 2 for a description of the context structure in the response.


Family “2.0”                                   TCG Published                                            Page 359
Level 00 Revision 01.16                Copyright © TCG 2006-2014                              October 30, 2014
Part 3: Commands                                                 Trusted Platform Module Library


28.2.2 Command and Response

                       Table 179 — TPM2_ContextSave Command
 Type                   Name                 Description

 TPMI_ST_COMMAND_TAG    tag                  TPM_ST_NO_SESSIONS
 UINT32                 commandSize
 TPM_CC                 commandCode          TPM_CC_ContextSave

                                             handle of the resource to save
 TPMI_DH_CONTEXT        saveHandle
                                             Auth Index: None


                       Table 180 — TPM2_ContextSave Response
 Type                   Name                 Description

 TPM_ST                 tag                  see clause 6
 UINT32                 responseSize
 TPM_RC                 responseCode

 TPMS_CONTEXT           context


Page 360                             TCG Published                                 Family “2.0”
October 30, 2014              Copyright © TCG 2006-2014                Level 00 Revision 01.16
     Trusted Platform Module Library                                                           Part 3: Commands


     28.2.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "ContextSave_fp.h"
3    #ifdef TPM_CC_ContextSave // Conditional expansion of this file
4    #include "Context_spt_fp.h"


     Error Returns                     Meaning

     TPM_RC_CONTEXT_GAP                a contextID could not be assigned for a session context save
     TPM_RC_TOO_MANY_CONTEXTS          no more contexts can be saved as the counter has maxed out

 5   TPM_RC
 6   TPM2_ContextSave(
 7       ContextSave_In        *in,              // IN: input parameter list
 8       ContextSave_Out       *out              // OUT: output parameter list
 9       )
10   {
11       TPM_RC            result;
12       UINT16            fingerprintSize;      // The size of fingerprint in context
13       // blob.
14       UINT64            contextID = 0;        // session context ID
15       TPM2B_SYM_KEY     symKey;
16       TPM2B_IV          iv;
17
18       TPM2B_DIGEST      integrity;
19       UINT16            integritySize;
20       BYTE              *buffer;
21
22       // This command may cause the orderlyState to be cleared due to
23       // the update of state reset data. If this is the case, check if NV is
24       // available first
25       if(gp.orderlyState != SHUTDOWN_NONE)
26       {
27           // The command needs NV update. Check if NV is available.
28           // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
29           // this point
30           result = NvIsAvailable();
31           if(result != TPM_RC_SUCCESS) return result;
32       }
33
34   // Internal Data Update
35
36       // Initialize output handle. At the end of command action, the output
37       // handle of an object will be replaced, while the output handle
38       // for a session will be the same as input
39       out->context.savedHandle = in->saveHandle;
40
41       // Get the size of fingerprint in context blob. The sequence value in
42       // TPMS_CONTEXT structure is used as the fingerprint
43       fingerprintSize = sizeof(out->context.sequence);
44
45       // Compute the integrity size at the beginning of context blob
46       integritySize = sizeof(integrity.t.size)
47                       + CryptGetHashDigestSize(CONTEXT_INTEGRITY_HASH_ALG);
48
49       // Perform object or session specific context save
50       switch(HandleGetType(in->saveHandle))
51       {
52       case TPM_HT_TRANSIENT:
53       {
54           OBJECT          *object = ObjectGet(in->saveHandle);

     Family “2.0”                               TCG Published                                         Page 361
     Level 00 Revision 01.16            Copyright © TCG 2006-2014                              October 30, 2014
      Part 3: Commands                                                  Trusted Platform Module Library

 55          OBJECT         *outObject =
 56                                 (OBJECT *)(out->context.contextBlob.t.buffer
 57                                             + integritySize + fingerprintSize);
 58
 59          // Set size of the context data. The contents of context blob is vendor
 60          // defined. In this implementation, the size is size of integrity
 61          // plus fingerprint plus the whole internal OBJECT structure
 62          out->context.contextBlob.t.size = integritySize +
 63                                            fingerprintSize + sizeof(OBJECT);
 64          // Make sure things fit
 65          pAssert(out->context.contextBlob.t.size
 66                  < sizeof(out->context.contextBlob.t.buffer));
 67
 68          // Copy the whole internal OBJECT structure to context blob, leave
 69          // the size for fingerprint
 70          *outObject = *object;
 71
 72          // Increment object context ID
 73          gr.objectContextID++;
 74          // If object context ID overflows, TPM should be put in failure mode
 75          if(gr.objectContextID == 0)
 76              FAIL(FATAL_ERROR_INTERNAL);
 77
 78          // Fill in other return values for an object.
 79          out->context.sequence = gr.objectContextID;
 80          // For regular object, savedHandle is 0x80000000. For sequence object,
 81          // savedHandle is 0x80000001. For object with stClear, savedHandle
 82          // is 0x80000002
 83          if(ObjectIsSequence(object))
 84          {
 85              out->context.savedHandle = 0x80000001;
 86              SequenceDataImportExport(object, outObject, EXPORT_STATE);
 87          }
 88          else if(object->attributes.stClear == SET)
 89          {
 90              out->context.savedHandle = 0x80000002;
 91          }
 92          else
 93          {
 94              out->context.savedHandle = 0x80000000;
 95          }
 96
 97          // Get object hierarchy
 98          out->context.hierarchy = ObjectDataGetHierarchy(object);
 99
100          break;
101      }
102      case TPM_HT_HMAC_SESSION:
103      case TPM_HT_POLICY_SESSION:
104      {
105          SESSION         *session = SessionGet(in->saveHandle);
106
107          // Set size of the context data. The contents of context blob is vendor
108          // defined. In this implementation, the size of context blob is the
109          // size of a internal session structure plus the size of
110          // fingerprint plus the size of integrity
111          out->context.contextBlob.t.size = integritySize +
112                                            fingerprintSize + sizeof(*session);
113
114          // Make sure things fit
115          pAssert(out->context.contextBlob.t.size
116                  < sizeof(out->context.contextBlob.t.buffer));
117
118          // Copy the whole internal SESSION structure to context blob.
119          // Save space for fingerprint at the beginning of the buffer
120          // This is done before anything else so that the actual context

      Page 362                              TCG Published                                 Family “2.0”
      October 30, 2014               Copyright © TCG 2006-2014               Level 00 Revision 01.16
      Trusted Platform Module Library                                               Part 3: Commands

121           // can be reclaimed after this call
122           MemoryCopy(out->context.contextBlob.t.buffer
123                      + integritySize + fingerprintSize,
124                      session, sizeof(*session),
125                      sizeof(out->context.contextBlob.t.buffer)
126                               - integritySize - fingerprintSize);
127
128           // Fill in the other return parameters for a session
129           // Get a context ID and set the session tracking values appropriately
130           // TPM_RC_CONTEXT_GAP is a possible error.
131           // SessionContextSave() will flush the in-memory context
132           // so no additional errors may occur after this call.
133           result = SessionContextSave(out->context.savedHandle, &contextID);
134           if(result != TPM_RC_SUCCESS) return result;
135
136           // sequence number is the current session contextID
137           out->context.sequence = contextID;
138
139           // use TPM_RH_NULL as hierarchy for session context
140           out->context.hierarchy = TPM_RH_NULL;
141
142           break;
143       }
144       default:
145           // SaveContext may only take an object handle or a session handle.
146           // All the other handle type should be filtered out at unmarshal
147           pAssert(FALSE);
148           break;
149       }
150
151       // Save fingerprint at the beginning of encrypted area of context blob.
152       // Reserve the integrity space
153       MemoryCopy(out->context.contextBlob.t.buffer + integritySize,
154                  &out->context.sequence, sizeof(out->context.sequence),
155                  sizeof(out->context.contextBlob.t.buffer) - integritySize);
156
157       // Compute context encryption key
158       ComputeContextProtectionKey(&out->context, &symKey, &iv);
159
160       // Encrypt context blob
161       CryptSymmetricEncrypt(out->context.contextBlob.t.buffer + integritySize,
162                             CONTEXT_ENCRYPT_ALG, CONTEXT_ENCRYPT_KEY_BITS,
163                             TPM_ALG_CFB, symKey.t.buffer, &iv,
164                             out->context.contextBlob.t.size - integritySize,
165                             out->context.contextBlob.t.buffer + integritySize);
166
167       // Compute integrity hash for the object
168       // In this implementation, the same routine is used for both sessions
169       // and objects.
170       ComputeContextIntegrity(&out->context, &integrity);
171
172       // add integrity at the beginning of context blob
173       buffer = out->context.contextBlob.t.buffer;
174       TPM2B_DIGEST_Marshal(&integrity, &buffer, NULL);
175
176       // orderly state should be cleared because of the update of state reset and
177       // state clear data
178       g_clearOrderly = TRUE;
179
180       return TPM_RC_SUCCESS;
181   }
182   #endif // CC_ContextSave


      Family “2.0”                           TCG Published                                 Page 363
      Level 00 Revision 01.16           Copyright © TCG 2006-2014                   October 30, 2014
Part 3: Commands                                                              Trusted Platform Module Library


28.3   TPM2_ContextLoad

28.3.1 General Description

This command is used to reload a context that has been saved by TPM2_ContextSave().
No authorization sessions of any type are allowed with this command and tag is required to be
TPM_ST_NO_SESSIONS (see note in 28.2.1).
The TPM will return TPM_RC_HIERARCHY if the context is associated with a hierarchy that is disabled.

NOTE            Contexts for authorization sessions and for sequence objects belong to the NULL hierarchy which is
                never disabled.

See the “Context Data” clause in TPM 2.0 Part 2 for a description of the values in the context parameter.
If the integrity HMAC of the saved context is not valid, the TPM shall return TPM_RC_INTEGRITY.
The TPM shall perform a check on the decrypted context as described in the "Context Confidentiality
Protections" clause of TPM 2.0 Part 1 and enter failure mode if the check fails.


Page 364                                      TCG Published                                         Family “2.0”
October 30, 2014                      Copyright © TCG 2006-2014                      Level 00 Revision 01.16
Trusted Platform Module Library                                                      Part 3: Commands


28.3.2 Command and Response

                            Table 181 — TPM2_ContextLoad Command
 Type                         Name                Description

 TPMI_ST_COMMAND_TAG          tag                 TPM_ST_NO_SESSIONS
 UINT32                       commandSize
 TPM_CC                       commandCode         TPM_CC_ContextLoad

 TPMS_CONTEXT                 context             the context blob


                            Table 182 — TPM2_ContextLoad Response
 Type                         Name                Description

 TPM_ST                       tag                 see clause 6
 UINT32                       responseSize
 TPM_RC                       responseCode

                                                  the handle assigned to the resource after it has been
 TPMI_DH_CONTEXT              loadedHandle
                                                  successfully loaded


Family “2.0”                             TCG Published                                         Page 365
Level 00 Revision 01.16             Copyright © TCG 2006-2014                        October 30, 2014
     Part 3: Commands                                                             Trusted Platform Module Library


     28.3.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "ContextLoad_fp.h"
3    #ifdef TPM_CC_ContextLoad // Conditional expansion of this file
4    #include "Context_spt_fp.h"


     Error Returns                 Meaning

     TPM_RC_CONTEXT_GAP            there is only one available slot and this is not the oldest saved
                                   session context
     TPM_RC_HANDLE                 'context. savedHandle' does not reference a saved session
     TPM_RC_HIERARCHY              'context.hierarchy' is disabled
     TPM_RC_INTEGRITY              context integrity check fail
     TPM_RC_OBJECT_MEMORY          no free slot for an object
     TPM_RC_SESSION_MEMORY         no free session slots
     TPM_RC_SIZE                   incorrect context blob size

 5   TPM_RC
 6   TPM2_ContextLoad(
 7       ContextLoad_In     *in,                  // IN: input parameter list
 8       ContextLoad_Out    *out                  // OUT: output parameter list
 9       )
10   {
11   // Local Variables
12       TPM_RC      result = TPM_RC_SUCCESS;
13
14       TPM2B_DIGEST       integrityToCompare;
15       TPM2B_DIGEST       integrity;
16       UINT16             integritySize;
17       UINT64             fingerprint;
18       BYTE               *buffer;
19       INT32              size;
20
21       TPM_HT             handleType;
22       TPM2B_SYM_KEY      symKey;
23       TPM2B_IV           iv;
24
25   // Input Validation
26
27       // Check context blob size
28       handleType = HandleGetType(in->context.savedHandle);
29
30       // Check integrity
31       // In this implementation, the same routine is used for both sessions
32       // and objects.
33       integritySize = CryptGetHashDigestSize(CONTEXT_INTEGRITY_HASH_ALG);
34
35       // Get integrity from context blob
36       buffer = in->context.contextBlob.t.buffer;
37       size = (INT32) in->context.contextBlob.t.size;
38       result = TPM2B_DIGEST_Unmarshal(&integrity, &buffer, &size);
39       if(result != TPM_RC_SUCCESS)
40           return result;
41       if(integrity.t.size != integritySize)
42           return TPM_RC_SIZE;
43
44       integritySize += sizeof(integrity.t.size);


     Page 366                                    TCG Published                                         Family “2.0”
     October 30, 2014                   Copyright © TCG 2006-2014                        Level 00 Revision 01.16
      Trusted Platform Module Library                                                Part 3: Commands

 45
 46       // Compute context integrity
 47       ComputeContextIntegrity(&in->context, &integrityToCompare);
 48
 49       // Compare integrity
 50       if(!Memory2BEqual(&integrity.b, &integrityToCompare.b))
 51           return TPM_RC_INTEGRITY + RC_ContextLoad_context;
 52
 53       // Compute context encryption key
 54       ComputeContextProtectionKey(&in->context, &symKey, &iv);
 55
 56       // Decrypt context data in place
 57       CryptSymmetricDecrypt(in->context.contextBlob.t.buffer + integritySize,
 58                             CONTEXT_ENCRYPT_ALG, CONTEXT_ENCRYPT_KEY_BITS,
 59                             TPM_ALG_CFB, symKey.t.buffer, &iv,
 60                             in->context.contextBlob.t.size - integritySize,
 61                             in->context.contextBlob.t.buffer + integritySize);
 62
 63       // Read the fingerprint value, skip the leading integrity size
 64       MemoryCopy(&fingerprint, in->context.contextBlob.t.buffer + integritySize,
 65                  sizeof(fingerprint), sizeof(fingerprint));
 66       // Check fingerprint. If the check fails, TPM should be put to failure mode
 67       if(fingerprint != in->context.sequence)
 68           FAIL(FATAL_ERROR_INTERNAL);
 69
 70       // Perform object or session specific input check
 71       switch(handleType)
 72       {
 73       case TPM_HT_TRANSIENT:
 74       {
 75           // Get a pointer to the object in the context blob
 76           OBJECT      *outObject = (OBJECT *)(in->context.contextBlob.t.buffer
 77                                   + integritySize + sizeof(fingerprint));
 78
 79           // Discard any changes to the handle that the TRM might have made
 80           in->context.savedHandle = TRANSIENT_FIRST;
 81
 82           // If hierarchy is disabled, no object context can be loaded in this
 83           // hierarchy
 84           if(!HierarchyIsEnabled(in->context.hierarchy))
 85               return TPM_RC_HIERARCHY + RC_ContextLoad_context;
 86
 87           // Restore object. A TPM_RC_OBJECT_MEMORY error may be returned at
 88           // this point
 89           result = ObjectContextLoad(outObject, &out->loadedHandle);
 90           if(result != TPM_RC_SUCCESS)
 91               return result;
 92
 93           // If this is a sequence object, the crypto library may need to
 94           // reformat the data into an internal format
 95           if(ObjectIsSequence(outObject))
 96               SequenceDataImportExport(ObjectGet(out->loadedHandle),
 97                                        outObject, IMPORT_STATE);
 98
 99           break;
100       }
101       case TPM_HT_POLICY_SESSION:
102       case TPM_HT_HMAC_SESSION:
103       {
104
105           SESSION      *session = (SESSION *)(in->context.contextBlob.t.buffer
106                                            + integritySize + sizeof(fingerprint));
107
108           // This command may cause the orderlyState to be cleared due to
109           // the update of state reset data. If this is the case, check if NV is
110           // available first

      Family “2.0”                            TCG Published                                 Page 367
      Level 00 Revision 01.16           Copyright © TCG 2006-2014                    October 30, 2014
      Part 3: Commands                                                  Trusted Platform Module Library

111          if(gp.orderlyState != SHUTDOWN_NONE)
112          {
113              // The command needs NV update. Check if NV is available.
114              // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned
115              // at this point
116              result = NvIsAvailable();
117              if(result != TPM_RC_SUCCESS)
118                  return result;
119          }
120
121          // Check if input handle points to a valid saved session
122          if(!SessionIsSaved(in->context.savedHandle))
123              return TPM_RC_HANDLE + RC_ContextLoad_context;
124
125          // Restore session. A TPM_RC_SESSION_MEMORY, TPM_RC_CONTEXT_GAP error
126          // may be returned at this point
127          result = SessionContextLoad(session, &in->context.savedHandle);
128          if(result != TPM_RC_SUCCESS)
129              return result;
130
131          out->loadedHandle = in->context.savedHandle;
132
133          // orderly state should be cleared because of the update of state
134          // reset and state clear data
135          g_clearOrderly = TRUE;
136
137          break;
138      }
139      default:
140          // Context blob may only have an object handle or a session handle.
141          // All the other handle type should be filtered out at unmarshal
142          pAssert(FALSE);
143          break;
144      }
145
146       return TPM_RC_SUCCESS;
147   }
148   #endif // CC_ContextLoad


      Page 368                              TCG Published                                 Family “2.0”
      October 30, 2014               Copyright © TCG 2006-2014               Level 00 Revision 01.16
Trusted Platform Module Library                                                            Part 3: Commands


28.4   TPM2_FlushContext

28.4.1 General Description

This command causes all context associated with a loaded object or session to be removed from TPM
memory.
This command may not be used to remove a persistent object from the TPM.
A session does not have to be loaded in TPM memory to have its context flushed. The saved session
context associated with the indicated handle is invalidated.
No sessions of any type are allowed with               this   command    and    tag   is    required   to   be
TPM_ST_NO_SESSIONS (see note in 28.2.1).
If the handle is for a transient object and the handle is not associated with a loaded object, then the TPM
shall return TPM_RC_HANDLE.
If the handle is for an authorization session and the handle does not reference a loaded or active session,
then the TPM shall return TPM_RC_HANDLE.
NOTE flushHandle is a parameter and not a handle. If it were in the handle area, the TPM would
validate that the context for the referenced entity is in the TPM. When a TPM2_FlushContext references a
saved session context, it is not necessary for the context to be in the TPM. When the flushHandle is in
the parameter area, the TPM does not validate that associated context is actually in the TPM.


Family “2.0”                                TCG Published                                         Page 369
Level 00 Revision 01.16              Copyright © TCG 2006-2014                             October 30, 2014
Part 3: Commands                                                     Trusted Platform Module Library


28.4.2 Command and Response

                       Table 183 — TPM2_FlushContext Command
 Type                    Name                  Description

 TPMI_ST_COMMAND_TAG     tag                   TPM_ST_NO_SESSIONS
 UINT32                  commandSize
 TPM_CC                  commandCode           TPM_CC_FlushContext

                                               the handle of the item to flush
 TPMI_DH_CONTEXT         flushHandle
                                               NOTE        This is a use of a handle as a parameter.


                       Table 184 — TPM2_FlushContext Response
 Type                    Name                  Description

 TPM_ST                  tag                   see clause 6
 UINT32                  responseSize
 TPM_RC                  responseCode


Page 370                               TCG Published                                         Family “2.0”
October 30, 2014               Copyright © TCG 2006-2014                    Level 00 Revision 01.16
     Trusted Platform Module Library                                                               Part 3: Commands


     28.4.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "FlushContext_fp.h"
3    #ifdef TPM_CC_FlushContext // Conditional expansion of this file


     Error Returns                     Meaning

     TPM_RC_HANDLE                     flushHandle does not reference a loaded object or session

 4   TPM_RC
 5   TPM2_FlushContext(
 6       FlushContext_In       *in                  // IN: input parameter list
 7       )
 8   {
 9   // Internal Data Update
10
11       // Call object or session specific routine to flush
12       switch(HandleGetType(in->flushHandle))
13       {
14       case TPM_HT_TRANSIENT:
15           if(!ObjectIsPresent(in->flushHandle))
16               return TPM_RC_HANDLE;
17           // Flush object
18           ObjectFlush(in->flushHandle);
19           break;
20       case TPM_HT_HMAC_SESSION:
21       case TPM_HT_POLICY_SESSION:
22           if(   !SessionIsLoaded(in->flushHandle)
23              && !SessionIsSaved(in->flushHandle)
24             )
25               return TPM_RC_HANDLE;
26
27           // If the session to be flushed is the exclusive audit session, then
28           // indicate that there is no exclusive audit session any longer.
29           if(in->flushHandle == g_exclusiveAuditSession)
30               g_exclusiveAuditSession = TPM_RH_UNASSIGNED;
31
32           // Flush session
33           SessionFlush(in->flushHandle);
34           break;
35       default:
36           // This command only take object or session handle.              Other handles
37           // should be filtered out at handle unmarshal
38           pAssert(FALSE);
39           break;
40       }
41
42       return TPM_RC_SUCCESS;
43   }
44   #endif // CC_FlushContext


     Family “2.0”                                  TCG Published                                          Page 371
     Level 00 Revision 01.16               Copyright © TCG 2006-2014                               October 30, 2014
Part 3: Commands                                                               Trusted Platform Module Library


28.5     TPM2_EvictControl

28.5.1 General Description

This command allows a transient object to be made persistent or a persistent object to be evicted.

NOTE 1           A transient object is one that may be removed from TPM memory using either TPM2_FlushContext
                 or TPM2_Startup(). A persistent object is not removed from TPM memory by TPM2_FlushContext()
                 or TPM2_Startup().

If objectHandle is a transient object, then the call is to make the object persistent and assign
persistentHandle to the persistent version of the object. If objectHandle is a persistent object, then the call
is to evict the persistent object.
Before execution of TPM2_EvictControl code below, the TPM verifies that objectHandle references an
object that is resident on the TPM and that persistentHandle is a valid handle for a persistent object.

NOTE 2           This requirement simplifies the unmarshaling code so that it only need check that persistentHandle
                 is always a persistent object.

If objectHandle references a transient object:
a) The TPM shall return TPM_RC_ATTRIBUTES if
     1) it is in the hierarchy of TPM_RH_NULL,
     2) only the public portion of the object is loaded, or
     3) the stClear is SET in the object or in an ancestor key.
b) The TPM shall return TPM_RC_HIERARCHY if the object is not in the proper hierarchy as
   determined by auth.
     1) If auth is TPM_RH_PLATFORM, the proper hierarchy is the Platform hierarchy.
     2) If auth is TPM_RH_OWNER, the proper hierarchy is either the Storage or the Endorsement
        hierarchy.
c) The TPM shall return TPM_RC_RANGE if persistentHandle is not in the proper range as determined
   by auth.
     1) If auth is TPM_RH_OWNER, then persistentHandle shall be in the inclusive range of
        81 00 00 0016 to 81 7F FF FF16.
     2) If auth is TPM_RH_PLATFORM, then persistentHandle shall be in the inclusive range of
        81 80 00 0016 to 81 FF FF FF16.
d) The TPM shall return TPM_RC_NV_DEFINED if a persistent object exists with the same handle as
   persistentHandle.
e) The TPM shall return TPM_RC_NV_SPACE if insufficient space is available to make the object
   persistent.
f)   The TPM shall return TPM_RC_NV_SPACE if execution of this command will prevent the TPM from
     being able to hold two transient objects of any kind.

     NOTE 3          This requirement anticipates that a TPM may be implemented suc h that all TPM memory is non-
                     volatile and not subject to endurance issues. In such case, there is no movement of an object
                     between memory of different types and it is necessary that the TPM ensure that it is always
                     possible for the management software to m ove objects to/from TPM memory in order to ensure
                     that the objects required for command execution can be context restored.

g) If the TPM returns TPM_RC_SUCCESS, the object referenced by objectHandle will not be flushed
   and both objectHandle and persistentHandle may be used to access the object.

Page 372                                       TCG Published                                        Family “2.0”
October 30, 2014                       Copyright © TCG 2006-2014                      Level 00 Revision 01.16
Trusted Platform Module Library                                                             Part 3: Commands

If objectHandle references a persistent object:
a) The TPM shall return TPM_RC_RANGE if objectHandle is not in the proper range as determined by
   auth. If auth is TPM_RC_OWNER, objectHandle shall be in the inclusive range of 81 00 00 0016 to
   81 7F FF FF16. If auth is TPM_RC_PLATFORM, objectHandle may be any valid persistent object
   handle.
b) If the TPM returns TPM_RC_SUCCESS, objectHandle will be removed from persistent memory and
   no longer be accessible.

NOTE 4          The persistent object is not converted to a transient object, as this would prevent the immediate
                revocation of an object by removing it from persistent memory.


Family “2.0”                                  TCG Published                                          Page 373
Level 00 Revision 01.16               Copyright © TCG 2006-2014                             October 30, 2014
Part 3: Commands                                                    Trusted Platform Module Library


28.5.2 Command and Response

                       Table 185 — TPM2_EvictControl Command
 Type                   Name                   Description

 TPMI_ST_COMMAND_TAG    tag                    TPM_ST_SESSIONS
 UINT32                 commandSize
 TPM_CC                 commandCode            TPM_CC_EvictControl {NV}

                                               TPM_RH_OWNER or TPM_RH_PLATFORM+{PP}
 TPMI_RH_PROVISION      @auth                  Auth Handle: 1
                                               Auth Role: USER
                                               the handle of a loaded object
 TPMI_DH_OBJECT         objectHandle
                                               Auth Index: None

                                               if objectHandle is a transient object handle, then this is
                                               the persistent handle for the object
 TPMI_DH_PERSISTENT     persistentHandle
                                               if objectHandle is a persistent object handle, then it
                                               shall be the same value as persistentHandle


                       Table 186 — TPM2_EvictControl Response
 Type                   Name                   Description

 TPM_ST                 tag                    see clause 6
 UINT32                 responseSize
 TPM_RC                 responseCode


Page 374                               TCG Published                                       Family “2.0”
October 30, 2014              Copyright © TCG 2006-2014                     Level 00 Revision 01.16
     Trusted Platform Module Library                                                                Part 3: Commands


     28.5.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "EvictControl_fp.h"
3    #ifdef TPM_CC_EvictControl // Conditional expansion of this file


     Error Returns                     Meaning

     TPM_RC_ATTRIBUTES                 an object with temporary, stClear or publicOnly attribute SET cannot
                                       be made persistent
     TPM_RC_HIERARCHY                  auth cannot authorize the operation in the hierarchy of evictObject
     TPM_RC_HANDLE                     evictHandle of the persistent object to be evicted is not the same as
                                       the persistentHandle argument
     TPM_RC_NV_HANDLE                  persistentHandle is unavailable
     TPM_RC_NV_SPACE                   no space in NV to make evictHandle persistent
     TPM_RC_RANGE                      persistentHandle is not in the range corresponding to the hierarchy of
                                       evictObject

 4   TPM_RC
 5   TPM2_EvictControl(
 6       EvictControl_In       *in                   // IN: input parameter list
 7       )
 8   {
 9       TPM_RC       result;
10       OBJECT       *evictObject;
11
12       // The command needs NV update. Check if NV is available.
13       // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
14       // this point
15       result = NvIsAvailable();
16       if(result != TPM_RC_SUCCESS) return result;
17
18   // Input Validation
19
20       // Get internal object pointer
21       evictObject = ObjectGet(in->objectHandle);
22
23       // Temporary, stClear or public only objects can not be made persistent
24       if(   evictObject->attributes.temporary == SET
25          || evictObject->attributes.stClear == SET
26          || evictObject->attributes.publicOnly == SET
27         )
28           return TPM_RC_ATTRIBUTES + RC_EvictControl_objectHandle;
29
30       // If objectHandle refers to a persistent object, it should be the same as
31       // input persistentHandle
32       if(   evictObject->attributes.evict == SET
33          && evictObject->evictHandle != in->persistentHandle
34         )
35           return TPM_RC_HANDLE + RC_EvictControl_objectHandle;
36
37       // Additional auth validation
38       if(in->auth == TPM_RH_PLATFORM)
39       {
40           // To make persistent
41           if(evictObject->attributes.evict == CLEAR)
42           {
43               // Platform auth can not set evict object in storage or endorsement
44               // hierarchy

     Family “2.0”                                   TCG Published                                               Page 375
     Level 00 Revision 01.16               Copyright © TCG 2006-2014                                October 30, 2014
     Part 3: Commands                                               Trusted Platform Module Library

45              if(evictObject->attributes.ppsHierarchy == CLEAR)
46                  return TPM_RC_HIERARCHY + RC_EvictControl_objectHandle;
47
48              // Platform cannot use a handle outside of platform persistent range.
49              if(!NvIsPlatformPersistentHandle(in->persistentHandle))
50                  return TPM_RC_RANGE + RC_EvictControl_persistentHandle;
51          }
52          // Platform auth can delete any persistent object
53      }
54      else if(in->auth == TPM_RH_OWNER)
55      {
56          // Owner auth can not set or clear evict object in platform hierarchy
57          if(evictObject->attributes.ppsHierarchy == SET)
58              return TPM_RC_HIERARCHY + RC_EvictControl_objectHandle;
59
60          // Owner cannot use a handle outside of owner persistent range.
61          if(   evictObject->attributes.evict == CLEAR
62             && !NvIsOwnerPersistentHandle(in->persistentHandle)
63            )
64              return TPM_RC_RANGE + RC_EvictControl_persistentHandle;
65      }
66      else
67      {
68          // Other auth is not allowed in this command and should be filtered out
69          // at unmarshal process
70          pAssert(FALSE);
71      }
72
73   // Internal Data Update
74
75      // Change evict state
76      if(evictObject->attributes.evict == CLEAR)
77      {
78          // Make object persistent
79          // A TPM_RC_NV_HANDLE or TPM_RC_NV_SPACE error may be returned at this
80          // point
81          result = NvAddEvictObject(in->persistentHandle, evictObject);
82          if(result != TPM_RC_SUCCESS) return result;
83      }
84      else
85      {
86          // Delete the persistent object in NV
87          NvDeleteEntity(evictObject->evictHandle);
88      }
89
90      return TPM_RC_SUCCESS;
91
92   }
93   #endif // CC_EvictControl


     Page 376                              TCG Published                                Family “2.0”
     October 30, 2014               Copyright © TCG 2006-2014             Level 00 Revision 01.16
Trusted Platform Module Library                                                               Part 3: Commands


29     Clocks and Timers

29.1    TPM2_ReadClock

29.1.1 General Description

This command reads the current TPMS_TIME_INFO structure that contains the current setting of Time,
Clock, resetCount, and restartCount.
No authorization sessions of any type are allowed with this command and tag is required to be
TPM_ST_NO_SESSIONS.

NOTE           This command is intended to allow the TCB to have access to values that have the potential to be
               privacy sensitive. The values may be read without authorization because the TCB will not disclose
               these values. Since they are not signed and cannot be accessed in a command that uses an
               authorization session, it is not possible for any entity, other than the TCB, to be assured that the
               values are accurate.


Family “2.0”                                  TCG Published                                            Page 377
Level 00 Revision 01.16               Copyright © TCG 2006-2014                              October 30, 2014
Part 3: Commands                                            Trusted Platform Module Library


29.1.2 Command and Response

                      Table 187 — TPM2_ReadClock Command
Type                   Name                  Description

TPMI_ST_COMMAND_TAG    tag                   TPM_ST_NO_SESSIONS
UINT32                 commandSize
TPM_CC                 commandCode           TPM_CC_ReadClock


                      Table 188 — TPM2_ReadClock Response
Type                   Name                  Description

TPM_ST                 tag                   see clause 6
UINT32                 responseSize
TPM_RC                 responseCode

TPMS_TIME_INFO         currentTime


Page 378                              TCG Published                           Family “2.0”
October 30, 2014             Copyright © TCG 2006-2014            Level 00 Revision 01.16
     Trusted Platform Module Library                                      Part 3: Commands


     29.1.3 Detailed Actions

 1   #include "InternalRoutines.h"
 2   #include "ReadClock_fp.h"
 3   #ifdef TPM_CC_ReadClock // Conditional expansion of this file
 4   TPM_RC
 5   TPM2_ReadClock(
 6       ReadClock_Out    *out            // OUT: output parameter list
 7       )
 8   {
 9   // Command Output
10
11       out->currentTime.time = g_time;
12       TimeFillInfo(&out->currentTime.clockInfo);
13
14       return TPM_RC_SUCCESS;
15   }
16   #endif // CC_ReadClock


     Family “2.0”                            TCG Published                       Page 379
     Level 00 Revision 01.16           Copyright © TCG 2006-2014          October 30, 2014
Part 3: Commands                                                                  Trusted Platform Module Library


29.2   TPM2_ClockSet

29.2.1 General Description

This command is used to advance the value of the TPM’s Clock. The command will fail if newTime is less
than the current value of Clock or if the new time is greater than FF FF 00 00 00 00 00 0016. If both of
these checks succeed, Clock is set to newTime. If either of these checks fails, the TPM shall return
TPM_RC_VALUE and make no change to Clock.

NOTE           This maximum setting would prevent Clock from rolling over to zero for approximately 8,000 year s if
               the Clock update rate was set so that TPM time was passing 33 percent faster than real time. This
               would still be more than 6,000 years before Clock would roll over to zero. Because Clock will not roll
               over in the lifetime of the TPM, there is no need for external software to deal with the possibility that
               Clock may wrap around.

If the value of Clock after the update makes the volatile and non-volatile versions of
TPMS_CLOCK_INFO.clock differ by more than the reported update interval, then the TPM shall update
the non-volatile version of TPMS_CLOCK_INFO.clock before returning.
This command requires Platform Authorization or Owner Authorization.


Page 380                                       TCG Published                                            Family “2.0”
October 30, 2014                       Copyright © TCG 2006-2014                         Level 00 Revision 01.16
Trusted Platform Module Library                                                         Part 3: Commands


29.2.2 Command and Response

                              Table 189 — TPM2_ClockSet Command
Type                          Name                  Description

TPMI_ST_COMMAND_TAG           tag                   TPM_ST_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode           TPM_CC_ClockSet {NV}

                                                    TPM_RH_OWNER or TPM_RH_PLATFORM+{PP}
TPMI_RH_PROVISION             @auth                 Auth Handle: 1
                                                    Auth Role: USER

UINT64                        newTime               new Clock setting in milliseconds


                              Table 190 — TPM2_ClockSet Response
Type                          Name                  Description

TPM_ST                        tag                   see clause 6
UINT32                        responseSize
TPM_RC                        responseCode


Family “2.0”                                 TCG Published                                     Page 381
Level 00 Revision 01.16             Copyright © TCG 2006-2014                           October 30, 2014
     Part 3: Commands                                                     Trusted Platform Module Library


     29.2.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "ClockSet_fp.h"
3    #ifdef TPM_CC_ClockSet // Conditional expansion of this file

     Read the current TPMS_TIMER_INFO structure settings

     Error Returns                 Meaning

     TPM_RC_VALUE                  invalid new clock

 4   TPM_RC
 5   TPM2_ClockSet(
 6       ClockSet_In       *in              // IN: input parameter list
 7       )
 8   {
 9   #define CLOCK_UPDATE_MASK    ((1ULL << NV_CLOCK_UPDATE_INTERVAL)- 1)
10       UINT64      clockNow;
11
12   // Input Validation
13
14       // new time can not be bigger than 0xFFFF000000000000 or smaller than
15       // current clock
16       if(in->newTime > 0xFFFF000000000000ULL
17               || in->newTime < go.clock)
18           return TPM_RC_VALUE + RC_ClockSet_newTime;
19
20   // Internal Data Update
21
22       // Internal Data Update
23       clockNow = go.clock;    // grab the old value
24       go.clock = in->newTime;       // set the new value
25       // Check to see if the update has caused a need for an nvClock update
26       if((in->newTime & CLOCK_UPDATE_MASK) > (clockNow & CLOCK_UPDATE_MASK))
27       {
28           CryptDrbgGetPutState(GET_STATE);
29           NvWriteReserved(NV_ORDERLY_DATA, &go);
30
31           // Now the time state is safe
32           go.clockSafe = YES;
33       }
34
35       return TPM_RC_SUCCESS;
36   }
37   #endif // CC_ClockSet


     Page 382                                  TCG Published                                Family “2.0”
     October 30, 2014                  Copyright © TCG 2006-2014               Level 00 Revision 01.16
Trusted Platform Module Library                                                                Part 3: Commands


29.3   TPM2_ClockRateAdjust

29.3.1 General Description

This command adjusts the rate of advance of Clock and Time to provide a better approximation to real
time.
The rateAdjust value is relative to the current rate and not the nominal rate of advance.

EXAMPLE 1       If this command had been called three times with rateAdjust = TPM_CLOCK_COARSE_SLOWER
                and once with rateAdjust = TPM_CLOCK_COARSE_FASTER, the net effect will be as if the
                command had been called twice with rateAdjust = TPM_CLOCK_COARSE_SLOWER.

The range of adjustment shall be sufficient to allow Clock and Time to advance at real time but no more.
If the requested adjustment would make the rate advance faster or slower than the nominal accuracy of
the input frequency, the TPM shall return TPM_RC_VALUE.

EXAMPLE 2       If the frequency tolerance of the TPM's input clock is +/-10 percent, then the TPM will return
                TPM_RC_VALUE if the adjustment would make Clock run more than 10 percent faster or slower than
                nominal. That is, if the input oscillator were nominally 100 megahertz (MHz), then 1 millisecond (ms)
                would normally take 100,000 counts. The update Clock should be adjustable so that 1 ms is between
                90,000 and 110,000 counts.

The interpretation of “fine” and “coarse” adjustments is implementation-specific.
The nominal rate of advance for Clock and Time shall be accurate to within 15 percent. That is, with no
adjustment applied, Clock and Time shall be advanced at a rate within 15 percent of actual time.

NOTE            If the adjustments are incorrect, it will be possible to make the difference between advance of
                Clock/Time and real time to be as much as 1.15 2 or ~1.33.

Changes to the current Clock update rate adjustment need not be persisted across TPM power cycles.


Family “2.0”                                   TCG Published                                             Page 383
Level 00 Revision 01.16                Copyright © TCG 2006-2014                               October 30, 2014
Part 3: Commands                                                   Trusted Platform Module Library


29.3.2 Command and Response

                      Table 191 — TPM2_ClockRateAdjust Command
Type                     Name                  Description

TPMI_ST_COMMAND_TAG      tag                   TPM_ST_SESSIONS
UINT32                   commandSize
TPM_CC                   commandCode           TPM_CC_ClockRateAdjust

                                               TPM_RH_OWNER or TPM_RH_PLATFORM+{PP}
TPMI_RH_PROVISION        @auth                 Auth Handle: 1
                                               Auth Role: USER

TPM_CLOCK_ADJUST         rateAdjust            Adjustment to current Clock update rate


                      Table 192 — TPM2_ClockRateAdjust Response
Type                     Name                  Description

TPM_ST                   tag                   see clause 6
UINT32                   responseSize
TPM_RC                   responseCode


Page 384                                TCG Published                                    Family “2.0”
October 30, 2014               Copyright © TCG 2006-2014                  Level 00 Revision 01.16
     Trusted Platform Module Library                                        Part 3: Commands


     29.3.3 Detailed Actions

 1   #include "InternalRoutines.h"
 2   #include "ClockRateAdjust_fp.h"
 3   #ifdef TPM_CC_ClockRateAdjust // Conditional expansion of this file
 4   TPM_RC
 5   TPM2_ClockRateAdjust(
 6       ClockRateAdjust_In    *in            // IN: input parameter list
 7       )
 8   {
 9   // Internal Data Update
10       TimeSetAdjustRate(in->rateAdjust);
11
12       return TPM_RC_SUCCESS;
13   }
14   #endif // CC_ClockRateAdjust


     Family “2.0”                             TCG Published                        Page 385
     Level 00 Revision 01.16           Copyright © TCG 2006-2014            October 30, 2014
Part 3: Commands                                                                 Trusted Platform Module Library


30     Capability Commands

30.1     Introduction

The TPM has numerous values that indicate the state, capabilities, and properties of the TPM. These
values are needed for proper management of the TPM. The TPM2_GetCapability() command is used to
access these values.
TPM2_GetCapability() allows reporting of multiple values in a single call. The values are grouped
according to type.

NOTE            TPM2_TestParms()is used to determine if a TPM supports a particular combination of algorith m
                parameters


30.2     TPM2_GetCapability

30.2.1 General Description

This command returns various information regarding the TPM and its current state.
The capability parameter determines the category of data returned. The property parameter selects the
first value of the selected category to be returned. If there is no property that corresponds to the value of
property, the next higher value is returned, if it exists.

EXAMPLE 1       The list of handles of transient objects currently loaded in the TPM may be read one at a time. O n
                the first read, set the property to TRANSIENT_FIRST and propertyCount to one. If a transient object
                is present, the lowest numbered handle is returned and moreData will be YES if transient objects
                with higher handles are loaded. On the subsequent call, u se returned handle value plus 1 in order to
                access the next higher handle.

The propertyCount parameter indicates the number of capabilities in the indicated group that are
requested. The TPM will return the number of requested values (propertyCount) or until the last property
of the requested type has been returned.

NOTE 1          The type of the capability is determined by a combination of capability and property.

NOTE 2          If the propertyCount selects an unimplemented property, the next higher implemented property is
                returned.

When all of the properties of the requested type have been returned, the moreData parameter in the
response will be set to NO. Otherwise, it will be set to YES.

NOTE 3          The moreData parameter will be YES if there are more properties even if the requested number of
                capabilities has been returned.

The TPM is not required to return more than one value at a time. It is not required to provide the same
number of values in response to subsequent requests.

EXAMPLE 2       A TPM may return 4 properties in response to a TPM2_GetCapability( capability =
                TPM_CAP_TPM_PROPERTY, property = TPM_PT_MANUFACTURER, propertyCount = 8 ) and for a
                latter request with the same parameters, the TPM m ay return as few as one and as many as 8
                values.

When the TPM is in Failure mode, a TPM is required to allow use of this command for access of the
following capabilities:


Page 386                                       TCG Published                                            Family “2.0”
October 30, 2014                       Copyright © TCG 2006-2014                        Level 00 Revision 01.16
Trusted Platform Module Library                                                                  Part 3: Commands


         TPM_PT_MANUFACTURER
         TPM_PT_VENDOR_STRING_1
    
                                           (3)
          TPM_PT_VENDOR_STRING_2
    
                                           (3)
          TPM_PT_VENDOR_STRING_3
    
                                           (3)
          TPM_PT_VENDOR_STRING_4
         TPM_PT_VENDOR_TPM_TYPE
         TPM_PT_FIRMWARE_VERSION_1
         TPM_PT_FIRMWARE_VERSION_2

NOTE 4          If the vendor string does not require one of these values, the property type does not need to exist.

A vendor may optionally allow the TPM to return other values.
If in Failure mode and a capability is requested that is not available in Failure mode, the TPM shall return
no value.

EXAMPLE 3       Assume the TPM is in Failure mode and the TPM only supports reporting of the minimum required
                set of properties (the limited set to TPML_TAGGED_PCR_PROPERTY values). If a
                TPM2_GetCapability is received requesting a capability that has a property type value greater than
                TPM_PT_FIRMWARE_VERSION_2, the TPM will return a zero length list with the moreData
                parameter set to NO. If the property type is less than TPM_PT_MANUFACTURER, the TPM will
                return TPM_PT_MANUFACTURER.

In Failure mode, tag is required to be TPM_ST_NO_SESSIONS or the TPM shall return
TPM_RC_FAILURE.
The capability categories and the types of the return values are:

 capability                            property                    Return Type
                                                      (1)
 TPM_CAP_ALGS                          TPM_ALG_ID                  TPML_ALG_PROPERTY
 TPM_CAP_HANDLES                       TPM_HANDLE                  TPML_HANDLE
 TPM_CAP_COMMANDS                      TPM_CC                      TPML_CCA
 TPM_CAP_PP_COMMANDS                   TPM_CC                      TPML_CC
 TPM_CAP_AUDIT_COMMANDS                TPM_CC                      TPML_CC
 TPM_CAP_PCRS                          Reserved                    TPML_PCR_SELECTION
 TPM_CAP_TPM_PROPERTIES                TPM_PT                      TPML_TAGGED_TPM_PROPERTY
 TPM_CAP_PCR_PROPERTIES                TPM_PT_PCR                  TPML_TAGGED_PCR_PROPERTY
                                                            (1)
 TPM_CAP_ECC_CURVE                     TPM_ECC_CURVE               TPML_ECC_CURVE
 TPM_CAP_VENDOR_PROPERTY               manufacturer specific       manufacturer-specific values
 NOTES:
 (1) The TPM_ALG_ID or TPM_ECC_CURVE is cast to a UINT32


Family “2.0”                                     TCG Published                                             Page 387
Level 00 Revision 01.16                Copyright © TCG 2006-2014                                 October 30, 2014
Part 3: Commands                                                               Trusted Platform Module Library


      TPM_CAP_ALGS – Returns a list of TPMS_ALG_PROPERTIES. Each entry is an algorithm ID
       and a set of properties of the algorithm.
      TPM_CAP_HANDLES – Returns a list of all of the handles within the handle range of the
       property parameter. The range of the returned handles is determined by the handle type (the
       most-significant octet (MSO) of the property). Any of the defined handle types is allowed

   EXAMPLE 4        If the MSO of property is TPM_HT_NV_INDEX, then the TPM will return a list of NV Index
                    values.

   EXAMPLE 5        If the MSO of property is TPM_HT_PCR, then the TPM will return a list of PCR.

      For this capability, use of TPM_HT_LOADED_SESSION and TPM_HT_SAVED_SESSION is
       allowed. Requesting handles with a handle type of TPM_HT_LOADED_SESSION will return
       handles for loaded sessions. The returned handle values will have a handle type of either
       TPM_HT_HMAC_SESSION or TPM_HT_POLICY_SESSION. If saved sessions are requested,
       all returned values will have the TPM_HT_HMAC_SESSION handle type because the TPM does
       not track the session type of saved sessions.

   NOTE 5           TPM_HT_LOADED_SESSION and TPM_HT_HMAC_SESSION have the same value, as do
                    TPM_HT_SAVED_SESSION and TPM_HT_POLICY_SESSION. It is not possible to request that
                    the TPM return a list of loaded HMAC sessions without including the policy sessions.

      TPM_CAP_COMMANDS – Returns a list of the command attributes for all of the commands
       implemented in the TPM, starting with the TPM_CC indicated by the property parameter. If
       vendor specific commands are implemented, the vendor-specific command attribute with the
       lowest commandIndex, is returned after the non-vendor-specific (base) command.

   NOTE 6           The type of the property parameter is a TPM_CC while the type of the returned list is
                    TPML_CCA.

      TPM_CAP_PP_COMMANDS – Returns a list of all of the commands currently requiring Physical
       Presence for confirmation of platform authorization. The list will start with the TPM_CC indicated
       by property.
      TPM_CAP_AUDIT_COMMANDS – Returns a list of all of the commands currently set for
       command audit.
      TPM_CAP_PCRS – Returns the current allocation of PCR in a TPML_PCR_SELECTION. The
       property parameter shall be zero. The TPM will always respond to this command with the full
       PCR allocation and moreData will be NO.
      TPM_CAP_TPM_PROPERTIES – Returns a list of tagged properties. The tag is a TPM_PT and
       the property is a 32-bit value. The properties are returned in groups. Each property group is on a
       256-value boundary (that is, the boundary occurs when the TPM_PT is evenly divisible by 256).
       The TPM will only return values in the same group as the property parameter in the command.
      TPM_CAP_PCR_PROPERTIES – Returns a list of tagged PCR properties. The tag is a
       TPM_PT_PCR and the property is a TPMS_PCR_SELECT.
   The input command property is a TPM_PT_PCR (see TPM 2.0 Part 2 for PCR properties to be
   requested) that specifies the first property to be returned. If propertyCount is greater than 1, the list of
   properties begins with that property and proceeds in TPM_PT_PCR sequence.
   Each item in the list is a TPMS_PCR_SELECT structure that contains a bitmap of all PCR.

   NOTE 7           A PCR index in all banks (all hash algorithms) has the same properties, so the hash algorithm is
                    not specified here.


Page 388                                      TCG Published                                          Family “2.0”
October 30, 2014                      Copyright © TCG 2006-2014                       Level 00 Revision 01.16
Trusted Platform Module Library                                                           Part 3: Commands


       TPM_CAP_TPM_ECC_CURVES – Returns a list of ECC curve identifiers currently available for
        use in the TPM.
The moreData parameter will have a value of YES if there are more values of the requested type that
were not returned.
If no next capability exists, the TPM will return a zero-length list and moreData will have a value of NO.


Family “2.0”                                 TCG Published                                        Page 389
Level 00 Revision 01.16               Copyright © TCG 2006-2014                          October 30, 2014
Part 3: Commands                                                     Trusted Platform Module Library


30.2.2 Command and Response

                        Table 193 — TPM2_GetCapability Command
 Type                     Name                 Description

                                               TPM_ST_SESSIONS if an audit session is present;
 TPMI_ST_COMMAND_TAG      tag
                                               otherwise, TPM_ST_NO_SESSIONS
 UINT32                   commandSize
 TPM_CC                   commandCode          TPM_CC_GetCapability

 TPM_CAP                  capability           group selection; determines the format of the response
 UINT32                   property             further definition of information
 UINT32                   propertyCount        number of properties of the indicated type to return


                        Table 194 — TPM2_GetCapability Response
 Type                     Name                 Description

 TPM_ST                   tag                  see clause 6
 UINT32                   responseSize
 TPM_RC                   responseCode

 TPMI_YES_NO              moreData             flag to indicate if there are more values of this type
 TPMS_CAPABILITY_DATA     capabilityData       the capability data


Page 390                               TCG Published                                       Family “2.0”
October 30, 2014                Copyright © TCG 2006-2014                   Level 00 Revision 01.16
     Trusted Platform Module Library                                                                 Part 3: Commands


     30.2.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "GetCapability_fp.h"
3    #ifdef TPM_CC_GetCapability // Conditional expansion of this file


     Error Returns                     Meaning

     TPM_RC_HANDLE                     value of property is in an unsupported handle range for the
                                       TPM_CAP_HANDLES capability value
     TPM_RC_VALUE                      invalid capability; or property is not 0 for the TPM_CAP_PCRS
                                       capability value

 4   TPM_RC
 5   TPM2_GetCapability(
 6       GetCapability_In      *in,                  // IN: input parameter list
 7       GetCapability_Out     *out                  // OUT: output parameter list
 8       )
 9   {
10   // Command Output
11
12       // Set output capability type the same as input type
13       out->capabilityData.capability = in->capability;
14
15       switch(in->capability)
16       {
17       case TPM_CAP_ALGS:
18           out->moreData = AlgorithmCapGetImplemented((TPM_ALG_ID) in->property,
19                           in->propertyCount, &out->capabilityData.data.algorithms);
20           break;
21       case TPM_CAP_HANDLES:
22           switch(HandleGetType((TPM_HANDLE) in->property))
23           {
24           case TPM_HT_TRANSIENT:
25               // Get list of handles of loaded transient objects
26               out->moreData = ObjectCapGetLoaded((TPM_HANDLE) in->property,
27                                                  in->propertyCount,
28                                                  &out->capabilityData.data.handles);
29               break;
30           case TPM_HT_PERSISTENT:
31               // Get list of handles of persistent objects
32               out->moreData = NvCapGetPersistent((TPM_HANDLE) in->property,
33                                                  in->propertyCount,
34                                                  &out->capabilityData.data.handles);
35               break;
36           case TPM_HT_NV_INDEX:
37               // Get list of defined NV index
38               out->moreData = NvCapGetIndex((TPM_HANDLE) in->property,
39                                             in->propertyCount,
40                                             &out->capabilityData.data.handles);
41               break;
42           case TPM_HT_LOADED_SESSION:
43               // Get list of handles of loaded sessions
44               out->moreData = SessionCapGetLoaded((TPM_HANDLE) in->property,
45                                                   in->propertyCount,
46                                                   &out->capabilityData.data.handles);
47               break;
48           case TPM_HT_ACTIVE_SESSION:
49               // Get list of handles of
50               out->moreData = SessionCapGetSaved((TPM_HANDLE) in->property,
51                                                  in->propertyCount,
52                                                  &out->capabilityData.data.handles);

     Family “2.0”                                   TCG Published                                           Page 391
     Level 00 Revision 01.16               Copyright © TCG 2006-2014                                 October 30, 2014
      Part 3: Commands                                                Trusted Platform Module Library

 53               break;
 54           case TPM_HT_PCR:
 55               // Get list of handles of PCR
 56               out->moreData = PCRCapGetHandles((TPM_HANDLE) in->property,
 57                                                in->propertyCount,
 58                                                &out->capabilityData.data.handles);
 59               break;
 60           case TPM_HT_PERMANENT:
 61               // Get list of permanent handles
 62               out->moreData = PermanentCapGetHandles(
 63                                   (TPM_HANDLE) in->property,
 64                                   in->propertyCount,
 65                                   &out->capabilityData.data.handles);
 66               break;
 67           default:
 68               // Unsupported input handle type
 69               return TPM_RC_HANDLE + RC_GetCapability_property;
 70               break;
 71           }
 72           break;
 73       case TPM_CAP_COMMANDS:
 74           out->moreData = CommandCapGetCCList((TPM_CC) in->property,
 75                                               in->propertyCount,
 76                                               &out->capabilityData.data.command);
 77           break;
 78       case TPM_CAP_PP_COMMANDS:
 79           out->moreData = PhysicalPresenceCapGetCCList((TPM_CC) in->property,
 80                           in->propertyCount, &out->capabilityData.data.ppCommands);
 81           break;
 82       case TPM_CAP_AUDIT_COMMANDS:
 83           out->moreData = CommandAuditCapGetCCList((TPM_CC) in->property,
 84                                           in->propertyCount,
 85                                           &out->capabilityData.data.auditCommands);
 86           break;
 87       case TPM_CAP_PCRS:
 88           // Input property must be 0
 89           if(in->property != 0)
 90               return TPM_RC_VALUE + RC_GetCapability_property;
 91           out->moreData = PCRCapGetAllocation(in->propertyCount,
 92                                               &out->capabilityData.data.assignedPCR);
 93           break;
 94       case TPM_CAP_PCR_PROPERTIES:
 95           out->moreData = PCRCapGetProperties((TPM_PT_PCR) in->property,
 96                                             in->propertyCount,
 97                                             &out->capabilityData.data.pcrProperties);
 98           break;
 99       case TPM_CAP_TPM_PROPERTIES:
100           out->moreData = TPMCapGetProperties((TPM_PT) in->property,
101                                             in->propertyCount,
102                                             &out->capabilityData.data.tpmProperties);
103           break;
104   #ifdef TPM_ALG_ECC
105       case TPM_CAP_ECC_CURVES:
106           out->moreData = CryptCapGetECCCurve((TPM_ECC_CURVE   ) in->property,
107                                               in->propertyCount,
108                                               &out->capabilityData.data.eccCurves);
109           break;
110   #endif // TPM_ALG_ECC
111       case TPM_CAP_VENDOR_PROPERTY:
112           // vendor property is not implemented
113       default:
114           // Unexpected TPM_CAP value
115           return TPM_RC_VALUE;
116           break;
117       }
118

      Page 392                               TCG Published                              Family “2.0”
      October 30, 2014                Copyright © TCG 2006-2014             Level 00 Revision 01.16
      Trusted Platform Module Library                               Part 3: Commands

119       return TPM_RC_SUCCESS;
120   }
121   #endif // CC_GetCapability


      Family “2.0”                           TCG Published                 Page 393
      Level 00 Revision 01.16           Copyright © TCG 2006-2014   October 30, 2014
Part 3: Commands                                                        Trusted Platform Module Library


30.3   TPM2_TestParms

30.3.1 General Description

This command is used to check to see if specific combinations of algorithm parameters are supported.
The TPM will unmarshal the provided TPMT_PUBLIC_PARMS. If the parameters unmarshal correctly,
then the TPM will return TPM_RC_SUCCESS, indicating that the parameters are valid for the TPM. The
TPM will return the appropriate unmarshaling error if a parameter is not valid.


Page 394                                   TCG Published                                   Family “2.0”
October 30, 2014                    Copyright © TCG 2006-2014                 Level 00 Revision 01.16
Trusted Platform Module Library                                                      Part 3: Commands


30.3.2 Command and Response

                             Table 195 — TPM2_TestParms Command
 Type                         Name                 Description

                                                   TPM_ST_SESSIONS if an audit session is present;
 TPMI_ST_COMMAND_TAG          tag
                                                   otherwise, TPM_ST_NO_SESSIONS
 UINT32                       commandSize
 TPM_CC                       commandCode          TPM_CC_TestParms

 TPMT_PUBLIC_PARMS            parameters           algorithm parameters to be validated


                             Table 196 — TPM2_TestParms Response
 Type                         Name                 Description

 TPM_ST                       tag                  see clause 6
 UINT32                       responseSize
 TPM_RC                       responseCode         TPM_RC


Family “2.0”                               TCG Published                                    Page 395
Level 00 Revision 01.16             Copyright © TCG 2006-2014                        October 30, 2014
     Part 3: Commands                                                 Trusted Platform Module Library


     30.3.3 Detailed Actions

 1   #include "InternalRoutines.h"
 2   #include "TestParms_fp.h"
 3   #ifdef TPM_CC_TestParms // Conditional expansion of this file
 4   TPM_RC
 5   TPM2_TestParms(
 6       TestParms_In   *in             // IN: input parameter list
 7       )
 8   {
 9       // Input parameter is not reference in command action
10       in = NULL;
11
12       // The parameters are tested at unmarshal process.   We do nothing in command
13       // action
14       return TPM_RC_SUCCESS;
15   }
16   #endif // CC_TestParms


     Page 396                               TCG Published                                Family “2.0”
     October 30, 2014                Copyright © TCG 2006-2014              Level 00 Revision 01.16
Trusted Platform Module Library                                                               Part 3: Commands


31     Non-volatile Storage

31.1     Introduction

The NV commands are used to create, update, read, and delete allocations of space in NV memory.
Before an Index may be used, it must be defined (TPM2_NV_DefineSpace()).
An Index may be modified if the proper write authorization is provided or read if the proper read
authorization is provided. Different controls are available for reading and writing.
An Index may have an Index-specific authValue and authPolicy. The authValue may be used to authorize
reading if TPMA_NV_AUTHREAD is SET and writing if TPMA_NV_AUTHREAD is SET. The authPolicy
may be used to authorize reading if TPMA_NV_POLICYREAD is SET and writing if
TPMA_NV_POLICYWRITE is SET.
For commands that have both authHandle and nvIndex parameters, authHandle can be an NV Index,
Platform Authorization, or Owner Authorization. If authHandle is an NV Index, it must be the same as
nvIndex (TPM_RC_NV_AUTHORIZATION).
TPMA_NV_PPREAD and TPMA_NV_PPWRITE indicate if reading or writing of the NV Index may be
authorized by platformAuth or platformPolicy.
TPMA_NV_OWNERREAD and TPMA_NV_OWNERWRITE indicate if reading or writing of the NV Index
may be authorized by ownerAuth or ownerPolicy.
If an operation on an NV index requires authorization, and the authHandle parameter is the handle of an
NV Index, then the nvIndex parameter must have the same value or the TPM will return
TPM_RC_NV_AUTHORIZATION.

NOTE 1          This check ensures that the authorization that was provided is associated with the NV Index being
                authorized.

For creating an Index, Owner Authorization may not be used if shEnable is CLEAR and Platform
Authorization may not be used if phEnableNV is CLEAR.
If an Index was defined using Platform Authorization, then that Index is not accessible when phEnableNV
is CLEAR. If an Index was defined using Owner Authorization, then that Index is not accessible when
shEnable is CLEAR.
For read access control, any combination of TPMA_NV_PPREAD, TPMA_NV_OWNERREAD,
TPMA_NV_AUTHREAD, or TPMA_NV_POLICYREAD is allowed as long as at least one is SET.
For write access control, any combination of TPMA_NV_PPWRITE, TPMA_NV_OWNERWRITE,
TPMA_NV_AUTHWRITE, or TPMA_NV_POLICYWRITE is allowed as long as at least one is SET.
If an Index has been defined and not written, then any operation on the NV Index that requires read
authorization will fail (TPM_RC_NV_INITIALIZED). This check may be made before or after other
authorization checks but shall be performed before checking the NV Index authValue. An authorization
failure due to the NV Index not having been written shall not be logged by the dictionary attack logic.
If TPMA_NV_CLEAR_STCLEAR is SET, then the TPMA_NV_WRITTEN will be CLEAR on each
TPM2_Startup(TPM_SU_CLEAR). TPMA_NV_CLEAR_STCLEAR     shall   not  be   SET   if
TPMA_NV_COUNTER is SET.
The code in the “Detailed Actions” clause of each command is written to interface with an implementation-
dependent library that allows access to NV memory. The actions assume no specific layout of the
structure of the NV data.
Only one NV Index may be directly referenced in a command.

NOTE 2          This means that, if authHandle references an NV Index, then nvIndex will have the same value.
                However, this does not limit the number of changes that may occur as side effects. For example, any
                number of NV Indexes might be relocated as a result of deleting or adding a NV Index.

Family “2.0”                                  TCG Published                                            Page 397
Level 00 Revision 01.16               Copyright © TCG 2006-2014                               October 30, 2014
Part 3: Commands                                                                 Trusted Platform Module Library


31.2     NV Counters

When an Index has the TPMA_NV_COUNTER attribute set, it behaves as a monotonic counter and may
only be updated using TPM2_NV_Increment().
When an NV counter is created, the TPM shall initialize the 8-octet counter value with a number that is
greater than any count value for any NV counter on the TPM since the time of TPM manufacture.
An NV counter may be defined with the TPMA_NV_ORDERLY attribute to indicate that the NV Index is
expected to be modified at a high frequency and that the data is only required to persist when the TPM
goes through an orderly shutdown process. The TPM may update the counter value in RAM and
occasionally update the non-volatile version of the counter. An orderly shutdown is one occasion to
update the non-volatile count. If the difference between the volatile and non-volatile version of the counter
becomes as large as MAX_ORDERLY_COUNT, this shall be another occasion for updating the non-
volatile count.
Before an NV counter can be used, the TPM shall validate that the count is not less than a previously
reported value. If the TPMA_NV_ORDERLY attribute is not SET, or if the TPM experienced an orderly
shutdown, then the count is assumed to be correct. If the TPMA_NV_ORDERLY attribute is SET, and the
TPM shutdown was not orderly, then the TPM shall OR MAX_ORDERLY_COUNT to the contents of the
non-volatile counter and set that as the current count.

NOTE 1          Because the TPM would have updated the NV Index if the difference between the count values was
                equal to MAX_ORDERLY_COUNT + 1, the highest value that could have been in the NV Index is
                MAX_ORDERLY_COUNT so it is safe to restore that value.

NOTE 2          The TPM may implement the RAM portion of the counter such that the effective value of the NV
                counter is the sum of both the volatile and non-volatile parts. If so, then the TPM may initialize the
                RAM version of the counter to MAX_ORDERLY_COUNT and no update of NV is necessary.

NOTE 3          When a new NV counter is created, the TPM may search all the coun ters to determine which has the
                highest value. In this search, the TPM would use the sum of the non -volatile and RAM portions of
                the counter. The RAM portion of the counter shall be properly initialized to reflect shutdown process
                (orderly or not) of the TPM.


Page 398                                       TCG Published                                           Family “2.0”
October 30, 2014                       Copyright © TCG 2006-2014                        Level 00 Revision 01.16
Trusted Platform Module Library                                                                 Part 3: Commands


31.3     TPM2_NV_DefineSpace

31.3.1 General Description

This command defines the attributes of an NV Index and causes the TPM to reserve space to hold the
data associated with the NV Index. If a definition already exists at the NV Index, the TPM will return
TPM_RC_NV_DEFINED.
The TPM will return TPM_RC_ATTRIBUTES if more                            than   one   of     TPMA_NV_COUNTER,
TPMA_NV_BITS, or TPMA_NV_EXTEND is SET in publicInfo.

NOTE 1         It is not required that any of these three attributes be set.

The TPM shall return TPM_RC_ATTRIBUTES if TPMA_NV_WRITTEN, TPM_NV_READLOCKED, or
TPMA_NV_WRITELOCKED is SET.
If TPMA_NV_COUNTER or TPMA_NV_BITS is SET, then publicInfo→dataSize shall be set to eight (8) or
the TPM shall return TPM_RC_SIZE.
If TPMA_NV_EXTEND is SET, then publicInfo→dataSize shall match the digest size of the
publicInfo.nameAlg or the TPM shall return TPM_RC_SIZE.
If the NV Index is an ordinary Index and publicInfo→dataSize is larger than supported by the TPM
implementation then the TPM shall return TPM_RC_SIZE.

NOTE 2         The limit for the data size may vary according to the type of the index. For example, if the index has
               TPMA_NV_ORDERLY SET, then the maximum size of an ordinary NV Index may be less than the
               size of an ordinary NV Index that has TPMA_NV_ORDERLY CLEAR.

At least one of TPMA_NV_PPREAD, TPMA_NV_OWNERREAD, TPMA_NV_AUTHREAD,                                              or
TPMA_NV_POLICYREAD shall be SET or the TPM shall return TPM_RC_ATTRIBUTES.
At least one of TPMA_NV_PPWRITE, TPMA_NV_OWNERWRITE, TPMA_NV_AUTHWRITE, or
TPMA_NV_POLICYWRITE shall be SET or the TPM shall return TPM_RC_ATTRIBUTES.
If TPMA_NV_CLEAR_STCLEAR is SET, then TPMA_NV_COUNTER shall be CLEAR or the TPM shall
return TPM_RC_ATTRIBUTES.
If platformAuth/platformPolicy is used for authorization, then TPMA_NV_PLATFORMCREATE shall be
SET in publicInfo. If ownerAuth/ownerPolicy is used for authorization, TPMA_NV_PLATFORMCREATE
shall be CLEAR in publicInfo. If TPMA_NV_PLATFORMCREATE is not set correctly for the authorization,
the TPM shall return TPM_RC_ATTRIBUTES.
If TPMA_NV_POLICY_DELETE is SET, then the authorization shall be with Platform Authorization or the
TPM shall return TPM_RC_ATTRIBUTES.
If the implementation does not support TPM2_NV_Increment(),                            the    TPM    shall    return
TPM_RC_ATTRIBUTES if TPMA_NV_COUNTER is SET.
If the implementation does not support TPM2_NV_SetBits(),                             the     TPM    shall    return
TPM_RC_ATTRIBUTES if TPMA_NV_BITS is SET.
If the implementation does not support TPM2_NV_Extend(),                              the     TPM    shall    return
TPM_RC_ATTRIBUTES if TPMA_NV_EXTEND is SET.
If the implementation does not support TPM2_NV_UndefineSpaceSpecial(), the TPM shall return
TPM_RC_ATTRIBUTES if TPMA_NV_POLICY_DELETE is SET.
After the successful completion of this command, the NV Index exists but TPMA_NV_WRITTEN will be
CLEAR. Any access of the NV data will return TPM_RC_NV_UINITIALIZED.


Family “2.0”                                    TCG Published                                            Page 399
Level 00 Revision 01.16                Copyright © TCG 2006-2014                                October 30, 2014
Part 3: Commands                                                            Trusted Platform Module Library

In some implementations, an NV Index with the TPMA_NV_COUNTER attribute may require special TPM
resources that provide higher endurance than regular NV. For those implementations, if this command
fails because of lack of resources, the TPM will return TPM_RC_NV_SPACE.
The value of auth is saved in the created structure. The size of auth is limited to be no larger than the size
of the digest produced by the NV Index's nameAlg (TPM_RC_SIZE).


Page 400                                      TCG Published                                     Family “2.0”
October 30, 2014                      Copyright © TCG 2006-2014                   Level 00 Revision 01.16
Trusted Platform Module Library                                                      Part 3: Commands


31.3.2 Command and Response

                          Table 197 — TPM2_NV_DefineSpace Command
 Type                         Name                 Description

 TPMI_ST_COMMAND_TAG          tag                  TPM_ST_SESSIONS
 UINT32                       commandSize
 TPM_CC                       commandCode          TPM_CC_NV_DefineSpace {NV}

                                                   TPM_RH_OWNER or TPM_RH_PLATFORM+{PP}
 TPMI_RH_PROVISION            @authHandle          Auth Index: 1
                                                   Auth Role: USER

 TPM2B_AUTH                   auth                 the authorization value
 TPM2B_NV_PUBLIC              publicInfo           the public parameters of the NV area


                          Table 198 — TPM2_NV_DefineSpace Response
 Type                         Name                 Description

 TPM_ST                       tag                  see clause 6
 UINT32                       responseSize
 TPM_RC                       responseCode


Family “2.0”                               TCG Published                                    Page 401
Level 00 Revision 01.16              Copyright © TCG 2006-2014                       October 30, 2014
     Part 3: Commands                                                              Trusted Platform Module Library


     31.3.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "NV_DefineSpace_fp.h"
3    #ifdef TPM_CC_NV_DefineSpace // Conditional expansion of this file


     Error Returns                 Meaning

     TPM_RC_NV_ATTRIBUTES          attributes of the index are not consistent
     TPM_RC_NV_DEFINED             index already exists
     TPM_RC_HIERARCHY              for authorizations using TPM_RH_PLATFORM phEnable_NV is
                                   clear.
     TPM_RC_NV_SPACE               Insufficient space for the index
     TPM_RC_SIZE                   'auth->size' or 'publicInfo->authPolicy.size' is larger than the digest
                                   size of 'publicInfo->nameAlg', or 'publicInfo->dataSize' is not
                                   consistent with 'publicInfo->attributes'.

 4   TPM_RC
 5   TPM2_NV_DefineSpace(
 6       NV_DefineSpace_In   *in                  // IN: input parameter list
 7       )
 8   {
 9       TPM_RC          result;
10       TPMA_NV         attributes;
11       UINT16          nameSize;
12
13       nameSize = CryptGetHashDigestSize(in->publicInfo.t.nvPublic.nameAlg);
14
15       // Check if NV is available. NvIsAvailable may return TPM_RC_NV_UNAVAILABLE
16       // TPM_RC_NV_RATE or TPM_RC_SUCCESS.
17       result = NvIsAvailable();
18       if(result != TPM_RC_SUCCESS)
19           return result;
20
21   // Input Validation
22       // If an index is being created by the owner and shEnable is
23       // clear, then we would not reach this point because ownerAuth
24       // can't be given when shEnable is CLEAR. However, if phEnable
25       // is SET but phEnableNV is CLEAR, we have to check here
26       if(in->authHandle == TPM_RH_PLATFORM && gc.phEnableNV == CLEAR)
27           return TPM_RC_HIERARCHY + RC_NV_DefineSpace_authHandle;
28
29       attributes = in->publicInfo.t.nvPublic.attributes;
30
31       //TPMS_NV_PUBLIC validation.
32       // Counters and bit fields must have a size of 8
33       if (   (attributes.TPMA_NV_COUNTER == SET || attributes.TPMA_NV_BITS == SET)
34           && (in->publicInfo.t.nvPublic.dataSize != 8))
35           return TPM_RC_SIZE + RC_NV_DefineSpace_publicInfo;
36
37       // check that the authPolicy consistent with hash algorithm
38       if(   in->publicInfo.t.nvPublic.authPolicy.t.size != 0
39          && in->publicInfo.t.nvPublic.authPolicy.t.size != nameSize)
40           return TPM_RC_SIZE + RC_NV_DefineSpace_publicInfo;
41
42       // make sure that the authValue is not too large
43       MemoryRemoveTrailingZeros(&in->auth);
44       if(in->auth.t.size > nameSize)
45           return TPM_RC_SIZE + RC_NV_DefineSpace_auth;
46

     Page 402                                   TCG Published                                                Family “2.0”
     October 30, 2014                   Copyright © TCG 2006-2014                         Level 00 Revision 01.16
      Trusted Platform Module Library                                                Part 3: Commands

 47       //TPMA_NV validation.
 48       // Locks may not be SET and written cannot be SET
 49       if(   attributes.TPMA_NV_WRITTEN == SET
 50          || attributes.TPMA_NV_WRITELOCKED == SET
 51          || attributes.TPMA_NV_READLOCKED == SET)
 52           return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo;
 53
 54       // There must be a way to read the index
 55       if(   attributes.TPMA_NV_OWNERREAD == CLEAR
 56          && attributes.TPMA_NV_PPREAD == CLEAR
 57          && attributes.TPMA_NV_AUTHREAD == CLEAR
 58          && attributes.TPMA_NV_POLICYREAD == CLEAR)
 59           return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo;
 60
 61       // There must be a way to write the index
 62       if(   attributes.TPMA_NV_OWNERWRITE == CLEAR
 63          && attributes.TPMA_NV_PPWRITE == CLEAR
 64          && attributes.TPMA_NV_AUTHWRITE == CLEAR
 65          && attributes.TPMA_NV_POLICYWRITE == CLEAR)
 66           return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo;
 67
 68       // Make sure that no attribute is used that is not supported by the proper
 69       // command
 70   #if CC_NV_Increment == NO
 71       if( attributes.TPMA_NV_COUNTER == SET)
 72           return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo;
 73   #endif
 74   #if CC_NV_SetBits == NO
 75          if( attributes.TPMA_NV_BITS == SET)
 76              return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo;
 77   #endif
 78   #if CC_NV_Extend == NO
 79         if( attributes.TPMA_NV_EXTEND == SET)
 80             return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo;
 81   #endif
 82   #if CC_NV_UndefineSpaceSpecial == NO
 83        if( attributes.TPMA_NV_POLICY_DELETE == SET)
 84            return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo;
 85   #endif
 86
 87       // Can be COUNTER or BITS or EXTEND but not more than one
 88       if( attributes.TPMA_NV_COUNTER == SET
 89          && attributes.TPMA_NV_BITS == SET)
 90           return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo;
 91       if(   attributes.TPMA_NV_COUNTER == SET
 92          && attributes.TPMA_NV_EXTEND == SET)
 93           return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo;
 94       if(   attributes.TPMA_NV_BITS == SET
 95          && attributes.TPMA_NV_EXTEND == SET)
 96           return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo;
 97
 98       // An index with TPMA_NV_CLEAR_STCLEAR can't be a counter and can't have
 99       // TPMA_NV_WRITEDEFINE SET
100       if(     attributes.TPMA_NV_CLEAR_STCLEAR == SET
101           && (    attributes.TPMA_NV_COUNTER == SET
102                || attributes.TPMA_NV_WRITEDEFINE == SET)
103          )
104           return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo;
105
106       // Make sure that the creator of the index can delete the index
107       if( (    in->publicInfo.t.nvPublic.attributes.TPMA_NV_PLATFORMCREATE == SET
108              && in->authHandle == TPM_RH_OWNER
109             )
110          || (   in->publicInfo.t.nvPublic.attributes.TPMA_NV_PLATFORMCREATE == CLEAR
111              && in->authHandle == TPM_RH_PLATFORM
112             )

      Family “2.0”                           TCG Published                                  Page 403
      Level 00 Revision 01.16           Copyright © TCG 2006-2014                    October 30, 2014
      Part 3: Commands                                                     Trusted Platform Module Library

113         )
114             return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_authHandle;
115
116      // If TPMA_NV_POLICY_DELETE is SET, then the index must be defined by
117      // the platform
118      if(    in->publicInfo.t.nvPublic.attributes.TPMA_NV_POLICY_DELETE == SET
119         && TPM_RH_PLATFORM != in->authHandle
120        )
121          return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo;
122
123      // If the NV index is used as a PCR, the data size must match the digest
124      // size
125      if(   in->publicInfo.t.nvPublic.attributes.TPMA_NV_EXTEND == SET
126         && in->publicInfo.t.nvPublic.dataSize != nameSize
127        )
128          return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo;
129
130      // See if the index is already defined.
131      if(NvIsUndefinedIndex(in->publicInfo.t.nvPublic.nvIndex))
132          return TPM_RC_NV_DEFINED;
133
134   // Internal Data Update
135       // define the space. A TPM_RC_NV_SPACE error may be returned at this point
136       result = NvDefineIndex(&in->publicInfo.t.nvPublic, &in->auth);
137       if(result != TPM_RC_SUCCESS)
138           return result;
139
140      return TPM_RC_SUCCESS;
141
142   }
143   #endif // CC_NV_DefineSpace


      Page 404                                 TCG Published                                 Family “2.0”
      October 30, 2014                  Copyright © TCG 2006-2014               Level 00 Revision 01.16
Trusted Platform Module Library                                                           Part 3: Commands


31.4   TPM2_NV_UndefineSpace

31.4.1 General Description

This command removes an Index from the TPM.
If nvIndex is not defined, the TPM shall return TPM_RC_HANDLE.
If nvIndex references an Index that has its TPMA_NV_PLATFORMCREATE attribute SET, the TPM shall
return TPM_RC_NV_AUTHORIZATION unless Platform Authorization is provided.
If nvIndex references an Index that has its TPMA_NV_POLICY_DELETE attribute SET, the TPM shall
return TPM_RC_ATTRIBUTES.

NOTE           An Index with TPMA_NV_PLATFORMCREATE CLEAR may be deleted with Platform Authorization
               as long as shEnable is SET. If shEnable is CLEAR, indexes created using Owner Authorization are
               not accessible even for deletion by the platform .


Family “2.0”                                TCG Published                                          Page 405
Level 00 Revision 01.16             Copyright © TCG 2006-2014                             October 30, 2014
Part 3: Commands                                               Trusted Platform Module Library


31.4.2 Command and Response

                     Table 199 — TPM2_NV_UndefineSpace Command
 Type                    Name                Description

 TPMI_ST_COMMAND_TAG     tag                 TPM_ST_SESSIONS
 UINT32                  commandSize
 TPM_CC                  commandCode         TPM_CC_NV_UndefineSpace {NV}

                                             TPM_RH_OWNER or TPM_RH_PLATFORM+{PP}
 TPMI_RH_PROVISION       @authHandle         Auth Index: 1
                                             Auth Role: USER
                                             the NV Index to remove from NV space
 TPMI_RH_NV_INDEX        nvIndex
                                             Auth Index: None


                     Table 200 — TPM2_NV_UndefineSpace Response
 Type                    Name                Description

 TPM_ST                  tag                 see clause 6
 UINT32                  responseSize
 TPM_RC                  responseCode


Page 406                            TCG Published                                   Family “2.0”
October 30, 2014               Copyright © TCG 2006-2014             Level 00 Revision 01.16
     Trusted Platform Module Library                                                              Part 3: Commands


     31.4.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "NV_UndefineSpace_fp.h"
3    #ifdef TPM_CC_NV_UndefineSpace // Conditional expansion of this file


     Error Returns                     Meaning

     TPM_RC_ATTRIBUTES                 TPMA_NV_POLICY_DELETE is SET in the Index referenced by
                                       nvIndex so this command may not be used to delete this Index (see
                                       TPM2_NV_UndefineSpaceSpecial())
     TPM_RC_NV_AUTHORIZATION           attempt to use ownerAuth to delete an index created by the platform

 4   TPM_RC
 5   TPM2_NV_UndefineSpace(
 6       NV_UndefineSpace_In       *in                   // IN: input parameter list
 7       )
 8   {
 9       TPM_RC            result;
10       NV_INDEX          nvIndex;
11
12       // The command needs NV update. Check if NV is available.
13       // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
14       // this point
15       result = NvIsAvailable();
16       if(result != TPM_RC_SUCCESS) return result;
17
18   // Input Validation
19
20       // Get NV index info
21       NvGetIndexInfo(in->nvIndex, &nvIndex);
22
23       // This command can't be used to delete an index with TPMA_NV_POLICY_DELETE SET
24       if(SET == nvIndex.publicArea.attributes.TPMA_NV_POLICY_DELETE)
25           return TPM_RC_ATTRIBUTES + RC_NV_UndefineSpace_nvIndex;
26
27       // The owner may only delete an index that was defined with ownerAuth. The
28       // platform may delete an index that was created with either auth.
29       if(   in->authHandle == TPM_RH_OWNER
30          && nvIndex.publicArea.attributes.TPMA_NV_PLATFORMCREATE == SET)
31           return TPM_RC_NV_AUTHORIZATION;
32
33   // Internal Data Update
34
35       // Call implementation dependent internal routine to delete NV index
36       NvDeleteEntity(in->nvIndex);
37
38       return TPM_RC_SUCCESS;
39   }
40   #endif // CC_NV_UndefineSpace


     Family “2.0”                                  TCG Published                                             Page 407
     Level 00 Revision 01.16               Copyright © TCG 2006-2014                              October 30, 2014
Part 3: Commands                                                         Trusted Platform Module Library


31.5   TPM2_NV_UndefineSpaceSpecial

31.5.1 General Description

This command allows removal of a platform-created NV Index that has TPMA_NV_POLICY_DELETE
SET.
This command requires that the policy of the NV Index be satisfied before the NV Index may be deleted.
Because administrative role is required, the policy must contain a command that sets the policy command
code to TPM_CC_NV_UndefineSpaceSpecial. This indicates that the policy that is being used is a policy
that is for this command, and not a policy that would approve another use. That is, authority to use an
object does not grant authority to undefine the object.
If nvIndex is not defined, the TPM shall return TPM_RC_HANDLE.
If nvIndex references an     Index  that    has   its    TPMA_NV_PLATFORMCREATE                         or
TPMA_NV_POLICY_DELETE attribute CLEAR, the TPM shall return TPM_RC_ATTRIBUTES.

NOTE           An   Index    with     TPMA_NV_PLATFORMCREATE              CLEAR       may be deleted  with
               TPM2_UndefineSpace()as long as shEnable is SET. If shEnable is CLEAR, indexes created using
               Owner Authorization are not accessible even for deletion by the platform .


Page 408                                   TCG Published                                    Family “2.0”
October 30, 2014                   Copyright © TCG 2006-2014                   Level 00 Revision 01.16
Trusted Platform Module Library                                               Part 3: Commands


31.5.2 Command and Response

                     Table 201 — TPM2_NV_UndefineSpaceSpecial Command
 Type                         Name                Description

 TPMI_ST_COMMAND_TAG          tag                 TPM_ST_SESSIONS
 UINT32                       commandSize
 TPM_CC                       commandCode         TPM_CC_NV_UndefineSpaceSpecial {NV}

                                                  Index to be deleted
 TPMI_RH_NV_INDEX             @nvIndex            Auth Index: 1
                                                  Auth Role: ADMIN
                                                  TPM_RH_PLATFORM + {PP}
 TPMI_RH_PLATFORM             @platform           Auth Index: 2
                                                  Auth Role: USER


                     Table 202 — TPM2_NV_UndefineSpaceSpecial Response
 Type                         Name                Description

 TPM_ST                       tag                 see clause 6
 UINT32                       responseSize
 TPM_RC                       responseCode


Family “2.0”                              TCG Published                                 Page 409
Level 00 Revision 01.16             Copyright © TCG 2006-2014                 October 30, 2014
     Part 3: Commands                                                        Trusted Platform Module Library


     31.5.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "NV_UndefineSpaceSpecial_fp.h"
3    #ifdef TPM_CC_NV_UndefineSpaceSpecial // Conditional expansion of this file


     Error Returns                    Meaning

     TPM_RC_ATTRIBUTES                TPMA_NV_POLICY_DELETE is not SET in the Index referenced by
                                      nvIndex

 4   TPM_RC
 5   TPM2_NV_UndefineSpaceSpecial(
 6       NV_UndefineSpaceSpecial_In      *in              // IN: input parameter list
 7       )
 8   {
 9       TPM_RC            result;
10       NV_INDEX          nvIndex;
11
12       // The command needs NV update. Check if NV is available.
13       // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
14       // this point
15       result = NvIsAvailable();
16       if(result != TPM_RC_SUCCESS)
17           return result;
18
19   // Input Validation
20
21       // Get NV index info
22       NvGetIndexInfo(in->nvIndex, &nvIndex);
23
24       // This operation only applies when the TPMA_NV_POLICY_DELETE attribute is SET
25       if(CLEAR == nvIndex.publicArea.attributes.TPMA_NV_POLICY_DELETE)
26           return TPM_RC_ATTRIBUTES + RC_NV_UndefineSpaceSpecial_nvIndex;
27
28   // Internal Data Update
29
30       // Call implementation dependent internal routine to delete NV index
31       NvDeleteEntity(in->nvIndex);
32
33       return TPM_RC_SUCCESS;
34   }
35   #endif // CC_NV_UndefineSpaceSpecial


     Page 410                                    TCG Published                                 Family “2.0”
     October 30, 2014                     Copyright © TCG 2006-2014                Level 00 Revision 01.16
Trusted Platform Module Library                                                   Part 3: Commands


31.6   TPM2_NV_ReadPublic

31.6.1 General Description

This command is used to read the public area and Name of an NV Index. The public area of an Index is
not privacy-sensitive and no authorization is required to read this data.


Family “2.0”                             TCG Published                                    Page 411
Level 00 Revision 01.16           Copyright © TCG 2006-2014                       October 30, 2014
Part 3: Commands                                                  Trusted Platform Module Library


31.6.2 Command and Response

                       Table 203 — TPM2_NV_ReadPublic Command
 Type                     Name                Description

                                              TPM_ST_SESSIONS if an audit or encrypt session is
 TPMI_ST_COMMAND_TAG      tag
                                              present; otherwise, TPM_ST_NO_SESSIONS
 UINT32                   commandSize
 TPM_CC                   commandCode         TPM_CC_NV_ReadPublic

                                              the NV Index
 TPMI_RH_NV_INDEX         nvIndex
                                              Auth Index: None


                       Table 204 — TPM2_NV_ReadPublic Response
 Type                     Name                Description
 TPM_ST                   tag                 see clause 6
 UINT32                   responseSize
 TPM_RC                   responseCode

 TPM2B_NV_PUBLIC          nvPublic            the public area of the NV Index
 TPM2B_NAME               nvName              the Name of the nvIndex


Page 412                             TCG Published                                  Family “2.0”
October 30, 2014                Copyright © TCG 2006-2014                Level 00 Revision 01.16
     Trusted Platform Module Library                                         Part 3: Commands


     31.6.3 Detailed Actions

 1   #include "InternalRoutines.h"
 2   #include "NV_ReadPublic_fp.h"
 3   #ifdef TPM_CC_NV_ReadPublic // Conditional expansion of this file
 4   TPM_RC
 5   TPM2_NV_ReadPublic(
 6       NV_ReadPublic_In      *in,          // IN: input parameter list
 7       NV_ReadPublic_Out     *out          // OUT: output parameter list
 8       )
 9   {
10       NV_INDEX         nvIndex;
11
12   // Command Output
13
14       // Get NV index info
15       NvGetIndexInfo(in->nvIndex, &nvIndex);
16
17       // Copy data to output
18       out->nvPublic.t.nvPublic = nvIndex.publicArea;
19
20       // Compute NV name
21       out->nvName.t.size = NvGetName(in->nvIndex, &out->nvName.t.name);
22
23       return TPM_RC_SUCCESS;
24   }
25   #endif // CC_NV_ReadPublic


     Family “2.0”                           TCG Published                           Page 413
     Level 00 Revision 01.16           Copyright © TCG 2006-2014             October 30, 2014
Part 3: Commands                                                             Trusted Platform Module Library


31.7     TPM2_NV_Write

31.7.1 General Description

This command writes a value to an area in NV memory that was previously defined by
TPM2_NV_DefineSpace().
Proper authorizations are required for this command as determined by TPMA_NV_PPWRITE;
TPMA_NV_OWNERWRITE; TPMA_NV_AUTHWRITE; and, if TPMA_NV_POLICY_WRITE is SET, the
authPolicy of the NV Index.
If the TPMA_NV_WRITELOCKED attribute of the NV Index is SET, then the TPM shall return
TPM_RC_NV_LOCKED.

NOTE 1          If authorization sessions are present, they are checked before checks to see if writes to the NV
                Index are locked.

If TPMA_NV_COUNTER, TPMA_NV_BITS or TPMA_NV_EXTEND of the NV Index is SET, then the
TPM shall return TPM_RC_ATTRIBUTES.
If the size of the data parameter plus the offset parameter adds to a value that is greater than the size of
the NV Index data, the TPM shall return TPM_RC_NV_RANGE and not write any data to the NV Index.
If the TPMA_NV_WRITEALL attribute of the NV Index is SET, then the TPM shall return
TPM_RC_NV_RANGE if the size of the data parameter of the command is not the same as the data field
of the NV Index.
If all checks succeed, the TPM will merge the data.size octets of data.buffer value into the nvIndex→data
starting at nvIndex→data[offset]. If the NV memory is implemented with a technology that has endurance
limitations, the TPM shall check that the merged data is different from the current contents of the NV
Index and only perform a write to NV memory if they differ.
After successful completion of this command, TPMA_NV_WRITTEN for the NV Index will be SET.

NOTE 2          Once SET, TPMA_NV_WRITTEN remains SET until the NV Index is undefined or the NV Index is
                cleared.


Page 414                                      TCG Published                                       Family “2.0”
October 30, 2014                      Copyright © TCG 2006-2014                    Level 00 Revision 01.16
Trusted Platform Module Library                                                        Part 3: Commands


31.7.2 Command and Response

                              Table 205 — TPM2_NV_Write Command
 Type                         Name                 Description

 TPMI_ST_COMMAND_TAG          tag                  TPM_ST_SESSIONS
 UINT32                       commandSize
 TPM_CC                       commandCode          TPM_CC_NV_Write {NV}

                                                   handle indicating the source of the authorization value
 TPMI_RH_NV_AUTH              @authHandle          Auth Index: 1
                                                   Auth Role: USER
                                                   the NV Index of the area to write
 TPMI_RH_NV_INDEX             nvIndex
                                                   Auth Index: None

 TPM2B_MAX_NV_BUFFER          data                 the data to write
 UINT16                       offset               the offset into the NV Area


                              Table 206 — TPM2_NV_Write Response
 Type                         Name                 Description

 TPM_ST                       tag                  see clause 6
 UINT32                       responseSize
 TPM_RC                       responseCode


Family “2.0”                              TCG Published                                         Page 415
Level 00 Revision 01.16              Copyright © TCG 2006-2014                         October 30, 2014
     Part 3: Commands                                                               Trusted Platform Module Library


     31.7.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "NV_Write_fp.h"
3    #ifdef TPM_CC_NV_Write // Conditional expansion of this file
4    #include "NV_spt_fp.h"


     Error Returns                    Meaning

     TPM_RC_ATTRIBUTES                Index referenced by nvIndex has either TPMA_NV_BITS,
                                      TPMA_NV_COUNTER, or TPMA_NV_EVENT attribute SET
     TPM_RC_NV_AUTHORIZATION          the authorization was valid but the authorizing entity (authHandle) is
                                      not allowed to write to the Index referenced by nvIndex
     TPM_RC_NV_LOCKED                 Index referenced by nvIndex is write locked
     TPM_RC_NV_RANGE                  if TPMA_NV_WRITEALL is SET then the write is not the size of the
                                      Index referenced by nvIndex; otherwise, the write extends beyond the
                                      limits of the Index

 5   TPM_RC
 6   TPM2_NV_Write(
 7       NV_Write_In       *in                 // IN: input parameter list
 8       )
 9   {
10       NV_INDEX          nvIndex;
11       TPM_RC            result;
12
13   // Input Validation
14
15       // Get NV index info
16       NvGetIndexInfo(in->nvIndex, &nvIndex);
17
18       // common access checks. NvWrtieAccessChecks() may return
19       // TPM_RC_NV_AUTHORIZATION or TPM_RC_NV_LOCKED
20       result = NvWriteAccessChecks(in->authHandle, in->nvIndex);
21       if(result != TPM_RC_SUCCESS)
22           return result;
23
24       // Bits index, extend index or counter index may not be updated by
25       // TPM2_NV_Write
26       if(   nvIndex.publicArea.attributes.TPMA_NV_COUNTER == SET
27          || nvIndex.publicArea.attributes.TPMA_NV_BITS == SET
28          || nvIndex.publicArea.attributes.TPMA_NV_EXTEND == SET)
29           return TPM_RC_ATTRIBUTES;
30
31       // Too much data
32       if((in->data.t.size + in->offset) > nvIndex.publicArea.dataSize)
33           return TPM_RC_NV_RANGE;
34
35       // If this index requires a full sized write, make sure that input range is
36       // full sized
37       if(   nvIndex.publicArea.attributes.TPMA_NV_WRITEALL == SET
38          && in->data.t.size < nvIndex.publicArea.dataSize)
39           return TPM_RC_NV_RANGE;
40
41   // Internal Data Update
42
43       // Perform the write. This called routine will SET the TPMA_NV_WRITTEN
44       // attribute if it has not already been SET. If NV isn't available, an error
45       // will be returned.
46       return NvWriteIndexData(in->nvIndex, &nvIndex, in->offset,
47                               in->data.t.size, in->data.t.buffer);

     Page 416                                      TCG Published                                          Family “2.0”
     October 30, 2014                     Copyright © TCG 2006-2014                        Level 00 Revision 01.16
     Trusted Platform Module Library                               Part 3: Commands

48
49   }
50   #endif // CC_NV_Write


     Family “2.0”                           TCG Published                 Page 417
     Level 00 Revision 01.16           Copyright © TCG 2006-2014   October 30, 2014
Part 3: Commands                                                            Trusted Platform Module Library


31.8     TPM2_NV_Increment

31.8.1 General Description

This command is used to increment the value in an NV Index that has TPMA_NV_COUNTER SET. The
data value of the NV Index is incremented by one.

NOTE 1         The NV Index counter is an unsigned value.

If TPMA_NV_COUNTER          is   not    SET   in   the   indicated   NV   Index,   the   TPM     shall   return
TPM_RC_ATTRIBUTES.
If TPMA_NV_WRITELOCKED is SET, the TPM shall return TPM_RC_NV_LOCKED.
If TPMA_NV_WRITTEN is CLEAR, it will be SET.
If TPMA_NV_ORDERLY is SET, and the difference between the volatile and non-volatile versions of this
field is greater than MAX_ORDERLY_COUNT, then the non-volatile version of the counter is updated.

NOTE 2         If a TPM implements TPMA_NV_ORDERLY and an Index is defined with TPMA_NV_ORDERLY and
               TPM_NV_COUNTER both SET, then in the Event of a non-orderly shutdown, the non-volatile value
               for the counter Index will be advanced by MAX_ORDERLY_COUNT at the next TPM2_Startup().

NOTE 3         An allowed implementation would keep a counter value in NV and a resettable counter in RAM. The
               reported value of the NV Index would be the sum of the two values. When the RAM count increments
               past the maximum allowed value (MAX_ORDERLY_COUNT), the non-volatile version of the count is
               updated with the sum of the values and the RAM count is reset to zero.


Page 418                                      TCG Published                                      Family “2.0”
October 30, 2014                       Copyright © TCG 2006-2014                   Level 00 Revision 01.16
Trusted Platform Module Library                                                       Part 3: Commands


31.8.2 Command and Response

                           Table 207 — TPM2_NV_Increment Command
 Type                         Name                Description

 TPMI_ST_COMMAND_TAG          tag                 TPM_ST_SESSIONS
 UINT32                       commandSize
 TPM_CC                       commandCode         TPM_CC_NV_Increment {NV}

                                                  handle indicating the source of the authorization value
 TPMI_RH_NV_AUTH              @authHandle         Auth Index: 1
                                                  Auth Role: USER
                                                  the NV Index to increment
 TPMI_RH_NV_INDEX             nvIndex
                                                  Auth Index: None


                           Table 208 — TPM2_NV_Increment Response
 Type                         Name                Description

 TPM_ST                       tag                 see clause 6
 UINT32                       responseSize
 TPM_RC                       responseCode


Family “2.0”                             TCG Published                                         Page 419
Level 00 Revision 01.16             Copyright © TCG 2006-2014                         October 30, 2014
     Part 3: Commands                                                       Trusted Platform Module Library


     31.8.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "NV_Increment_fp.h"
3    #ifdef TPM_CC_NV_Increment // Conditional expansion of this file
4    #include "NV_spt_fp.h"


     Error Returns                   Meaning

     TPM_RC_ATTRIBUTES               NV index is not a counter
     TPM_RC_NV_AUTHORIZATION         authorization failure
     TPM_RC_NV_LOCKED                Index is write locked

 5   TPM_RC
 6   TPM2_NV_Increment(
 7       NV_Increment_In       *in                  // IN: input parameter list
 8       )
 9   {
10       TPM_RC            result;
11       NV_INDEX          nvIndex;
12       UINT64            countValue;
13
14   // Input Validation
15
16       // Common access checks, a TPM_RC_NV_AUTHORIZATION or TPM_RC_NV_LOCKED
17       // error may be returned at this point
18       result = NvWriteAccessChecks(in->authHandle, in->nvIndex);
19       if(result != TPM_RC_SUCCESS)
20           return result;
21
22       // Get NV index info
23       NvGetIndexInfo(in->nvIndex, &nvIndex);
24
25       // Make sure that this is a counter
26       if(nvIndex.publicArea.attributes.TPMA_NV_COUNTER != SET)
27           return TPM_RC_ATTRIBUTES + RC_NV_Increment_nvIndex;
28
29   // Internal Data Update
30
31       // If counter index is not been written, initialize it
32       if(nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == CLEAR)
33           countValue = NvInitialCounter();
34       else
35           // Read NV data in native format for TPM CPU.
36           NvGetIntIndexData(in->nvIndex, &nvIndex, &countValue);
37
38       // Do the increment
39       countValue++;
40
41       // If this is an orderly counter that just rolled over, need to be able to
42       // write to NV to proceed. This check is done here, because NvWriteIndexData()
43       // does not see if the update is for counter rollover.
44       if(    nvIndex.publicArea.attributes.TPMA_NV_ORDERLY == SET
45           && (countValue & MAX_ORDERLY_COUNT) == 0)
46       {
47           result = NvIsAvailable();
48           if(result != TPM_RC_SUCCESS)
49               return result;
50
51           // Need to force an NV update
52           g_updateNV = TRUE;


     Page 420                                     TCG Published                               Family “2.0”
     October 30, 2014                     Copyright © TCG 2006-2014               Level 00 Revision 01.16
     Trusted Platform Module Library                                             Part 3: Commands

53       }
54
55       // Write NV data back. A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may
56       // be returned at this point. If necessary, this function will set the
57       // TPMA_NV_WRITTEN attribute
58       return NvWriteIndexData(in->nvIndex, &nvIndex, 0, 8, &countValue);
59
60   }
61   #endif // CC_NV_Increment


     Family “2.0”                           TCG Published                               Page 421
     Level 00 Revision 01.16           Copyright © TCG 2006-2014                 October 30, 2014
Part 3: Commands                                                              Trusted Platform Module Library


31.9     TPM2_NV_Extend

31.9.1 General Description

This command extends a value to an area in NV memory that was previously defined by
TPM2_NV_DefineSpace.
If TPMA_NV_EXTEND is not SET, then the TPM shall return TPM_RC_ATTRIBUTES.
Proper write authorizations are required for this command as determined by TPMA_NV_PPWRITE,
TPMA_NV_OWNERWRITE, TPMA_NV_AUTHWRITE, and the authPolicy of the NV Index.
After successful completion of this command, TPMA_NV_WRITTEN for the NV Index will be SET.

NOTE 1           Once SET, TPMA_NV_WRITTEN remains SET until the NV Index is undefined, unless the
                 TPMA_NV_CLEAR_STCLEAR attribute is SET and a TPM Reset or TPM Restart occurs.

If the TPMA_NV_WRITELOCKED attribute of the NV Index is SET, then the TPM shall return
TPM_RC_NV_LOCKED.

NOTE 2           If authorization sessions are present, they are checked before checks to see if writes to the NV
                 Index are locked.

The data.buffer parameter may be larger than the defined size of the NV Index.
The Index will be updated by:
                       nvIndex→datanew ≔ HnameAkg(nvIndex→dataold || data.buffer)                           (39)
where
         HnameAkg()                        the hash algorithm indicated in nvIndex→nameAlg
         nvIndex→data                      the value of the data field in the NV Index
         data.buffer                       the data buffer of the command parameter

NOTE 3           If TPMA_NV_WRITTEN is CLEAR, then nvIndex→data is a Zero Digest.


Page 422                                       TCG Published                                       Family “2.0”
October 30, 2014                       Copyright © TCG 2006-2014                    Level 00 Revision 01.16
Trusted Platform Module Library                                                        Part 3: Commands


31.9.2 Command and Response

                             Table 209 — TPM2_NV_Extend Command
 Type                         Name                 Description

 TPMI_ST_COMMAND_TAG          tag                  TPM_ST_SESSIONS
 UINT32                       commandSize
 TPM_CC                       commandCode          TPM_CC_NV_Extend {NV}

                                                   handle indicating the source of the authorization value
 TPMI_RH_NV_AUTH              @authHandle          Auth Index: 1
                                                   Auth Role: USER
                                                   the NV Index to extend
 TPMI_RH_NV_INDEX             nvIndex
                                                   Auth Index: None

 TPM2B_MAX_NV_BUFFER          data                 the data to extend


                             Table 210 — TPM2_NV_Extend Response
 Type                         Name                 Description

 TPM_ST                       tag                  see clause 6
 UINT32                       responseSize
 TPM_RC                       responseCode


Family “2.0”                              TCG Published                                         Page 423
Level 00 Revision 01.16              Copyright © TCG 2006-2014                         October 30, 2014
     Part 3: Commands                                                          Trusted Platform Module Library


     31.9.3 Detailed Actions

1    #include "InternalRoutines.h"
2    #include "NV_Extend_fp.h"
3    #ifdef TPM_CC_NV_Extend // Conditional expansion of this file
4    #include "NV_spt_fp.h"


     Error Returns               Meaning

     TPM_RC_ATTRIBUTES           the TPMA_NV_EXTEND attribute is not SET in the Index referenced
                                 by nvIndex
     TPM_RC_NV_AUTHORIZATION     the authorization was valid but the authorizing entity (authHandle) is
                                 not allowed to write to the Index referenced by nvIndex
     TPM_RC_NV_LOCKED            the Index referenced by nvIndex is locked for writing

 5   TPM_RC
 6   TPM2_NV_Extend(
 7       NV_Extend_In      *in            // IN: input parameter list
 8       )
 9   {
10       TPM_RC                  result;
11       NV_INDEX                nvIndex;
12
13       TPM2B_DIGEST            oldDigest;
14       TPM2B_DIGEST            newDigest;
15       HASH_STATE              hashState;
16
17   // Input Validation
18
19       // Common access checks, NvWriteAccessCheck() may return TPM_RC_NV_AUTHORIZATION
20       // or TPM_RC_NV_LOCKED
21       result = NvWriteAccessChecks(in->authHandle, in->nvIndex);
22       if(result != TPM_RC_SUCCESS)
23           return result;
24
25       // Get NV index info
26       NvGetIndexInfo(in->nvIndex, &nvIndex);
27
28       // Make sure that this is an extend index
29       if(nvIndex.publicArea.attributes.TPMA_NV_EXTEND != SET)
30           return TPM_RC_ATTRIBUTES + RC_NV_Extend_nvIndex;
31
32       // If the Index is not-orderly, or if this is the first write, NV will
33       // need to be updated.
34       if(   nvIndex.publicArea.attributes.TPMA_NV_ORDERLY == CLEAR
35          || nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == CLEAR)
36       {
37           // Check if NV is available. NvIsAvailable may return TPM_RC_NV_UNAVAILABLE
38           // TPM_RC_NV_RATE or TPM_RC_SUCCESS.
39           result = NvIsAvailable();
40           if(result != TPM_RC_SUCCESS)
41               return result;
42       }
43
44   // Internal Data Update
45
46       // Perform the write.
47       oldDigest.t.size = CryptGetHashDigestSize(nvIndex.publicArea.nameAlg);
48       pAssert(oldDigest.t.size <= sizeof(oldDigest.t.buffer));
49       if(nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == SET)
50       {

     Page 424                                 TCG Published                                          Family “2.0”
     October 30, 2014                Copyright © TCG 2006-2014                           Level 00 Revision 01.16
     Trusted Platform Module Library                                             Part 3: Commands

51           NvGetIndexData(in->nvIndex, &nvIndex, 0,
52                          oldDigest.t.size, oldDigest.t.buffer);
53       }
54       else
55       {
56           MemorySet(oldDigest.t.buffer, 0, oldDigest.t.size);
57       }
58       // Start hash
59       newDigest.t.size = CryptStartHash(nvIndex.publicArea.nameAlg, &hashState);
60
61       // Adding old digest
62       CryptUpdateDigest2B(&hashState, &oldDigest.b);
63
64       // Adding new data
65       CryptUpdateDigest2B(&hashState, &in->data.b);
66
67       // Complete hash
68       CryptCompleteHash2B(&hashState, &newDigest.b);
69
70       // Write extended hash back.
71       // Note, this routine will SET the TPMA_NV_WRITTEN attribute if necessary
72       return NvWriteIndexData(in->nvIndex, &nvIndex, 0,
73                               newDigest.t.size, newDigest.t.buffer);
74   }
75   #endif // CC_NV_Extend


     Family “2.0”                           TCG Published                               Page 425
     Level 00 Revision 01.16           Copyright © TCG 2006-2014                 October 30, 2014
Part 3: Commands                                                        Trusted Platform Module Library


31.10 TPM2_NV_SetBits

31.10.1     General Description

This command is used to SET bits in an NV Index that was created as a bit field. Any number of bits from
0 to 64 may be SET. The contents of data are ORed with the current contents of the NV Index starting at
offset.
If TPMA_NV_WRITTEN is not SET, then, for the purposes of this command, the NV Index is considered
to contain all zero bits and data is OR with that value.
If TPMA_NV_BITS is not SET, then the TPM shall return TPM_RC_ATTRIBUTES.
After successful completion of this command, TPMA_NV_WRITTEN for the NV Index will be SET.

NOTE            TPMA_NV_WRITTEN will be SET even if no bits were SET.


Page 426                                    TCG Published                                  Family “2.0”
October 30, 2014                    Copyright © TCG 2006-2014                 Level 00 Revision 01.16
Trusted Platform Module Library                                                         Part 3: Commands


31.10.2    Command and Response

                             Table 211 — TPM2_NV_SetBits Command
 Type                         Name                 Description

 TPMI_ST_COMMAND_TAG          tag                  TPM_ST_SESSIONS
 UINT32                       commandSize
 TPM_CC                       commandCode          TPM_CC_NV_SetBits {NV}

                                                   handle indicating the source of the authorization value
 TPMI_RH_NV_AUTH              @authHandle          Auth Index: 1
                                                   Auth Role: USER
                                                   NV Index of the area in which the bit is to be set
 TPMI_RH_NV_INDEX             nvIndex
                                                   Auth Index: None

 UINT64                       bits                 the data to OR with the current contents


                             Table 212 — TPM2_NV_SetBits Response
 Type                         Name                 Description

 TPM_ST                       tag                  see clause 6
 UINT32                       responseSize
 TPM_RC                       responseCode


Family “2.0”                              TCG Published                                          Page 427
Level 00 Revision 01.16              Copyright © TCG 2006-2014                          October 30, 2014
     Part 3: Commands                                                            Trusted Platform Module Library


     31.10.3    Detailed Actions

1    #include "InternalRoutines.h"
2    #include "NV_SetBits_fp.h"
3    #ifdef TPM_CC_NV_SetBits // Conditional expansion of this file
4    #include "NV_spt_fp.h"


     Error Returns                 Meaning

     TPM_RC_ATTRIBUTES             the TPMA_NV_BITS attribute is not SET in the Index referenced by
                                   nvIndex
     TPM_RC_NV_AUTHORIZATION       the authorization was valid but the authorizing entity (authHandle) is
                                   not allowed to write to the Index referenced by nvIndex
     TPM_RC_NV_LOCKED              the Index referenced by nvIndex is locked for writing

 5   TPM_RC
 6   TPM2_NV_SetBits(
 7       NV_SetBits_In     *in              // IN: input parameter list
 8       )
 9   {
10       TPM_RC            result;
11       NV_INDEX          nvIndex;
12       UINT64            oldValue;
13       UINT64            newValue;
14
15   // Input Validation
16
17       // Common access checks, NvWriteAccessCheck() may return TPM_RC_NV_AUTHORIZATION
18       // or TPM_RC_NV_LOCKED
19       // error may be returned at this point
20       result = NvWriteAccessChecks(in->authHandle, in->nvIndex);
21       if(result != TPM_RC_SUCCESS)
22           return result;
23
24       // Get NV index info
25       NvGetIndexInfo(in->nvIndex, &nvIndex);
26
27       // Make sure that this is a bit field
28       if(nvIndex.publicArea.attributes.TPMA_NV_BITS != SET)
29           return TPM_RC_ATTRIBUTES + RC_NV_SetBits_nvIndex;
30
31       // If index is not been written, initialize it
32       if(nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == CLEAR)
33           oldValue = 0;
34       else
35           // Read index data
36           NvGetIntIndexData(in->nvIndex, &nvIndex, &oldValue);
37
38       // Figure out what the new value is going to be
39       newValue = oldValue | in->bits;
40
41       // If the Index is not-orderly and it has changed, or if this is the first
42       // write, NV will need to be updated.
43       if(    (    nvIndex.publicArea.attributes.TPMA_NV_ORDERLY == CLEAR
44               && newValue != oldValue)
45           || nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == CLEAR)
46       {
47
48   // Internal Data Update
49           // Check if NV is available. NvIsAvailable may return TPM_RC_NV_UNAVAILABLE
50           // TPM_RC_NV_RATE or TPM_RC_SUCCESS.

     Page 428                                   TCG Published                                          Family “2.0”
     October 30, 2014                  Copyright © TCG 2006-2014                           Level 00 Revision 01.16
     Trusted Platform Module Library                                              Part 3: Commands

51           result = NvIsAvailable();
52           if(result != TPM_RC_SUCCESS)
53               return result;
54
55           // Write index data back. If necessary, this function will SET
56           // TPMA_NV_WRITTEN.
57           result = NvWriteIndexData(in->nvIndex, &nvIndex, 0, 8, &newValue);
58       }
59       return result;
60
61   }
62   #endif // CC_NV_SetBits


     Family “2.0”                           TCG Published                                Page 429
     Level 00 Revision 01.16           Copyright © TCG 2006-2014                  October 30, 2014
Part 3: Commands                                                    Trusted Platform Module Library


31.11 TPM2_NV_WriteLock

31.11.1    General Description

If the TPMA_NV_WRITEDEFINE or TPMA_NV_WRITE_STCLEAR attributes of an NV location are SET,
then this command may be used to inhibit further writes of the NV Index.
Proper write authorization is required for this command as determined by TPMA_NV_PPWRITE,
TPMA_NV_OWNERWRITE, TPMA_NV_AUTHWRITE, and the authPolicy of the NV Index.
It is not an error if TPMA_NV_WRITELOCKED for the NV Index is already SET.
If neither TPMA_NV_WRITEDEFINE nor TPMA_NV_WRITE_STCLEAR of the NV Index is SET, then the
TPM shall return TPM_RC_ATTRIBUTES.
If the command is properly authorized and TPMA_NV_WRITE_STCLEAR or TPMA_NV_WRITEDEFINE
is SET, then the TPM shall SET TPMA_NV_WRITELOCKED for the NV Index.
TPMA_NV_WRITELOCKED will be clear on the next TPM2_Startup(TPM_SU_CLEAR) unless
TPMA_NV_WRITEDEFINE is SET or if TPM_NV_WRITTEN is CLEAR.


Page 430                                 TCG Published                                Family “2.0”
October 30, 2014                  Copyright © TCG 2006-2014              Level 00 Revision 01.16
Trusted Platform Module Library                                                       Part 3: Commands


31.11.2    Command and Response

                           Table 213 — TPM2_NV_WriteLock Command
 Type                         Name                Description

 TPMI_ST_COMMAND_TAG          tag                 TPM_ST_SESSIONS
 UINT32                       commandSize
 TPM_CC                       commandCode         TPM_CC_NV_WriteLock {NV}

                                                  handle indicating the source of the authorization value
 TPMI_RH_NV_AUTH              @authHandle         Auth Index: 1
                                                  Auth Role: USER
                                                  the NV Index of the area to lock
 TPMI_RH_NV_INDEX             nvIndex
                                                  Auth Index: None


                           Table 214 — TPM2_NV_WriteLock Response
 Type                         Name                Description

 TPM_ST                       tag                 see clause 6
 UINT32                       responseSize
 TPM_RC                       responseCode


Family “2.0”                             TCG Published                                         Page 431
Level 00 Revision 01.16             Copyright © TCG 2006-2014                         October 30, 2014
     Part 3: Commands                                                               Trusted Platform Module Library


     31.11.3    Detailed Actions

1    #include "InternalRoutines.h"
2    #include "NV_WriteLock_fp.h"
3    #ifdef TPM_CC_NV_WriteLock // Conditional expansion of this file
4    #include "NV_spt_fp.h"


     Error Returns                    Meaning

     TPM_RC_ATTRIBUTES                neither TPMA_NV_WRITEDEFINE nor
                                      TPMA_NV_WRITE_STCLEAR is SET in Index referenced by
                                      nvIndex
     TPM_RC_NV_AUTHORIZATION          the authorization was valid but the authorizing entity (authHandle) is
                                      not allowed to write to the Index referenced by nvIndex

 5   TPM_RC
 6   TPM2_NV_WriteLock(
 7       NV_WriteLock_In       *in                  // IN: input parameter list
 8       )
 9   {
10       TPM_RC            result;
11       NV_INDEX          nvIndex;
12
13   // Input Validation:
14
15       // Common write access checks, a TPM_RC_NV_AUTHORIZATION or TPM_RC_NV_LOCKED
16       // error may be returned at this point
17       result = NvWriteAccessChecks(in->authHandle, in->nvIndex);
18       if(result != TPM_RC_SUCCESS)
19       {
20           if(result == TPM_RC_NV_AUTHORIZATION)
21               return TPM_RC_NV_AUTHORIZATION;
22           // If write access failed because the index is already locked, then it is
23           // no error.
24           return TPM_RC_SUCCESS;
25       }
26
27       // Get NV index info
28       NvGetIndexInfo(in->nvIndex, &nvIndex);
29
30       // if neither TPMA_NV_WRITEDEFINE nor TPMA_NV_WRITE_STCLEAR is set, the index
31       // can not be write-locked
32       if(   nvIndex.publicArea.attributes.TPMA_NV_WRITEDEFINE == CLEAR
33          && nvIndex.publicArea.attributes.TPMA_NV_WRITE_STCLEAR == CLEAR)
34           return TPM_RC_ATTRIBUTES + RC_NV_WriteLock_nvIndex;
35
36   // Internal Data Update
37
38       // The command needs NV update. Check if NV is available.
39       // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
40       // this point
41       result = NvIsAvailable();
42       if(result != TPM_RC_SUCCESS)
43           return result;
44
45       // Set the WRITELOCK attribute.
46       // Note: if TPMA_NV_WRITELOCKED were already SET, then the write access check
47       // above would have failed and this code isn't executed.
48       nvIndex.publicArea.attributes.TPMA_NV_WRITELOCKED = SET;
49
50       // Write index info back
51       NvWriteIndexInfo(in->nvIndex, &nvIndex);

     Page 432                                      TCG Published                                          Family “2.0”
     October 30, 2014                     Copyright © TCG 2006-2014                        Level 00 Revision 01.16
     Trusted Platform Module Library                               Part 3: Commands

52
53       return TPM_RC_SUCCESS;
54   }
55   #endif // CC_NV_WriteLock


     Family “2.0”                           TCG Published                 Page 433
     Level 00 Revision 01.16           Copyright © TCG 2006-2014   October 30, 2014
Part 3: Commands                                                             Trusted Platform Module Library


31.12 TPM2_NV_GlobalWriteLock

31.12.1    General Description

The command will SET TPMA_NV_WRITELOCKED                         for   all     indexes   that   have   their
TPMA_NV_GLOBALLOCK attribute SET.
If an Index has both TPMA_NV_WRITELOCKED and TPMA_NV_WRITEDEFINE SET, then this
command will permanently lock the NV Index for writing unless TPMA_NV_WRITTEN is CLEAR.

NOTE           If an Index is defined with TPMA_NV_GLOBALLOCK SET, then the global lock does not apply until
               the next time this command is executed.

This command requires either platformAuth/platformPolicy or ownerAuth/ownerPolicy.


Page 434                                    TCG Published                                       Family “2.0”
October 30, 2014                    Copyright © TCG 2006-2014                     Level 00 Revision 01.16
Trusted Platform Module Library                                               Part 3: Commands


31.12.2    Command and Response

                        Table 215 — TPM2_NV_GlobalWriteLock Command
 Type                         Name                Description

 TPMI_ST_COMMAND_TAG          tag                 TPM_ST_SESSIONS
 UINT32                       commandSize
 TPM_CC                       commandCode         TPM_CC_NV_GlobalWriteLock

                                                  TPM_RH_OWNER or TPM_RH_PLATFORM+{PP}
 TPMI_RH_PROVISION            @authHandle         Auth Index: 1
                                                  Auth Role: USER


                        Table 216 — TPM2_NV_GlobalWriteLock Response
 Type                         Name                Description
 TPM_ST                       tag                 see clause 6
 UINT32                       responseSize
 TPM_RC                       responseCode


Family “2.0”                             TCG Published                               Page 435
Level 00 Revision 01.16             Copyright © TCG 2006-2014                 October 30, 2014
     Part 3: Commands                                                    Trusted Platform Module Library


     31.12.3      Detailed Actions

 1   #include "InternalRoutines.h"
 2   #include "NV_GlobalWriteLock_fp.h"
 3   #ifdef TPM_CC_NV_GlobalWriteLock // Conditional expansion of this file
 4   TPM_RC
 5   TPM2_NV_GlobalWriteLock(
 6       NV_GlobalWriteLock_In       *in             // IN: input parameter list
 7       )
 8   {
 9       TPM_RC           result;
10
11       // Input parameter is not reference in command action
12       in = NULL; // to silence compiler warnings.
13
14       // The command needs NV update. Check if NV is available.
15       // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
16       // this point
17       result = NvIsAvailable();
18       if(result != TPM_RC_SUCCESS)
19           return result;
20
21   // Internal Data Update
22
23       // Implementation dependent method of setting the global lock
24       NvSetGlobalLock();
25
26       return TPM_RC_SUCCESS;
27   }
28   #endif // CC_NV_GlobalWriteLock


     Page 436                                   TCG Published                              Family “2.0”
     October 30, 2014                      Copyright © TCG 2006-2014           Level 00 Revision 01.16
Trusted Platform Module Library                                                               Part 3: Commands


31.13 TPM2_NV_Read

31.13.1    General Description

This command reads a            value    from    an    area    in   NV    memory      previously     defined    by
TPM2_NV_DefineSpace().
Proper authorizations are required for this command as determined by TPMA_NV_PPREAD,
TPMA_NV_OWNERREAD, TPMA_NV_AUTHREAD, and the authPolicy of the NV Index.
If TPMA_NV_READLOCKED of the NV Index is SET, then the TPM shall return TPM_RC_NV_LOCKED.

NOTE           If authorization sessions are present, they are checked before the read -lock status of the NV Index
               is checked.

If the size parameter plus the offset parameter adds to a value that is greater than the size of the NV
Index data area, the TPM shall return TPM_RC_NV_RANGE and not read any data from the NV Index.
If the NV Index has been defined but the TPMA_NV_WRITTEN attribute is CLEAR, then this command
shall return TPM_RC_NV_UINITIALIZED even if size is zero.
The data parameter in the response may be encrypted using parameter encryption.


Family “2.0”                                  TCG Published                                            Page 437
Level 00 Revision 01.16               Copyright © TCG 2006-2014                              October 30, 2014
Part 3: Commands                                                  Trusted Platform Module Library


31.13.2    Command and Response

                        Table 217 — TPM2_NV_Read Command
 Type                   Name                 Description

 TPMI_ST_COMMAND_TAG    tag                  TPM_ST_SESSIONS
 UINT32                 commandSize
 TPM_CC                 commandCode          TPM_CC_NV_Read

                                             the handle indicating the source of the authorization
                                             value
 TPMI_RH_NV_AUTH        @authHandle
                                             Auth Index: 1
                                             Auth Role: USER
                                             the NV Index to be read
 TPMI_RH_NV_INDEX       nvIndex
                                             Auth Index: None

 UINT16                 size                 number of octets to read
                                             octet offset into the area
 UINT16                 offset               This value shall be less than or equal to the size of the
                                             nvIndex data.


                        Table 218 — TPM2_NV_Read Response
 Type                   Name                 Description

 TPM_ST                 tag                  see clause 6
 UINT32                 responseSize
 TPM_RC                 responseCode

 TPM2B_MAX_NV_BUFFER    data                 the data read


Page 438                            TCG Published                                       Family “2.0”
October 30, 2014               Copyright © TCG 2006-2014                 Level 00 Revision 01.16
     Trusted Platform Module Library                                                                 Part 3: Commands


     31.13.3    Detailed Actions

1    #include "InternalRoutines.h"
2    #include "NV_Read_fp.h"
3    #ifdef TPM_CC_NV_Read // Conditional expansion of this file
4    #include "NV_spt_fp.h"


     Error Returns                     Meaning

     TPM_RC_NV_AUTHORIZATION           the authorization was valid but the authorizing entity (authHandle) is
                                       not allowed to read from the Index referenced by nvIndex
     TPM_RC_NV_LOCKED                  the Index referenced by nvIndex is read locked
     TPM_RC_NV_RANGE                   read range defined by size and offset is outside the range of the
                                       Index referenced by nvIndex
     TPM_RC_NV_UNINITIALIZED           the Index referenced by nvIndex has not been initialized (written)

 5   TPM_RC
 6   TPM2_NV_Read(
 7       NV_Read_In        *in,                 // IN: input parameter list
 8       NV_Read_Out       *out                 // OUT: output parameter list
 9       )
10   {
11       NV_INDEX          nvIndex;
12       TPM_RC            result;
13
14   // Input Validation
15
16       // Get NV index info
17       NvGetIndexInfo(in->nvIndex, &nvIndex);
18
19       // Common read access checks. NvReadAccessChecks() returns
20       // TPM_RC_NV_AUTHORIZATION, TPM_RC_NV_LOCKED, or TPM_RC_NV_UNINITIALIZED
21       // error may be returned at this point
22       result = NvReadAccessChecks(in->authHandle, in->nvIndex);
23       if(result != TPM_RC_SUCCESS)
24           return result;
25
26       // Too much data
27       if((in->size + in->offset) > nvIndex.publicArea.dataSize)
28           return TPM_RC_NV_RANGE;
29
30   // Command Output
31
32       // Set the return size
33       out->data.t.size = in->size;
34       // Perform the read
35       NvGetIndexData(in->nvIndex, &nvIndex, in->offset, in->size, out->data.t.buffer);
36
37       return TPM_RC_SUCCESS;
38   }
39   #endif // CC_NV_Read


     Family “2.0”                                   TCG Published                                               Page 439
     Level 00 Revision 01.16               Copyright © TCG 2006-2014                                 October 30, 2014
Part 3: Commands                                                                 Trusted Platform Module Library


31.14 TPM2_NV_ReadLock

31.14.1     General Description

If TPMA_NV_READ_STCLEAR is SET in an Index, then this command may be used to prevent further
reads of the NV Index until the next TPM2_Startup (TPM_SU_CLEAR).
Proper authorizations are required for this command as determined by TPMA_NV_PPREAD,
TPMA_NV_OWNERREAD, TPMA_NV_AUTHREAD, and the authPolicy of the NV Index.

NOTE            Only an entity that may read an Index is allowed to lock the NV Index for read.

If the command is properly authorized and TPMA_NV_READ_STCLEAR of the NV Index is SET, then the
TPM shall SET TPMA_NV_READLOCKED for the NV Index. If TPMA_NV_READ_STCLEAR of the NV
Index is CLEAR, then the TPM shall return TPM_RC_ATTRIBUTES. TPMA_NV_READLOCKED will be
CLEAR by the next TPM2_Startup(TPM_SU_CLEAR).
It is not an error to use this command for an Index that is already locked for reading.
An Index that had not been written may be locked for reading.


Page 440                                       TCG Published                                       Family “2.0”
October 30, 2014                       Copyright © TCG 2006-2014                        Level 00 Revision 01.16
Trusted Platform Module Library                                                       Part 3: Commands


31.14.2    Command and Response

                           Table 219 — TPM2_NV_ReadLock Command
 Type                         Name                Description

 TPMI_ST_COMMAND_TAG          tag                 TPM_ST_SESSIONS
 UINT32                       commandSize
 TPM_CC                       commandCode         TPM_CC_NV_ReadLock

                                                  the handle indicating the source of the authorization
                                                  value
 TPMI_RH_NV_AUTH              @authHandle
                                                  Auth Index: 1
                                                  Auth Role: USER
                                                  the NV Index to be locked
 TPMI_RH_NV_INDEX             nvIndex
                                                  Auth Index: None


                           Table 220 — TPM2_NV_ReadLock Response
 Type                         Name                Description

 TPM_ST                       tag                 see clause 6
 UINT32                       responseSize
 TPM_RC                       responseCode


Family “2.0”                             TCG Published                                         Page 441
Level 00 Revision 01.16             Copyright © TCG 2006-2014                         October 30, 2014
     Part 3: Commands                                                               Trusted Platform Module Library


     31.14.3     Detailed Actions

1    #include "InternalRoutines.h"
2    #include "NV_ReadLock_fp.h"
3    #ifdef TPM_CC_NV_ReadLock // Conditional expansion of this file
4    #include "NV_spt_fp.h"


     Error Returns                    Meaning

     TPM_RC_ATTRIBUTES                TPMA_NV_READ_STCLEAR is not SET so Index referenced by
                                      nvIndex may not be write locked
     TPM_RC_NV_AUTHORIZATION          the authorization was valid but the authorizing entity (authHandle) is
                                      not allowed to read from the Index referenced by nvIndex

 5   TPM_RC
 6   TPM2_NV_ReadLock(
 7       NV_ReadLock_In    *in                 // IN: input parameter list
 8       )
 9   {
10       TPM_RC            result;
11       NV_INDEX          nvIndex;
12
13       // The command needs NV update. Check if NV is available.
14       // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
15       // this point
16       result = NvIsAvailable();
17       if(result != TPM_RC_SUCCESS) return result;
18
19   // Input Validation
20
21       // Common read access checks. NvReadAccessChecks() returns
22       // TPM_RC_NV_AUTHORIZATION, TPM_RC_NV_LOCKED, or TPM_RC_NV_UNINITIALIZED
23       // error may be returned at this point
24       result = NvReadAccessChecks(in->authHandle, in->nvIndex);
25       if(result != TPM_RC_SUCCESS)
26       {
27           if(result == TPM_RC_NV_AUTHORIZATION)
28               return TPM_RC_NV_AUTHORIZATION;
29           // Index is already locked for write
30           else if(result == TPM_RC_NV_LOCKED)
31               return TPM_RC_SUCCESS;
32
33             // If NvReadAccessChecks return TPM_RC_NV_UNINITALIZED, then continue.
34             // It is not an error to read lock an uninitialized Index.
35       }
36
37       // Get NV index info
38       NvGetIndexInfo(in->nvIndex, &nvIndex);
39
40       // if TPMA_NV_READ_STCLEAR is not set, the index can not be read-locked
41       if(nvIndex.publicArea.attributes.TPMA_NV_READ_STCLEAR == CLEAR)
42           return TPM_RC_ATTRIBUTES + RC_NV_ReadLock_nvIndex;
43
44   // Internal Data Update
45
46       // Set the READLOCK attribute
47       nvIndex.publicArea.attributes.TPMA_NV_READLOCKED = SET;
48       // Write NV info back
49       NvWriteIndexInfo(in->nvIndex, &nvIndex);
50
51       return TPM_RC_SUCCESS;
52   }

     Page 442                                      TCG Published                                          Family “2.0”
     October 30, 2014                     Copyright © TCG 2006-2014                        Level 00 Revision 01.16
     Trusted Platform Module Library                               Part 3: Commands

53   #endif // CC_NV_ReadLock


     Family “2.0”                           TCG Published                 Page 443
     Level 00 Revision 01.16           Copyright © TCG 2006-2014   October 30, 2014
Part 3: Commands                                                                  Trusted Platform Module Library


31.15 TPM2_NV_ChangeAuth

31.15.1     General Description

This command allows the authorization secret for an NV Index to be changed.
If successful, the authorization secret (authValue) of the NV Index associated with nvIndex is changed.
This command requires that a policy session be used for authorization of nvIndex so that the ADMIN role
may be asserted and that commandCode in the policy session context shall be
TPM_CC_NV_ChangeAuth. That is, the policy must contain a specific authorization for changing the
authorization value of the referenced object.

NOTE            The reason for this restriction is to ensure that the administrative actions on nvIndex require explicit
                approval while other commands may use policy that is not command -dependent.

The size of the newAuth value may be no larger than the size of authorization indicated when the NV
Index was defined.
Since the NV Index authorization is changed before the response HMAC is calculated, the newAuth value
is used when generating the response HMAC key if required.                  See TPM 2.0 Part 4
ComputeResponseHMAC().


Page 444                                        TCG Published                                           Family “2.0”
October 30, 2014                       Copyright © TCG 2006-2014                         Level 00 Revision 01.16
Trusted Platform Module Library                                                 Part 3: Commands


31.15.2    Command and Response

                          Table 221 — TPM2_NV_ChangeAuth Command
Type                          Name                  Description

TPMI_ST_COMMAND_TAG           tag                   TPM_ST_SESSIONS
UINT32                        commandSize
TPM_CC                        commandCode           TPM_CC_NV_ChangeAuth {NV}

                                                    handle of the object
TPMI_RH_NV_INDEX              @nvIndex              Auth Index: 1
                                                    Auth Role: ADMIN

TPM2B_AUTH                    newAuth               new authorization value


                          Table 222 — TPM2_NV_ChangeAuth Response
Type                          Name                  Description

TPM_ST                        tag                   see clause 6
UINT32                        responseSize
TPM_RC                        responseCode


Family “2.0”                                 TCG Published                             Page 445
Level 00 Revision 01.16             Copyright © TCG 2006-2014                   October 30, 2014
     Part 3: Commands                                                           Trusted Platform Module Library


     31.15.3    Detailed Actions

1    #include "InternalRoutines.h"
2    #include "NV_ChangeAuth_fp.h"
3    #ifdef TPM_CC_NV_ChangeAuth // Conditional expansion of this file


     Error Returns                 Meaning

     TPM_RC_SIZE                   newAuth size is larger than the digest size of the Name algorithm for
                                   the Index referenced by 'nvIndex

 4   TPM_RC
 5   TPM2_NV_ChangeAuth(
 6       NV_ChangeAuth_In   *in                  // IN: input parameter list
 7       )
 8   {
 9       TPM_RC         result;
10       NV_INDEX       nvIndex;
11
12   // Input Validation
13       // Check if NV is available. NvIsAvailable may return TPM_RC_NV_UNAVAILABLE
14       // TPM_RC_NV_RATE or TPM_RC_SUCCESS.
15       result = NvIsAvailable();
16       if(result != TPM_RC_SUCCESS) return result;
17
18       // Read index info from NV
19       NvGetIndexInfo(in->nvIndex, &nvIndex);
20
21       // Remove any trailing zeros that might have been added by the caller
22       // to obfuscate the size.
23       MemoryRemoveTrailingZeros(&(in->newAuth));
24
25       // Make sure that the authValue is no larger than the nameAlg of the Index
26       if(in->newAuth.t.size > CryptGetHashDigestSize(nvIndex.publicArea.nameAlg))
27           return TPM_RC_SIZE + RC_NV_ChangeAuth_newAuth;
28
29   // Internal Data Update
30       // Change auth
31       nvIndex.authValue = in->newAuth;
32       // Write index info back to NV
33       NvWriteIndexInfo(in->nvIndex, &nvIndex);
34
35       return TPM_RC_SUCCESS;
36   }
37   #endif // CC_NV_ChangeAuth


     Page 446                                   TCG Published                                         Family “2.0”
     October 30, 2014                  Copyright © TCG 2006-2014                       Level 00 Revision 01.16
Trusted Platform Module Library                                                        Part 3: Commands


31.16 TPM2_NV_Certify

31.16.1     General Description

The purpose of this command is to certify the contents of an NV Index or portion of an NV Index.
If proper authorization for reading the NV Index is provided, the portion of the NV Index selected by size
and offset are included in an attestation block and signed using the key indicated by signHandle. The
attestation also includes size and offset so that the range of the data can be determined.

NOTE 1          See 18.1 for description of how the signing scheme is selected.

NOTE 2          If signHandle is TPM_RH_NULL, the TPMS_ATTEST structure is returned and signature is a NULL
                Signature.


Family “2.0”                                   TCG Published                                    Page 447
Level 00 Revision 01.16                Copyright © TCG 2006-2014                       October 30, 2014
Part 3: Commands                                                       Trusted Platform Module Library


31.16.2    Command and Response

                       Table 223 — TPM2_NV_Certify Command
Type                    Name                  Description

TPMI_ST_COMMAND_TAG     tag                   TPM_ST_SESSIONS
UINT32                  commandSize
TPM_CC                  commandCode           TPM_CC_NV_Certify

                                              handle of the key used to sign the attestation structure
TPMI_DH_OBJECT+         @signHandle           Auth Index: 1
                                              Auth Role: USER
                                                  handle indicating the source of the authorization value
                                                  for the NV Index
 TPMI_RH_NV_AUTH        @authHandle
                                                  Auth Index: 2
                                                  Auth Role: USER
                                                  Index for the area to be certified
 TPMI_RH_NV_INDEX       nvIndex
                                                  Auth Index: None

TPM2B_DATA              qualifyingData        user-provided qualifying data
                                              signing scheme to use if the scheme for signHandle is
TPMT_SIG_SCHEME+        inScheme
                                              TPM_ALG_NULL
 UINT16                 size                      number of octets to certify
                                                  octet offset into the area
 UINT16                 offset                    This value shall be less than or equal to the size of the
                                                  nvIndex data.


                       Table 224 — TPM2_NV_Certify Response
Type                    Name                  Description

TPM_ST                  tag                   see clause 6
UINT32                  responseSize
TPM_RC                  responseCode          .

TPM2B_ATTEST            certifyInfo           the structure that was signed
                                              the asymmetric signature over certifyInfo using the key
TPMT_SIGNATURE          signature
                                              referenced by signHandle


Page 448                               TCG Published                                         Family “2.0”
October 30, 2014               Copyright © TCG 2006-2014                        Level 00 Revision 01.16
     Trusted Platform Module Library                                                                 Part 3: Commands


     31.16.3    Detailed Actions

1    #include "InternalRoutines.h"
2    #include "Attest_spt_fp.h"
3    #include "NV_spt_fp.h"
4    #include "NV_Certify_fp.h"
5    #ifdef TPM_CC_NV_Certify // Conditional expansion of this file


     Error Returns                     Meaning

     TPM_RC_NV_AUTHORIZATION           the authorization was valid but the authorizing entity (authHandle) is
                                       not allowed to read from the Index referenced by nvIndex
     TPM_RC_KEY                        signHandle does not reference a signing key
     TPM_RC_NV_LOCKED                  Index referenced by nvIndex is locked for reading
     TPM_RC_NV_RANGE                   offset plus size extends outside of the data range of the Index
                                       referenced by nvIndex
     TPM_RC_NV_UNINITIALIZED           Index referenced by nvIndex has not been written
     TPM_RC_SCHEME                     inScheme is not an allowed value for the key definition

 6   TPM_RC
 7   TPM2_NV_Certify(
 8       NV_Certify_In     *in,                 // IN: input parameter list
 9       NV_Certify_Out    *out                 // OUT: output parameter list
10       )
11   {
12       TPM_RC                    result;
13       NV_INDEX                  nvIndex;
14       TPMS_ATTEST               certifyInfo;
15
16       // Attestation command may cause the orderlyState to be cleared due to
17       // the reporting of clock info. If this is the case, check if NV is
18       // available first
19       if(gp.orderlyState != SHUTDOWN_NONE)
20       {
21           // The command needs NV update. Check if NV is available.
22           // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
23           // this point
24           result = NvIsAvailable();
25           if(result != TPM_RC_SUCCESS)
26               return result;
27       }
28
29   // Input Validation
30
31       // Get NV index info
32       NvGetIndexInfo(in->nvIndex, &nvIndex);
33
34       // Common access checks. A TPM_RC_NV_AUTHORIZATION or TPM_RC_NV_LOCKED
35       // error may be returned at this point
36       result = NvReadAccessChecks(in->authHandle, in->nvIndex);
37       if(result != TPM_RC_SUCCESS)
38           return result;
39
40       // See if the range to be certified is out of the bounds of the defined
41       // Index
42       if((in->size + in->offset) > nvIndex.publicArea.dataSize)
43           return TPM_RC_NV_RANGE;
44
45   // Command Output

     Family “2.0”                                   TCG Published                                               Page 449
     Level 00 Revision 01.16               Copyright © TCG 2006-2014                                 October 30, 2014
      Part 3: Commands                                                  Trusted Platform Module Library

 46
 47      // Filling in attest information
 48      // Common fields
 49      // FillInAttestInfo can return TPM_RC_SCHEME or TPM_RC_KEY
 50      result = FillInAttestInfo(in->signHandle,
 51                                &in->inScheme,
 52                                &in->qualifyingData,
 53                                &certifyInfo);
 54      if(result != TPM_RC_SUCCESS)
 55      {
 56          if(result == TPM_RC_KEY)
 57              return TPM_RC_KEY + RC_NV_Certify_signHandle;
 58          else
 59              return RcSafeAddToResult(result, RC_NV_Certify_inScheme);
 60      }
 61      // NV certify specific fields
 62      // Attestation type
 63      certifyInfo.type = TPM_ST_ATTEST_NV;
 64
 65      // Get the name of the index
 66      certifyInfo.attested.nv.indexName.t.size =
 67          NvGetName(in->nvIndex, &certifyInfo.attested.nv.indexName.t.name);
 68
 69      // Set the return size
 70      certifyInfo.attested.nv.nvContents.t.size = in->size;
 71
 72      // Set the offset
 73      certifyInfo.attested.nv.offset = in->offset;
 74
 75      // Perform the read
 76      NvGetIndexData(in->nvIndex, &nvIndex,
 77                     in->offset, in->size,
 78                     certifyInfo.attested.nv.nvContents.t.buffer);
 79
 80      // Sign attestation structure. A NULL signature will be returned if
 81      // signHandle is TPM_RH_NULL. SignAttestInfo() may return TPM_RC_VALUE,
 82      // TPM_RC_SCHEME or TPM_RC_ATTRUBUTES.
 83      // Note: SignAttestInfo may return TPM_RC_ATTRIBUTES if the key is not a
 84      // signing key but that was checked above. TPM_RC_VALUE would mean that the
 85      // data to sign is too large but the data to sign is a digest
 86      result = SignAttestInfo(in->signHandle,
 87                              &in->inScheme,
 88                              &certifyInfo,
 89                              &in->qualifyingData,
 90                              &out->certifyInfo,
 91                              &out->signature);
 92      if(result != TPM_RC_SUCCESS)
 93          return result;
 94
 95      // orderly state should be cleared because of the reporting of clock info
 96      // if signing happens
 97      if(in->signHandle != TPM_RH_NULL)
 98          g_clearOrderly = TRUE;
 99
100       return TPM_RC_SUCCESS;
101   }
102   #endif // CC_NV_Certify


      Page 450                              TCG Published                                 Family “2.0”
      October 30, 2014               Copyright © TCG 2006-2014               Level 00 Revision 01.16