Trusted Platform Module Library Part 3: Commands Family “2.0” Level 00 Revision 00.99 October 31, 2013 Contact: admin@trustedcomputinggroup.org Published Copyright © TCG 2006-2013 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 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands CONTENTS 1 2 3 4 Scope .................................................................................................................................................... 1 Terms and Definitions ........................................................................................................................... 1 Symbols and abbreviated terms ............................................................................................................ 1 Notation ................................................................................................................................................. 1 4.1 4.2 4.3 4.4 5 6 7 Introduction ..................................................................................................................................... 1 Table Decorations ........................................................................................................................... 1 Handle and Parameter Demarcation .............................................................................................. 3 AuthorizationSize and ParameterSize ............................................................................................ 3 Normative References ........................................................................................................................... 4 Symbols and Abbreviated Terms .......................................................................................................... 4 Command Processing ........................................................................................................................... 4 7.1 7.2 7.3 7.4 7.5 7.6 7.7 7.8 7.9 8 Introduction ..................................................................................................................................... 4 Command Header Validation .......................................................................................................... 4 Mode Checks .................................................................................................................................. 4 Handle Area Validation ................................................................................................................... 5 Session Area Validation .................................................................................................................. 6 Authorization Checks ...................................................................................................................... 7 Parameter Decryption ..................................................................................................................... 8 Parameter Unmarshaling ................................................................................................................ 9 Command Post Processing .......................................................................................................... 10 Response Values ................................................................................................................................ 12 8.1 8.2 9 10 Implementation Dependent ................................................................................................................. 15 Detailed Actions Assumptions ............................................................................................................. 16 10.1 10.2 10.3 11 Introduction ................................................................................................................................... 28 TPM2_SelfTest ............................................................................................................................. 29 TPM2_IncrementalSelfTest .......................................................................................................... 32 TPM2_GetTestResult ................................................................................................................... 35 Session Commands ............................................................................................................................ 38 13.1 13.2 14 Introduction ................................................................................................................................... 17 _TPM_Init...................................................................................................................................... 17 TPM2_Startup ............................................................................................................................... 19 TPM2_Shutdown .......................................................................................................................... 24 Testing ................................................................................................................................................. 28 12.1 12.2 12.3 12.4 13 Introduction ................................................................................................................................... 16 Pre-processing .............................................................................................................................. 16 Post Processing ............................................................................................................................ 16 Start-up ................................................................................................................................................ 17 11.1 11.2 11.3 11.4 12 Tag ................................................................................................................................................ 12 Response Codes .......................................................................................................................... 12 TPM2_StartAuthSession .............................................................................................................. 38 TPM2_PolicyRestart ..................................................................................................................... 43 Object Commands............................................................................................................................... 46 Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page iii October 31, 2013 Part 3: Commands 14.1 14.2 14.3 14.4 14.5 14.6 14.7 14.8 15 Introduction ................................................................................................................................. 132 TPM2_HMAC_Start .................................................................................................................... 132 TPM2_HashSequenceStart ........................................................................................................ 136 TPM2_SequenceUpdate ............................................................................................................ 139 TPM2_SequenceComplete......................................................................................................... 143 TPM2_EventSequenceComplete ............................................................................................... 147 Attestation Commands ...................................................................................................................... 151 20.1 20.2 20.3 20.4 20.5 20.6 20.7 21 TPM2_GetRandom ..................................................................................................................... 126 TPM2_StirRandom ..................................................................................................................... 129 Hash/HMAC/Event Sequences ......................................................................................................... 132 19.1 19.2 19.3 19.4 19.5 19.6 20 Introduction ................................................................................................................................. 113 TPM2_EncryptDecrypt ................................................................................................................ 115 TPM2_Hash ................................................................................................................................ 119 TPM2_HMAC .............................................................................................................................. 122 Random Number Generator .............................................................................................................. 126 18.1 18.2 19 Introduction ................................................................................................................................... 92 TPM2_RSA_Encrypt ..................................................................................................................... 92 TPM2_RSA_Decrypt .................................................................................................................... 97 TPM2_ECDH_KeyGen ............................................................................................................... 101 TPM2_ECDH_ZGen ................................................................................................................... 104 TPM2_ECC_Parameters ............................................................................................................ 107 TPM2_ZGen_2Phase ................................................................................................................. 108 Symmetric Primitives ......................................................................................................................... 113 17.1 17.2 17.3 17.4 18 TPM2_Duplicate ........................................................................................................................... 77 TPM2_Rewrap .............................................................................................................................. 81 TPM2_Import ................................................................................................................................ 86 Asymmetric Primitives ......................................................................................................................... 92 16.1 16.2 16.3 16.4 16.5 16.6 16.7 17 TPM2_Create................................................................................................................................ 46 TPM2_Load .................................................................................................................................. 51 TPM2_LoadExternal ..................................................................................................................... 55 TPM2_ReadPublic ........................................................................................................................ 60 TPM2_ActivateCredential ............................................................................................................. 63 TPM2_MakeCredential ................................................................................................................. 67 TPM2_Unseal ............................................................................................................................... 70 TPM2_ObjectChangeAuth ............................................................................................................ 73 Duplication Commands ....................................................................................................................... 77 15.1 15.2 15.3 16 Trusted Platform Module Library Introduction ................................................................................................................................. 151 TPM2_Certify .............................................................................................................................. 153 TPM2_CertifyCreation ................................................................................................................ 157 TPM2_Quote............................................................................................................................... 161 TPM2_GetSessionAuditDigest ................................................................................................... 165 TPM2_GetCommandAuditDigest ............................................................................................... 169 TPM2_GetTime........................................................................................................................... 173 Ephemeral EC Keys .......................................................................................................................... 177 Page iv October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 21.1 21.2 21.3 22 Introduction ................................................................................................................................. 200 TPM2_PCR_Extend ................................................................................................................... 201 TPM2_PCR_Event ..................................................................................................................... 204 TPM2_PCR_Read ...................................................................................................................... 207 TPM2_PCR_Allocate .................................................................................................................. 210 TPM2_PCR_SetAuthPolicy ........................................................................................................ 213 TPM2_PCR_SetAuthValue ......................................................................................................... 216 TPM2_PCR_Reset ..................................................................................................................... 219 _TPM_Hash_Start ...................................................................................................................... 222 _TPM_Hash_Data ...................................................................................................................... 224 _TPM_Hash_End ....................................................................................................................... 226 Enhanced Authorization (EA) Commands ........................................................................................ 229 25.1 25.2 25.3 25.4 25.5 25.6 25.7 25.8 25.9 25.10 25.11 25.12 25.13 25.14 25.15 25.16 25.17 25.18 25.19 25.20 26 Introduction ................................................................................................................................. 195 TPM2_SetCommandCodeAuditStatus ....................................................................................... 196 Integrity Collection (PCR) .................................................................................................................. 200 24.1 24.2 24.3 24.4 24.5 24.6 24.7 24.8 24.9 24.10 24.11 25 TPM2_VerifySignature ................................................................................................................ 187 TPM2_Sign ................................................................................................................................. 191 Command Audit ................................................................................................................................. 195 23.1 23.2 24 Introduction ................................................................................................................................. 177 TPM2_Commit ............................................................................................................................ 178 TPM2_EC_Ephemeral ................................................................................................................ 184 Signing and Signature Verification .................................................................................................... 187 22.1 22.2 23 Part 3: Commands Introduction ................................................................................................................................. 229 Signed Authorization Actions ...................................................................................................... 230 TPM2_PolicySigned ................................................................................................................... 234 TPM2_PolicySecret .................................................................................................................... 240 TPM2_PolicyTicket ..................................................................................................................... 244 TPM2_PolicyOR ......................................................................................................................... 248 TPM2_PolicyPCR ....................................................................................................................... 252 TPM2_PolicyLocality .................................................................................................................. 256 TPM2_PolicyNV .......................................................................................................................... 260 TPM2_PolicyCounterTimer......................................................................................................... 265 TPM2_PolicyCommandCode ..................................................................................................... 270 TPM2_PolicyPhysicalPresence .................................................................................................. 273 TPM2_PolicyCpHash .................................................................................................................. 276 TPM2_PolicyNameHash ............................................................................................................. 280 TPM2_PolicyDuplicationSelect ................................................................................................... 283 TPM2_PolicyAuthorize ............................................................................................................... 287 TPM2_PolicyAuthValue .............................................................................................................. 291 TPM2_PolicyPassword ............................................................................................................... 294 TPM2_PolicyGetDigest ............................................................................................................... 297 TPM2_PolicyNvWritten ............................................................................................................... 300 Hierarchy Commands........................................................................................................................ 304 26.1 26.2 26.3 TPM2_CreatePrimary ................................................................................................................. 304 TPM2_HierarchyControl ............................................................................................................. 308 TPM2_SetPrimaryPolicy ............................................................................................................. 312 Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page v October 31, 2013 Part 3: Commands 26.4 26.5 26.6 26.7 26.8 27 TPM2_ReadClock ....................................................................................................................... 372 TPM2_ClockSet .......................................................................................................................... 375 TPM2_ClockRateAdjust .............................................................................................................. 378 Capability Commands ....................................................................................................................... 381 32.1 32.2 32.3 33 Introduction ................................................................................................................................. 354 TPM2_ContextSave .................................................................................................................... 354 TPM2_ContextLoad .................................................................................................................... 359 TPM2_FlushContext ................................................................................................................... 364 TPM2_EvictControl ..................................................................................................................... 367 Clocks and Timers............................................................................................................................. 372 31.1 31.2 31.3 32 Introduction ................................................................................................................................. 343 TPM2_FieldUpgradeStart ........................................................................................................... 345 TPM2_FieldUpgradeData ........................................................................................................... 348 TPM2_FirmwareRead ................................................................................................................. 351 Context Management ........................................................................................................................ 354 30.1 30.2 30.3 30.4 30.5 31 Introduction ................................................................................................................................. 337 TPM2_PP_Commands ............................................................................................................... 337 TPM2_SetAlgorithmSet .............................................................................................................. 340 Field Upgrade .................................................................................................................................... 343 29.1 29.2 29.3 29.4 30 Introduction ................................................................................................................................. 331 TPM2_DictionaryAttackLockReset ............................................................................................. 331 TPM2_DictionaryAttackParameters............................................................................................ 334 Miscellaneous Management Functions ............................................................................................. 337 28.1 28.2 28.3 29 TPM2_ChangePPS .................................................................................................................... 315 TPM2_ChangeEPS .................................................................................................................... 318 TPM2_Clear ................................................................................................................................ 321 TPM2_ClearControl .................................................................................................................... 325 TPM2_HierarchyChangeAuth ..................................................................................................... 328 Dictionary Attack Functions ............................................................................................................... 331 27.1 27.2 27.3 28 Trusted Platform Module Library Introduction ................................................................................................................................. 381 TPM2_GetCapability ................................................................................................................... 381 TPM2_TestParms ....................................................................................................................... 389 Non-volatile Storage .......................................................................................................................... 392 33.1 33.2 33.3 33.4 33.5 33.6 33.7 33.8 33.9 33.10 33.11 Introduction ................................................................................................................................. 392 NV Counters ............................................................................................................................... 393 TPM2_NV_DefineSpace ............................................................................................................. 394 TPM2_NV_UndefineSpace ......................................................................................................... 400 TPM2_NV_UndefineSpaceSpecial ............................................................................................. 403 TPM2_NV_ReadPublic ............................................................................................................... 406 TPM2_NV_Write ......................................................................................................................... 409 TPM2_NV_Increment ................................................................................................................. 413 TPM2_NV_Extend ...................................................................................................................... 417 TPM2_NV_SetBits ...................................................................................................................... 421 TPM2_NV_WriteLock ................................................................................................................. 425 Page vi October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 33.12 33.13 33.14 33.15 33.16 Part 3: Commands TPM2_NV_GlobalWriteLock ....................................................................................................... 429 TPM2_NV_Read ......................................................................................................................... 432 TPM2_NV_ReadLock ................................................................................................................. 435 TPM2_NV_ChangeAuth ............................................................................................................. 438 TPM2_NV_Certify ....................................................................................................................... 441 Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page vii October 31, 2013 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 .......................................................................................................... 21 Table 6 — TPM2_Startup Response .......................................................................................................... 21 Table 7 — TPM2_Shutdown Command ..................................................................................................... 25 Table 8 — TPM2_Shutdown Response ...................................................................................................... 25 Table 9 — TPM2_SelfTest Command ........................................................................................................ 30 Table 10 — TPM2_SelfTest Response ...................................................................................................... 30 Table 11 — TPM2_IncrementalSelfTest Command ................................................................................... 33 Table 12 — TPM2_IncrementalSelfTest Response ................................................................................... 33 Table 13 — TPM2_GetTestResult Command ............................................................................................ 36 Table 14 — TPM2_GetTestResult Response............................................................................................. 36 Table 15 — TPM2_StartAuthSession Command ....................................................................................... 40 Table 16 — TPM2_StartAuthSession Response ........................................................................................ 40 Table 17 — TPM2_PolicyRestart Command .............................................................................................. 44 Table 18 — TPM2_PolicyRestart Response .............................................................................................. 44 Table 19 — TPM2_Create Command ........................................................................................................ 48 Table 20 — TPM2_Create Response ......................................................................................................... 48 Table 21 — TPM2_Load Command ........................................................................................................... 52 Table 22 — TPM2_Load Response ............................................................................................................ 52 Table 23 — TPM2_LoadExternal Command .............................................................................................. 57 Table 24 — TPM2_LoadExternal Response .............................................................................................. 57 Table 25 — TPM2_ReadPublic Command ................................................................................................. 61 Table 26 — TPM2_ReadPublic Response ................................................................................................. 61 Table 27 — TPM2_ActivateCredential Command ...................................................................................... 64 Table 28 — TPM2_ActivateCredential Response ...................................................................................... 64 Table 29 — TPM2_MakeCredential Command .......................................................................................... 68 Table 30 — TPM2_MakeCredential Response .......................................................................................... 68 Table 31 — TPM2_Unseal Command ........................................................................................................ 71 Table 32 — TPM2_Unseal Response ........................................................................................................ 71 Table 33 — TPM2_ObjectChangeAuth Command ..................................................................................... 74 Table 34 — TPM2_ObjectChangeAuth Response ..................................................................................... 74 Table 35 — TPM2_Duplicate Command .................................................................................................... 78 Table 36 — TPM2_Duplicate Response ..................................................................................................... 78 Table 37 — TPM2_Rewrap Command ....................................................................................................... 82 Table 38 — TPM2_Rewrap Response ....................................................................................................... 82 Page viii October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands Table 39 — TPM2_Import Command ......................................................................................................... 88 Table 40 — TPM2_Import Response ......................................................................................................... 88 Table 41 — Padding Scheme Selection ..................................................................................................... 92 Table 42 — Message Size Limits Based on Padding ................................................................................. 93 Table 43 — TPM2_RSA_Encrypt Command.............................................................................................. 94 Table 44 — TPM2_RSA_Encrypt Response .............................................................................................. 94 Table 45 — TPM2_RSA_Decrypt Command ............................................................................................. 98 Table 46 — TPM2_RSA_Decrypt Response .............................................................................................. 98 Table 47 — TPM2_ECDH_KeyGen Command ........................................................................................ 102 Table 48 — TPM2_ECDH_KeyGen Response ........................................................................................ 102 Table 49 — TPM2_ECDH_ZGen Command ............................................................................................ 105 Table 50 — TPM2_ECDH_ZGen Response ............................................................................................ 105 Table 51 — TPM2_ECC_Parameters Command ..................................................................................... 107 Table 52 — TPM2_ECC_Parameters Response ..................................................................................... 107 Table 53 — TPM2_ZGen_2Phase Command .......................................................................................... 110 Table 54 — TPM2_ZGen_2Phase Response .......................................................................................... 110 Table 55 — Symmetric Chaining Process ................................................................................................ 114 Table 56 — TPM2_EncryptDecrypt Command......................................................................................... 116 Table 57 — TPM2_EncryptDecrypt Response ......................................................................................... 116 Table 58 — TPM2_Hash Command ......................................................................................................... 120 Table 59 — TPM2_Hash Response ......................................................................................................... 120 Table 60 — TPM2_HMAC Command ....................................................................................................... 123 Table 61 — TPM2_HMAC Response ....................................................................................................... 123 Table 62 — TPM2_GetRandom Command .............................................................................................. 127 Table 63 — TPM2_GetRandom Response .............................................................................................. 127 Table 64 — TPM2_StirRandom Command .............................................................................................. 130 Table 65 — TPM2_StirRandom Response ............................................................................................... 130 Table 66 — Hash Selection Matrix ........................................................................................................... 132 Table 67 — TPM2_HMAC_Start Command ............................................................................................. 133 Table 68 — TPM2_HMAC_Start Response ............................................................................................. 133 Table 69 — TPM2_HashSequenceStart Command ................................................................................. 137 Table 70 — TPM2_HashSequenceStart Response ................................................................................. 137 Table 71 — TPM2_SequenceUpdate Command ..................................................................................... 140 Table 72 — TPM2_SequenceUpdate Response ...................................................................................... 140 Table 73 — TPM2_SequenceComplete Command ................................................................................. 144 Table 74 — TPM2_SequenceComplete Response .................................................................................. 144 Table 75 — TPM2_EventSequenceComplete Command ........................................................................ 148 Table 76 — TPM2_EventSequenceComplete Response ......................................................................... 148 Table 77 — TPM2_Certify Command ....................................................................................................... 154 Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page ix October 31, 2013 Part 3: Commands Trusted Platform Module Library Table 78 — TPM2_Certify Response ....................................................................................................... 154 Table 79 — TPM2_CertifyCreation Command ......................................................................................... 158 Table 80 — TPM2_CertifyCreation Response .......................................................................................... 158 Table 81 — TPM2_Quote Command ....................................................................................................... 162 Table 82 — TPM2_Quote Response ........................................................................................................ 162 Table 83 — TPM2_GetSessionAuditDigest Command ............................................................................ 166 Table 84 — TPM2_GetSessionAuditDigest Response ............................................................................ 166 Table 85 — TPM2_GetCommandAuditDigest Command ........................................................................ 170 Table 86 — TPM2_GetCommandAuditDigest Response ......................................................................... 170 Table 87 — TPM2_GetTime Command ................................................................................................... 174 Table 88 — TPM2_GetTime Response .................................................................................................... 174 Table 89 — TPM2_Commit Command ..................................................................................................... 180 Table 90 — TPM2_Commit Response ..................................................................................................... 180 Table 91 — TPM2_EC_Ephemeral Command ......................................................................................... 185 Table 92 — TPM2_EC_Ephemeral Response ......................................................................................... 185 Table 93 — TPM2_VerifySignature Command......................................................................................... 188 Table 94 — TPM2_VerifySignature Response ......................................................................................... 188 Table 95 — TPM2_Sign Command .......................................................................................................... 192 Table 96 — TPM2_Sign Response .......................................................................................................... 192 Table 97 — TPM2_SetCommandCodeAuditStatus Command ................................................................ 197 Table 98 — TPM2_SetCommandCodeAuditStatus Response ................................................................ 197 Table 99 — TPM2_PCR_Extend Command ............................................................................................ 202 Table 100 — TPM2_PCR_Extend Response ........................................................................................... 202 Table 101 — TPM2_PCR_Event Command ............................................................................................ 205 Table 102 — TPM2_PCR_Event Response ............................................................................................. 205 Table 103 — TPM2_PCR_Read Command ............................................................................................. 208 Table 104 — TPM2_PCR_Read Response ............................................................................................. 208 Table 105 — TPM2_PCR_Allocate Command ......................................................................................... 211 Table 106 — TPM2_PCR_Allocate Response ......................................................................................... 211 Table 107 — TPM2_PCR_SetAuthPolicy Command ............................................................................... 214 Table 108 — TPM2_PCR_SetAuthPolicy Response ............................................................................... 214 Table 109 — TPM2_PCR_SetAuthValue Command ............................................................................... 217 Table 110 — TPM2_PCR_SetAuthValue Response ................................................................................ 217 Table 111 — TPM2_PCR_Reset Command ............................................................................................ 220 Table 112 — TPM2_PCR_Reset Response ............................................................................................. 220 Table 113 — TPM2_PolicySigned Command .......................................................................................... 236 Table 114 — TPM2_PolicySigned Response ........................................................................................... 236 Table 115 — TPM2_PolicySecret Command ........................................................................................... 241 Table 116 — TPM2_PolicySecret Response ............................................................................................ 241 Page x October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands Table 117 — TPM2_PolicyTicket Command ............................................................................................ 245 Table 118 — TPM2_PolicyTicket Response ............................................................................................ 245 Table 119 — TPM2_PolicyOR Command ................................................................................................ 249 Table 120 — TPM2_PolicyOR Response ................................................................................................. 249 Table 121 — TPM2_PolicyPCR Command .............................................................................................. 253 Table 122 — TPM2_PolicyPCR Response .............................................................................................. 253 Table 123 — TPM2_PolicyLocality Command ......................................................................................... 257 Table 124 — TPM2_PolicyLocality Response .......................................................................................... 257 Table 125 — TPM2_PolicyNV Command ................................................................................................. 261 Table 126 — TPM2_PolicyNV Response ................................................................................................. 261 Table 127 — TPM2_PolicyCounterTimer Command ............................................................................... 266 Table 128 — TPM2_PolicyCounterTimer Response ................................................................................ 266 Table 129 — TPM2_PolicyCommandCode Command ............................................................................ 271 Table 130 — TPM2_PolicyCommandCode Response ............................................................................. 271 Table 131 — TPM2_PolicyPhysicalPresence Command ......................................................................... 274 Table 132 — TPM2_PolicyPhysicalPresence Response ......................................................................... 274 Table 133 — TPM2_PolicyCpHash Command......................................................................................... 277 Table 134 — TPM2_PolicyCpHash Response ......................................................................................... 277 Table 135 — TPM2_PolicyNameHash Command.................................................................................... 281 Table 136 — TPM2_PolicyNameHash Response .................................................................................... 281 Table 137 — TPM2_PolicyDuplicationSelect Command .......................................................................... 284 Table 138 — TPM2_PolicyDuplicationSelect Response .......................................................................... 284 Table 139 — TPM2_PolicyAuthorize Command ...................................................................................... 288 Table 140 — TPM2_PolicyAuthorize Response ....................................................................................... 288 Table 141 — TPM2_PolicyAuthValue Command ..................................................................................... 292 Table 142 — TPM2_PolicyAuthValue Response ..................................................................................... 292 Table 143 — TPM2_PolicyPassword Command ...................................................................................... 295 Table 144 — TPM2_PolicyPassword Response ...................................................................................... 295 Table 145 — TPM2_PolicyGetDigest Command...................................................................................... 298 Table 146 — TPM2_PolicyGetDigest Response ...................................................................................... 298 Table 133 — TPM2_PolicyNvWritten Command ...................................................................................... 301 Table 134 — TPM2_PolicyNvWritten Response ...................................................................................... 301 Table 147 — TPM2_CreatePrimary Command ........................................................................................ 305 Table 148 — TPM2_CreatePrimary Response ........................................................................................ 305 Table 149 — TPM2_HierarchyControl Command .................................................................................... 309 Table 150 — TPM2_HierarchyControl Response .................................................................................... 309 Table 151 — TPM2_SetPrimaryPolicy Command .................................................................................... 313 Table 152 — TPM2_SetPrimaryPolicy Response .................................................................................... 313 Table 153 — TPM2_ChangePPS Command ........................................................................................... 316 Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page xi October 31, 2013 Part 3: Commands Trusted Platform Module Library Table 154 — TPM2_ChangePPS Response ............................................................................................ 316 Table 155 — TPM2_ChangeEPS Command ........................................................................................... 319 Table 156 — TPM2_ChangeEPS Response ............................................................................................ 319 Table 157 — TPM2_Clear Command ....................................................................................................... 322 Table 158 — TPM2_Clear Response ....................................................................................................... 322 Table 159 — TPM2_ClearControl Command ........................................................................................... 326 Table 160 — TPM2_ClearControl Response ........................................................................................... 326 Table 161 — TPM2_HierarchyChangeAuth Command ............................................................................ 329 Table 162 — TPM2_HierarchyChangeAuth Response ............................................................................ 329 Table 163 — TPM2_DictionaryAttackLockReset Command .................................................................... 332 Table 164 — TPM2_DictionaryAttackLockReset Response .................................................................... 332 Table 165 — TPM2_DictionaryAttackParameters Command .................................................................. 335 Table 166 — TPM2_DictionaryAttackParameters Response ................................................................... 335 Table 167 — TPM2_PP_Commands Command ...................................................................................... 338 Table 168 — TPM2_PP_Commands Response ...................................................................................... 338 Table 169 — TPM2_SetAlgorithmSet Command ..................................................................................... 341 Table 170 — TPM2_SetAlgorithmSet Response...................................................................................... 341 Table 171 — TPM2_FieldUpgradeStart Command .................................................................................. 346 Table 172 — TPM2_FieldUpgradeStart Response .................................................................................. 346 Table 173 — TPM2_FieldUpgradeData Command .................................................................................. 349 Table 174 — TPM2_FieldUpgradeData Response .................................................................................. 349 Table 175 — TPM2_FirmwareRead Command........................................................................................ 352 Table 176 — TPM2_FirmwareRead Response ........................................................................................ 352 Table 177 — TPM2_ContextSave Command........................................................................................... 355 Table 178 — TPM2_ContextSave Response ........................................................................................... 355 Table 179 — TPM2_ContextLoad Command ........................................................................................... 360 Table 180 — TPM2_ContextLoad Response ........................................................................................... 360 Table 181 — TPM2_FlushContext Command .......................................................................................... 365 Table 182 — TPM2_FlushContext Response .......................................................................................... 365 Table 183 — TPM2_EvictControl Command ............................................................................................ 369 Table 184 — TPM2_EvictControl Response ............................................................................................ 369 Table 185 — TPM2_ReadClock Command.............................................................................................. 373 Table 186 — TPM2_ReadClock Response .............................................................................................. 373 Table 187 — TPM2_ClockSet Command ................................................................................................. 376 Table 188 — TPM2_ClockSet Response ................................................................................................. 376 Table 189 — TPM2_ClockRateAdjust Command..................................................................................... 379 Table 190 — TPM2_ClockRateAdjust Response ..................................................................................... 379 Table 191 — TPM2_GetCapability Command.......................................................................................... 385 Table 192 — TPM2_GetCapability Response .......................................................................................... 385 Page xii October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands Table 193 — TPM2_TestParms Command .............................................................................................. 390 Table 194 — TPM2_TestParms Response .............................................................................................. 390 Table 195 — TPM2_NV_DefineSpace Command ................................................................................... 396 Table 196 — TPM2_NV_DefineSpace Response .................................................................................... 396 Table 197 — TPM2_NV_UndefineSpace Command ............................................................................... 401 Table 198 — TPM2_NV_UndefineSpace Response ................................................................................ 401 Table 199 — TPM2_NV_UndefineSpaceSpecial Command .................................................................... 404 Table 200 — TPM2_NV_UndefineSpaceSpecial Response .................................................................... 404 Table 201 — TPM2_NV_ReadPublic Command ...................................................................................... 407 Table 202 — TPM2_NV_ReadPublic Response ...................................................................................... 407 Table 203 — TPM2_NV_Write Command ................................................................................................ 410 Table 204 — TPM2_NV_Write Response ................................................................................................ 410 Table 205 — TPM2_NV_Increment Command ........................................................................................ 414 Table 206 — TPM2_NV_Increment Response......................................................................................... 414 Table 207 — TPM2_NV_Extend Command ............................................................................................. 418 Table 208 — TPM2_NV_Extend Response ............................................................................................. 418 Table 209 — TPM2_NV_SetBits Command ............................................................................................. 422 Table 210 — TPM2_NV_SetBits Response ............................................................................................. 422 Table 211 — TPM2_NV_WriteLock Command ........................................................................................ 426 Table 212 — TPM2_NV_WriteLock Response......................................................................................... 426 Table 213 — TPM2_NV_GlobalWriteLock Command .............................................................................. 430 Table 214 — TPM2_NV_GlobalWriteLock Response .............................................................................. 430 Table 215 — TPM2_NV_Read Command................................................................................................ 433 Table 216 — TPM2_NV_Read Response ................................................................................................ 433 Table 217 — TPM2_NV_ReadLock Command ........................................................................................ 436 Table 218 — TPM2_NV_ReadLock Response ........................................................................................ 436 Table 219 — TPM2_NV_ChangeAuth Command .................................................................................... 439 Table 220 — TPM2_NV_ChangeAuth Response .................................................................................... 439 Table 221 — TPM2_NV_Certify Command .............................................................................................. 442 Table 222 — TPM2_NV_Certify Response .............................................................................................. 442 Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page xiii October 31, 2013 Trusted Platform Module Library Part 3: Commands Trusted Platform Module Library Part 3: Commands 1 Scope This part 3 of the Trusted Module Library specification contains the definitions of the TPM commands. These commands make use of the constants, flags, structure, and union definitions defined in part 2: Structures. 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 part 3 is normative but does not fully describe the behavior of a TPM. The combination of this part 3 and part 4: Supporting Routines 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 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 part 1 of this specification apply. 3 Symbols and abbreviated terms For the purposes of this document, the symbols and abbreviated terms given in part 1 apply. 4 Notation 4.1 Introduction In addition to the notation in this clause, the “Notations” clause in Part 1 of this specification is applicable to this Part 3. Command and response tables used 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” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 1 October 31, 2013 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 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 {E} {NV F} EXAMPLE 2 TPM2_SequenceComplete() will flush the context associated with the sequenceHandle. 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 Auth Index: {NV E} EXAMPLE 2 TPM2_Clear() will flush all contexts associated with the Storage hierarchy and the Endorsement hierarchy. 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 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 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 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 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(). 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 Part 2, "TPMA_NV (NV Index Attributes)." 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 the command tag is TPM_ST_NO_SESSIONS, no authorizations are present and no authorizationSize field is required and shall not be present. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 3 October 31, 2013 Part 3: Commands 5 Trusted Platform Module Library Normative References The “Normative References” clause in Part 1 of this specification is applicable to this Part 3. 6 Symbols and Abbreviated Terms The “Symbols and Abbreviated Terms” clause in Part 1 of this specification is applicable to this Part 3. 7 7.1 Command Processing 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. 7.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 directly from that memory. c) The TPM shall successfully unmarshal a TPM_CC and verify that the command is implemented (TPM_RC_COMMAND_CODE). 7.3 Mode Checks The following mode checks shall be performed in the order listed: Page 4 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 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 proc essing 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. The mode checks may be performed before or after the command header validation. 7.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. 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 1 The TPM may unmarshal a handle and validate that it references an entity on the TPM before unmarshaling a subsequent handle. NOTE 2 If the submitted command contains fewer handles than required 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 flushe d so this check will fail. 2) If the handle references a persistent object, then i) the handle shall reference a persistent object that is currently in TPM non-volatile memory (TPM_RC_HANDLE); ii) the hierarchy associated with the object is not disabled (TPM_RC_HIERARCHY); and iii) if the TPM implementation moves a persistent object to RAM for command processing then sufficient RAM space is available (TPM_RC_OBJECT_MEMORY). Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 5 October 31, 2013 Part 3: Commands Trusted Platform Module Library 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) the hierarchy associated (TPM_RC_HIERARCHY) with an NV index being defined is not disabled 4) If the handle references a session, then the session context shall be present in TPM memory (TPM_RC_REFERENCE_S0 + N). 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 4 7.5 In the reference implementation, this TPM_RC_VALUE is returned by the unmarshaling code for a TPMI_DH_PCR. Session Area Validation a) If the tag is TPM_ST_SESSIONS and the command is a context management command (TPM2_ContextSave(), TPM2_ContextLoad(), or TPM2_FlushContext()) the TPM will return TPM_RC_AUTH_CONTEXT. b) 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. c) 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. Page 6 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 4) The consistency of the authorization session attributes is checked. i) An authorization session is present for each of the handles with the “@” decoration (TPM_RC_AUTH_MISSING). ii) 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. NOTE 3 7.6 A session used for decrypting a command parameter may also be used for encrypting a response parameter. 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 (TPM_RC_AUTH_UNAVAILABLE). of the object shall be present on the TPM 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 TPM2_PolicyAuthValue() or TPM2_PolicyPassword(). session when the policy contains 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, 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 required use of ADMIN role authorization are commands that operate on objects and NV Indices. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 7 October 31, 2013 Part 3: Commands f) Trusted Platform Module Library 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). 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); (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 (TPM_RC_EXPIRED); has been set, the session shall not have 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 (TPM_RC_POLICY_FAIL); shall match the authPolicy associated with the handle 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 7) 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 5 For a bound session, if the handle references the object us ed to initiate the session, then the authValue will not be required but proof of knowledge of the session secret is necessary. NOTE 6 A policy session may require proof of knowledge of the authValue of the object being authorized. 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 7.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. 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. Page 8 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands Otherwise, the TPM will decrypt the parameter using the values associated with the session before parsing parameters. 7.8 7.8.1 Parameter Unmarshaling 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. 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 Part 2 of this specification. 7.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” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 9 October 31, 2013 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 Part 2 definition of the parameter type even if that parameter is not used in the command actions. 7.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. Page 10 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands NOTE 1 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 2 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” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 11 October 31, 2013 Part 3: Commands 8 8.1 Trusted Platform Module Library Response Values 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. 8.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 value 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 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands Table 4 — Command-Independent Response Codes Response Code Meaning TPM_RC_CANCELLED 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 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. TPM_RC_CONTEXT_GAP This response code can be returned for commands that manage session contexts. It indicates that the gap between the lowest numbered active session 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. TPM_RC_LOCKOUT This response indicates that authorizations for objects subject to DA protection are not allowed at this time because the TPM is in DA lockout mode. The remedy is to wait or to exeucte TPM2_DictionaryAttackLockoutReset(). TPM_RC_MEMORY 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 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. TPM_RC_NV_RATE 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 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. TPM_RC_NV_UNAVAILABLE 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 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. TPM_RC_OBJECT_HANDLES 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 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. TPM_RC_OBJECT_MEMORY 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 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. TPM_RC_REFERENCE_Hx 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 . The TPM resource manager needs to find the correct object and load it. It may then adjust the handle and retry the command. NOTE Family “2.0” Level 00 Revision 00.99 Usually, this error indicates that the TPM resource manager has a corrupted database. Published Copyright © TCG 2006-2013 Page 13 October 31, 2013 Part 3: Commands Trusted Platform Module Library Response Code Meaning TPM_RC_REFERENCE_Sx 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 . 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(). TPM_RC_SESSION_MEMORY 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()). 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. TPM_RC_SUCCESS Normal completion for any command. If the responseCode is TPM_RC_SESSIONS, then the rest of the response has the format indicated in the response schematic. Otherwise, the response is a 10 octet value indicating an error. TPM_RC_TESTING This response code indicates that the TPM is performing tests and cannot respond to the request at this time. The command may be retried. TPM_RC_YIELDED the TPM has suspended operation on the command; forward progress was made and the command may be retried. See Part 1, “Multi-tasking.” NOTE Page 14 October 31, 2013 This cannot occur on the reference implementation. Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 9 Part 3: Commands 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” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 15 October 31, 2013 Part 3: Commands Trusted Platform Module Library Detailed Actions Assumptions 10 10.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. 10.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 commands. If the response has handles or parameters, the calling stack contains a pointer to a data structure ( out) to hold the handles and 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 Part 2.  Space set aside for the out structure is sufficient to hold the largest out structure that could be produced by the command 10.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 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 11 Part 3: Commands Start-up 11.1 Introduction This clause contains the commands used to manage the startup and restart state of a TPM. 11.2 _TPM_Init 11.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” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 17 October 31, 2013 Part 3: Commands Trusted Platform Module Library 11.2.2 Detailed Actions 1 #include "InternalRoutines.h" This function is used to process a _TPM_Init() indication. 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 void _TPM_Init(void) { // Initialize crypto engine CryptInitUnits(); // Initialize NV environment NvPowerOn(); // Start clock TimePowerOn(); // Set initialization state TPMInit(); // Set g_DRTMHandle as unassigned g_DRTMHandle = TPM_RH_UNASSIGNED; // No H-CRTM, yet. g_DrtmPreStartup = FALSE; return; } Page 18 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 11.3 Part 3: Commands TPM2_Startup 11.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 11.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 these 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 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 default 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” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 19 October 31, 2013 Part 3: Commands Trusted Platform Module Library  platformAuth and platformPolicy shall be set to the Empty Buffer,  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 platformspecific specification. 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 Part 1 of this specification 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, and  PCR in all banks are reset to their default initial conditions.  If a 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 platformspecific specification. 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. NOTE 6 The TPM will require Shutdown(CLEAR). NOTE 7 If startupType is neither TPM_SU_STATE nor TPM_SU_CLEAR, then the unmarshaling code returns TPM_RC_VALUE. Page 20 October 31, 2013 TPM_SU_CLEAR when no Published Copyright © TCG 2006-2013 shutdown was performed or after Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 11.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 8 UINT32 responseSize TPM_RC responseCode Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 21 October 31, 2013 Part 3: Commands Trusted Platform Module Library 11.3.3 Detailed Actions 1 2 #include "InternalRoutines.h" #include "Startup_fp.h" Error Returns TPM_RC_VALUE 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 Meaning start up type is not compatible with previous shutdown sequence TPM_RC TPM2_Startup( Startup_In *in // IN: input parameter list ) { STARTUP_TYPE TPM_RC BOOL startup; result; prevDrtmPreStartup; // The command needs NV update. Check if NV is available. // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at // this point result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; // Input Validation // Read orderly shutdown states from previous power cycle NvReadReserved(NV_ORDERLY, &g_prevOrderlyState); // HACK to extract the DRTM startup type associated with the previous shutdown prevDrtmPreStartup = (g_prevOrderlyState == (TPM_SU_STATE + 0x8000)); if(prevDrtmPreStartup) g_prevOrderlyState = TPM_SU_STATE; // if the previous power cycle was shut down with no StateSave command, or // with StateSave command for CLEAR, this cycle can not startup up with // STATE if( ( g_prevOrderlyState == SHUTDOWN_NONE || g_prevOrderlyState == TPM_SU_CLEAR ) && in->startupType == TPM_SU_STATE ) return TPM_RC_VALUE + RC_Startup_startupType; // Internal Date Update // Translate the TPM2_ShutDown and TPM2_Startup sequence into the startup // types. if(in->startupType == TPM_SU_CLEAR && g_prevOrderlyState == TPM_SU_STATE) { startup = SU_RESTART; // Read state reset data NvReadReserved(NV_STATE_RESET, &gr); } else if(in->startupType == TPM_SU_STATE && g_prevOrderlyState == TPM_SU_STATE) { // For a resume, the H-CRTM startup method must be the same if(g_DrtmPreStartup != prevDrtmPreStartup) return TPM_RC_LOCALITY; Page 22 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 Part 3: Commands // Read state clear and state reset data NvReadReserved(NV_STATE_CLEAR, &gc); NvReadReserved(NV_STATE_RESET, &gr); startup = SU_RESUME; } else { startup = SU_RESET; } // Read persistent data from NV NvReadPersistent(); // Crypto Startup CryptUtilStartup(startup); // Start up subsystems // Start counters and timers TimeStartup(startup); // Start dictionary attack subsystem DAStartup(startup); // Enable hierarchies HierarchyStartup(startup); // Restore/Initialize PCR PCRStartup(startup); // Restore/Initialize command audit information CommandAuditStartup(startup); // Object context variables if(startup == SU_RESET) { // Reset object context ID to 0 gr.objectContextID = 0; // Reset clearCount to 0 gr.clearCount= 0; } // Initialize object table ObjectStartup(); // Initialize session table SessionStartup(startup); // Initialize index/evict data. // in NV index NvEntityStartup(startup); This function clear read/write locks // Initialize the orderly shut down flag for this cycle to SHUTDOWN_NONE. gp.orderlyState = SHUTDOWN_NONE; NvWriteReserved(NV_ORDERLY, &gp.orderlyState); // Update TPM internal states if command succeeded. // Record a TPM2_Startup command has been received. TPMRegisterStartup(); return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 23 October 31, 2013 Part 3: Commands 11.4 Trusted Platform Module Library TPM2_Shutdown 11.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 24 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 11.4.2 Command and Response Table 7 — TPM2_Shutdown Command Type Name Description TPMI_ST_COMMAND_TAG tag 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 8 UINT32 responseSize TPM_RC responseCode Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 25 October 31, 2013 Part 3: Commands Trusted Platform Module Library 11.4.3 Detailed Actions 1 2 #include "InternalRoutines.h" #include "Shutdown_fp.h" Error Returns TPM_RC_TYPE 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 Meaning if PCR bank has been re-configured, a CLEAR StateSave() is required TPM_RC TPM2_Shutdown( Shutdown_In *in // IN: input parameter list ) { TPM_RC result; // The command needs NV update. Check if NV is available. // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at // this point result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; // Input Validation // If PCR bank has been reconfigured, a CLEAR state save is required if(g_pcrReConfig && in->shutdownType == TPM_SU_STATE) return TPM_RC_TYPE + RC_Shutdown_shutdownType; // Internal Data Update // PCR private date state save PCRStateSave(in->shutdownType); // Get DRBG state CryptDrbgGetPutState(GET_STATE); // Save all orderly data NvWriteReserved(NV_ORDERLY_DATA, &go); // Save RAM backed NV index data NvStateSave(); if(in->shutdownType == TPM_SU_STATE) { // Save STATE_RESET and STATE_CLEAR data NvWriteReserved(NV_STATE_CLEAR, &gc); NvWriteReserved(NV_STATE_RESET, &gr); } else if(in->shutdownType == TPM_SU_CLEAR) { // Save STATE_RESET data NvWriteReserved(NV_STATE_RESET, &gr); } // Write orderly shut down state if(in->shutdownType == TPM_SU_CLEAR) gp.orderlyState = TPM_SU_CLEAR; else if(in->shutdownType == TPM_SU_STATE) gp.orderlyState = TPM_SU_STATE; else Page 26 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 54 55 56 57 58 59 Part 3: Commands pAssert(FALSE); NvWriteReserved(NV_ORDERLY, &gp.orderlyState); return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 27 October 31, 2013 Part 3: Commands 12 12.1 Trusted Platform Module Library Testing 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 tha t 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 28 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 12.2 Part 3: Commands TPM2_SelfTest 12.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 the “background” processing is complete. This would be in addition to the interrupt 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” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 29 October 31, 2013 Part 3: Commands Trusted Platform Module Library 12.2.2 Command and Response Table 9 — TPM2_SelfTest Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_SelfTest {NV} TPMI_YES_NO fullTest YES if full test to be performed NO if only test of untested functions required Table 10 — TPM2_SelfTest Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode Page 30 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 12.2.3 Detailed Actions 1 2 #include "InternalRoutines.h" #include "SelfTest_fp.h" Error Returns TPM_RC_TESTING 3 4 5 6 7 8 9 10 11 12 Meaning self test in process TPM_RC TPM2_SelfTest( SelfTest_In ) { // Command Output *in // IN: input parameter list // Call self test function in crypt module return CryptSelfTest(in->fullTest); } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 31 October 31, 2013 Part 3: Commands 12.3 Trusted Platform Module Library TPM2_IncrementalSelfTest 12.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. 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. 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 3 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 4 If none of the algorithms listed in toTest is in the toDoList, then no tests will be performed. If all the parameters in this command are valid, the TPM returns TPM_RC_SUCCESS and the toDoList (which may be empty). NOTE 5 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 32 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 12.3.2 Command and Response Table 11 — TPM2_IncrementalSelfTest Command Type Name Description TPMI_ST_COMMAND_TAG tag 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 8 UINT32 responseSize TPM_RC responseCode TPML_ALG toDoList Family “2.0” Level 00 Revision 00.99 list of algorithms that need testing Published Copyright © TCG 2006-2013 Page 33 October 31, 2013 Part 3: Commands Trusted Platform Module Library 12.3.3 Detailed Actions 1 2 3 4 5 6 7 8 9 10 11 12 13 #include "InternalRoutines.h" #include "IncrementalSelfTest_fp.h" TPM_RC TPM2_IncrementalSelfTest( IncrementalSelfTest_In IncrementalSelfTest_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { // Command Output // Call incremental self test function in crypt module return CryptIncrementalSelfTest(&in->toTest, &out->toDoList); } Page 34 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 12.4 Part 3: Commands TPM2_GetTestResult 12.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. If the TPM is in Failure mode because of an invalid startupType in TPM2_Startup(), testResult will be TPM_RC_INITIALIZE. 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” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 35 October 31, 2013 Part 3: Commands Trusted Platform Module Library 12.4.2 Command and Response Table 13 — TPM2_GetTestResult Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_GetTestResult Table 14 — TPM2_GetTestResult Response Type Name Description TPMI_ST_COMMAND_TAG tag see clause 8 UINT32 responseSize TPM_RC responseCode TPM2B_MAX_BUFFER outData TPM_RC testResult Page 36 October 31, 2013 test result data contains manufacturer-specific information Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 12.4.3 Detailed Actions 1 2 3 4 5 6 7 8 9 10 11 12 13 14 #include "InternalRoutines.h" #include "GetTestResult_fp.h" TPM_RC TPM2_GetTestResult( GetTestResult_Out ) { // Command Output *out // OUT: output parameter list // Call incremental self test function in crypt module out->testResult = CryptGetTestResult(&out->outData); return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 37 October 31, 2013 Part 3: Commands Trusted Platform Module Library Session Commands 13 13.1 TPM2_StartAuthSession 13.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 Part 1 of this specification) 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 o f 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 the 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 TPM_RC_SESSION_HANDLES. a free slot for an authorization session, it shall return 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 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_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 encode OAEP value, or 4) the decrypted salt value is larger than the size of the digest produced by the nameAlg of tpmKey; or Page 38 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 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. 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 comm and in order to reestablish the orderly state of the TPM. This is because the created context 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” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 39 October 31, 2013 Part 3: Commands Trusted Platform Module Library 13.1.2 Command and Response Table 15 — TPM2_StartAuthSession Command Type Name TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_StartAuthSession TPMI_DH_OBJECT+ tpmKey handle of a loaded decrypt key used to encrypt salt may be TPM_RH_NULL Auth Index: None TPMI_DH_ENTITY+ bind entity providing the authValue may be TPM_RH_NULL Auth Index: None TPM2B_NONCE nonceCaller Description initial nonceCaller, sets nonce size for the session shall be at least 16 octets TPM2B_ENCRYPTED_SECRET encryptedSalt value encrypted according to the type of tpmKey If tpmKey is TPM_RH_NULL, this shall be the Empty Buffer. TPM_SE sessionType indicates the type of the session; simple HMAC or policy (including a trial policy) TPMT_SYM_DEF+ symmetric the algorithm and key size for parameter encryption may select TPM_ALG_NULL TPMI_ALG_HASH authHash hash algorithm to use for the session 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 8 UINT32 responseSize TPM_RC responseCode TPMI_SH_AUTH_SESSION sessionHandle handle for the newly created session TPM2B_NONCE nonceTPM the initial nonce from the TPM, used in the computation of the sessionKey Page 40 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 13.1.3 Detailed Actions 1 2 #include "InternalRoutines.h" #include "StartAuthSession_fp.h" Error Returns 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 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 Meaning secret size does not match decrypt key type; or the recovered secret is larget 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. TPM_RC TPM2_StartAuthSession( StartAuthSession_In StartAuthSession_Out *in, *out // IN: input parameter buffer // OUT: output parameter buffer TPM_RC OBJECT SESSION TPM2B_DATA result = TPM_RC_SUCCESS; *tpmKey; // TPM key for decrypt salt *session; // session internal data salt; ) { // Input Validation // Check input nonce size. IT should be at least 16 bytes but not larger // than the digest size of session hash. if( in->nonceCaller.t.size < 16 || in->nonceCaller.t.size > CryptGetHashDigestSize(in->authHash)) return TPM_RC_SIZE + RC_StartAuthSession_nonceCaller; // If an decrypt key is passed in, check its validation if(in->tpmKey != TPM_RH_NULL) { // secret size cannot be 0 if(in->encryptedSalt.t.size == 0) return TPM_RC_VALUE + RC_StartAuthSession_encryptedSalt; // Get pointer to loaded decrypt key tpmKey = ObjectGet(in->tpmKey); // Decrypting salt requires accessing the private portion of a key. // Therefore, tmpKey can not be a key with only public portion loaded if(tpmKey->attributes.publicOnly) return TPM_RC_HANDLE + RC_StartAuthSession_tpmKey; Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 41 October 31, 2013 Part 3: Commands 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 Trusted Platform Module Library // HMAC session input handle check. // tpmKey should be a decryption key if(tpmKey->publicArea.objectAttributes.decrypt != SET) return TPM_RC_ATTRIBUTES + RC_StartAuthSession_tpmKey; // Secret Decryption. A TPM_RC_VALUE, TPM_RC_KEY or Unmarshal errors // may be returned at this point result = CryptSecretDecrypt(in->tpmKey, &in->nonceCaller, "SECRET", &in->encryptedSalt, &salt); if(result != TPM_RC_SUCCESS) return TPM_RC_VALUE + RC_StartAuthSession_encryptedSalt; } else { // secret size must be 0 if(in->encryptedSalt.t.size != 0) return TPM_RC_VALUE + RC_StartAuthSession_encryptedSalt; salt.t.size = 0; } // If 'symmetric' is a symmetric block cipher (not TPM_ALG_NULL or TPM_ALG_XOR) // then the mode must be CFB. if( in->symmetric.algorithm != TPM_ALG_NULL && in->symmetric.algorithm != TPM_ALG_XOR && in->symmetric.mode.sym != TPM_ALG_CFB) return TPM_RC_MODE + RC_StartAuthSession_symmetric; // Internal Data Update // Create internal session structure. TPM_RC_CONTEXT_GAP, TPM_RC_NO_HANDLES // or TPM_RC_SESSION_MEMORY errors may be returned returned at this point. // // The detailed actions for creating the session context are not shown here // as the details are implementation dependent // SessionCreate sets the output handle result = SessionCreate(in->sessionType, in->authHash, &in->nonceCaller, &in->symmetric, in->bind, &salt, &out->sessionHandle); if(result != TPM_RC_SUCCESS) return result; // Command Output // Get session pointer session = SessionGet(out->sessionHandle); // Copy nonceTPM out->nonceTPM = session->nonceTPM; return TPM_RC_SUCCESS; } Page 42 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 13.2 Part 3: Commands TPM2_PolicyRestart 13.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” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 43 October 31, 2013 Part 3: Commands Trusted Platform Module Library 13.2.2 Command and Response Table 17 — TPM2_PolicyRestart Command Type Name Description TPMI_ST_COMMAND_TAG tag 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 8 UINT32 responseSize TPM_RC responseCode Page 44 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 13.2.3 Detailed Actions 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 #include "InternalRoutines.h" #include "PolicyRestart_fp.h" TPM_RC TPM2_PolicyRestart( PolicyRestart_In *in // IN: input parameter list SESSION BOOL *session; wasTrialSession; ) { // Internal Data Update session = SessionGet(in->sessionHandle); wasTrialSession = session->attributes.isTrialPolicy == SET; // Initialize policy session SessionResetPolicyData(session); session->attributes.isTrialPolicy = wasTrialSession; return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 45 October 31, 2013 Part 3: Commands Trusted Platform Module Library Object Commands 14 14.1 TPM2_Create 14.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 Part 1 and “TPMA_OBJECT” in 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.authValue), 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 Part 2. The sensitive 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 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.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.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.buffer 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 sensitive.data is not the Empty Buffer, then the TPM shall return TPM_RC_VALUE. Page 46 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 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.symKey value is created; otherwise, TPMT_SENSITIVE.symKey.size is set to zero. 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 1 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.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.data is not an Empty Buffer, the TPM will copy the inSensitive.data to TPMT_SENSITIVE.sensitive of the new object. NOTE 2 The size of inSensitive.data is limited to be no larger TPMT_SENSITIVE.sensitive.bits.data by MAX_SYM_DATA. than the largest value of 3) If inSensitive.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.any.buffer. 4) A TPM-generated obfuscation value that is the size of the digest produced by the nameAlg of inPublic is placed in TPMT_SENSITIVE.symKey.buffer. 5) The TPMT_PUBLIC.unique.sym.buffer 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 3 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 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. 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. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 47 October 31, 2013 Part 3: Commands Trusted Platform Module Library 14.1.2 Command and Response Table 19 — TPM2_Create Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_Create TPMI_DH_OBJECT @parentHandle handle of parent for new object Auth Index: 1 Auth Role: USER TPM2B_SENSITIVE_CREATE inSensitive the sensitive data TPM2B_PUBLIC inPublic the public template TPM2B_DATA outsideInfo data that will be included in the creation data for this 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 8 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 TPMT_TK_CREATION creationTicket ticket used by TPM2_CertifyCreation() to validate that the creation data was produced by the TPM Page 48 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 14.1.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "Object_spt_fp.h" #include "Create_fp.h" Error Returns TPM_RC_ASYMMETRIC non-duplicable storage key and its parent have different public params 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 FOr() an RSA key, the exponent value 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 4 5 6 7 8 9 10 11 12 13 Meaning there is no free slot for the object. This implementation does not return this error. TPM_RC TPM2_Create( Create_In Create_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { TPM_RC TPMT_SENSITIVE TPM2B_NAME Family “2.0” Level 00 Revision 00.99 result = TPM_RC_SUCCESS; sensitive; name; Published Copyright © TCG 2006-2013 Page 49 October 31, 2013 Part 3: Commands 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 Trusted Platform Module Library // Input Validation OBJECT *parentObject; parentObject = ObjectGet(in->parentHandle); // Does parent have the proper attributes? if(!AreAttributesForParent(parentObject)) return TPM_RC_TYPE + RC_Create_parentHandle; // The sensitiveDataOrigin attribute must be consistent with the setting of // the size of the data object in inSensitive. if( (in->inPublic.t.publicArea.objectAttributes.sensitiveDataOrigin == SET) != (in->inSensitive.t.sensitive.data.t.size == 0)) // Mismatch between the object attributes and the parameter. return TPM_RC_ATTRIBUTES + RC_Create_inSensitive; // Check attributes in input public area. TPM_RC_ASYMMETRIC, TPM_RC_ATTRIBUTES, // TPM_RC_HASH, TPM_RC_KDF, TPM_RC_SCHEME, TPM_RC_SIZE, TPM_RC_SYMMETRIC, // or TPM_RC_TYPE error may be returned at this point. result = PublicAttributesValidation(FALSE, in->parentHandle, &in->inPublic.t.publicArea); if(result != TPM_RC_SUCCESS) return RcSafeAddToResult(result, RC_Create_inPublic); // Validate the sensitive area values if( MemoryRemoveTrailingZeros(&in->inSensitive.t.sensitive.userAuth) > CryptGetHashDigestSize(in->inPublic.t.publicArea.nameAlg)) return TPM_RC_SIZE + RC_Create_inSensitive; // Command Output // Create object crypto data result = CryptCreateObject(in->parentHandle, &in->inPublic.t.publicArea, &in->inSensitive.t.sensitive, &sensitive); if(result != TPM_RC_SUCCESS) return result; // Fill in creation data FillInCreationData(in->parentHandle, in->inPublic.t.publicArea.nameAlg, &in->creationPCR, &in->outsideInfo, &out->creationData, &out->creationHash); // Copy public area from input to output out->outPublic.t.publicArea = in->inPublic.t.publicArea; // Compute name from public area ObjectComputeName(&(out->outPublic.t.publicArea), &name); // Compute creation ticket TicketComputeCreation(EntityGetHierarchy(in->parentHandle), &name, &out->creationHash, &out->creationTicket); // Prepare output private data from sensitive SensitiveToPrivate(&sensitive, &name, in->parentHandle, out->outPublic.t.publicArea.nameAlg, &out->outPrivate); return TPM_RC_SUCCESS; } Page 50 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 14.2 Part 3: Commands TPM2_Load 14.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 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 o n 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) or 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 private 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. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 51 October 31, 2013 Part 3: Commands Trusted Platform Module Library 14.2.2 Command and Response Table 21 — TPM2_Load Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_Load TPMI_DH_OBJECT @parentHandle TPM handle of parent key; shall not be a reserved handle 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 8 UINT32 responseSize TPM_RC responseCode TPM_HANDLE objectHandle handle for the loaded object TPM2B_NAME name Name of the loaded object Page 52 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 14.2.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "Load_fp.h" #include "Object_spt_fp.h" Error Returns 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 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 Meaning decryption failure TPM_RC TPM2_Load( Load_In *in, Load_Out *out // IN: input parameter list // OUT: output parameter list ) { TPM_RC TPMT_SENSITIVE TPMI_RH_HIERARCHY OBJECT BOOL result = TPM_RC_SUCCESS; sensitive; hierarchy; *parentObject = NULL; skipChecks = FALSE; // Input Validation if(in->inPrivate.t.size == 0) return TPM_RC_SIZE + RC_Load_inPrivate; parentObject = ObjectGet(in->parentHandle); // Is the object that is being used as the parent actually a parent. if(!AreAttributesForParent(parentObject)) return TPM_RC_TYPE + RC_Load_parentHandle; // If the parent is fixedTPM, then the attributes of the object // are either "correct by construction" or were validated // when the object was imported. If they pass the integrity // check, then the values are valid if(parentObject->publicArea.objectAttributes.fixedTPM) skipChecks = TRUE; Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 53 October 31, 2013 Part 3: Commands 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 Trusted Platform Module Library else { // If parent doesn't have fixedTPM SET, then this can't have // fixedTPM SET. if(in->inPublic.t.publicArea.objectAttributes.fixedTPM == SET) return TPM_RC_ATTRIBUTES + RC_Load_inPublic; // Perform self check on input public area. A TPM_RC_SIZE, TPM_RC_SCHEME, // TPM_RC_VALUE, TPM_RC_SYMMETRIC, TPM_RC_TYPE, TPM_RC_HASH, // TPM_RC_ASYMMETRIC, TPM_RC_ATTRIBUTES or TPM_RC_KDF error may be returned // at this point result = PublicAttributesValidation(TRUE, in->parentHandle, &in->inPublic.t.publicArea); if(result != TPM_RC_SUCCESS) return RcSafeAddToResult(result, RC_Load_inPublic); } // Compute the name of object ObjectComputeName(&in->inPublic.t.publicArea, &out->name); // Retrieve sensitive data. PrivateToSensitive() may return TPM_RC_INTEGRITY or // TPM_RC_SENSITIVE // errors may be returned at this point result = PrivateToSensitive(&in->inPrivate, &out->name, in->parentHandle, in->inPublic.t.publicArea.nameAlg, &sensitive); if(result != TPM_RC_SUCCESS) return RcSafeAddToResult(result, RC_Load_inPrivate); // Internal Data Update // Get hierarchy of parent hierarchy = ObjectGetHierarchy(in->parentHandle); // Create internal object. A lot of different errors may be returned by this // loading operation as it will do several validations, including the public // binding check result = ObjectLoad(hierarchy, &in->inPublic.t.publicArea, &sensitive, &out->name, in->parentHandle, skipChecks, &out->objectHandle); if(result != TPM_RC_SUCCESS) return result; return TPM_RC_SUCCESS; } Page 54 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 14.3 Part 3: Commands TPM2_LoadExternal 14.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 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. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 55 October 31, 2013 Part 3: Commands Trusted Platform Module Library 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. Page 56 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 14.3.2 Command and Response Table 23 — TPM2_LoadExternal Command Type Name Description TPMI_ST_COMMAND_TAG tag 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 8 UINT32 responseSize TPM_RC responseCode TPM_HANDLE objectHandle handle for the loaded object TPM2B_NAME name name of the loaded object Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 57 October 31, 2013 Part 3: Commands Trusted Platform Module Library 14.3.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "LoadExternal_fp.h" #include "Object_spt_fp.h" Error Returns 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 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 Meaning inPublic and inPrivate are not the same type TPM_RC TPM2_LoadExternal( LoadExternal_In LoadExternal_Out *in, *out // IN: input parameter list // OUT: output parameter list TPM_RC TPMT_SENSITIVE BOOL result; *sensitive; skipChecks; ) { // Input Validation // If the target hierarchy is turned off, the object can not be loaded. if(!HierarchyIsEnabled(in->hierarchy)) return TPM_RC_HIERARCHY + RC_LoadExternal_hierarchy; // the size of authPolicy is either 0 or the digest size of nameAlg if(in->inPublic.t.publicArea.authPolicy.t.size != 0 && in->inPublic.t.publicArea.authPolicy.t.size != CryptGetHashDigestSize(in->inPublic.t.publicArea.nameAlg)) return TPM_RC_SIZE + RC_LoadExternal_inPublic; // For loading an object with both public and sensitive if(in->inPrivate.t.size != 0) { // An external object can only be loaded at TPM_RH_NULL hierarchy if(in->hierarchy != TPM_RH_NULL) return TPM_RC_HIERARCHY + RC_LoadExternal_hierarchy; // An external object with a sensitive area must have fixedTPM == CLEAR // fixedParent == CLEAR, and must have restrict CLEAR so that it does not Page 58 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 Part 3: Commands // appear to be a key that was created by this TPM. if( in->inPublic.t.publicArea.objectAttributes.fixedTPM != CLEAR || in->inPublic.t.publicArea.objectAttributes.fixedParent != CLEAR || in->inPublic.t.publicArea.objectAttributes.restricted != CLEAR ) return TPM_RC_ATTRIBUTES + RC_LoadExternal_inPublic; } // Validate the scheme parameters result = SchemeChecks(TRUE, TPM_RH_NULL, &in->inPublic.t.publicArea); if(result != TPM_RC_SUCCESS) return RcSafeAddToResult(result, RC_LoadExternal_inPublic); // Internal Data Update // Need the name to compute the qualified name ObjectComputeName(&in->inPublic.t.publicArea, &out->name); skipChecks = (in->inPublic.t.publicArea.nameAlg == TPM_ALG_NULL); // If a sensitive area was provided, load it if(in->inPrivate.t.size != 0) sensitive = &in->inPrivate.t.sensitiveArea; else sensitive = NULL; // Create external object. A TPM_RC_BINDING, TPM_RC_KEY, TPM_RC_OBJECT_MEMORY // or TPM_RC_TYPE error may be returned by ObjectLoad() result = ObjectLoad(in->hierarchy, &in->inPublic.t.publicArea, sensitive, &out->name, TPM_RH_NULL, skipChecks, &out->objectHandle); return result; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 59 October 31, 2013 Part 3: Commands 14.4 Trusted Platform Module Library TPM2_ReadPublic 14.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. Page 60 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 14.4.2 Command and Response Table 25 — TPM2_ReadPublic Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_ReadPublic TPMI_DH_OBJECT objectHandle TPM handle of an object Auth Index: None Table 26 — TPM2_ReadPublic Response Type Name Description TPM_ST tag see clause 8 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 Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 61 October 31, 2013 Part 3: Commands Trusted Platform Module Library 14.4.3 Detailed Actions 1 2 #include "InternalRoutines.h" #include "ReadPublic_fp.h" Error Returns TPM_RC_SEQUENCE 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 Meaning can not read the public area of a sequence object TPM_RC TPM2_ReadPublic( ReadPublic_In ReadPublic_Out *in, *out // IN: input parameter list // OUT: output parameter list OBJECT *object; ) { // Input Validation // Get loaded object pointer object = ObjectGet(in->objectHandle); // Can not read public area of a sequence object if(ObjectIsSequence(object)) return TPM_RC_SEQUENCE; // Command Output // Compute size of public area in canonical form out->outPublic.t.size = TPMT_PUBLIC_Marshal(&object->publicArea, NULL, NULL); // Copy public area to output out->outPublic.t.publicArea = object->publicArea; // Copy name to output out->name.t.size = ObjectGetName(in->objectHandle, &out->name.t.name); // Copy qualified name to output ObjectGetQualifiedName(in->objectHandle, &out->qualifiedName); return TPM_RC_SUCCESS; } Page 62 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 14.5 Part 3: Commands TPM2_ActivateCredential 14.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 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. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 63 October 31, 2013 Part 3: Commands Trusted Platform Module Library 14.5.2 Command and Response Table 27 — TPM2_ActivateCredential Command Type Name TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode Description TPM_CC_ActivateCredential TPMI_DH_OBJECT @activateHandle handle of the object associated with certificate in credentialBlob Auth Index: 1 Auth Role: ADMIN TPMI_DH_OBJECT @keyHandle loaded key used to decrypt the TPMS_SENSITIVE in credentialBlob Auth Index: 2 Auth Role: USER TPM2B_ID_OBJECT credentialBlob the credential TPM2B_ENCRYPTED_SECRET secret keyHandle algorithm-dependent encrypted seed that protects credentialBlob Table 28 — TPM2_ActivateCredential Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode TPM2B_DIGEST certInfo Page 64 October 31, 2013 the decrypted certificate information the data should be no larger than the size of the digest of the nameAlg associated with keyHandle Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 14.5.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "ActivateCredential_fp.h" #include "Object_spt_fp.h" Error Returns 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 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 Meaning secret is invalid (when keyHandle is an RSA key) TPM_RC TPM2_ActivateCredential( ActivateCredential_In ActivateCredential_Out *in, *out // IN: input parameter list // OUT: output parameter list TPM_RC OBJECT OBJECT // credential TPM2B_DATA result = TPM_RC_SUCCESS; *object; // decrypt key *activateObject;// key associated with ) { data; // credential data // Input Validation // Get decrypt key pointer object = ObjectGet(in->keyHandle); // Get certificated object pointer activateObject = ObjectGet(in->activateHandle); // input decrypt key must be an asymmetric, restricted decryption key if( !CryptIsAsymAlgorithm(object->publicArea.type) || object->publicArea.objectAttributes.decrypt == CLEAR || object->publicArea.objectAttributes.restricted == CLEAR) return TPM_RC_TYPE + RC_ActivateCredential_keyHandle; // Command output // Decrypt input credential data via asymmetric decryption. A // TPM_RC_VALUE, TPM_RC_KEY or unmarshal errors may be returned at this // point result = CryptSecretDecrypt(in->keyHandle, NULL, "IDENTITY", &in->secret, &data); if(result != TPM_RC_SUCCESS) { if(result == TPM_RC_KEY) return TPM_RC_FAILURE; Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 65 October 31, 2013 Part 3: Commands 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 Trusted Platform Module Library return RcSafeAddToResult(result, RC_ActivateCredential_secret); } // Retrieve secret data. A TPM_RC_INTEGRITY error or unmarshal // errors may be returned at this point result = CredentialToSecret(&in->credentialBlob, &activateObject->name, (TPM2B_SEED *) &data, in->keyHandle, &out->certInfo); if(result != TPM_RC_SUCCESS) return RcSafeAddToResult(result,RC_ActivateCredential_credentialBlob); return TPM_RC_SUCCESS; } Page 66 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 14.6 Part 3: Commands TPM2_MakeCredential 14.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 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. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 67 October 31, 2013 Part 3: Commands Trusted Platform Module Library 14.6.2 Command and Response Table 29 — TPM2_MakeCredential Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_MakeCredential TPMI_DH_OBJECT handle loaded public area, used to encrypt the sensitive area 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 8 UINT32 responseSize TPM_RC responseCode TPM2B_ID_OBJECT credentialBlob TPM2B_ENCRYPTED_SECRET secret Page 68 October 31, 2013 the credential handle algorithm-dependent data that wraps the key that encrypts credentialBlob Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 14.6.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "MakeCredential_fp.h" #include "Object_spt_fp.h" Error Returns 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 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 Meaning handle does not reference an asymmetric decryption key TPM_RC TPM2_MakeCredential( MakeCredential_In MakeCredential_Out *in, *out // IN: input parameter list // OUT: output parameter list TPM_RC result = TPM_RC_SUCCESS; OBJECT TPM2B_DATA *object; data; ) { // Input Validation // Get object pointer object = ObjectGet(in->handle); // input key must be an asymmetric, restricted decryption key // NOTE: Needs to be restricted to have a symmetric value. if( !CryptIsAsymAlgorithm(object->publicArea.type) || object->publicArea.objectAttributes.decrypt == CLEAR || object->publicArea.objectAttributes.restricted == CLEAR ) return TPM_RC_TYPE + RC_MakeCredential_handle; // The credential information may not be larger than the digest size used for // the Name of the key associated with handle. if(in->credential.t.size > CryptGetHashDigestSize(object->publicArea.nameAlg)) return TPM_RC_SIZE + RC_MakeCredential_credential; // Command Output // Make encrypt key and its associated secret structure. // Even though CrypeSecretEncrypt() may return out->secret.t.size = sizeof(out->secret.t.secret); result = CryptSecretEncrypt(in->handle, "IDENTITY", &data, &out->secret); if(result != TPM_RC_SUCCESS) return result; // Prepare output credential data from secret SecretToCredential(&in->credential, &in->objectName, (TPM2B_SEED *) &data, in->handle, &out->credentialBlob); return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 69 October 31, 2013 Part 3: Commands 14.7 Trusted Platform Module Library TPM2_Unseal 14.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. A Sealed Data Object is more likely to be created externally and imported (TPM2_Import()) so that the data is not created by the TPM. 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. Page 70 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 14.7.2 Command and Response Table 31 — TPM2_Unseal Command Type Name TPMI_ST_COMMAND_TAG Tag UINT32 commandSize TPM_CC commandCode TPM_CC_Unseal TPMI_DH_OBJECT @itemHandle handle of a loaded data object Auth Index: 1 Auth Role: USER Description Table 32 — TPM2_Unseal Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode TPM2B_SENSITIVE_DATA outData Family “2.0” Level 00 Revision 00.99 unsealed data Size of outData is limited to be no more than 128 octets. Published Copyright © TCG 2006-2013 Page 71 October 31, 2013 Part 3: Commands Trusted Platform Module Library 14.7.3 Detailed Actions 1 2 #include "InternalRoutines.h" #include "Unseal_fp.h" Error Returns TPM_RC_ATTRIBUTES itemHandle has wrong attributes TPM_RC_TYPE 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 Meaning itemHandle is not a KEYEDHASH data object TPM_RC TPM2_Unseal(Unseal_In *in, Unseal_Out *out) { OBJECT *object; // Input Validation // Get pointer to loaded object object = ObjectGet(in->itemHandle); // Input handle must be a data object if(object->publicArea.type != TPM_ALG_KEYEDHASH) return TPM_RC_TYPE + RC_Unseal_itemHandle; if( object->publicArea.objectAttributes.decrypt == SET || object->publicArea.objectAttributes.sign == SET || object->publicArea.objectAttributes.restricted == SET) return TPM_RC_ATTRIBUTES + RC_Unseal_itemHandle; // Command Output // Copy data MemoryCopy2B(&out->outData.b, &object->sensitive.sensitive.bits.b, sizeof(out->outData.t.buffer)); return TPM_RC_SUCCESS; } Page 72 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 14.8 Part 3: Commands TPM2_ObjectChangeAuth 14.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()). Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 73 October 31, 2013 Part 3: Commands Trusted Platform Module Library 14.8.2 Command and Response Table 33 — TPM2_ObjectChangeAuth Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_ObjectChangeAuth TPMI_DH_OBJECT @objectHandle handle of the object Auth Index: 1 Auth Role: ADMIN TPMI_DH_OBJECT parentHandle handle of the parent Auth Index: None TPM2B_AUTH newAuth new authorization value Table 34 — TPM2_ObjectChangeAuth Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode TPM2B_PRIVATE outPrivate Page 74 October 31, 2013 private area containing the new authorization value Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 14.8.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "ObjectChangeAuth_fp.h" #include "Object_spt_fp.h" Error Returns TPM_RC_SIZE newAuth is larger than the size of the digest of the Name algorithm of objectHandle TPM_RC_TYPE 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 Meaning the key referenced by parentHandle is not the parent of the object referenced by objectHandle; or objectHandle is a sequence object. TPM_RC TPM2_ObjectChangeAuth( ObjectChangeAuth_In ObjectChangeAuth_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { TPMT_SENSITIVE OBJECT TPM2B_NAME TPM2B_NAME sensitive; *object; objectQN, QNCompare; parentQN; // Input Validation // Get object pointer object = ObjectGet(in->objectHandle); // Can not change auth on sequence object if(ObjectIsSequence(object)) return TPM_RC_TYPE + RC_ObjectChangeAuth_objectHandle; // Make sure that the auth value is consistent with the nameAlg if( MemoryRemoveTrailingZeros(&in->newAuth) > CryptGetHashDigestSize(object->publicArea.nameAlg)) return TPM_RC_SIZE + RC_ObjectChangeAuth_newAuth; // Check parent for object // parent handle must be the parent of object handle. In this // implementation we verify this by checking the QN of object. Other // implementation may choose different method to verify this attribute. ObjectGetQualifiedName(in->parentHandle, &parentQN); ObjectComputeQualifiedName(&parentQN, object->publicArea.nameAlg, &object->name, &QNCompare); ObjectGetQualifiedName(in->objectHandle, &objectQN); if(!Memory2BEqual(&objectQN.b, &QNCompare.b)) return TPM_RC_TYPE + RC_ObjectChangeAuth_parentHandle; // Command Output // Copy internal sensitive area sensitive = object->sensitive; // Copy authValue sensitive.authValue = in->newAuth; // Prepare output private data from sensitive SensitiveToPrivate(&sensitive, &object->name, in->parentHandle, Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 75 October 31, 2013 Part 3: Commands 52 53 54 55 56 Trusted Platform Module Library object->publicArea.nameAlg, &out->outPrivate); return TPM_RC_SUCCESS; } Page 76 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 15 Part 3: Commands Duplication Commands 15.1 TPM2_Duplicate 15.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 policySession→nameHash is compared to been executed as part of the policy, HpolicyAlg(objectHandle→Name || newParentHandle→Name) the (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_PolicyCommaneCode( code = TPM_CC_Duplicate). The TPM shall follow the process of encryption defined in the “Duplication” subclause of “Protected Storage Hierarchy” in Part 1 of this specification. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 77 October 31, 2013 Part 3: Commands Trusted Platform Module Library 15.1.2 Command and Response Table 35 — TPM2_Duplicate Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_Duplicate TPMI_DH_OBJECT @objectHandle loaded object to duplicate Auth Index: 1 Auth Role: DUP TPMI_DH_OBJECT+ newParentHandle shall reference the public area of an asymmetric key Auth Index: None TPM2B_DATA encryptionKeyIn optional symmetric encryption key The size for this key is set to zero when the TPM is to generate the key. This parameter may be encrypted. TPMT_SYM_DEF_OBJECT+ symmetricAlg definition for the symmetric algorithm to be used for the 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 8 UINT32 responseSize TPM_RC responseCode TPM2B_DATA encryptionKeyOut If the caller provided an encryption key or if symmetricAlg was TPM_ALG_NULL, then this will be the Empty Buffer; otherwise, it shall contain the TPMgenerated, symmetric encryption key for the inner wrapper. TPM2B_PRIVATE duplicate private area that may be encrypted by encryptionKeyIn; and may be doubly encrypted TPM2B_ENCRYPTED_SECRET outSymSeed Page 78 October 31, 2013 seed protected by the asymmetric algorithms of new parent (NP) Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 15.1.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "Duplicate_fp.h" #include "Object_spt_fp.h" Error Returns 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 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 Meaning newParentHandle is neither a storage key nor TPM_RH_NULL; or the object has a NULL nameAlg TPM_RC TPM2_Duplicate( Duplicate_In Duplicate_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { TPM_RC TPMT_SENSITIVE result = TPM_RC_SUCCESS; sensitive; UINT16 innerKeySize = 0; // encrypt key size for inner wrap OBJECT TPM2B_DATA *object; data; // Input Validation // Get duplicate object pointer object = ObjectGet(in->objectHandle); // duplicate key must have fixParent bit CLEAR. if(object->publicArea.objectAttributes.fixedParent == SET) return TPM_RC_ATTRIBUTES + RC_Duplicate_objectHandle; // Do not duplicate object with NULL nameAlg if(object->publicArea.nameAlg == TPM_ALG_NULL) return TPM_RC_TYPE + RC_Duplicate_objectHandle; // new parent key must be a storage object or TPM_RH_NULL if(in->newParentHandle != TPM_RH_NULL && !ObjectIsStorage(in->newParentHandle)) return TPM_RC_TYPE + RC_Duplicate_newParentHandle; // If the duplicates object has encryptedDuplication SET, then there must be // an inner wrapper and the new parent may not be TPM_RH_NULL if(object->publicArea.objectAttributes.encryptedDuplication == SET) { if(in->symmetricAlg.algorithm == TPM_ALG_NULL) return TPM_RC_SYMMETRIC + RC_Duplicate_symmetricAlg; if(in->newParentHandle == TPM_RH_NULL) Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 79 October 31, 2013 Part 3: Commands 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 Trusted Platform Module Library return TPM_RC_HIERARCHY + RC_Duplicate_newParentHandle; } if(in->symmetricAlg.algorithm == TPM_ALG_NULL) { // if algorithm is TPM_ALG_NULL, input key size must be 0 if(in->encryptionKeyIn.t.size != 0) return TPM_RC_SIZE + RC_Duplicate_encryptionKeyIn; } else { // Get inner wrap key size innerKeySize = in->symmetricAlg.keyBits.sym; // If provided the input symmetric key must match the size of the algorithm if(in->encryptionKeyIn.t.size != 0 && in->encryptionKeyIn.t.size != (innerKeySize + 7) / 8) return TPM_RC_SIZE + RC_Duplicate_encryptionKeyIn; } // Command Output if(in->newParentHandle != TPM_RH_NULL) { // Make encrypt key and its associated secret structure. A TPM_RC_KEY // error may be returned at this point out->outSymSeed.t.size = sizeof(out->outSymSeed.t.secret); result = CryptSecretEncrypt(in->newParentHandle, "DUPLICATE", &data, &out->outSymSeed); pAssert(result != TPM_RC_VALUE); if(result != TPM_RC_SUCCESS) return result; } else { // Do not apply outer wrapper data.t.size = 0; out->outSymSeed.t.size = 0; } // Copy sensitive area sensitive = object->sensitive; // Prepare output private data from sensitive SensitiveToDuplicate(&sensitive, &object->name, in->newParentHandle, object->publicArea.nameAlg, (TPM2B_SEED *) &data, &in->symmetricAlg, &in->encryptionKeyIn, &out->duplicate); out->encryptionKeyOut = in->encryptionKeyIn; return TPM_RC_SUCCESS; } Page 80 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 15.2 Part 3: Commands TPM2_Rewrap 15.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 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 Part 2 encryptedDuplication. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 81 October 31, 2013 Part 3: Commands Trusted Platform Module Library 15.2.2 Command and Response Table 37 — TPM2_Rewrap Command Type Name TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_Rewrap TPMI_DH_OBJECT+ @oldParent parent of object Auth Index: 1 Auth Role: User TPMI_DH_OBJECT+ newParent new parent of the object Auth Index: None TPM2B_PRIVATE inDuplicate an object encrypted using symmetric key derived from inSymSeed TPM2B_NAME name the Name of the object being rewrapped TPM2B_ENCRYPTED_SECRET inSymSeed Description seed for symmetric key 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 8 UINT32 responseSize TPM_RC responseCode TPM2B_PRIVATE outDuplicate TPM2B_ENCRYPTED_SECRET outSymSeed Page 82 October 31, 2013 an object encrypted using symmetric key derived from outSymSeed seed for a symmetric key protected by newParent asymmetric key Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 15.2.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "Rewrap_fp.h" #include "Object_spt_fp.h" Error Returns 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 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 Meaning errors during unmarshaling the input encrypted buffer to a ECC public key, or unmarshal the private buffer to sensitive TPM_RC TPM2_Rewrap( Rewrap_In Rewrap_Out *in, *out // IN: input parameter list // OUT: output parameter list TPM_RC OBJECT TPM2B_DATA UINT16 TPM2B_PRIVATE result = TPM_RC_SUCCESS; *oldParent; data; // symmetric key hashSize = 0; privateBlob; // A temporary private blob // to transit between old // and new wrappers ) { // Input Validation if((in->inSymSeed.t.size == 0 && in->oldParent != TPM_RH_NULL) || (in->inSymSeed.t.size != 0 && in->oldParent == TPM_RH_NULL)) return TPM_RC_HANDLE + RC_Rewrap_oldParent; if(in->oldParent != TPM_RH_NULL) { // Get old parent pointer oldParent = ObjectGet(in->oldParent); // old parent key must be a storage object if(!ObjectIsStorage(in->oldParent)) return TPM_RC_TYPE + RC_Rewrap_oldParent; // Decrypt input secret data via asymmetric decryption. A // TPM_RC_VALUE, TPM_RC_KEY or unmarshal errors may be returned at this // point result = CryptSecretDecrypt(in->oldParent, NULL, "DUPLICATE", &in->inSymSeed, &data); if(result != TPM_RC_SUCCESS) return TPM_RC_VALUE + RC_Rewrap_inSymSeed; Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 83 October 31, 2013 Part 3: Commands 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 Trusted Platform Module Library // Unwrap Outer result = UnwrapOuter(in->oldParent, &in->name, oldParent->publicArea.nameAlg, (TPM2B_SEED *) &data, FALSE, in->inDuplicate.t.size, in->inDuplicate.t.buffer); if(result != TPM_RC_SUCCESS) return RcSafeAddToResult(result, RC_Rewrap_inDuplicate); // Copy unwrapped data to temporary variable, remove the integrity field hashSize = sizeof(UINT16) + CryptGetHashDigestSize(oldParent->publicArea.nameAlg); privateBlob.t.size = in->inDuplicate.t.size - hashSize; MemoryCopy(privateBlob.t.buffer, in->inDuplicate.t.buffer + hashSize, privateBlob.t.size, sizeof(privateBlob.t.buffer)); } else { // No outer wrap from input blob. privateBlob = in->inDuplicate; } Direct copy. if(in->newParent != TPM_RH_NULL) { OBJECT *newParent; newParent = ObjectGet(in->newParent); // New parent must be a storage object if(!ObjectIsStorage(in->newParent)) return TPM_RC_TYPE + RC_Rewrap_newParent; // Make new encrypt key and its associated secret structure. A // TPM_RC_VALUE error may be returned at this point if RSA algorithm is // enabled in TPM out->outSymSeed.t.size = sizeof(out->outSymSeed.t.secret); result = CryptSecretEncrypt(in->newParent, "DUPLICATE", &data, &out->outSymSeed); if(result != TPM_RC_SUCCESS) return result; // Command output // Copy temporary variable to output, reserve the space for integrity hashSize = sizeof(UINT16) + CryptGetHashDigestSize(newParent->publicArea.nameAlg); out->outDuplicate.t.size = privateBlob.t.size; MemoryCopy(out->outDuplicate.t.buffer + hashSize, privateBlob.t.buffer, privateBlob.t.size, sizeof(out->outDuplicate.t.buffer)); // Produce outer wrapper for output out->outDuplicate.t.size = ProduceOuterWrap(in->newParent, &in->name, newParent->publicArea.nameAlg, (TPM2B_SEED *) &data, FALSE, out->outDuplicate.t.size, out->outDuplicate.t.buffer); } else // New parent is a null key so there is no seed { out->outSymSeed.t.size = 0; // Copy privateBlob directly out->outDuplicate = privateBlob; } Page 84 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 104 105 Part 3: Commands return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 85 October 31, 2013 Part 3: Commands 15.3 Trusted Platform Module Library TPM2_Import 15.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). However, see Note 2. Recovery of the sensitive data of the object occurs in the TPM in a three-step process in the following order:  If present, the outer layer of symmetric encryption is removed. If inSymSeed has a non-zero size, 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. When recovering the seed, L is “DUPLICATE”. NOTE 1 If the encryptedDuplication attribute of the object TPM_RC_ATTRIBUTES if inSymSeed is an empty buffer. is SET, the TPM shall return  If present, the inner layer of symmetric encryption is removed. If encryptionKey and symmetricAlg are provided, they are used to decrypt duplication.  If present, the integrity value of the blob is checked. The presence of the integrity value is indicated by a non-zero value for duplicate.data.integrity.size. The integrity of the private area is validated using the Name of objectPublic in the integrity HMAC computation. If either the outer layer or inner layer of encryption is performed, then the integrity value shall be present. If the inner or outer wrapper is present, then a valid integrity value shall be present or the TPM shall return TPM_RC_INTEGRITY. NOTE 2 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 protected 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. Before duplicate.buffer is decrypted using the symmetric key of the parent, the integrity value shall be checked before the sensitive area is used, or unmarshaled. After integrity checks and decryption, the TPM will create a new symmetrically encrypted private area using the encryption key of the parent. 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. Page 86 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library NOTE 4 Part 3: Commands The symmetric re-encryption is the normal integrity generation and symmetric encryption applied to a child object. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 87 October 31, 2013 Part 3: Commands Trusted Platform Module Library 15.3.2 Command and Response Table 39 — TPM2_Import Command Type Name TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_Import TPMI_DH_OBJECT @parentHandle the handle of the new parent for the object Auth Index: 1 Auth Role: USER TPM2B_DATA encryptionKey the optional symmetric encryption key used as the inner wrapper for duplicate If symmetricAlg is TPM_ALG_NULL, then this parameter shall be the Empty Buffer. TPM2B_PUBLIC objectPublic Description the public area of the object to be imported This is provided so that the integrity value for duplicate and the object attributes can be checked. NOTE TPM2B_PRIVATE duplicate 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 contain an inner symmetric wrapper TPM2B_ENCRYPTED_SECRET inSymSeed symmetric key used to encrypt duplicate inSymSeed is encrypted/encoded using the algorithms of newParent. TPMT_SYM_DEF_OBJECT+ symmetricAlg definition for the symmetric algorithm to use for the inner wrapper 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 8 UINT32 responseSize TPM_RC responseCode TPM2B_PRIVATE outPrivate Page 88 October 31, 2013 the sensitive area encrypted with the symmetric key of parentHandle Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 15.3.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "Import_fp.h" #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 params 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 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 is not of the same size as RSA key referenced by 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 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 Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 89 October 31, 2013 Part 3: Commands 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 Trusted Platform Module Library TPM_RC TPM2_Import( Import_In Import_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { TPM_RC OBJECT TPM2B_DATA TPMT_SENSITIVE TPM2B_NAME result = TPM_RC_SUCCESS; *parentObject; data; // symmetric key sensitive; name; UINT16 innerKeySize = 0; // encrypt key size for inner // wrapper // Input Validation // FixedTPM and fixedParent must be CLEAR if( in->objectPublic.t.publicArea.objectAttributes.fixedTPM == SET || in->objectPublic.t.publicArea.objectAttributes.fixedParent == SET) return TPM_RC_ATTRIBUTES + RC_Import_objectPublic; // Get parent pointer parentObject = ObjectGet(in->parentHandle); if(!AreAttributesForParent(parentObject)) return TPM_RC_TYPE + RC_Import_parentHandle; if(in->symmetricAlg.algorithm != TPM_ALG_NULL) { // Get inner wrap key size innerKeySize = in->symmetricAlg.keyBits.sym; // Input symmetric key must match the size of algorithm. if(in->encryptionKey.t.size != (innerKeySize + 7) / 8) return TPM_RC_SIZE + RC_Import_encryptionKey; } else { // If input symmetric algorithm is NULL, input symmetric key size must // be 0 as well if(in->encryptionKey.t.size != 0) return TPM_RC_SIZE + RC_Import_encryptionKey; } // See if there is an outer wrapper if(in->inSymSeed.t.size != 0) { // Decrypt input secret data via asymmetric decryption. TPM_RC_ATTRIBUTES, // TPM_RC_ECC_POINT, TPM_RC_INSUFFICIENT, TPM_RC_KEY, TPM_RC_NO_RESULT, // TPM_RC_SIZE, TPM_RC_VALUE may be returned at this point result = CryptSecretDecrypt(in->parentHandle, NULL, "DUPLICATE", &in->inSymSeed, &data); pAssert(result != TPM_RC_BINDING); if(result != TPM_RC_SUCCESS) return TPM_RC_VALUE + RC_Import_inSymSeed; } else { data.t.size = 0; } // Compute name of object ObjectComputeName(&(in->objectPublic.t.publicArea), &name); Page 90 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 Part 3: Commands // Retrieve sensitive from private. // TPM_RC_INSUFFICIENT, TPM_RC_INTEGRITY, TPM_RC_SIZE may be returned here. result = DuplicateToSensitive(&in->duplicate, &name, in->parentHandle, in->objectPublic.t.publicArea.nameAlg, (TPM2B_SEED *) &data, &in->symmetricAlg, &in->encryptionKey, &sensitive); if(result != TPM_RC_SUCCESS) return RcSafeAddToResult(result, RC_Import_duplicate); // If the parent of this object has fixedTPM SET, then fully validate this // object so that validation can be skipped when it is loaded if(parentObject->publicArea.objectAttributes.fixedTPM == SET) { TPM_HANDLE objectHandle; // Perform self check on input public area. A TPM_RC_SIZE, TPM_RC_SCHEME, // TPM_RC_VALUE, TPM_RC_SYMMETRIC, TPM_RC_TYPE, TPM_RC_HASH, // TPM_RC_ASYMMETRIC, TPM_RC_ATTRIBUTES or TPM_RC_KDF error may be returned // at this point result = PublicAttributesValidation(TRUE, in->parentHandle, &in->objectPublic.t.publicArea); if(result != TPM_RC_SUCCESS) return RcSafeAddToResult(result, RC_Import_objectPublic); // Create internal object. A TPM_RC_KEY_SIZE, TPM_RC_KEY or // TPM_RC_OBJECT_MEMORY error may be returned at this point result = ObjectLoad(TPM_RH_NULL, &in->objectPublic.t.publicArea, &sensitive, NULL, in->parentHandle, FALSE, &objectHandle); if(result != TPM_RC_SUCCESS) return result; // Don't need the object, just needed the checks to be performed so // flush the object ObjectFlush(objectHandle); } // Command output // Prepare output private data from sensitive SensitiveToPrivate(&sensitive, &name, in->parentHandle, in->objectPublic.t.publicArea.nameAlg, &out->outPrivate); return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 91 October 31, 2013 Part 3: Commands 16 Trusted Platform Module Library Asymmetric Primitives 16.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. 16.2 TPM2_RSA_Encrypt 16.2.1 General Description This command performs RSA encryption using the indicated padding scheme according to PKCS#1v2.1 (PKCS#1). 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 publi c 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 PKCS#1 v2.1. The only supported mask generation is MGF1. 2) TPM_ALG_RSAES – Data is padded as described in 7.2 of PKCS#1 v2.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 OAEP RSAES TPM_ALG_RSAES RSAES error (TPM_RC_SCHEME) TPM_ALG_NULL OAEP TPM_ALG_RSAES error (TPM_RC_SCHEME) TPM_AGL_OAEP October 31, 2013 RSAES TPM_ALG_OAEP Page 92 TPM_ALG_RSAES TPM_ALG_NULL TPM_ALG_OAEP none TPM_ALG_OAEP TPM_ALG_RSAES padding scheme used TPM_ALG_NULL TPM_ALG_NULL inScheme OAEP Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands After padding, the data is RSAEP encrypted according to 5.1.1 of PKCS#1v2.1. 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, the 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 Scheme Maximum Message Length (mLen) in Octets TPM_ALG_OAEP mLen  k – 2hLen – 2 TPM_ALG_RSAES mLen  k – 11 TPM_ALG_NULL mLen  k Comments The numeric value of the message must be less than the numeric value of the public modulus (n). NOTES 1) 2) k ≔ the number of byes in the public modulus 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” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 93 October 31, 2013 Part 3: Commands Trusted Platform Module Library 16.2.2 Command and Response Table 43 — TPM2_RSA_Encrypt Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_RSA_Encrypt TPMI_DH_OBJECT keyHandle reference to public portion of RSA key to use for encryption Auth Index: None message to be encrypted TPM2B_PUBLIC_KEY_RSA message TPMT_RSA_DECRYPT+ inScheme TPM2B_DATA label NOTE 1 The data type was chosen because it limits the 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 keyHandle is TPM_ALG_NULL optional label L to be associated with the message 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 8 UINT32 responseSize TPM_RC responseCode TPM2B_PUBLIC_KEY_RSA outData Page 94 October 31, 2013 encrypted output Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 16.2.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "RSA_Encrypt_fp.h" #ifdef TPM_ALG_RSA Error Returns 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 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 Meaning 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 TPM_RC TPM2_RSA_Encrypt( RSA_Encrypt_In RSA_Encrypt_Out *in, *out // IN: input parameter list // OUT: output parameter list TPM_RC OBJECT TPMT_RSA_DECRYPT char result; *rsaKey; *scheme; *label = NULL; ) { // Input Validation rsaKey = ObjectGet(in->keyHandle); // selected key must be an RSA key if(rsaKey->publicArea.type != TPM_ALG_RSA) return TPM_RC_KEY + RC_RSA_Encrypt_keyHandle; // selected key must have the decryption attribute if(rsaKey->publicArea.objectAttributes.decrypt != SET) return TPM_RC_ATTRIBUTES + RC_RSA_Encrypt_keyHandle; // Is there a label? if(in->label.t.size > 0) { // label is present, so make sure that is it NULL-terminated if(in->label.t.buffer[in->label.t.size - 1] != 0) return TPM_RC_VALUE + RC_RSA_Encrypt_label; label = (char *)in->label.t.buffer; } // Command Output // Select a scheme for encryption scheme = CryptSelectRSAScheme(in->keyHandle, &in->inScheme); if(scheme == NULL) return TPM_RC_SCHEME + RC_RSA_Encrypt_inScheme; // Encryption. TPM_RC_VALUE, or TPM_RC_SCHEME errors my be returned buy // CryptEncyptRSA. Note: It can also return TPM_RC_ATTRIBUTES if the key does // not have the decrypt attribute but that was checked above. out->outData.t.size = sizeof(out->outData.t.buffer); Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 95 October 31, 2013 Part 3: Commands 47 48 49 50 51 52 Trusted Platform Module Library result = CryptEncryptRSA(&out->outData.t.size, out->outData.t.buffer, rsaKey, scheme, in->message.t.size, in->message.t.buffer, label); return result; } #endif Page 96 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 16.3 Part 3: Commands TPM2_RSA_Decrypt 16.3.1 General Description This command performs RSA decryption using the indicated padding scheme according to PKCS#1v2.1 (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 PKCS#1v2.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, the label parameter is required to be present in the decryption process and label is required to be the same in both cases. The TPM shall verify that the label is consistent and if not it shall return 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 the decryption scheme does not require a hash function, the hash parameter of inScheme may be set to any valid hash function or TPM_ALG_NULL. If the description 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” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 97 October 31, 2013 Part 3: Commands Trusted Platform Module Library 16.3.2 Command and Response Table 45 — TPM2_RSA_Decrypt Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_RSA_Decrypt TPMI_DH_OBJECT @keyHandle RSA key to use for decryption Auth Index: 1 Auth Role: USER TPM2B_PUBLIC_KEY_RSA cipherText NOTE TPMT_RSA_DECRYPT+ inScheme the padding scheme to use if scheme associated with keyHandle is TPM_ALG_NULL TPM2B_DATA label label whose association with the message is to be verified cipher text to be decrypted An encrypted RSA data block is the size of the public modulus. Table 46 — TPM2_RSA_Decrypt Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode TPM2B_PUBLIC_KEY_RSA message Page 98 October 31, 2013 decrypted output Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 16.3.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "RSA_Decrypt_fp.h" #ifdef TPM_ALG_RSA Error Returns 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 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 Meaning label is not a null terminated string or the value of cipherText is greater that the modulus of keyHandle TPM_RC TPM2_RSA_Decrypt( RSA_Decrypt_In RSA_Decrypt_Out *in, *out // IN: input parameter list // OUT: output parameter list TPM_RC OBJECT TPMT_RSA_DECRYPT char result; *rsaKey; *scheme; *label = NULL; ) { // Input Validation rsaKey = ObjectGet(in->keyHandle); // The selected key must be an RSA key if(rsaKey->publicArea.type != TPM_ALG_RSA) return TPM_RC_KEY + RC_RSA_Decrypt_keyHandle; // The selected key must be an unrestricted decryption key if( rsaKey->publicArea.objectAttributes.restricted == SET || rsaKey->publicArea.objectAttributes.decrypt == CLEAR) return TPM_RC_ATTRIBUTES + RC_RSA_Decrypt_keyHandle; // // // // NOTE: Proper operation of this command requires that the sensitive area of the key is loaded. This is assured because authorization is required to use the sensitive area of the key. In order to check the authorization, the sensitive area has to be loaded, even if authorization is with policy. // If label is present, make sure that it is a NULL-terminated string if(in->label.t.size > 0) { // Present, so make sure that it is NULL-terminated if(in->label.t.buffer[in->label.t.size - 1] != 0) return TPM_RC_VALUE + RC_RSA_Decrypt_label; label = (char *)in->label.t.buffer; } // Command Output // Select a scheme for decrypt. scheme = CryptSelectRSAScheme(in->keyHandle, &in->inScheme); if(scheme == NULL) Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 99 October 31, 2013 Part 3: Commands 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 Trusted Platform Module Library return TPM_RC_SCHEME + RC_RSA_Decrypt_inScheme; // Decryption. TPM_RC_VALUE, TPM_RC_SIZE, and TPM_RC_KEY error may be // returned by CryptDecryptRSA. // NOTE: CryptDecryptRSA can also return TPM_RC_ATTRIBUTES or TPM_RC_BINDING // when the key is not a decryption key but that was checked above. out->message.t.size = sizeof(out->message.t.buffer); result = CryptDecryptRSA(&out->message.t.size, out->message.t.buffer, rsaKey, scheme, in->cipherText.t.size, in->cipherText.t.buffer, label); return result; } #endif Page 100 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 16.4 Part 3: Commands TPM2_ECDH_KeyGen 16.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” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 101 October 31, 2013 Part 3: Commands Trusted Platform Module Library 16.4.2 Command and Response Table 47 — TPM2_ECDH_KeyGen Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_ECDH_KeyGen TPMI_DH_OBJECT keyHandle Handle of a loaded ECC key public area. Auth Index: None Table 48 — TPM2_ECDH_KeyGen Response Type Name Description TPM_ST tag see clause 8 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 102 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 16.4.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "ECDH_KeyGen_fp.h" #ifdef TPM_ALG_ECC Error Returns TPM_RC_KEY 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 Meaning keyHandle does not reference a non-restricted decryption ECC key TPM_RC TPM2_ECDH_KeyGen( ECDH_KeyGen_In ECDH_KeyGen_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { OBJECT TPM2B_ECC_PARAMETER TPM_RC *eccKey; sensitive; result; // Input Validation eccKey = ObjectGet(in->keyHandle); // Input key must be a non-restricted, decrypt ECC key if( eccKey->publicArea.type != TPM_ALG_ECC || eccKey->publicArea.objectAttributes.restricted == SET || eccKey->publicArea.objectAttributes.decrypt != SET ) return TPM_RC_KEY + RC_ECDH_KeyGen_keyHandle; // Command Output do { // Create ephemeral ECC key CryptNewEccKey(eccKey->publicArea.parameters.eccDetail.curveID, &out->pubPoint.t.point, &sensitive); out->pubPoint.t.size = TPMS_ECC_POINT_Marshal(&out->pubPoint.t.point, NULL, NULL); // Compute Z result = CryptEccPointMultiply(&out->zPoint.t.point, eccKey->publicArea.parameters.eccDetail.curveID, &sensitive, &eccKey->publicArea.unique.ecc); // The point in the key is not on the curve. Indicate that the key is bad. if(result == TPM_RC_ECC_POINT) return TPM_RC_KEY + RC_ECDH_KeyGen_keyHandle; // The other possible error is TPM_RC_NO_RESULT indicating that the // multiplication resulted in the point at infinity, so get a new // random key and start over (hardly ever happens). } while(result != TPM_RC_SUCCESS); // Marshal the values to generate the point. out->zPoint.t.size = TPMS_ECC_POINT_Marshal(&out->zPoint.t.point, NULL, NULL); return TPM_RC_SUCCESS; } #endif Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 103 October 31, 2013 Part 3: Commands 16.5 Trusted Platform Module Library TPM2_ECDH_ZGen 16.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. Page 104 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 16.5.2 Command and Response Table 49 — TPM2_ECDH_ZGen Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_ECDH_ZGen TPMI_DH_OBJECT @keyHandle handle of a loaded ECC key 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 8 UINT32 responseSize TPM_RC responseCode TPM2B_ECC_POINT outPoint Family “2.0” Level 00 Revision 00.99 X and Y coordinates of the product of the multiplication Z = (xZ , yZ) ≔ [hdS]QB Published Copyright © TCG 2006-2013 Page 105 October 31, 2013 Part 3: Commands Trusted Platform Module Library 16.5.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "ECDH_ZGen_fp.h" #ifdef TPM_ALG_ECC Error Returns TPM_RC_KEY keyHandle does not reference a non-restricted decryption ECC key TPM_RC_ECC_POINT invalid argument TPM_RC_NO_RESULT 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 Meaning multiplying inPoint resulted in a point at infinity TPM_RC TPM2_ECDH_ZGen( ECDH_ZGen_In ECDH_ZGen_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { TPM_RC OBJECT result; *eccKey; // Input Validation eccKey = ObjectGet(in->keyHandle); // Input key must be a non-restricted, decrypt ECC key if( eccKey->publicArea.type != TPM_ALG_ECC || eccKey->publicArea.objectAttributes.restricted == SET || eccKey->publicArea.objectAttributes.decrypt != SET ) return TPM_RC_KEY + RC_ECDH_ZGen_keyHandle; // Command Output // Compute Z. TPM_RC_ECC_POINT or TPM_RC_NO_RESULT may be returned here. result = CryptEccPointMultiply(&out->outPoint.t.point, eccKey->publicArea.parameters.eccDetail.curveID, &eccKey->sensitive.sensitive.ecc, &in->inPoint.t.point); if(result != TPM_RC_SUCCESS) return RcSafeAddToResult(result, RC_ECDH_ZGen_inPoint); out->outPoint.t.size = TPMS_ECC_POINT_Marshal(&out->outPoint.t.point, NULL, NULL); return TPM_RC_SUCCESS; } #endif Page 106 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 16.6 Part 3: Commands TPM2_ECC_Parameters 16.6.1 General Description This command returns the parameters of an ECC curve identified by its TCG-assigned curveID. 16.6.2 Command and Response Table 51 — TPM2_ECC_Parameters Command Type Name Description TPMI_ST_COMMAND_TAG tag 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 8 UINT32 responseSize TPM_RC responseCode TPMS_ALGORITHM_DETAIL_ECC parameters Family “2.0” Level 00 Revision 00.99 ECC parameters for the selected curve Published Copyright © TCG 2006-2013 Page 107 October 31, 2013 Part 3: Commands Trusted Platform Module Library 16.6.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "ECC_Parameters_fp.h" #ifdef TPM_ALG_ECC Error Returns TPM_RC_VALUE 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 Meaning Unsupported ECC curve ID TPM_RC TPM2_ECC_Parameters( ECC_Parameters_In ECC_Parameters_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { // Command Output // Get ECC curve parameters if(CryptEccGetParameters(in->curveID, &out->parameters)) return TPM_RC_SUCCESS; else return TPM_RC_VALUE + RC_ECC_Parameters_curveID; } #endif 16.7 16.7.1 TPM2_ZGen_2Phase 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. Page 108 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library NOTE 2 Part 3: Commands A non-restricted 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 ju st an x-coordinate. If a computation of either Z produces the point at infinity, then the corresponding Z value will be an Empty Point. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 109 October 31, 2013 Part 3: Commands 16.7.2 Trusted Platform Module Library Command and Response Table 53 — TPM2_ZGen_2Phase Command Type Name TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode Description 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 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() Auth Index: 1 Auth Role: USER Table 54 — TPM2_ZGen_2Phase Response Type Name TPM_ST tag UINT32 responseSize TPM_RC responseCode TPM2B_ECC_POINT outZ1 X and Y coordinates of the computed value (scheme dependent) TPM2B_ECC_POINT outZ2 X and Y coordinates of the second computed value (scheme dependent) Page 110 October 31, 2013 Description Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 16.7.3 1 2 3 Part 3: Commands Detailed Actions #include "InternalRoutines.h" #include "ZGen_2Phase_fp.h" #if defined TPM_ALG_ECC && (CC_ZGen_2Phase == YES) This command uses the TPM to recover one or two Z values in a two phase key exchange protocol Error Returns 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 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 Meaning the scheme of the key referenced by keyA is not TPM_ALG_NULL, TPM_ALG_ECDH, TPM_ALG_ECMQV or TPM_ALG_SM2 TPM_RC TPM2_ZGen_2Phase( ZGen_2Phase_In ZGen_2Phase_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { TPM_RC OBJECT TPM2B_ECC_PARAMETER TPM_ALG_ID result; *eccKey; r; scheme; // Input Validation eccKey = ObjectGet(in->keyA); // keyA must be an ECC key if(eccKey->publicArea.type != TPM_ALG_ECC) return TPM_RC_KEY + RC_ZGen_2Phase_keyA; // keyA must not be restricted and must be a decrypt key if( eccKey->publicArea.objectAttributes.restricted == SET || eccKey->publicArea.objectAttributes.decrypt != SET ) return TPM_RC_ATTRIBUTES + RC_ZGen_2Phase_keyA; // if the scheme of keyA is TPM_ALG_NULL, then use the input scheme; otherwise // the input scheme must be the same as the scheme of keyA scheme = eccKey->publicArea.parameters.asymDetail.scheme.scheme; if(scheme != TPM_ALG_NULL) { if(scheme != in->inScheme) return TPM_RC_SCHEME + RC_ZGen_2Phase_inScheme; } else scheme = in->inScheme; if(scheme == TPM_ALG_NULL) return TPM_RC_SCHEME + RC_ZGen_2Phase_inScheme; // Input points must be on the curve of keyA if(!CryptEccIsPointOnCurve(eccKey->publicArea.parameters.eccDetail.curveID, &in->inQsB.t.point)) return TPM_RC_ECC_POINT + RC_ZGen_2Phase_inQsB; if(!CryptEccIsPointOnCurve(eccKey->publicArea.parameters.eccDetail.curveID, Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 111 October 31, 2013 Part 3: Commands 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 Trusted Platform Module Library &in->inQeB.t.point)) return TPM_RC_ECC_POINT + RC_ZGen_2Phase_inQeB; if(!CryptGenerateR(&r, &in->counter, eccKey->publicArea.parameters.eccDetail.curveID, NULL)) return TPM_RC_VALUE + RC_ZGen_2Phase_counter; // Command Output result = CryptEcc2PhaseKeyExchange(&out->outZ1.t.point, &out->outZ2.t.point, eccKey->publicArea.parameters.eccDetail.curveID, scheme, &eccKey->sensitive.sensitive.ecc, &r, &in->inQsB.t.point, &in->inQeB.t.point); if(result != TPM_RC_SUCCESS) return result; CryptEndCommit(in->counter); return TPM_RC_SUCCESS; } #endif Page 112 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 17 17.1 Part 3: Commands Symmetric Primitives 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: Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 113 October 31, 2013 Part 3: Commands Trusted Platform Module Library Table 55 — Symmetric Chaining Process Mode Chaining process TPM_ALG_CTR The TPM will increment the entire IV provided by the caller. The last encrypted value will be returned to the caller as ivOut. This can be the input value to the next encrypted 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. 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. Page 114 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 17.2 Part 3: Commands TPM2_EncryptDecrypt 17.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 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_CANCEL. In such case, outData may be less than inData. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 115 October 31, 2013 Part 3: Commands Trusted Platform Module Library 17.2.2 Command and Response Table 56 — TPM2_EncryptDecrypt Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_EncryptDecrypt TPMI_DH_OBJECT @keyHandle the symmetric key used for the operation Auth Index: 1 Auth Role: USER TPMI_YES_NO decrypt if YES, then the operation is decryption; if NO, the operation is encryption TPMI_ALG_SYM_MODE+ mode symmetric 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 8 UINT32 responseSize TPM_RC responseCode TPM2B_MAX_BUFFER outData encrypted output TPM2B_IV ivOut chaining value to use for IV in next round Page 116 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 17.2.3 Detailed Actions 1 2 #include "InternalRoutines.h" #include "EncryptDecrypt_fp.h" Error Returns 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 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 Meaning keyHandle is restricted and the argument mode does not match the key's mode TPM_RC TPM2_EncryptDecrypt( EncryptDecrypt_In EncryptDecrypt_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { OBJECT UINT16 UINT16 BYTE TPM_ALG_ID *symKey; keySize; blockSize; *key; alg; // Input Validation symKey = ObjectGet(in->keyHandle); // The input key should be a symmetric decrypt key. if( symKey->publicArea.type != TPM_ALG_SYMCIPHER || symKey->attributes.publicOnly == SET) return TPM_RC_KEY + RC_EncryptDecrypt_keyHandle; // If the input mode is TPM_ALG_NULL, use the key's mode if( in->mode == TPM_ALG_NULL) in->mode = symKey->publicArea.parameters.symDetail.sym.mode.sym; // If the key is restricted, the input sym mode should match the key's sym // mode if( symKey->publicArea.objectAttributes.restricted == SET && symKey->publicArea.parameters.symDetail.sym.mode.sym != in->mode) return TPM_RC_VALUE + RC_EncryptDecrypt_mode; // If the mode is null, then we have a problem. // Note: Construction of a TPMT_SYM_DEF does not allow the 'mode' to be // TPM_ALG_NULL so setting in->mode to the mode of the key should have // produced a valid mode. However, this is suspenders. if(in->mode == TPM_ALG_NULL) return TPM_RC_VALUE + RC_EncryptDecrypt_mode; // The input iv for ECB mode should be null. All the other modes should // have an iv size same as encryption block size keySize = symKey->publicArea.parameters.symDetail.sym.keyBits.sym; alg = symKey->publicArea.parameters.symDetail.sym.algorithm; blockSize = CryptGetSymmetricBlockSize(alg, keySize); if( (in->mode == TPM_ALG_ECB && in->ivIn.t.size != 0) || (in->mode != TPM_ALG_ECB && in->ivIn.t.size != blockSize)) return TPM_RC_SIZE + RC_EncryptDecrypt_ivIn; Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 117 October 31, 2013 Part 3: Commands 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 Trusted Platform Module Library // The input data size of CBC mode or ECB mode must be an even multiple of // the symmetric algorithm's block size if( (in->mode == TPM_ALG_CBC || in->mode == TPM_ALG_ECB) && (in->inData.t.size % blockSize) != 0) return TPM_RC_SIZE + RC_EncryptDecrypt_inData; // Copy IV // Note: This is copied here so that the calls to the encrypt/decrypt functions // will modify the output buffer, not the input buffer out->ivOut = in->ivIn; // Command Output key = symKey->sensitive.sensitive.sym.t.buffer; // For symmetric encryption, the cipher data size is the same as plain data // size. out->outData.t.size = in->inData.t.size; if(in->decrypt == YES) { // Decrypt data to output CryptSymmetricDecrypt(out->outData.t.buffer, alg, keySize, in->mode, key, &(out->ivOut), in->inData.t.size, in->inData.t.buffer); } else { // Encrypt data to output CryptSymmetricEncrypt(out->outData.t.buffer, alg, keySize, in->mode, key, &(out->ivOut), in->inData.t.size, in->inData.t.buffer); } return TPM_RC_SUCCESS; } Page 118 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 17.3 Part 3: Commands TPM2_Hash 17.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. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 119 October 31, 2013 Part 3: Commands Trusted Platform Module Library 17.3.2 Command and Response Table 58 — TPM2_Hash Command Type Name Description TPMI_ST_COMMAND_TAG tag Shall have at least one session UINT32 commandSize TPM_CC commandCode TPM_CC_Hash TPM2B_MAX_BUFFER data data to be hashed TPMI_ALG_HASH hashAlg algorithm for the hash being computed – shall not be 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 8 UINT32 responseSize TPM_RC responseCode TPM2B_DIGEST outHash results TPMT_TK_HASHCHECK validation ticket indicating that the sequence of octets used to compute outDigest did not start with TPM_GENERATED_VALUE will be a NULL ticket if the digest may not be signed with a restricted key Page 120 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 17.3.3 Detailed Actions 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 #include "InternalRoutines.h" #include "Hash_fp.h" TPM_RC TPM2_Hash( Hash_In Hash_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { HASH_STATE hashState; // Command Output // Output hash // Start hash stack out->outHash.t.size = CryptStartHash(in->hashAlg, &hashState); // Adding hash data CryptUpdateDigest2B(&hashState, &in->data.b); // Complete hash CryptCompleteHash2B(&hashState, &out->outHash.b); // Output ticket out->validation.tag = TPM_ST_HASHCHECK; out->validation.hierarchy = in->hierarchy; if(in->hierarchy == TPM_RH_NULL) { // Ticket is not required out->validation.hierarchy = TPM_RH_NULL; out->validation.digest.t.size = 0; } else if( in->data.t.size >= sizeof(TPM_GENERATED) && !TicketIsSafe(&in->data.b)) { // Ticket is not safe out->validation.hierarchy = TPM_RH_NULL; out->validation.digest.t.size = 0; } else { // Compute ticket TicketComputeHashCheck(in->hierarchy, &out->outHash, &out->validation); } return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 121 October 31, 2013 Part 3: Commands 17.4 Trusted Platform Module Library TPM2_HMAC 17.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 handle references a restricted key, then the hash algorithm specified in the key's scheme is used as the hash algorithm for the HMAC and the TPM shall return TPM_RC_VALUE if hashAlg is not TPM_ALG_NULL or the same algorithm as selected in the key's scheme. NOTE 1 A restricted key may only have one of sign or decrypt SET and the default scheme may not be TPM_ALG_NULL. These restrictions are enforced by TPM2_Create() and TPM2_CreatePrimary(), If the key referenced by handle is not restricted, then the TPM will use hashAlg for the HMAC. However, if hashAlg is TPM_ALG_NULL the TPM will use the default scheme of the key. If both hashAlg and the key default are TPM_ALG_NULL, the TPM shall return TPM_RC_VALUE. NOTE A key may only have both sign and decrypt SET if the key is unrestricted. When bo th sign and decrypt are set, there is no default scheme for the key and the hash algorithm must be specified . Page 122 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 17.4.2 Command and Response Table 60 — TPM2_HMAC Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_HMAC TPMI_DH_OBJECT @handle handle for the symmetric signing key providing the HMAC key 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 8 UINT32 responseSize TPM_RC responseCode TPM2B_DIGEST outHMAC Family “2.0” Level 00 Revision 00.99 the returned HMAC in a sized buffer Published Copyright © TCG 2006-2013 Page 123 October 31, 2013 Part 3: Commands Trusted Platform Module Library 17.4.3 Detailed Actions 1 2 #include "InternalRoutines.h" #include "HMAC_fp.h" Error Returns TPM_RC_ATTRIBUTES key referenced by handle is not a signing key TPM_RC_TYPE key referenced by handle is not an HMAC key TPM_RC_VALUE 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 Meaning hashAlg specified when the key is restricted is neither TPM_ALG_NULL not equal to that of the key scheme; or both hashAlg and the key scheme's algorithm are TPM_ALG_NULL TPM_RC TPM2_HMAC( HMAC_In HMAC_Out *in, *out // IN: input parameter list // OUT: output parameter list HMAC_STATE OBJECT TPMI_ALG_HASH TPMT_PUBLIC hmacState; *hmacObject; hashAlg; *publicArea; ) { // Input Validation // Get HMAC key object and public area pointers hmacObject = ObjectGet(in->handle); publicArea = &hmacObject->publicArea; // Make sure that the key is an HMAC signing key if(publicArea->type != TPM_ALG_KEYEDHASH) return TPM_RC_TYPE + RC_HMAC_handle; if(publicArea->objectAttributes.sign != SET) return TPM_RC_ATTRIBUTES + RC_HMAC_handle; // Assume that the key default scheme is used hashAlg = publicArea->parameters.keyedHashDetail.scheme.details.hmac.hashAlg; // if the key is restricted, then need to use the scheme of the key and the // input algorithm must be TPM_ALG_NULL or the same as the key scheme if(publicArea->objectAttributes.restricted == SET) { if(in->hashAlg != TPM_ALG_NULL && in->hashAlg != hashAlg) hashAlg = TPM_ALG_NULL; } else { // for a non-restricted key, use hashAlg if it is provided; if(in->hashAlg != TPM_ALG_NULL) hashAlg = in->hashAlg; } // if the hashAlg is TPM_ALG_NULL, then the input hashAlg is not compatible // with the key scheme or type if(hashAlg == TPM_ALG_NULL) return TPM_RC_VALUE + RC_HMAC_hashAlg; // Command Output Page 124 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 50 51 52 53 54 55 56 57 58 59 60 61 Part 3: Commands // Start HMAC stack out->outHMAC.t.size = CryptStartHMAC2B(hashAlg, &hmacObject->sensitive.sensitive.bits.b, &hmacState); // Adding HMAC data CryptUpdateDigest2B(&hmacState, &in->buffer.b); // Complete HMAC CryptCompleteHMAC2B(&hmacState, &out->outHMAC.b); return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 125 October 31, 2013 Part 3: Commands 18 Trusted Platform Module Library Random Number Generator 18.1 TPM2_GetRandom 18.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 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 digest 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. Page 126 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 18.1.2 Command and Response Table 62 — TPM2_GetRandom Command Type Name Description TPMI_ST_COMMAND_TAG tag 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 8 UINT32 responseSize TPM_RC responseCode TPM2B_DIGEST randomBytes Family “2.0” Level 00 Revision 00.99 the random octets Published Copyright © TCG 2006-2013 Page 127 October 31, 2013 Part 3: Commands Trusted Platform Module Library 18.1.3 Detailed Actions 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 #include "InternalRoutines.h" #include "GetRandom_fp.h" TPM_RC TPM2_GetRandom( GetRandom_In GetRandom_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { // Command Output // if the requested bytes exceed the output buffer size, generates the // maximum bytes that the output buffer allows if(in->bytesRequested > sizeof(TPMU_HA)) out->randomBytes.t.size = sizeof(TPMU_HA); else out->randomBytes.t.size = in->bytesRequested; CryptGenerateRandom(out->randomBytes.t.size, out->randomBytes.t.buffer); return TPM_RC_SUCCESS; } Page 128 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 18.2 Part 3: Commands TPM2_StirRandom 18.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. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 129 October 31, 2013 Part 3: Commands Trusted Platform Module Library 18.2.2 Command and Response Table 64 — TPM2_StirRandom Command Type Name Description TPMI_ST_COMMAND_TAG tag 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 8 UINT32 responseSize TPM_RC responseCode Page 130 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 18.2.3 Detailed Actions 1 2 3 4 5 6 7 8 9 10 11 12 #include "InternalRoutines.h" #include "StirRandom_fp.h" TPM_RC TPM2_StirRandom( StirRandom_In *in // IN: input parameter list ) { // Internal Data Update CryptStirRandom(in->inData.t.size, in->inData.t.buffer); return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 131 October 31, 2013 Part 3: Commands 19 Trusted Platform Module Library Hash/HMAC/Event Sequences 19.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 Part 1. 19.2 TPM2_HMAC_Start 19.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 1 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 handle references a restricted key, then the hash algorithm specified in the key's scheme is used as the hash algorithm for the HMAC and the TPM shall return TPM_RC_VALUE if hashAlg is not TPM_ALG_NULL or the same algorithm in the key's scheme. If the key referenced by handle is not restricted, then the TPM will use hashAlg for the HMAC; unless hashAlg is TPM_ALG_NULL in which case it will use the default scheme of the key. Table 66 — Hash Selection Matrix handle→restricted (key's restricted attribute) handle→scheme (hash algorithm from key's scheme) CLEAR (unrestricted) TPM_ALG_NULL CLEAR don’t care CLEAR valid hash hash used TPM_ALG_NULL error valid hash (1) hashAlg hashAlg (2) (TPM_RC_SCHEME) TPM_ALG_NULL handle→scheme same as handle→scheme handle→scheme (3) SET handle→scheme (3) SET (restricted) TPM_ALG_NULL (3) not same as handle→scheme error valid hash valid hash SET valid hash (4) (TPM_RC_SCHEME) NOTES: 1) The scheme for the handle may only be TPM_ALG_NULL if both sign and decrypt are SET. 2) A hash algorithm is required for the HMAC. 3) A restricted key is required to have a scheme with a valid hash algorithm. A restricted key may not have both sign and decrypt SET. 4) The scheme for a restricted key cannot be overridden. Page 132 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 19.2.2 Command and Response Table 67 — TPM2_HMAC_Start Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_HMAC_Start TPMI_DH_OBJECT @handle handle of an HMAC key 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 8 UINT32 responseSize TPM_RC responseCode TPMI_DH_OBJECT sequenceHandle Family “2.0” Level 00 Revision 00.99 a handle to reference the sequence Published Copyright © TCG 2006-2013 Page 133 October 31, 2013 Part 3: Commands Trusted Platform Module Library 19.2.3 Detailed Actions 1 2 #include "InternalRoutines.h" #include "HMAC_Start_fp.h" Error Returns TPM_RC_ATTRIBUTES key referenced by handle is not a signing key TPM_RC_OBJECT_MEMORY no space to create an internal object TPM_RC_TYPE key referenced by handle is not an HMAC key TPM_RC_VALUE 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 Meaning hashAlg specified when the key is restricted is neither TPM_ALG_NULL not equal to that of the key scheme; or both hashAlg and the key scheme's algorithm are TPM_ALG_NULL TPM_RC TPM2_HMAC_Start( HMAC_Start_In HMAC_Start_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { OBJECT TPMT_PUBLIC TPM_ALG_ID *hmacObject; *publicArea; hashAlg; // Input Validation // Get HMAC key object and public area pointers hmacObject = ObjectGet(in->handle); publicArea = &hmacObject->publicArea; // Make sure that the key is an HMAC signing key if(publicArea->type != TPM_ALG_KEYEDHASH) return TPM_RC_TYPE + RC_HMAC_Start_handle; if(publicArea->objectAttributes.sign != SET) return TPM_RC_ATTRIBUTES + RC_HMAC_Start_handle; // Assume that the key default scheme is used hashAlg = publicArea->parameters.keyedHashDetail.scheme.details.hmac.hashAlg; // if the key is restricted, then need to use the scheme of the key and the // input algorithm must be TPM_ALG_NULL or the same as the key scheme if(publicArea->objectAttributes.restricted == SET) { if(in->hashAlg != TPM_ALG_NULL && in->hashAlg != hashAlg) hashAlg = TPM_ALG_NULL; } else { // for a non-restricted key, use hashAlg if it is provided; if(in->hashAlg != TPM_ALG_NULL) hashAlg = in->hashAlg; } // if the algorithm selection ended up with TPM_ALG_NULL, then either the // schemes are not compatible or no hash was provided and both conditions // are errors. if(hashAlg == TPM_ALG_NULL) return TPM_RC_VALUE + RC_HMAC_Start_hashAlg; // Internal Data Update Page 134 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 48 49 50 51 52 53 54 55 Part 3: Commands // Create a HMAC sequence object. A TPM_RC_OBJECT_MEMORY error may be // returned at this point return ObjectCreateHMACSequence(hashAlg, in->handle, &in->auth, &out->sequenceHandle); } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 135 October 31, 2013 Part 3: Commands 19.3 Trusted Platform Module Library TPM2_HashSequenceStart 19.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 structure or an Event sequence structure. Additionally, it will assign a handle to the sequence and set the authValue of the sequence to the value in auth. A sequence structure for an Event (hashAlg = TPM_ALG_NULL) contains a hash context for each of the PCR banks implemented on the TPM. Page 136 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 19.3.2 Command and Response Table 69 — TPM2_HashSequenceStart Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_HashSequenceStart TPM2B_AUTH auth authorization value for subsequent use of the sequence TPMI_ALG_HASH+ hashAlg the hash algorithm to use for the hash sequence An Event sequence starts if this is TPM_ALG_NULL. Table 70 — TPM2_HashSequenceStart Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode TPMI_DH_OBJECT sequenceHandle Family “2.0” Level 00 Revision 00.99 a handle to reference the sequence Published Copyright © TCG 2006-2013 Page 137 October 31, 2013 Part 3: Commands Trusted Platform Module Library 19.3.3 Detailed Actions 1 2 #include "InternalRoutines.h" #include "HashSequenceStart_fp.h" Error Returns TPM_RC_OBJECT_MEMORY 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 Meaning no space to create an internal object TPM_RC TPM2_HashSequenceStart( HashSequenceStart_In HashSequenceStart_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { // Internal Data Update if(in->hashAlg == TPM_ALG_NULL) // Start a event sequence. A TPM_RC_OBJECT_MEMORY error may be // returned at this point return ObjectCreateEventSequence(&in->auth, &out->sequenceHandle); // Start a hash sequence. A TPM_RC_OBJECT_MEMORY error may be // returned at this point return ObjectCreateHashSequence(in->hashAlg, &in->auth, &out->sequenceHandle); } Page 138 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 19.4 Part 3: Commands TPM2_SequenceUpdate 19.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 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 This requirement allows the TPM to validate that the first block is safe to sign without having to accumulate octets over multiple calls. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 139 October 31, 2013 Part 3: Commands Trusted Platform Module Library 19.4.2 Command and Response Table 71 — TPM2_SequenceUpdate Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_SequenceUpdate TPMI_DH_OBJECT @sequenceHandle handle for the sequence object 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 8 UINT32 responseSize TPM_RC responseCode Page 140 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 19.4.3 Detailed Actions 1 2 #include "InternalRoutines.h" #include "SequenceUpdate_fp.h" Error Returns TPM_RC_MODE 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 Meaning sequenceHandle does not reference a hash or HMAC sequence object TPM_RC TPM2_SequenceUpdate( SequenceUpdate_In *in // IN: input parameter list ) { OBJECT *object; // Input Validation // Get sequence object pointer object = ObjectGet(in->sequenceHandle); // Check that referenced object is a sequence object. if(!ObjectIsSequence(object)) return TPM_RC_MODE + RC_SequenceUpdate_sequenceHandle; // Internal Data Update if(object->attributes.eventSeq == SET) { // Update event sequence object UINT32 i; HASH_OBJECT *hashObject = (HASH_OBJECT *)object; for(i = 0; i < HASH_COUNT; i++) { // Update sequence object CryptUpdateDigest2B(&hashObject->state.hashState[i], &in->buffer.b); } } else { HASH_OBJECT *hashObject = (HASH_OBJECT *)object; // Update hash/HMAC sequence object if(hashObject->attributes.hashSeq == SET) { // Is this the first block of the sequence if(hashObject->attributes.firstBlock == CLEAR) { // If so, indicate that first block was received hashObject->attributes.firstBlock = SET; // Check the first block to see if the first block can contain // the TPM_GENERATED_VALUE. If it does, it is not safe for // a ticket. if(TicketIsSafe(&in->buffer.b)) hashObject->attributes.ticketSafe = SET; } // Update sequence object hash/HMAC stack CryptUpdateDigest2B(&hashObject->state.hashState[0], &in->buffer.b); Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 141 October 31, 2013 Part 3: Commands 54 55 56 57 58 59 60 61 62 63 64 65 Trusted Platform Module Library } else if(object->attributes.hmacSeq == SET) { HASH_OBJECT *hashObject = (HASH_OBJECT *)object; // Update sequence object hash/HMAC stack CryptUpdateDigest2B(&hashObject->state.hmacState, &in->buffer.b); } } return TPM_RC_SUCCESS; } Page 142 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 19.5 Part 3: Commands TPM2_SequenceComplete 19.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. 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. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 143 October 31, 2013 Part 3: Commands Trusted Platform Module Library 19.5.2 Command and Response Table 73 — TPM2_SequenceComplete Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_SequenceComplete {F} TPMI_DH_OBJECT @sequenceHandle authorization for the sequence 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 8 UINT32 responseSize TPM_RC responseCode TPM2B_DIGEST result the returned HMAC or digest in a sized buffer TPMT_TK_HASHCHECK validation ticket indicating that the sequence of octets used to compute outDigest did not start with TPM_GENERATED_VALUE This is a NULL Ticket when the session is HMAC. Page 144 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 19.5.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "SequenceComplete_fp.h" #include Error Returns TPM_RC_TYPE 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 Meaning sequenceHandle does not reference a hash or HMAC sequence object TPM_RC TPM2_SequenceComplete( SequenceComplete_In SequenceComplete_Out *in, *out OBJECT // IN: input parameter list // OUT: output parameter list *object; ) { // Input validation // Get hash object pointer object = ObjectGet(in->sequenceHandle); // input handle must be a hash or HMAC sequence object. if( object->attributes.hashSeq == CLEAR && object->attributes.hmacSeq == CLEAR) return TPM_RC_MODE + RC_SequenceComplete_sequenceHandle; // Command Output if(object->attributes.hashSeq == SET) // sequence object for hash { // Update last piece of data HASH_OBJECT *hashObject = (HASH_OBJECT *)object; CryptUpdateDigest2B(&hashObject->state.hashState[0], &in->buffer.b); // Complete hash out->result.t.size = CryptGetHashDigestSize( CryptGetContextAlg(&hashObject->state.hashState[0])); CryptCompleteHash2B(&hashObject->state.hashState[0], &out->result.b); // Check if the first block of the sequence has been received if(hashObject->attributes.firstBlock == CLEAR) { // If not, then this is the first block so see if it is 'safe' // to sign. if(TicketIsSafe(&in->buffer.b)) hashObject->attributes.ticketSafe = SET; } // Output ticket out->validation.tag = TPM_ST_HASHCHECK; out->validation.hierarchy = in->hierarchy; if(in->hierarchy == TPM_RH_NULL) { // Ticket is not required out->validation.digest.t.size = 0; Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 145 October 31, 2013 Part 3: Commands 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 Trusted Platform Module Library } else if(object->attributes.ticketSafe == CLEAR) { // Ticket is not safe to generate out->validation.hierarchy = TPM_RH_NULL; out->validation.digest.t.size = 0; } else { // Compute ticket TicketComputeHashCheck(out->validation.hierarchy, &out->result, &out->validation); } } else { HASH_OBJECT *hashObject = (HASH_OBJECT *)object; // Update last piece of data CryptUpdateDigest2B(&hashObject->state.hmacState, &in->buffer.b); // Complete hash/HMAC out->result.t.size = CryptGetHashDigestSize( CryptGetContextAlg(&hashObject->state.hmacState.hashState)); CryptCompleteHMAC2B(&(hashObject->state.hmacState), &out->result.b); // No ticket is generated for HMAC sequence out->validation.tag = TPM_ST_HASHCHECK; out->validation.hierarchy = TPM_RH_NULL; out->validation.digest.t.size = 0; } // Internal Data Update // mark sequence object as evict so it will be flushed on the way out object->attributes.evict = SET; return TPM_RC_SUCCESS; } Page 146 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 19.6 Part 3: Commands TPM2_EventSequenceComplete 19.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. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 147 October 31, 2013 Part 3: Commands Trusted Platform Module Library 19.6.2 Command and Response Table 75 — TPM2_EventSequenceComplete Command Type Name TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_EventSequenceComplete {NV F} TPMI_DH_PCR+ @pcrHandle PCR to be extended with the Event data Auth Index: 1 Auth Role: USER TPMI_DH_OBJECT @sequenceHandle authorization for the sequence Auth Index: 2 Auth Role: USER TPM2B_MAX_BUFFER buffer data to be added to the Event Description Table 76 — TPM2_EventSequenceComplete Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode TPML_DIGEST_VALUES results Page 148 October 31, 2013 list of digests computed for the PCR Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 19.6.3 Detailed Actions 1 2 #include "InternalRoutines.h" #include "EventSequenceComplete_fp.h" Error Returns TPM_RC_LOCALITY PCR extension is not allowed at the current locality TPM_RC_MODE 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 Meaning input handle is not a valid event sequence object TPM_RC TPM2_EventSequenceComplete( EventSequenceComplete_In EventSequenceComplete_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { TPM_RC HASH_OBJECT UINT32 TPM_ALG_ID result; *hashObject; i; hashAlg; // Input validation // get the event sequence object pointer hashObject = (HASH_OBJECT *)ObjectGet(in->sequenceHandle); // input handle must reference an event sequence object if(hashObject->attributes.eventSeq != SET) return TPM_RC_MODE + RC_EventSequenceComplete_sequenceHandle; // see if a PCR extend is requested in call if(in->pcrHandle != TPM_RH_NULL) { // see if extend of the PCR is allowed at the locality of the command, if(!PCRIsExtendAllowed(in->pcrHandle)) return TPM_RC_LOCALITY; // if an extend is going to take place, then check to see if there has // been an orderly shutdown. If so, and the selected PCR is one of the // state saved PCR, then the orderly state has to change. The orderly state // does not change for PCR that are not preserved. // NOTE: This doesn't just check for Shutdown(STATE) because the orderly // state will have to change if this is a state-saved PCR regardless // of the current state. This is because a subsequent Shutdown(STATE) will // check to see if there was an orderly shutdown and not do anything if // there was. So, this must indicate that a future Shutdown(STATE) has // something to do. if(gp.orderlyState != SHUTDOWN_NONE && PCRIsStateSaved(in->pcrHandle)) { result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; g_clearOrderly = TRUE; } } // Command Output out->results.count = 0; for(i = 0; i < HASH_COUNT; i++) { hashAlg = CryptGetHashAlgByIndex(i); Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 149 October 31, 2013 Part 3: Commands 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 Trusted Platform Module Library // Update last piece of data CryptUpdateDigest2B(&hashObject->state.hashState[i], &in->buffer.b); // Complete hash out->results.digests[out->results.count].hashAlg = hashAlg; CryptCompleteHash(&hashObject->state.hashState[i], CryptGetHashDigestSize(hashAlg), (BYTE *) &out->results.digests[out->results.count].digest); // Extend PCR if(in->pcrHandle != TPM_RH_NULL) PCRExtend(in->pcrHandle, hashAlg, CryptGetHashDigestSize(hashAlg), (BYTE *) &out->results.digests[out->results.count].digest); out->results.count++; } // Internal Data Update // mark sequence object as evict so it will be flushed on the way out hashObject->attributes.evict = SET; return TPM_RC_SUCCESS; } Page 150 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands Attestation Commands 20 20.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. For all signing commands, provisions are made for the caller to provide 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. 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, 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. 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 Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 151 October 31, 2013 Part 3: Commands Trusted Platform Module Library hashed and signed. However, for some schemes such as ECDAA, the qualifyingData is used in a different manner (for details, see “ECDAA” in Part 1). Page 152 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 20.2 Part 3: Commands TPM2_Certify 20.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 selfconsistent 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 20.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 matched sensitive area, then the public area may not represent a valid object a nd 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. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 153 October 31, 2013 Part 3: Commands Trusted Platform Module Library 20.2.2 Command and Response Table 77 — TPM2_Certify Command Type Name TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_Certify TPMI_DH_OBJECT @objectHandle handle of the object to be certified Auth Index: 1 Auth Role: ADMIN TPMI_DH_OBJECT+ @signHandle handle of the key used to sign the attestation structure Auth Index: 2 Auth Role: USER TPM2B_DATA qualifyingData user provided qualifying data TPMT_SIG_SCHEME+ inScheme signing scheme to use if the scheme for signHandle is TPM_ALG_NULL Description Table 78 — TPM2_Certify Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode . TPM2B_ATTEST certifyInfo the structure that was signed TPMT_SIGNATURE signature the asymmetric signature over certifyInfo using the key referenced by signHandle Page 154 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 20.2.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "Attest_spt_fp.h" #include "Certify_fp.h" Error Returns TPM_RC_KEY key referenced by signHandle is not a signing key TPM_RC_SCHEME inScheme is not compatible with signHandle TPM_RC_VALUE 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 Meaning 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). TPM_RC TPM2_Certify( Certify_In Certify_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { TPM_RC TPMS_ATTEST result; certifyInfo; // Command Output // Filling in attest information // Common fields result = FillInAttestInfo(in->signHandle, &in->inScheme, &in->qualifyingData, &certifyInfo); if(result != TPM_RC_SUCCESS) { if(result == TPM_RC_KEY) return TPM_RC_KEY + RC_Certify_signHandle; else return RcSafeAddToResult(result, RC_Certify_inScheme); } // Certify specific fields // Attestation type certifyInfo.type = TPM_ST_ATTEST_CERTIFY; // Certified object name certifyInfo.attested.certify.name.t.size = ObjectGetName(in->objectHandle, &certifyInfo.attested.certify.name.t.name); // Certified object qualified name ObjectGetQualifiedName(in->objectHandle, &certifyInfo.attested.certify.qualifiedName); // Sign attestation structure. A NULL signature will be returned if // signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE, // TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned // by SignAttestInfo() result = SignAttestInfo(in->signHandle, &in->inScheme, &certifyInfo, &in->qualifyingData, &out->certifyInfo, Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 155 October 31, 2013 Part 3: Commands 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 Trusted Platform Module Library &out->signature); // TPM_RC_ATTRIBUTES cannot be returned here as FillInAttestInfo would already // have returned TPM_RC_KEY pAssert(result != TPM_RC_ATTRIBUTES); if(result != TPM_RC_SUCCESS) return result; // orderly state should be cleared because of the reporting of clock info // if signing happens if(in->signHandle != TPM_RH_NULL) g_clearOrderly = TRUE; return TPM_RC_SUCCESS; } Page 156 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 20.3 Part 3: Commands TPM2_CertifyCreation 20.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 20.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(). Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 157 October 31, 2013 Part 3: Commands Trusted Platform Module Library 20.3.2 Command and Response Table 79 — TPM2_CertifyCreation Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_CertifyCreation TPMI_DH_OBJECT+ @signHandle handle of the key that will sign the attestation block Auth Index: 1 Auth Role: USER TPMI_DH_OBJECT objectHandle the object associated with the creation data Auth Index: None TPM2B_DATA qualifyingData user-provided qualifying data TPM2B_DIGEST creationHash hash of the creation data produced by TPM2_Create() or TPM2_CreatePrimary() TPMT_SIG_SCHEME+ inScheme signing scheme to use if the scheme for signHandle is TPM_ALG_NULL TPMT_TK_CREATION creationTicket ticket produced by TPM2_Create() or TPM2_CreatePrimary() Table 80 — TPM2_CertifyCreation Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode TPM2B_ATTEST certifyInfo the structure that was signed TPMT_SIGNATURE signature the signature over certifyInfo Page 158 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 20.3.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "Attest_spt_fp.h" #include "CertifyCreation_fp.h" Error Returns 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 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 Meaning 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). TPM_RC TPM2_CertifyCreation( CertifyCreation_In CertifyCreation_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { TPM_RC TPM2B_NAME TPMT_TK_CREATION TPMS_ATTEST result; name; ticket; certifyInfo; // Input Validation // CertifyCreation specific input validation // Get certified object name name.t.size = ObjectGetName(in->objectHandle, &name.t.name); // Re-compute ticket TicketComputeCreation(in->creationTicket.hierarchy, &name, &in->creationHash, &ticket); // Compare ticket if(!Memory2BEqual(&ticket.digest.b, &in->creationTicket.digest.b)) return TPM_RC_TICKET + RC_CertifyCreation_creationTicket; // Command Output // Common fields result = FillInAttestInfo(in->signHandle, &in->inScheme, &in->qualifyingData, &certifyInfo); if(result != TPM_RC_SUCCESS) { if(result == TPM_RC_KEY) return TPM_RC_KEY + RC_CertifyCreation_signHandle; else return RcSafeAddToResult(result, RC_CertifyCreation_inScheme); } // CertifyCreation specific fields // Attestation type certifyInfo.type = TPM_ST_ATTEST_CREATION; certifyInfo.attested.creation.objectName = name; // Copy the creationHash certifyInfo.attested.creation.creationHash = in->creationHash; Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 159 October 31, 2013 Part 3: Commands 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 Trusted Platform Module Library // Sign attestation structure. A NULL signature will be returned if // signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE, // TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned at // this point result = SignAttestInfo(in->signHandle, &in->inScheme, &certifyInfo, &in->qualifyingData, &out->certifyInfo, &out->signature); // TPM_RC_ATTRIBUTES cannot be returned here as FillInAttestInfo would already // have returned TPM_RC_KEY pAssert(result != TPM_RC_ATTRIBUTES); if(result != TPM_RC_SUCCESS) return result; // orderly state should be cleared because of the reporting of clock info // if signing happens if(in->signHandle != TPM_RH_NULL) g_clearOrderly = TRUE; return TPM_RC_SUCCESS; } Page 160 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 20.4 Part 3: Commands TPM2_Quote 20.4.1 General Description This command is used to quote PCR values. NOTE See 20.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 Part 1, Selecting Multiple PCR. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 161 October 31, 2013 Part 3: Commands Trusted Platform Module Library 20.4.2 Command and Response Table 81 — TPM2_Quote Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_Quote TPMI_DH_OBJECT @signHandle handle of key that will perform signature Auth Index: 1 Auth Role: USER TPM2B_DATA qualifyingData data supplied by the caller TPMT_SIG_SCHEME+ inScheme signing scheme to use if the scheme for signHandle is TPM_ALG_NULL TPML_PCR_SELECTION PCRselect PCR set to quote Table 82 — TPM2_Quote Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode TPM2B_ATTEST quoted the quoted information TPMT_SIGNATURE signature the signature over quoted Page 162 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 20.4.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "Attest_spt_fp.h" #include "Quote_fp.h" Error Returns TPM_RC_KEY signHandle does not reference a signing key; TPM_RC_SCHEME 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 Meaning 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 TPM2_Quote( Quote_In Quote_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { TPM_RC TPMI_ALG_HASH TPMS_ATTEST result; hashAlg; quoted; // Command Output // Filling in attest information // Common fields // FillInAttestInfo will return TPM_RC_SCHEME or TPM_RC_KEY result = FillInAttestInfo(in->signHandle, &in->inScheme, &in->qualifyingData, "ed); if(result != TPM_RC_SUCCESS) { if(result == TPM_RC_KEY) return TPM_RC_KEY + RC_Quote_signHandle; else return RcSafeAddToResult(result, RC_Quote_inScheme); } // Quote specific fields // Attestation type quoted.type = TPM_ST_ATTEST_QUOTE; // Get hash algorithm in sign scheme. This hash algorithm is used to // compute PCR digest. If there is no algorithm, then the PCR cannot // be digested and this command returns TPM_RC_SCHEME hashAlg = in->inScheme.details.any.hashAlg; if(hashAlg == TPM_ALG_NULL) return TPM_RC_SCHEME + RC_Quote_inScheme; // Compute PCR digest PCRComputeCurrentDigest(hashAlg, &in->PCRselect, "ed.attested.quote.pcrDigest); // Copy PCR select. "PCRselect" is modified in PCRComputeCurrentDigest // function quoted.attested.quote.pcrSelect = in->PCRselect; Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 163 October 31, 2013 Part 3: Commands 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 Trusted Platform Module Library // Sign attestation structure. A NULL signature will be returned if // signHandle is TPM_RH_NULL. TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES // error may be returned by SignAttestInfo. // NOTE: TPM_RC_ATTRIBUTES means that the key is not a signing key but that // was checked above and TPM_RC_KEY was returned. TPM_RC_VALUE means that the // value to sign is too large but that means that the digest is too big and // that can't happen. result = SignAttestInfo(in->signHandle, &in->inScheme, "ed, &in->qualifyingData, &out->quoted, &out->signature); if(result != TPM_RC_SUCCESS) return result; // orderly state should be cleared because of the reporting of clock info // if signing happens if(in->signHandle != TPM_RH_NULL) g_clearOrderly = TRUE; return TPM_RC_SUCCESS; } Page 164 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 20.5 Part 3: Commands TPM2_GetSessionAuditDigest 20.5.1 General Description This command returns a digital signature of the audit session digest. NOTE 1 See 20.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 endorsementAuth) 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 The audit session digest will be reset if the sessionHandle is used as the audit session for the command and the auditReset attribute of the session is set; and this command will be the first command in the audit digest. NOTE 4 A reason for using 'sessionHahdle' in this command is so that the continueSession attribute may be CLEAR. This will flush the session at the end of the command. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 165 October 31, 2013 Part 3: Commands Trusted Platform Module Library 20.5.2 Command and Response Table 83 — TPM2_GetSessionAuditDigest Command Type Name TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_GetSessionAuditDigest TPMI_RH_ENDORSEMENT @privacyAdminHandle handle of the privacy administrator (TPM_RH_ENDORSEMENT) Auth Index: 1 Auth Role: USER TPMI_DH_OBJECT+ @signHandle handle of the signing key Auth Index: 2 Auth Role: USER TPMI_SH_HMAC sessionHandle handle of the audit session Auth Index: None TPM2B_DATA qualifyingData user-provided qualifying data – may be zero-length TPMT_SIG_SCHEME+ inScheme signing scheme to use if the scheme for signHandle is TPM_ALG_NULL Description Table 84 — TPM2_GetSessionAuditDigest Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode TPM2B_ATTEST auditInfo the audit information that was signed TPMT_SIGNATURE signature the signature over auditInfo Page 166 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 20.5.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "Attest_spt_fp.h" #include "GetSessionAuditDigest_fp.h" Error Returns 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 nonempty default key scheme differs from scheme TPM_RC_TYPE sessionHandle does not reference an audit session TPM_RC_VALUE 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 Meaning 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) TPM_RC TPM2_GetSessionAuditDigest( GetSessionAuditDigest_In GetSessionAuditDigest_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { TPM_RC SESSION TPMS_ATTEST result; *session; auditInfo; // Input Validation // SessionAuditDigest specific input validation // Get session pointer session = SessionGet(in->sessionHandle); // session must be an audit session if(session->attributes.isAudit == CLEAR) return TPM_RC_TYPE + RC_GetSessionAuditDigest_sessionHandle; // Command Output // Filling in attest information // Common fields result = FillInAttestInfo(in->signHandle, &in->inScheme, &in->qualifyingData, &auditInfo); if(result != TPM_RC_SUCCESS) { if(result == TPM_RC_KEY) return TPM_RC_KEY + RC_GetSessionAuditDigest_signHandle; else return RcSafeAddToResult(result, RC_GetSessionAuditDigest_inScheme); } // SessionAuditDigest specific fields // Attestation type auditInfo.type = TPM_ST_ATTEST_SESSION_AUDIT; // Copy digest Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 167 October 31, 2013 Part 3: Commands 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 Trusted Platform Module Library auditInfo.attested.sessionAudit.sessionDigest = session->u2.auditDigest; // Exclusive audit session if(g_exclusiveAuditSession == in->sessionHandle) auditInfo.attested.sessionAudit.exclusiveSession = TRUE; else auditInfo.attested.sessionAudit.exclusiveSession = FALSE; // Sign attestation structure. A NULL signature will be returned if // signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE, // TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned at // this point result = SignAttestInfo(in->signHandle, &in->inScheme, &auditInfo, &in->qualifyingData, &out->auditInfo, &out->signature); if(result != TPM_RC_SUCCESS) return result; // orderly state should be cleared because of the reporting of clock info // if signing happens if(in->signHandle != TPM_RH_NULL) g_clearOrderly = TRUE; return TPM_RC_SUCCESS; } Page 168 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 20.6 Part 3: Commands TPM2_GetCommandAuditDigest 20.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 20.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. 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 endorsementAuth) as well as authorization to use the key associated with signHandle. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 169 October 31, 2013 Part 3: Commands Trusted Platform Module Library 20.6.2 Command and Response Table 85 — TPM2_GetCommandAuditDigest Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_GetCommandAuditDigest {NV} TPMI_RH_ENDORSEMENT @privacyHandle handle of the privacy administrator (TPM_RH_ENDORSEMENT) Auth Index: 1 Auth Role: USER TPMI_DH_OBJECT+ @signHandle the handle of the signing key Auth Index: 2 Auth Role: USER TPM2B_DATA qualifyingData other data to associate with this audit digest TPMT_SIG_SCHEME+ inScheme signing scheme to use if the scheme for signHandle is TPM_ALG_NULL Table 86 — TPM2_GetCommandAuditDigest Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode TPM2B_ATTEST auditInfo the auditInfo that was signed TPMT_SIGNATURE signature the signature over auditInfo Page 170 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 20.6.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "Attest_spt_fp.h" #include "GetCommandAuditDigest_fp.h" Error Returns 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 nonempty default key scheme differs from scheme TPM_RC_VALUE 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 Meaning 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) TPM_RC TPM2_GetCommandAuditDigest( GetCommandAuditDigest_In GetCommandAuditDigest_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { TPM_RC TPMS_ATTEST result; auditInfo; // Command Output // Filling in attest information // Common fields result = FillInAttestInfo(in->signHandle, &in->inScheme, &in->qualifyingData, &auditInfo); if(result != TPM_RC_SUCCESS) { if(result == TPM_RC_KEY) return TPM_RC_KEY + RC_GetCommandAuditDigest_signHandle; else return RcSafeAddToResult(result, RC_GetCommandAuditDigest_inScheme); } // CommandAuditDigest specific fields // Attestation type auditInfo.type = TPM_ST_ATTEST_COMMAND_AUDIT; // Copy audit hash algorithm auditInfo.attested.commandAudit.digestAlg = gp.auditHashAlg; // Copy counter value auditInfo.attested.commandAudit.auditCounter = gp.auditCounter; // Copy command audit log auditInfo.attested.commandAudit.auditDigest = gr.commandAuditDigest; CommandAuditGetDigest(&auditInfo.attested.commandAudit.commandDigest); // // // // Sign attestation structure. A NULL signature will be returned if signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE, TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned at this point Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 171 October 31, 2013 Part 3: Commands 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 Trusted Platform Module Library result = SignAttestInfo(in->signHandle, &in->inScheme, &auditInfo, &in->qualifyingData, &out->auditInfo, &out->signature); if(result != TPM_RC_SUCCESS) return result; // Internal Data Update if(in->signHandle != TPM_RH_NULL) { // Reset log gr.commandAuditDigest.t.size = 0; // orderly state should be cleared because of the update in // commandAuditDigest, as well as the reporting of clock info g_clearOrderly = TRUE; } return TPM_RC_SUCCESS; } Page 172 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 20.7 Part 3: Commands TPM2_GetTime 20.7.1 General Description This command returns the current values of Time and Clock. NOTE 1 See 20.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 TPM_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. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 173 October 31, 2013 Part 3: Commands Trusted Platform Module Library 20.7.2 Command and Response Table 87 — TPM2_GetTime Command Type Name TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_GetTime TPMI_RH_ENDORSEMENT @privacyAdminHandle handle of the privacy administrator (TPM_RH_ENDORSEMENT) Auth Index: 1 Auth Role: USER TPMI_DH_OBJECT+ @signHandle the keyHandle identifier of a loaded key that can perform digital signatures Auth Index: 2 Auth Role: USER TPM2B_DATA qualifyingData data to tick stamp TPMT_SIG_SCHEME+ inScheme signing scheme to use if the scheme for signHandle is TPM_ALG_NULL Description Table 88 — TPM2_GetTime Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode . TPM2B_ATTEST timeInfo standard TPM-generated attestation block TPMT_SIGNATURE signature the signature over timeInfo Page 174 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 20.7.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "Attest_spt_fp.h" #include "GetTime_fp.h" Error Returns 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 nonempty default key scheme differs from scheme TPM_RC_VALUE 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 Meaning 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) TPM_RC TPM2_GetTime( GetTime_In GetTime_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { TPM_RC TPMS_ATTEST result; timeInfo; // Command Output // Filling in attest information // Common fields result = FillInAttestInfo(in->signHandle, &in->inScheme, &in->qualifyingData, &timeInfo); if(result != TPM_RC_SUCCESS) { if(result == TPM_RC_KEY) return TPM_RC_KEY + RC_GetTime_signHandle; else return RcSafeAddToResult(result, RC_GetTime_inScheme); } // GetClock specific fields // Attestation type timeInfo.type = TPM_ST_ATTEST_TIME; // current clock in plain text timeInfo.attested.time.time.time = g_time; TimeFillInfo(&timeInfo.attested.time.time.clockInfo); // Firmware version in plain text timeInfo.attested.time.firmwareVersion = ((UINT64) gp.firmwareV1) << 32; timeInfo.attested.time.firmwareVersion += gp.firmwareV2; // Sign attestation structure. A NULL signature will be returned if // signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE, // TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned at // this point result = SignAttestInfo(in->signHandle, Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 175 October 31, 2013 Part 3: Commands 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 Trusted Platform Module Library &in->inScheme, &timeInfo, &in->qualifyingData, &out->timeInfo, &out->signature); if(result != TPM_RC_SUCCESS) return result; // orderly state should be cleared because of the reporting of clock info // if signing happens if(in->signHandle != TPM_RH_NULL) g_clearOrderly = TRUE; return TPM_RC_SUCCESS; } Page 176 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 21 Part 3: Commands Ephemeral EC Keys 21.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 TPMgenerated 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 part 1. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 177 October 31, 2013 Part 3: Commands 21.2 Trusted Platform Module Library TPM2_Commit 21.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) using an anonymous signing scheme (TPM_RC_SCHEME). 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. If p1, s2, and y2 are all Empty Buffers, the TPM shall return TPM_RC_NO_RESULT. In the algorithm below, the following additional values are used in addition to the command parameters: HnameAlg hash function using the nameAlg of the key associated with signHandle p field modulus of the curve associated with signHandle n order of the curve associated with signHandle ds private key associated with signHandle c counter that increments each time a TPM2_Commit() is successfully completed A[i] array of bits used to indicate when a value of c has been used in a signing operation; values of i are 0 to 2n-1 k nonce that is set to a random value on each TPM Reset; nonce size is twice the security strength of any ECDAA key supported by the TPM. The algorithm is: a) set K, L, and E to be Empty Buffers. b) if s2 is not an Empty Buffer, compute x2 ≔ HnameAlg (s2) mod p, else skip to step (e) c) if (x2, y2) is not a point on the curve of signHandle, return TPM_RC_ECC_POINT d) set K ≔ [ds] (x2, y2) e) generate or derive r (see the "Commit Random Value" clause in Part 1) f) set r ≔ r mod n NOTE 1 nLen is the number of bits in n g) if p1 is an Empty Buffer, skip to step i) h) if (p1) is not a point on the curve of signHandle, return TPM_RC_ECC_POINT i) set E ≔ [r] (p1) j) if K is not an Empty Buffer, set L ≔ [r] (x2, y2) k) if K, L, or E is the point at infinity, return TPM_RC_NO_RESULT l) set counter ≔ commitCount m) set commitCount ≔ commitCount + 1 Page 178 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library NOTE 2 Part 3: Commands Depending on the method of generating r, it may be necessary to update the tracking array here. n) output K, L, E and counter NOTE 3 Depending on the input parameters K and L may be Empty Buffers or E may be an Empty Buffer Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 179 October 31, 2013 Part 3: Commands Trusted Platform Module Library 21.2.2 Command and Response Table 89 — TPM2_Commit Command Type Name TPMI_ST_COMMAND_TAG tag UINT32 paramSize TPM_CC commandCode Description 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 8 UINT32 paramSize 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 180 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 21.2.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "Commit_fp.h" #ifdef TPM_ALG_ECC Error Returns 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 keyHandle references a restricted signing key that does not use and anonymous scheme TPM_RC_NO_RESULT K, L or E was a point at infinity; or failed to generate r value TPM_RC_SIZE 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 Meaning s2 is empty but y2 is not or s2 provided but y2 is not TPM_RC TPM2_Commit( Commit_In Commit_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { OBJECT TPMS_ECC_POINT TPMS_ECC_POINT TPMS_ECC_POINT TPM2B_ECC_PARAMETER TPM2B TPM_RC UINT16 *eccKey; P2; *pP2 = NULL; *pP1 = NULL; r; *p; result; hashResults; // Input Validation eccKey = ObjectGet(in->signHandle); // Input key must be an ECC key if(eccKey->publicArea.type != TPM_ALG_ECC) return TPM_RC_KEY + RC_Commit_signHandle; // if the key is restricted, it must be a signing key using an anonymous scheme if(eccKey->publicArea.objectAttributes.restricted == SET) { if(eccKey->publicArea.objectAttributes.sign != SET) return TPM_RC_ATTRIBUTES + RC_Commit_signHandle; if(!CryptIsSchemeAnonymous( eccKey->publicArea.parameters.eccDetail.scheme.scheme)) return TPM_RC_SCHEME + RC_Commit_signHandle; } else { // if not restricted, s2, and y2 must be an Empty Buffer if(in->s2.t.size) return TPM_RC_SIZE + RC_Commit_s2; } // Make sure that both parts of P2 are present if either is present if((in->s2.t.size == 0) != (in->y2.t.size == 0)) Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 181 October 31, 2013 Part 3: Commands 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 Trusted Platform Module Library return TPM_RC_SIZE + RC_Commit_y2; // Get prime modulus for the curve. This is needed later but getting this now // allows confirmation that the curve exists p = (TPM2B *)CryptEccGetParameter('p', eccKey->publicArea.parameters.eccDetail.curveID); // if no p, then the curve ID is bad // NOTE: This should never occur if the input unmarshaling code is working // correctly if(p == NULL) return TPM_RC_KEY + RC_Commit_signHandle; // Get the random value that will be used in the point multiplications // Note: this does not commit the count. if(!CryptGenerateR(&r, NULL, eccKey->publicArea.parameters.eccDetail.curveID, &eccKey->name)) return TPM_RC_NO_RESULT; // Set up P2 if s2 and Y2 are provided if(in->s2.t.size != 0) { pP2 = &P2; // copy y2 for P2 MemoryCopy2B(&P2.y.b, &in->y2.b, sizeof(P2.y.t.buffer)); // Compute x2 HnameAlg(s2) mod p // do the hash operation on s2 with the size of curve 'p' hashResults = CryptHashBlock(eccKey->publicArea.nameAlg, in->s2.t.size, in->s2.t.buffer, p->size, P2.x.t.buffer); // If there were error returns in the hash routine, indicate a problem // with the hash in if(hashResults == 0) return TPM_RC_HASH + RC_Commit_signHandle; // set the size of the X value to the size of the hash P2.x.t.size = hashResults; // set p2.x = hash(s2) mod p if(CryptDivide(&P2.x.b, p, NULL, &P2.x.b) != TPM_RC_SUCCESS) return TPM_RC_NO_RESULT; if(!CryptEccIsPointOnCurve(eccKey->publicArea.parameters.eccDetail.curveID, pP2)) return TPM_RC_ECC_POINT + RC_Commit_s2; if(eccKey->attributes.publicOnly == SET) return TPM_RC_KEY + RC_Commit_signHandle; } else // If there is a P1, make sure that it is on the curve // NOTE: an "empty" point has two UINT16 values which are the size values // for each of the coordinates. if(in->P1.t.size > 4) { Page 182 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 Part 3: Commands pP1 = &in->P1.t.point; if(!CryptEccIsPointOnCurve(eccKey->publicArea.parameters.eccDetail.curveID, pP1)) return TPM_RC_ECC_POINT + RC_Commit_P1; } // Pass the parameters to CryptCommit. // The work is not done inline because it does several point multiplies // with the same curve. There is significant optimization by not // having to reload the curve parameters multiple times. result = CryptCommitCompute(&out->K.t.point, &out->L.t.point, &out->E.t.point, eccKey->publicArea.parameters.eccDetail.curveID, pP1, pP2, &eccKey->sensitive.sensitive.ecc, &r); if(result != TPM_RC_SUCCESS) return result; out->K.t.size = TPMS_ECC_POINT_Marshal(&out->K.t.point, NULL, NULL); out->L.t.size = TPMS_ECC_POINT_Marshal(&out->L.t.point, NULL, NULL); out->E.t.size = TPMS_ECC_POINT_Marshal(&out->E.t.point, NULL, NULL); // The commit computation was successful so complete the commit by setting // the bit out->counter = CryptCommit(); return TPM_RC_SUCCESS; } #endif Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 183 October 31, 2013 Part 3: Commands 21.3 Trusted Platform Module Library TPM2_EC_Ephemeral 21.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 184 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 21.3.2 Command and Response Table 91 — TPM2_EC_Ephemeral Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 paramSize 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 8 UINT32 paramSize TPM_RC responseCode TPM2B_ECC_POINT Q ephemeral public key Q ≔ [r]G UINT16 counter least-significant 16 bits of commitCount Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 185 October 31, 2013 Part 3: Commands Trusted Platform Module Library 21.3.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "EC_Ephemeral_fp.h" #ifdef TPM_ALG_ECC Error Returns none 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 Meaning ... TPM_RC TPM2_EC_Ephemeral( EC_Ephemeral_In EC_Ephemeral_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { TPM2B_ECC_PARAMETER r; // Get the random value that will be used in the point multiplications // Note: this does not commit the count. if(!CryptGenerateR(&r, NULL, in->curveID, NULL)) return TPM_RC_NO_RESULT; CryptEccPointMultiply(&out->Q.t.point, in->curveID, &r, NULL); // commit the count value out->counter = CryptCommit(); return TPM_RC_SUCCESS; } #endif Page 186 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 22 Part 3: Commands Signing and Signature Verification 22.1 TPM2_VerifySignature 22.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” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 187 October 31, 2013 Part 3: Commands Trusted Platform Module Library 22.1.2 Command and Response Table 93 — TPM2_VerifySignature Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_VerifySignature TPMI_DH_OBJECT keyHandle handle of public key that will be used in the validation 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 8 UINT32 responseSize TPM_RC responseCode TPMT_TK_VERIFIED validation Page 188 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 22.1.3 Detailed Actions 1 2 #include "InternalRoutines.h" #include "VerifySignature_fp.h" Error Returns TPM_RC_ATTRIBUTES keyHandle does not reference a signing key TPM_RC_SIGNATURE signature is not genuine TPM_RC_SCHEME CryptVerifySignature() TPM_RC_HANDLE 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 Meaning the input handle is not a sign key with private portion loaded TPM_RC TPM2_VerifySignature( VerifySignature_In VerifySignature_Out *in, *out // IN: input parameter list // OUT: output parameter list TPM_RC TPM2B_NAME OBJECT TPMI_RH_HIERARCHY result; name; *signObject; hierarchy; ) { // Input Validation // Get sign object pointer signObject = ObjectGet(in->keyHandle); // The object to validate the signature must be a signing key. if(signObject->publicArea.objectAttributes.sign != SET) return TPM_RC_ATTRIBUTES + RC_VerifySignature_keyHandle; // If it doesn't have a sensitive area loaded // then it can't be a keyed hash signing key if( signObject->attributes.publicOnly == SET && signObject->publicArea.type == TPM_ALG_KEYEDHASH ) return TPM_RC_HANDLE + RC_VerifySignature_keyHandle; // Validate Signature. A TPM_RC_BINDING, TPM_RC_SCHEME or TPM_RC_SIGNATURE // error may be returned by CryptCVerifySignatrue() result = CryptVerifySignature(in->keyHandle, &in->digest, &in->signature); if(result != TPM_RC_SUCCESS) return RcSafeAddToResult(result, RC_VerifySignature_signature); // Command Output hierarchy = ObjectGetHierarchy(in->keyHandle); if( hierarchy == TPM_RH_NULL || signObject->publicArea.nameAlg == TPM_ALG_NULL) { // produce empty ticket if hierarchy is TPM_RH_NULL or nameAlg is // TPM_ALG_NULL out->validation.tag = TPM_ST_VERIFIED; out->validation.hierarchy = TPM_RH_NULL; out->validation.digest.t.size = 0; } else { Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 189 October 31, 2013 Part 3: Commands 50 51 52 53 54 55 56 57 Trusted Platform Module Library // Get object name that verifies the signature name.t.size = ObjectGetName(in->keyHandle, &name.t.name); // Compute ticket TicketComputeVerified(hierarchy, &in->digest, &name, &out->validation); } return TPM_RC_SUCCESS; } Page 190 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 22.2 Part 3: Commands TPM2_Sign 22.2.1 General Description This command causes the TPM to sign an externally provided hash with the specified asymmetric signing key. NOTE 1 Symmetric “signing” is done with an HMAC. 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 requires a hash algorithm, the hash is defined in the qualifying data of 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. As long as it is no larger than allowed, the digest parameter is not required to have any specific size but the signature operation may fail if digest is too large for the selected scheme. 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. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 191 October 31, 2013 Part 3: Commands Trusted Platform Module Library 22.2.2 Command and Response Table 95 — TPM2_Sign Command Type Name TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_Sign TPMI_DH_OBJECT @keyHandle Handle of key that will perform signing Auth Index: 1 Auth Role: USER TPM2B_DIGEST digest digest to be signed TPMT_SIG_SCHEME+ inScheme signing scheme to use if the scheme for keyHandle is TPM_ALG_NULL TPMT_TK_HASHCHECK validation proof that digest was created by the TPM If keyHandle is not a restricted signing key, then this may be a NULL Ticket with tag = TPM_ST_CHECKHASH. Description Table 96 — TPM2_Sign Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode TPMT_SIGNATURE signature Page 192 October 31, 2013 the signature Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 22.2.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "Sign_fp.h" #include "Attest_spt_fp.h" Error Returns TPM_RC_ATTRIBUTES key referenced by keHandle is not a signing key TPM_RC_BINDING The public and private portions of the key are not properly bound. TPM_RC_SCHEME inScheme is not compatible with keyHandle; both inScheme and key's default scheme are empty; or inScheme is empty while key's default scheme requires explicit input scheme (split signing); or nonempty default key scheme differs from inScheme TPM_RC_TICKET validation is not a valid ticket TPM_RC_VALUE 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 Meaning the value to sign is larger than allowed for the type of keyHandle TPM_RC TPM2_Sign( Sign_In Sign_Out *in, *out // IN: input parameter list // OUT: output parameter list TPM_RC TPMT_TK_HASHCHECK OBJECT result; ticket; *signKey; ) { // Input Validation // Get sign key pointer signKey = ObjectGet(in->keyHandle); // If validation is provided, or the key is restricted, check the ticket if( in->validation.digest.t.size != 0 || signKey->publicArea.objectAttributes.restricted == SET) { // Compute and compare ticket TicketComputeHashCheck(in->validation.hierarchy, &in->digest, &ticket); if(!Memory2BEqual(&in->validation.digest.b, &ticket.digest.b)) return TPM_RC_TICKET + RC_Sign_validation; } // Command Output // pick a scheme for sign. If the input sign scheme is not compatible with // the default scheme, return an error. result = CryptSelectSignScheme(in->keyHandle, &in->inScheme); if(result != TPM_RC_SUCCESS) { if(result == TPM_RC_KEY) return TPM_RC_KEY + RC_Sign_keyHandle; else return RcSafeAddToResult(result, RC_Sign_inScheme); } // Sign the hash. A TPM_RC_VALUE, TPM_RC_SCHEME, or TPM_RC_ATTRIBUTES // error may be returned at this point result = CryptSign(in->keyHandle, &in->inScheme, &in->digest, &out->signature); Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 193 October 31, 2013 Part 3: Commands 45 46 47 Trusted Platform Module Library return result; } Page 194 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 23 Part 3: Commands Command Audit 23.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 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” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 195 October 31, 2013 Part 3: Commands 23.2 Trusted Platform Module Library TPM2_SetCommandCodeAuditStatus 23.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, it 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 algorithm is the evidence that this command was used to change the algorithm. The commands in setList indicate the commands that 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 196 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 23.2.2 Command and Response Table 97 — TPM2_SetCommandCodeAuditStatus Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_SetCommandCodeAuditStatus {NV} TPMI_RH_PROVISION @auth TPM_RH_ENDORSEMENT or TPM_RH_PLATFORM+{PP} Auth Index: 1 Auth Role: USER TPMI_ALG_HASH+ auditAlg hash algorithm for the audit digest; if TPM_ALG_NULL, then the hash is not changed TPML_CC setList list of commands that will be added to those that will 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 8 UINT32 responseSize TPM_RC responseCode Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 197 October 31, 2013 Part 3: Commands Trusted Platform Module Library 23.2.3 Detailed Actions 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 #include "InternalRoutines.h" #include "SetCommandCodeAuditStatus_fp.h" TPM_RC TPM2_SetCommandCodeAuditStatus( SetCommandCodeAuditStatus_In *in // IN: input parameter list ) { TPM_RC UINT32 BOOL result; i; changed = FALSE; // The command needs NV update. Check if NV is available. // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at // this point result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; // Internal Data Update // Update hash algorithm if( in->auditAlg != TPM_ALG_NULL && in->auditAlg != gp.auditHashAlg) { // Can't change the algorithm and command list at the same time if(in->setList.count != 0 || in->clearList.count != 0) return TPM_RC_VALUE + RC_SetCommandCodeAuditStatus_auditAlg; // Change the hash algorithm for audit gp.auditHashAlg = in->auditAlg; // Set the digest size to a unique value that indicates that the digest // algorithm has been changed. The size will be cleared to zero in the // command audit processing on exit. gr.commandAuditDigest.t.size = 1; // Save the change of command audit data (this sets g_updateNV so that NV // will be updagted on exit.) NvWriteReserved(NV_AUDIT_HASH_ALG, &gp.auditHashAlg); } else { // Process set list for(i = 0; i < in->setList.count; i++) // If change is made in CommandAuditSet, set changed flag if(CommandAuditSet(in->setList.commandCodes[i])) changed = TRUE; // Process clear list for(i = 0; i < in->clearList.count; i++) // If change is made in CommandAuditClear, set changed flag if(CommandAuditClear(in->clearList.commandCodes[i])) changed = TRUE; // if change was made to command list, update NV if(changed) // this sets g_updateNV so that NV will be updagted on exit. NvWriteReserved(NV_AUDIT_COMMANDS, &gp.auditComands); Page 198 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 61 62 63 64 Part 3: Commands } return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 199 October 31, 2013 Part 3: Commands 24 Trusted Platform Module Library Integrity Collection (PCR) 24.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 b ecause these PCR are changed at the whim of the TCB and are not intended to represent the trust state of the platform. Page 200 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 24.2 Part 3: Commands TPM2_PCR_Extend 24.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 value 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 into the SHA1 bank and a SHA256 digest would be Extended into a 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 TPM_RH_PCR0) alg the PCR algorithm selector for the digest data[alg].buffer the bank-specific data to be extended selector (equal to pcrHandle – If no digest value is specified for a bank, then the PCR in that bank are 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. 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” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 201 October 31, 2013 Part 3: Commands Trusted Platform Module Library 24.2.2 Command and Response Table 99 — TPM2_PCR_Extend Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_PCR_Extend {NV} TPMI_DH_PCR+ @pcrHandle handle of the PCR 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 8 UINT32 responseSize TPM_RC responseCode Page 202 October 31, 2013 . Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 24.2.3 Detailed Actions 1 2 #include "InternalRoutines.h" #include "PCR_Extend_fp.h" Error Returns TPM_RC_LOCALITY 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 Meaning current command locality is not allowed to extend the PCR referenced by pcrHandle TPM_RC TPM2_PCR_Extend( PCR_Extend_In *in // IN: input parameter list ) { TPM_RC UINT32 result; i; // Input Validation // // // // // // // NOTE: This function assumes that the unmarshaling function for 'digests' will have validated that all of the indicated hash algorithms are valid. If the hash algorithms are correct, the unmarshaling code will unmarshal a digest of the size indicated by the hash algorithm. If the overall size is not consistent, the unmarshaling code will run out of input data or have input data left over. In either case, it will cause an unmarshaling error and this function will not be called. // For NULL handle, do nothing and return success if(in->pcrHandle == TPM_RH_NULL) return TPM_RC_SUCCESS; // Check if the extend operation is allowed by the current command locality if(!PCRIsExtendAllowed(in->pcrHandle)) return TPM_RC_LOCALITY; // If PCR is state saved and we need to update orderlyState, check NV // availability if(PCRIsStateSaved(in->pcrHandle) && gp.orderlyState != SHUTDOWN_NONE) { result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; g_clearOrderly = TRUE; } // Internal Data Update // Iterate input digest list to extend for(i = 0; i < in->digests.count; i++) { PCRExtend(in->pcrHandle, in->digests.digests[i].hashAlg, CryptGetHashDigestSize(in->digests.digests[i].hashAlg), (BYTE *) &in->digests.digests[i].digest); } return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 203 October 31, 2013 Part 3: Commands 24.3 Trusted Platform Module Library TPM2_PCR_Event 24.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, 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. 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 204 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 24.3.2 Command and Response Table 101 — TPM2_PCR_Event Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_PCR_Event {NV} TPMI_DH_PCR+ @pcrHandle Handle of the PCR 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 8 UINT32 responseSize TPM_RC responseCode TPML_DIGEST_VALUES digests Family “2.0” Level 00 Revision 00.99 . Published Copyright © TCG 2006-2013 Page 205 October 31, 2013 Part 3: Commands Trusted Platform Module Library 24.3.3 Detailed Actions 1 2 #include "InternalRoutines.h" #include "PCR_Event_fp.h" Error Returns TPM_RC_LOCALITY 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 Meaning current command locality is not allowed to extend the PCR referenced by pcrHandle TPM_RC TPM2_PCR_Event( PCR_Event_In PCR_Event_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { TPM_RC HASH_STATE UINT32 UINT16 result; hashState; i; size; // Input Validation // If a PCR extend is required if(in->pcrHandle != TPM_RH_NULL) { // If the PCR is not allow to extend, return error if(!PCRIsExtendAllowed(in->pcrHandle)) return TPM_RC_LOCALITY; // If PCR is state saved and we need to update orderlyState, check NV // availability if(PCRIsStateSaved(in->pcrHandle) && gp.orderlyState != SHUTDOWN_NONE) { result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; g_clearOrderly = TRUE; } } // Internal Data Update out->digests.count = HASH_COUNT; // Iterate supported PCR bank algorithms to extend for(i = 0; i < HASH_COUNT; i++) { TPM_ALG_ID hash = CryptGetHashAlgByIndex(i); out->digests.digests[i].hashAlg = hash; size = CryptStartHash(hash, &hashState); CryptUpdateDigest2B(&hashState, &in->eventData.b); CryptCompleteHash(&hashState, size, (BYTE *) &out->digests.digests[i].digest); if(in->pcrHandle != TPM_RH_NULL) PCRExtend(in->pcrHandle, hash, size, (BYTE *) &out->digests.digests[i].digest); } return TPM_RC_SUCCESS; } Page 206 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 24.4 Part 3: Commands TPM2_PCR_Read 24.4.1 General Description This command returns the values of all PCR specified in pcrSelect. 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 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 pcrValue. 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” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 207 October 31, 2013 Part 3: Commands Trusted Platform Module Library 24.4.2 Command and Response Table 103 — TPM2_PCR_Read Command Type Name Description TPMI_ST_COMMAND_TAG tag 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 8 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 TPML_DIGEST pcrValues the contents of the PCR indicated in pcrSelect as tagged digests Page 208 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 24.4.3 Detailed Actions 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 #include "InternalRoutines.h" #include "PCR_Read_fp.h" TPM_RC TPM2_PCR_Read( PCR_Read_In PCR_Read_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { // Command Output // Call PCR read function. input pcrSelectionIn parameter could be changed // to reflect the actual PCR being returned PCRRead(&in->pcrSelectionIn, &out->pcrValues, &out->pcrUpdateCounter); out->pcrSelectionOut = in->pcrSelectionIn; return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 209 October 31, 2013 Part 3: Commands 24.5 Trusted Platform Module Library TPM2_PCR_Allocate 24.5.1 General Description This command is used to set the desired PCR allocation of PCR and algorithms. This command requires platformAuth. 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 no allocation is specified for a bank, then no PCR will be allocated to that bank. 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. If the command is properly authorized, it will return 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. After this command, TPM2_Shutdown() is only allowed to have a startupType equal to TPM_SU_CLEAR. NOTE 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 implementation. 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 210 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 24.5.2 Command and Response Table 105 — TPM2_PCR_Allocate Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_PCR_Allocate {NV} TPMI_RH_PLATFORM @authHandle TPM_RH_PLATFORM+{PP} 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 8 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 UINT32 sizeAvailable Number of octets available. Computed before the allocation. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 211 October 31, 2013 Part 3: Commands Trusted Platform Module Library 24.5.3 Detailed Actions 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 #include "InternalRoutines.h" #include "PCR_Allocate_fp.h" TPM_RC TPM2_PCR_Allocate( PCR_Allocate_In PCR_Allocate_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { TPM_RC result; // The command needs NV update. Check if NV is available. // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at // this point. // Note: These codes are not listed in the return values above because it is // an implementation choice to check in this routine rather than in a common // function that is called before these actions are called. These return values // are described in the Response Code section of Part 3. result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; // Command Output // Call PCR Allocation function. out->allocationSuccess = PCRAllocate(&in->pcrAllocation, &out->maxPCR, &out->sizeNeeded, &out->sizeAvailable); // if re-configuration succeeds, set the flag to indicate PCR configuration is // going to be changed in next boot if(out->allocationSuccess == YES) g_pcrReConfig = TRUE; return TPM_RC_SUCCESS; } Page 212 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 24.6 Part 3: Commands TPM2_PCR_SetAuthPolicy 24.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” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 213 October 31, 2013 Part 3: Commands Trusted Platform Module Library 24.6.2 Command and Response Table 107 — TPM2_PCR_SetAuthPolicy Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_PCR_SetAuthPolicy {NV} TPMI_RH_PLATFORM @authHandle TPM_RH_PLATFORM+{PP} Auth Index: 1 Auth Role: USER TPM2B_DIGEST authPolicy the desired authPolicy TPMI_ALG_HASH+ policyDigest the digest 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 8 UINT32 responseSize TPM_RC responseCode Page 214 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 24.6.3 Detailed Actions 1 2 #include "InternalRoutines.h" #include "PCR_SetAuthPolicy_fp.h" Error Returns TPM_RC_SIZE size of authPolicy is not the size of a digest produced by policyDigest TPM_RC_VALUE 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 Meaning PCR referenced by pcrNum is not a member of a PCR policy group TPM_RC TPM2_PCR_SetAuthPolicy( PCR_SetAuthPolicy_In *in // IN: input parameter list ) { UINT32 groupIndex; TPM_RC result; // The command needs NV update. Check if NV is available. // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at // this point result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; // Input Validation: // Check the authPolicy consistent with hash algorithm if(in->authPolicy.t.size != CryptGetHashDigestSize(in->policyDigest)) return TPM_RC_SIZE + RC_PCR_SetAuthPolicy_authPolicy; // If PCR does not belong to a policy group, return TPM_RC_VALUE if(!PCRBelongsPolicyGroup(in->pcrNum, &groupIndex)) return TPM_RC_VALUE + RC_PCR_SetAuthPolicy_pcrNum; // Internal Data Update // Set PCR policy gp.pcrPolicies.hashAlg[groupIndex] = in->policyDigest; gp.pcrPolicies.policy[groupIndex] = in->authPolicy; // Save new policy to NV NvWriteReserved(NV_PCR_POLICIES, &gp.pcrPolicies); return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 215 October 31, 2013 Part 3: Commands 24.7 Trusted Platform Module Library TPM2_PCR_SetAuthValue 24.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 216 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 24.7.2 Command and Response Table 109 — TPM2_PCR_SetAuthValue Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_PCR_SetAuthValue TPMI_DH_PCR @pcrHandle handle for a PCR that may have an authorization value set 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 8 UINT32 responseSize TPM_RC responseCode Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 217 October 31, 2013 Part 3: Commands Trusted Platform Module Library 24.7.3 Detailed Actions 1 2 #include "InternalRoutines.h" #include "PCR_SetAuthValue_fp.h" Error Returns TPM_RC_VALUE 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 Meaning PCR referenced by pcrHandle is not a member of a PCR authorization group TPM_RC TPM2_PCR_SetAuthValue( PCR_SetAuthValue_In *in // IN: input parameter list ) { UINT32 TPM_RC groupIndex; result; // Input Validation: // If PCR does not belong to an auth group, return TPM_RC_VALUE if(!PCRBelongsAuthGroup(in->pcrHandle, &groupIndex)) return TPM_RC_VALUE; // The command may cause the orderlyState to be cleared due to the update of // state clear data. If this is the case, Check if NV is available. // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at // this point if(gp.orderlyState != SHUTDOWN_NONE) { result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; g_clearOrderly = TRUE; } // Internal Data Update // Set PCR authValue gc.pcrAuthValues.auth[groupIndex] = in->auth; return TPM_RC_SUCCESS; } Page 218 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 24.8 Part 3: Commands TPM2_PCR_Reset 24.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 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” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 219 October 31, 2013 Part 3: Commands Trusted Platform Module Library 24.8.2 Command and Response Table 111 — TPM2_PCR_Reset Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_PCR_Reset {NV} TPMI_DH_PCR @pcrHandle the PCR to reset Auth Index: 1 Auth Role: USER Table 112 — TPM2_PCR_Reset Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode Page 220 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 24.8.3 Detailed Actions 1 2 #include "InternalRoutines.h" #include "PCR_Reset_fp.h" Error Returns TPM_RC_LOCALITY 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 Meaning current command locality is not allowed to reset the PCR referenced by pcrHandle TPM_RC TPM2_PCR_Reset( PCR_Reset_In *in // IN: input parameter list ) { TPM_RC result; // Input Validation // Check if the reset operation is allowed by the current command locality if(!PCRIsResetAllowed(in->pcrHandle)) return TPM_RC_LOCALITY; // If PCR is state saved and we need to update orderlyState, check NV // availability if(PCRIsStateSaved(in->pcrHandle) && gp.orderlyState != SHUTDOWN_NONE) { result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; g_clearOrderly = TRUE; } // Internal Data Update // Reset seleccted PCR in all banks to 0 PCRSetValue(in->pcrHandle, 0); // Indicate that the PCR changed so that pcrCounter will be incremented if // necessary. PCRChanged(in->pcrHandle); return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 221 October 31, 2013 Part 3: Commands 24.9 Trusted Platform Module Library _TPM_Hash_Start 24.9.1 Description This indication from the TPM interface indicates the start of a dynamic Core Root of Trust for Measurement (D-CRTM) measurement sequence. On receipt of this indication, the TPM will initialize an 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 Event sequence context will always succeed. A platform-specific specification may allow this indication before TPM2_Startup(). NOTE If this indication occurs after TPM2_Startup(), it 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 222 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 24.9.2 Detailed Actions 1 #include "InternalRoutines.h" This function is called to process a _TPM_Hash_Start() indication. 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 void _TPM_Hash_Start(void) { TPM_RC TPMI_DH_OBJECT result; handle; // If a DRTM sequence object exists, terminate it. if(g_DRTMHandle != TPM_RH_UNASSIGNED) ObjectTerminateEvent(); // Create an event sequence object and store the handle in global // g_DRTMHandle. A TPM_RC_OBJECT_MEMORY error may be returned at this point // The null value for the 'auth' parameter will cause the sequence structure to // be allocated without being set as present. This keeps the sequence from // being left behind if the sequence is terminated early. result = ObjectCreateEventSequence(NULL, &g_DRTMHandle); // If a free slot was not available, then free up a slot. if(result != TPM_RC_SUCCESS) { // An implementation does not need to have a fixed relationship between // slot numbers and handle numbers. To handle the general case, scan for // a handle that is assigned an free it for the DRTM sequence. // In the reference implementation, the relationship between handles and // slots is fixed. So, if the call to ObjectCreateEvenSequence() // failed indicating that all slots are occupied, then the first handle we // are going to check (TRANSIENT_FIRST) will be occupied. It will be freed // so that it can be assigned for use as the DRTM sequence object. for(handle = TRANSIENT_FIRST; handle < TRANSIENT_LAST; handle++) { // try to flush the first object if(ObjectIsPresent(handle)) break; } // If the first call to find a slot fails but none of the slots is occupied // then there's a big problem pAssert(handle < TRANSIENT_LAST); // Free the slot ObjectFlush(handle); // Try to create an event sequence object again. This time, we must // succeed. result = ObjectCreateEventSequence(NULL, &g_DRTMHandle); pAssert(result == TPM_RC_SUCCESS); } return; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 223 October 31, 2013 Part 3: Commands Trusted Platform Module Library 24.10 _TPM_Hash_Data 24.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 Core Root of Trust for Measurement (CRTM) 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 DRTM Event Sequence context exists, this indication is discarded and no other action is performed. Page 224 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 24.10.2 1 2 Part 3: Commands Detailed Actions #include "InternalRoutines.h" #include "Platform.h" This function is called to process a _TPM_Hash_Data() indication. 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 void _TPM_Hash_Data( UINT32 BYTE dataSize, *data UINT32 HASH_OBJECT // IN: size of data to be extend // IN: data buffer i; *hashObject; ) { // If there is no DRTM sequence object, then _TPM_Hash_Start // was not called so this function returns without doing // anything. if(g_DRTMHandle == TPM_RH_UNASSIGNED) return; hashObject = (HASH_OBJECT *)ObjectGet(g_DRTMHandle); pAssert(hashObject->attributes.eventSeq); // For each of the implemented hash algorithms, update the digest with the // data provided. NOTE: the implementation could be done such that the TPM // only computes the hash for the banks that contain the DRTM PCR. for(i = 0; i < HASH_COUNT; i++) { // Update sequence object CryptUpdateDigest(&hashObject->state.hashState[i], dataSize, data); } return; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 225 October 31, 2013 Part 3: Commands Trusted Platform Module Library 24.11 _TPM_Hash_End 24.11.1 Description This indication from the TPM interface indicates the end of the CRTM measurement. This indication is discarded and no other action performed if the TPM does not contain a CRTM Event sequence context. NOTE A CRTM Event Sequence context is created by _TPM_Hash_Start(). If the 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, DRTM PCR. PCR[DRTM][hashAlg] ≔ HhashAlg (initial_value || HhashAlg (hash_data)) (7) where DRTM index for CRTM PCR designated by a platform-specific specification 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)) NOTE (8) 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. Page 226 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 24.11.2 1 Part 3: Commands Detailed Actions #include "InternalRoutines.h" This function is called to process a _TPM_Hash_End() indication. 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 void _TPM_Hash_End(void) { UINT32 TPM2B_DIGEST HASH_OBJECT TPMI_DH_PCR i; digest; *hashObject; pcrHandle; // If the DRTM handle is not being used, then either _TPM_Hash_Start has not // been called, _TPM_Hash_End was previously called, or some other command // was executed and the sequence was aborted. if(g_DRTMHandle == TPM_RH_UNASSIGNED) return; // Get DRTM sequence object hashObject = (HASH_OBJECT *)ObjectGet(g_DRTMHandle); // Is this _TPM_Hash_End after Startup or before if(TPMIsStarted()) { // After // Reset the DRTM PCR PCRResetDynamics(); // Extend the DRTM_PCR. pcrHandle = PCR_FIRST + DRTM_PCR; // DRTM sequence increments restartCount gr.restartCount++; } else { pcrHandle = PCR_FIRST + HCRTM_PCR; } // Complete hash and extend PCR, or if this is an HCRTM, complete // the hash and write the PCR for(i = 0; i < HASH_COUNT; i++) { TPMI_ALG_HASH hash = CryptGetHashAlgByIndex(i); // Complete hash digest.t.size = CryptGetHashDigestSize(hash); CryptCompleteHash2B(&hashObject->state.hashState[i], &digest.b); // If this is DRTM, extend to zeroed PCR // If this is H-DRTM, copy to HCRM PCR if(TPMIsStarted()) // Extend PCR PCRExtend(pcrHandle, hash, digest.t.size, digest.t.buffer); else PcrWrite(pcrHandle, hash, &digest); Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 227 October 31, 2013 Part 3: Commands 58 59 60 61 62 63 64 65 66 67 68 Trusted Platform Module Library } // Flush sequence object. ObjectFlush(g_DRTMHandle); g_DRTMHandle = TPM_RH_UNASSIGNED; g_DrtmPreStartup = TRUE; return; } Page 228 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 25 Part 3: Commands Enhanced Authorization (EA) Commands 25.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 i n 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 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” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 229 October 31, 2013 Part 3: Commands 25.2 Trusted Platform Module Library Signed Authorization Actions 25.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. 25.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 policySession→nonceTPM, then the TPM shall return TPM_RC_VALUE. it does not match 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 indicted 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. 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 does not have its default value or 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 policySession→policyDigest. NOTE 4 Page 230 October 31, 2013 if cpHashA is not the same size as PolicySession→policyDigest is the size of the digest produced by the hash algorithm used to compute policyDigest. Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 25.2.3 PolicyDigest 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) policyDigestnew+1 ≔ HpolicyAlg(policyDigestnew || arg3.buffer) (11) followed by 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 hashes 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. 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” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 231 October 31, 2013 Part 3: Commands Trusted Platform Module Library 25.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 change 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 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 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 232 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 25.2.5 Policy Ticket Creation If for TPM2_PolicySigned() or TPM2_PolicySecret() the caller specified a negative value for expiration, and the policy update succeeds, then the TPM will return a ticket that includes a value indicating when the authorization expires. 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 NOTE 2 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 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” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 233 October 31, 2013 Part 3: Commands 25.3 Trusted Platform Module Library TPM2_PolicySigned 25.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 25.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 object 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() NOTE 1 the hash associated with the auth parameter of this command 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. 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 2 This is not the cpHash of this TPM2_PolicySigned() command. policyRef EXAMPLE an opaque value determined by the authorizing entity. Set to the Empty Buffer if no value is present. 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 private key associated with key. The signature and signing parameters are combined to create the auth parameter. The TPM will perform the parameter checks listed in 25.2.2 If the parameter checks succeed, the TPM will construct a test digest (tHash) over the provided parameters using the same formulation a 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 234 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands When all validations have succeeded, policySession→policyDigest is updated by PolicyUpdate() (see 25.2.3). PolicyUpdate(TPM_CC_PolicySigned, authObject→Name, policyRef) (14) If the cpHashA parameter is not an Empty Buffer, it is copied to policySession→cpHash. The TPM will optionally produce a ticket as described in 25.2.5. Authorization to use authObject is not required. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 235 October 31, 2013 Part 3: Commands Trusted Platform Module Library 25.3.2 Command and Response Table 113 — TPM2_PolicySigned Command Type Name TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_PolicySigned TPMI_DH_OBJECT authObject handle for a public key that will validate the signature Auth Index: None TPMI_SH_POLICY policySession handle for the policy session being extended Auth Index: None TPM2B_NONCE nonceTPM the policy nonce for the session If the nonce is not included in the authorization qualification, this field is the Empty Buffer. TPM2B_DIGEST cpHashA digest of the command parameters to which this authorization is limited 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. TPM2B_NONCE policyRef a reference to a policy relating to the authorization – may be the Empty Buffer Size is limited to be no larger than the nonce size supported on the TPM. INT32 expiration time when authorization will expire, measured in seconds from the time that nonceTPM was generated If expiration is zero, a NULL Ticket is returned. TPMT_SIGNATURE auth signed authorization (not optional) Description Table 114 — TPM2_PolicySigned Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode TPM2B_TIMEOUT timeout TPMT_TK_AUTH policyTicket Page 236 October 31, 2013 implementation-specific time value, used to indicate to the TPM when the ticket expires NOTE If policyTicket is a NULL Ticket, then this shall be the Empty Buffer. produced if the command succeeds and expiration in the command was non-zero; this ticket will use the TPMT_ST_AUTH_SIGNED structure tag Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 25.3.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "Policy_spt_fp.h" #include "PolicySigned_fp.h" Error Returns 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 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 Meaning input policyID or expiration does not match the internal data in policy session TPM_RC TPM2_PolicySigned( PolicySigned_In PolicySigned_Out *in, *out // IN: input parameter list // OUT: output parameter list TPM_RC SESSION OBJECT TPM2B_NAME TPM2B_DIGEST HASH_STATE UINT32 result = TPM_RC_SUCCESS; *session; *authObject; entityName; authHash; hashState; expiration = (in->expiration < 0) ? -(in->expiration) : in->expiration; authTimeout = 0; ) { UINT64 // Input Validation // Set up local pointers session = SessionGet(in->policySession); authObject = ObjectGet(in->authObject); // the session structure // pointer for the object // providing authorization // signature // Only do input validation if this is not a trial policy session if(session->attributes.isTrialPolicy == CLEAR) { if(expiration != 0) authTimeout = expiration * 1000 + session->startTime; result = PolicyParameterChecks(session, authTimeout, &in->cpHashA, &in->nonceTPM, RC_PolicySigned_nonceTPM, RC_PolicySigned_cpHashA, RC_PolicySigned_expiration); if(result != TPM_RC_SUCCESS) Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 237 October 31, 2013 Part 3: Commands 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 Trusted Platform Module Library return result; // Re-compute the digest being signed /*(See part 3 specification) // The digest is computed as: // aHash := hash ( nonceTPM | expiration | cpHashA | policyRef) // where: // hash() the hash associated with the signed auth // nonceTPM the nonceTPM value from the TPM2_StartAuthSession . // response If the authorization is not limited to this // session, the size of this value is 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 hash of the command parameters for the command being // approved using the hash algorithm of the PSAP session. // Set to NULLauth if the authorization is not limited // to a specific command. // policyRef hash of an opaque value determined by the authorizing // object. Set to the NULLdigest if no hash is present. */ // Start hash authHash.t.size = CryptStartHash(CryptGetSignHashAlg(&in->auth), &hashState); // add nonceTPM CryptUpdateDigest2B(&hashState, &in->nonceTPM.b); // add expiration CryptUpdateDigestInt(&hashState, sizeof(UINT32), (BYTE*) &in->expiration); // add cpHashA CryptUpdateDigest2B(&hashState, &in->cpHashA.b); // add policyRef CryptUpdateDigest2B(&hashState, &in->policyRef.b); // Complete digest CryptCompleteHash2B(&hashState, &authHash.b); // Validate Signature. A TPM_RC_SCHEME, TPM_RC_TYPE or TPM_RC_SIGNATURE // error may be returned at this point result = CryptVerifySignature(in->authObject, &authHash, &in->auth); if(result != TPM_RC_SUCCESS) return RcSafeAddToResult(result, RC_PolicySigned_auth); } // Internal Data Update // Need the Name of the signing entity entityName.t.size = EntityGetName(in->authObject, &entityName.t.name); // Update policy with input policyRef and name of auth key // These values are updated even if the session is a trial session PolicyContextUpdate(TPM_CC_PolicySigned, &entityName, &in->policyRef, &in->cpHashA, authTimeout, session); // Command Output // Create ticket and timeout buffer if in->expiration < 0 and this is not // a trial session. // NOTE: PolicyParameterChecks() makes sure that nonceTPM is present // when expiration is non-zero. if( in->expiration < 0 && session->attributes.isTrialPolicy == CLEAR ) Page 238 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 Part 3: Commands { // Generate timeout buffer. The format of output timeout buffer is // TPM-specific. // Note: can't do a direct copy because the output buffer is a byte // array and it may not be aligned to accept a 64-bit value. The method // used has the side-effect of making the returned value a big-endian, // 64-bit value that is byte aligned. out->timeout.t.size = sizeof(UINT64); UINT64_TO_BYTE_ARRAY(authTimeout, out->timeout.t.buffer); // Compute policy ticket TicketComputeAuth(TPM_ST_AUTH_SIGNED, EntityGetHierarchy(in->authObject), authTimeout, &in->cpHashA, &in->policyRef, &entityName, &out->policyTicket); } else { // Generate a null ticket. // timeout buffer is null out->timeout.t.size = 0; // auth ticket is null out->policyTicket.tag = TPM_ST_AUTH_SIGNED; out->policyTicket.hierarchy = TPM_RH_NULL; out->policyTicket.digest.t.size = 0; } return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 239 October 31, 2013 Part 3: Commands 25.4 Trusted Platform Module Library TPM2_PolicySecret 25.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 authObject, 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 th is 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 25.2.2. When all validations have succeeded, policySession→policyDigest is updated by PolicyUpdate() (see 25.2.3). PolicyUpdate(TPM_CC_PolicySecret, authObject→Name, policyRef) (15) If the cpHashA command parameter is not an Empty Buffer, it is copied to cpHash in the session context. The TPM will optionally produce a ticket as described in 25.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 240 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 25.4.2 Command and Response Table 115 — TPM2_PolicySecret Command Type Name Description TPMI_ST_COMMAND_TAG tag see clause 8 UINT32 commandSize TPM_CC commandCode TPM_CC_PolicySecret TPMI_DH_ENTITY @authHandle handle for an entity providing the authorization Auth Index: 1 Auth Role: USER TPMI_SH_POLICY policySession handle for the policy session being extended Auth Index: None TPM2B_NONCE nonceTPM the policy nonce for the session If the nonce is not included in the authorization qualification, this field is the Empty Buffer. TPM2B_DIGEST cpHashA digest of the command parameters to which this authorization is limited 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. TPM2B_NONCE policyRef a reference to a policy relating to the authorization – may be the Empty Buffer Size is limited to be no larger than the nonce size supported on the TPM. INT32 expiration time when authorization will expire, measured in seconds from the time that nonceTPM was generated If expiration is zero, a NULL Ticket is returned. Table 116 — TPM2_PolicySecret Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode TPM2B_TIMEOUT timeout implementation-specific time value used to indicate to the TPM when the ticket expires; this ticket will use the TPMT_ST_AUTH_SECRET structure tag TPMT_TK_AUTH policyTicket produced if the command succeeds and expiration in the command was non-zero Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 241 October 31, 2013 Part 3: Commands Trusted Platform Module Library 25.4.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "PolicySecret_fp.h" #include "Policy_spt_fp.h" Error Returns 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 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 Meaning input policyID or expiration does not match the internal data in policy session TPM_RC TPM2_PolicySecret( PolicySecret_In PolicySecret_Out *in, *out // IN: input parameter list // OUT: output parameter list TPM_RC SESSION TPM2B_NAME UINT32 result; *session; entityName; expiration = (in->expiration < 0) ? -(in->expiration) : in->expiration; authTimeout = 0; ) { UINT64 // Input Validation // Get pointer to the session structure session = SessionGet(in->policySession); //Only do input validation if this is not a trial policy session if(session->attributes.isTrialPolicy == CLEAR) { if(expiration != 0) authTimeout = expiration * 1000 + session->startTime; result = PolicyParameterChecks(session, authTimeout, &in->cpHashA, &in->nonceTPM, RC_PolicySecret_nonceTPM, RC_PolicySecret_cpHashA, RC_PolicySecret_expiration); if(result != TPM_RC_SUCCESS) return result; } // Internal Data Update // Need the name of the authorizing entity entityName.t.size = EntityGetName(in->authHandle, &entityName.t.name); // Update policy context with input policyRef and name of auth key // This value is computed even for trial sessions. Possibly update the cpHash PolicyContextUpdate(TPM_CC_PolicySecret, &entityName, &in->policyRef, Page 242 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 Part 3: Commands &in->cpHashA, authTimeout, session); // Command Output // Create ticket and timeout buffer if in->expiration < 0 and this is not // a trial session. // NOTE: PolicyParameterChecks() makes sure that nonceTPM is present // when expiration is non-zero. if( in->expiration < 0 && session->attributes.isTrialPolicy == CLEAR ) { // Generate timeout buffer. The format of output timeout buffer is // TPM-specific. // Note: can't do a direct copy because the output buffer is a byte // array and it may not be aligned to accept a 64-bit value. The method // used has the side-effect of making the returned value a big-endian, // 64-bit value that is byte aligned. out->timeout.t.size = sizeof(UINT64); UINT64_TO_BYTE_ARRAY(authTimeout, out->timeout.t.buffer); // Compute policy ticket TicketComputeAuth(TPM_ST_AUTH_SECRET, EntityGetHierarchy(in->authHandle), authTimeout, &in->cpHashA, &in->policyRef, &entityName, &out->policyTicket); } else { // timeout buffer is null out->timeout.t.size = 0; // auth ticket is null out->policyTicket.tag = TPM_ST_AUTH_SECRET; out->policyTicket.hierarchy = TPM_RH_NULL; out->policyTicket.digest.t.size = 0; } return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 243 October 31, 2013 Part 3: Commands 25.5 Trusted Platform Module Library TPM2_PolicyTicket 25.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 25.2.2. If the checks succeed, the TPM uses the timeout, cpHashA, policyRef, and keyName 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 25.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. If the cpHashA command parameter is not an Empty Buffer, it may be copied to cpHash in the session context.as described in 25.2.1. Page 244 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 25.5.2 Command and Response Table 117 — TPM2_PolicyTicket Command Type Name Description TPMI_ST_COMMAND_TAG tag see clause 8 UINT32 commandSize TPM_CC commandCode TPM_CC_PolicyTicket TPMI_SH_POLICY policySession handle for the policy session being extended Auth Index: None TPM2B_TIMEOUT timeout time when authorization will expire The contents are TPM specific. This shall be the value returned when ticket was produced. TPM2B_DIGEST cpHashA digest of the command parameters to which this authorization is limited If it is not limited, the parameter will be the Empty Buffer. TPM2B_NONCE policyRef reference to a qualifier for the policy – may be the Empty Buffer TPM2B_NAME authName name of the object that provided the authorization TPMT_TK_AUTH ticket an authorization ticket returned by the TPM in response to a TPM2_PolicySigned() or TPM2_PolicySecret() Table 118 — TPM2_PolicyTicket Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 245 October 31, 2013 Part 3: Commands Trusted Platform Module Library 25.5.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "PolicyTicket_fp.h" #include "Policy_spt_fp.h" Error Returns 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 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 Meaning ticket is not valid TPM_RC TPM2_PolicyTicket( PolicyTicket_In *in // IN: input parameter list TPM_RC SESSION UINT64 TPMT_TK_AUTH TPM_CC result; *session; timeout; ticketToCompare; commandCode = TPM_CC_PolicySecret; ) { // Input Validation // Get pointer to the session structure session = SessionGet(in->policySession); // NOTE: A trial policy session is not allowed to use this command. // A ticket is used in place of a previously given authorization. Since // a trial policy doesn't actually authenticate, the validated // ticket is not necessary and, in place of using a ticket, one // should use the intended authorization for which the ticket // would be a subsitute. if(session->attributes.isTrialPolicy) return TPM_RCS_ATTRIBUTES + RC_PolicyTicket_policySession; // Restore timeout data. The format of timeout buffer is TPM-specific. // In this implementation, we simply copy the value of timeout to the // buffer. if(in->timeout.t.size != sizeof(UINT64)) return TPM_RC_SIZE + RC_PolicyTicket_timeout; timeout = BYTE_ARRAY_TO_UINT64(in->timeout.t.buffer); // Do the normal checks on the cpHashA and timeout values result = PolicyParameterChecks(session, timeout, &in->cpHashA, NULL, 0, // no bad nonce return RC_PolicyTicket_cpHashA, RC_PolicyTicket_timeout); if(result != TPM_RC_SUCCESS) return result; // Validate Ticket // Re-generate policy ticket by input parameters TicketComputeAuth(in->ticket.tag, in->ticket.hierarchy, timeout, &in->cpHashA, &in->policyRef, &in->authName, &ticketToCompare); Page 246 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 Part 3: Commands // Compare generated digest with input ticket digest if(!Memory2BEqual(&in->ticket.digest.b, &ticketToCompare.digest.b)) return TPM_RC_TICKET + RC_PolicyTicket_ticket; // Internal Data Update // Is this ticket to take the place of a TPM2_PolicySigned() or // a TPM2_PolicySecret()? if(in->ticket.tag == TPM_ST_AUTH_SIGNED) commandCode = TPM_CC_PolicySigned; else if(in->ticket.tag == TPM_ST_AUTH_SECRET) commandCode = TPM_CC_PolicySecret; else // There could only be two possible tag values. Any other value should // be caught by the ticket validation process. pAssert(FALSE); // Update policy context PolicyContextUpdate(commandCode, &in->authName, &in->policyRef, &in->cpHashA, timeout, session); return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 247 October 31, 2013 Part 3: Commands 25.6 Trusted Platform Module Library TPM2_PolicyOR 25.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 NOTE 1 (17) The TPM makes no check to see if the size of an entry matches the size of the digest of the policy. 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) NOTE 2 (18) 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 248 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 25.6.2 Command and Response Table 119 — TPM2_PolicyOR Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_PolicyOR. TPMI_SH_POLICY policySession handle for the policy session being extended 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 8 UINT32 responseSize TPM_RC responseCode Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 249 October 31, 2013 Part 3: Commands Trusted Platform Module Library 25.6.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "PolicyOR_fp.h" #include "Policy_spt_fp.h" Error Returns TPM_RC_VALUE 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 Meaning no digest in pHashList matched the current value of policyDigest for policySession TPM_RC TPM2_PolicyOR( PolicyOR_In *in // IN: input parameter list ) { SESSION UINT32 *session; i; // Input Validation and Update // Get pointer to the session structure session = SessionGet(in->policySession); // Compare and Update Internal Session policy if match for(i = 0; i < in->pHashList.count; i++) { if( session->attributes.isTrialPolicy == SET || (Memory2BEqual(&session->u2.policyDigest.b, &in->pHashList.digests[i].b)) ) { // Found a match HASH_STATE hashState; TPM_CC commandCode = TPM_CC_PolicyOR; // Start hash session->u2.policyDigest.t.size = CryptStartHash(session->authHashAlg, &hashState); // Set policyDigest to 0 string and add it to hash MemorySet(session->u2.policyDigest.t.buffer, 0, session->u2.policyDigest.t.size); CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); // add command code CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); // Add each of the hashes in the list for(i = 0; i < in->pHashList.count; i++) { // Extend policyDigest CryptUpdateDigest2B(&hashState, &in->pHashList.digests[i].b); } // Complete digest CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); return TPM_RC_SUCCESS; } } // None of the values in the list matched the current policyDigest return TPM_RC_VALUE + RC_PolicyOR_pHashList; Page 250 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 54 Part 3: Commands } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 251 October 31, 2013 Part 3: Commands 25.7 Trusted Platform Module Library TPM2_PolicyPCR 25.7.1 General Description This command is used to cause conditional gating of a policy based on PCR. This 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 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 incorr ect 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. If policySession→pcrUpdateCounter has not been set, then it is set to the current value of pcrUpdateCounter. 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 2 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. Page 252 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 25.7.2 Command and Response Table 121 — TPM2_PolicyPCR Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_PolicyPCR TPMI_SH_POLICY policySession handle for the policy session being extended Auth Index: None TPM2B_DIGEST pcrDigest expected digest value of the selected PCR using the 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 8 UINT32 responseSize TPM_RC responseCode Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 253 October 31, 2013 Part 3: Commands Trusted Platform Module Library 25.7.3 Detailed Actions 1 2 #include "InternalRoutines.h" #include "PolicyPCR_fp.h" Error Returns TPM_RC_VALUE if provided, pcrDigest does not match the current PCR settings TPM_RC_PCR_CHANGED 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 Meaning a previous TPM2_PolicyPCR() set pcrCounter and it has changed TPM_RC TPM2_PolicyPCR( PolicyPCR_In *in // IN: input parameter list SESSION TPM2B_DIGEST BYTE UINT32 BYTE TPM_CC HASH_STATE *session; pcrDigest; pcrs[sizeof(TPML_PCR_SELECTION)]; pcrSize; *buffer; commandCode = TPM_CC_PolicyPCR; hashState; ) { // Input Validation // Get pointer to the session structure session = SessionGet(in->policySession); // Do validation for non trial session if(session->attributes.isTrialPolicy == CLEAR) { // Make sure that this is not going to invalidate a previous PCR check if(session->pcrCounter != 0 && session->pcrCounter != gr.pcrCounter) return TPM_RC_PCR_CHANGED; // Compute current PCR digest PCRComputeCurrentDigest(session->authHashAlg, &in->pcrs, &pcrDigest); // If the caller specified the PCR digest and it does not // match the current PCR settings, return an error.. if(in->pcrDigest.t.size != 0) { if(!Memory2BEqual(&in->pcrDigest.b, &pcrDigest.b)) return TPM_RC_VALUE + RC_PolicyPCR_pcrDigest; } } else { // For trial session, just use the input PCR digest pcrDigest = in->pcrDigest; } // Internal Data Update // Update policy hash // policyDigestnew = hash( policyDigestold || TPM_CC_PolicyPCR // || pcrs || pcrDigest) // Start hash CryptStartHash(session->authHashAlg, &hashState); // add old digest CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); Page 254 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 Part 3: Commands // add commandCode CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); // add PCRS buffer = pcrs; pcrSize = TPML_PCR_SELECTION_Marshal(&in->pcrs, &buffer, NULL); CryptUpdateDigest(&hashState, pcrSize, pcrs); // add PCR digest CryptUpdateDigest2B(&hashState, &pcrDigest.b); // complete the hash and get the results CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); // update pcrCounter in session context for non trial session if(session->attributes.isTrialPolicy == CLEAR) { session->pcrCounter = gr.pcrCounter; } return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 255 October 31, 2013 Part 3: Commands 25.8 Trusted Platform Module Library TPM2_PolicyLocality 25.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. It is initialized when the policy session is started to allow 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 is 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 or 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. Page 256 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 25.8.2 Command and Response Table 123 — TPM2_PolicyLocality Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_PolicyLocality TPMI_SH_POLICY policySession handle for the policy session being extended 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 8 UINT32 responseSize TPM_RC responseCode Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 257 October 31, 2013 Part 3: Commands Trusted Platform Module Library 25.8.3 Detailed Actions 1 2 #include "InternalRoutines.h" #include "PolicyLocality_fp.h" Limit a policy to a specific locality Error Returns TPM_RC_RANGE 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 Meaning all the locality values selected by locality have been disabled by previous TPM2_PolicyLocality() calls. TPM_RC TPM2_PolicyLocality( PolicyLocality_In *in // IN: input parameter list ) { SESSION BYTE BYTE UINT32 BYTE TPM_CC HASH_STATE *session; marshalBuffer[sizeof(TPMA_LOCALITY)]; prevSetting[sizeof(TPMA_LOCALITY)]; marshalSize; *buffer; commandCode = TPM_CC_PolicyLocality; hashState; // Input Validation // Get pointer to the session structure session = SessionGet(in->policySession); // Get new locality setting in canonical form buffer = marshalBuffer; marshalSize = TPMA_LOCALITY_Marshal(&in->locality, &buffer, NULL); // Its an error if the locality parameter is zero if(marshalBuffer[0] == 0) return TPM_RC_RANGE + RC_PolicyLocality_locality; // Get existing locality setting in canonical form buffer = prevSetting; TPMA_LOCALITY_Marshal(&session->commandLocality, &buffer, NULL); // If the locality has been previously set, then it needs to be the same // tye as the input locality (i.e. both extended or both normal if(prevSetting[0] != 0 && ((prevSetting[0] <= 0) != (marshalBuffer[0] <= 0))) return TPM_RC_RANGE + RC_PolicyLocality_locality; // See if the input is a regular or extended locality if(marshalBuffer[0] < 32) { // For regular locality // The previous setting must not be an extended locality if(prevSetting[0] > 31) return TPM_RC_RANGE + RC_PolicyLocality_locality; // if there was no previous setting, start with all normal localities // enabled if(prevSetting[0] == 0) prevSetting[0] = 0x1F; // AND the new setting with the previous setting and store it in prevSetting Page 258 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 Part 3: Commands prevSetting[0] &= marshalBuffer[0]; // The result setting can not be 0 if(prevSetting[0] == 0) return TPM_RC_RANGE + RC_PolicyLocality_locality; } else { // for extended locality // if the locality has already been set, then it must match the if(prevSetting[0] != 0 && prevSetting[0] != marshalBuffer[0]) return TPM_RC_RANGE + RC_PolicyLocality_locality; // Setting is OK prevSetting[0] = marshalBuffer[0]; } // Internal Data Update // Update policy hash // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyLocality || locality) // Start hash CryptStartHash(session->authHashAlg, &hashState); // add old digest CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); // add commandCode CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); // add input locality CryptUpdateDigest(&hashState, marshalSize, marshalBuffer); // complete the digest CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); // update session locality by unmarshal function. The function must succeed // because both input and existing locality setting have been validated. buffer = prevSetting; TPMA_LOCALITY_Unmarshal(&session->commandLocality, &buffer, (INT32 *) &marshalSize); return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 259 October 31, 2013 Part 3: Commands 25.9 Trusted Platform Module Library TPM2_PolicyNV 25.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 1 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. The TPM will perform the indicated arithmetic check on the indicated portion of the selected NV Index. 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(operand.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. 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 260 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 25.9.2 Command and Response Table 125 — TPM2_PolicyNV Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_PolicyNV TPMI_RH_NV_AUTH @authHandle handle indicating the source of the authorization value Auth Index: 1 Auth Role: USER TPMI_RH_NV_INDEX nvIndex the NV Index of the area to read Auth Index: None TPMI_SH_POLICY policySession handle for the policy session being extended 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 8 UINT32 responseSize TPM_RC responseCode Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 261 October 31, 2013 Part 3: Commands Trusted Platform Module Library 25.9.3 Detailed Actions 1 2 3 4 #include #include #include #include "InternalRoutines.h" "PolicyNV_fp.h" "Policy_spt_fp.h" "NV_spt_fp.h" // Include NV support routine for read access check Error Returns 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 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 Meaning the size of nvIndex data starting at offset is less than the size of operandB TPM_RC TPM2_PolicyNV( PolicyNV_In *in // IN: input parameter list TPM_RC SESSION NV_INDEX BYTE TPM2B_NAME TPM_CC HASH_STATE TPM2B_DIGEST result; *session; nvIndex; nvBuffer[sizeof(in->operandB.t.buffer)]; nvName; commandCode = TPM_CC_PolicyNV; hashState; argHash; ) { // Input Validation // Get NV index information NvGetIndexInfo(in->nvIndex, &nvIndex); // Get pointer to the session structure session = SessionGet(in->policySession); //If this is a trial policy, skip all validations and the operation if(session->attributes.isTrialPolicy == CLEAR) { // NV Read access check. NV index should be allowed for read. A // TPM_RC_AUTH_TYPE or TPM_RC_NV_LOCKED error may be return at this // point result = NvReadAccessChecks(in->authHandle, in->nvIndex); if(result != TPM_RC_SUCCESS) return result; // Valid NV data size should not be smaller than input operandB size if((nvIndex.publicArea.dataSize - in->offset) < in->operandB.t.size) return TPM_RC_SIZE + RC_PolicyNV_operandB; // Arithmetic Comparison // Get NV data. The size of NV data equals the input operand B size NvGetIndexData(in->nvIndex, &nvIndex, in->offset, in->operandB.t.size, nvBuffer); switch(in->operation) Page 262 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 Part 3: Commands { case TPM_EO_EQ: // compare A = B if(CryptCompare(in->operandB.t.size, nvBuffer, in->operandB.t.size, in->operandB.t.buffer) return TPM_RC_POLICY; break; case TPM_EO_NEQ: // compare A != B if(CryptCompare(in->operandB.t.size, nvBuffer, in->operandB.t.size, in->operandB.t.buffer) return TPM_RC_POLICY; break; case TPM_EO_SIGNED_GT: // compare A > B signed if(CryptCompareSigned(in->operandB.t.size, nvBuffer, in->operandB.t.size, in->operandB.t.buffer) return TPM_RC_POLICY; break; case TPM_EO_UNSIGNED_GT: // compare A > B unsigned if(CryptCompare(in->operandB.t.size, nvBuffer, in->operandB.t.size, in->operandB.t.buffer) return TPM_RC_POLICY; break; case TPM_EO_SIGNED_LT: // compare A < B signed if(CryptCompareSigned(in->operandB.t.size, nvBuffer, in->operandB.t.size, in->operandB.t.buffer) return TPM_RC_POLICY; break; case TPM_EO_UNSIGNED_LT: // compare A < B unsigned if(CryptCompare(in->operandB.t.size, nvBuffer, in->operandB.t.size, in->operandB.t.buffer) return TPM_RC_POLICY; break; case TPM_EO_SIGNED_GE: // compare A >= B signed if(CryptCompareSigned(in->operandB.t.size, nvBuffer, in->operandB.t.size, in->operandB.t.buffer) return TPM_RC_POLICY; break; case TPM_EO_UNSIGNED_GE: // compare A >= B unsigned if(CryptCompare(in->operandB.t.size, nvBuffer, in->operandB.t.size, in->operandB.t.buffer) return TPM_RC_POLICY; break; case TPM_EO_SIGNED_LE: // compare A <= B signed if(CryptCompareSigned(in->operandB.t.size, nvBuffer, in->operandB.t.size, in->operandB.t.buffer) return TPM_RC_POLICY; break; case TPM_EO_UNSIGNED_LE: // compare A <= B unsigned if(CryptCompare(in->operandB.t.size, nvBuffer, in->operandB.t.size, in->operandB.t.buffer) return TPM_RC_POLICY; break; case TPM_EO_BITSET: // All bits SET in B are SET in A. ((A&B)=B) { Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 != 0) == 0) <= 0) <= 0) >= 0) >= 0) < 0) < 0) > 0) > 0) Page 263 October 31, 2013 Part 3: Commands 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 Trusted Platform Module Library UINT32 i; for (i = 0; i < in->operandB.t.size; i++) if((nvBuffer[i] & in->operandB.t.buffer[i]) != in->operandB.t.buffer[i]) return TPM_RC_POLICY; } break; case TPM_EO_BITCLEAR: // All bits SET in B are CLEAR in A. ((A&B)=0) { UINT32 i; for (i = 0; i < in->operandB.t.size; i++) if((nvBuffer[i] & in->operandB.t.buffer[i]) != 0) return TPM_RC_POLICY; } break; default: pAssert(FALSE); break; } } // Internal Data Update // Start argument hash argHash.t.size = CryptStartHash(session->authHashAlg, &hashState); // add operandB CryptUpdateDigest2B(&hashState, &in->operandB.b); // add offset CryptUpdateDigestInt(&hashState, sizeof(UINT16), &in->offset); // add operation CryptUpdateDigestInt(&hashState, sizeof(TPM_EO), &in->operation); // complete argument digest CryptCompleteHash2B(&hashState, &argHash.b); // Update policyDigest // Start digest CryptStartHash(session->authHashAlg, &hashState); // add old digest CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); // add commandCode CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); // add argument digest CryptUpdateDigest2B(&hashState, &argHash.b); // Adding nvName nvName.t.size = EntityGetName(in->nvIndex, &nvName.t.name); CryptUpdateDigest2B(&hashState, &nvName.b); // complete the digest CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); return TPM_RC_SUCCESS; } Page 264 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 25.10 TPM2_PolicyCounterTimer 25.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. Magnitude comparisons assume that the octet at offset zero in the referenced location and in operandB contain the most significant octet of the data. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 265 October 31, 2013 Part 3: Commands 25.10.2 Trusted Platform Module Library Command and Response Table 127 — TPM2_PolicyCounterTimer Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_PolicyCounterTimer TPMI_SH_POLICY policySession handle for the policy session being extended Auth Index: None TPM2B_OPERAND operandB the second operand UINT16 offset the offset in TPMS_TIME_INFO structure for the start of operand A TPM_EO operation the comparison to make Table 128 — TPM2_PolicyCounterTimer Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode Page 266 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 25.10.3 1 2 3 Part 3: Commands Detailed Actions #include "InternalRoutines.h" #include "PolicyCounterTimer_fp.h" #include "Policy_spt_fp.h" Error Returns TPM_RC_POLICY the comparison of the selected portion of the TPMS_TIME_INFO with operandB failed TPM_RC_RANGE 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 Meaning offset + size exceed size of TPMS_TIME_INFO structure TPM_RC TPM2_PolicyCounterTimer( PolicyCounterTimer_In *in // IN: input parameter list ) { TPM_RC SESSION TIME_INFO TPM_CC HASH_STATE TPM2B_DIGEST result; *session; infoData; // data buffer of TPMS_TIME_INFO commandCode = TPM_CC_PolicyCounterTimer; hashState; argHash; // Input Validation // If the command is going to use any part of the counter or timer, need // to verify that time is advancing. // The time and clock vales are the first two 64-bit values in the clock if(in->offset < sizeof(UINT64) + sizeof(UINT64)) { // Using Clock or Time so see if clock is running. Clock doesn't run while // NV is unavailable. // TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned here. result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; } // Get pointer to the session structure session = SessionGet(in->policySession); //If this is a trial policy, skip all validations and the operation if(session->attributes.isTrialPolicy == CLEAR) { // Get time data info. The size of time info data equals the input // operand B size. A TPM_RC_RANGE error may be returned at this point result = TimeGetRange(in->offset, in->operandB.t.size, &infoData); if(result != TPM_RC_SUCCESS) return result; // Arithmetic Comparison switch(in->operation) { case TPM_EO_EQ: // compare A = B if(CryptCompare(in->operandB.t.size, infoData, in->operandB.t.size, in->operandB.t.buffer) != 0) return TPM_RC_POLICY; break; case TPM_EO_NEQ: // compare A != B if(CryptCompare(in->operandB.t.size, infoData, Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 267 October 31, 2013 Part 3: Commands 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 Trusted Platform Module Library in->operandB.t.size, in->operandB.t.buffer) return TPM_RC_POLICY; break; case TPM_EO_SIGNED_GT: // compare A > B signed if(CryptCompareSigned(in->operandB.t.size, infoData, in->operandB.t.size, in->operandB.t.buffer) return TPM_RC_POLICY; break; case TPM_EO_UNSIGNED_GT: // compare A > B unsigned if(CryptCompare(in->operandB.t.size, infoData, in->operandB.t.size, in->operandB.t.buffer) return TPM_RC_POLICY; break; case TPM_EO_SIGNED_LT: // compare A < B signed if(CryptCompareSigned(in->operandB.t.size, infoData, in->operandB.t.size, in->operandB.t.buffer) return TPM_RC_POLICY; break; case TPM_EO_UNSIGNED_LT: // compare A < B unsigned if(CryptCompare(in->operandB.t.size, infoData, in->operandB.t.size, in->operandB.t.buffer) return TPM_RC_POLICY; break; case TPM_EO_SIGNED_GE: // compare A >= B signed if(CryptCompareSigned(in->operandB.t.size, infoData, in->operandB.t.size, in->operandB.t.buffer) return TPM_RC_POLICY; break; case TPM_EO_UNSIGNED_GE: // compare A >= B unsigned if(CryptCompare(in->operandB.t.size, infoData, in->operandB.t.size, in->operandB.t.buffer) return TPM_RC_POLICY; break; case TPM_EO_SIGNED_LE: // compare A <= B signed if(CryptCompareSigned(in->operandB.t.size, infoData, in->operandB.t.size, in->operandB.t.buffer) return TPM_RC_POLICY; break; case TPM_EO_UNSIGNED_LE: // compare A <= B unsigned if(CryptCompare(in->operandB.t.size, infoData, in->operandB.t.size, in->operandB.t.buffer) return TPM_RC_POLICY; break; case TPM_EO_BITSET: // All bits SET in B are SET in A. ((A&B)=B) { UINT32 i; for (i = 0; i < in->operandB.t.size; i++) if( (infoData[i] & in->operandB.t.buffer[i]) != in->operandB.t.buffer[i]) return TPM_RC_POLICY; } break; case TPM_EO_BITCLEAR: // All bits SET in B are CLEAR in A. ((A&B)=0) { Page 268 October 31, 2013 Published Copyright © TCG 2006-2013 == 0) <= 0) <= 0) >= 0) >= 0) < 0) < 0) > 0) > 0) Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 Part 3: Commands UINT32 i; for (i = 0; i < in->operandB.t.size; i++) if((infoData[i] & in->operandB.t.buffer[i]) != 0) return TPM_RC_POLICY; } break; default: pAssert(FALSE); break; } } // Internal Data Update // Start argument list hash argHash.t.size = CryptStartHash(session->authHashAlg, &hashState); // add operandB CryptUpdateDigest2B(&hashState, &in->operandB.b); // add offset CryptUpdateDigestInt(&hashState, sizeof(UINT16), &in->offset); // add operation CryptUpdateDigestInt(&hashState, sizeof(TPM_EO), &in->operation); // complete argument hash CryptCompleteHash2B(&hashState, &argHash.b); // update policyDigest // start hash CryptStartHash(session->authHashAlg, &hashState); // add old digest CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); // add commandCode CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); // add argument digest CryptUpdateDigest2B(&hashState, &argHash.b); // complete the digest CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 269 October 31, 2013 Part 3: Commands Trusted Platform Module Library 25.11 TPM2_PolicyCommandCode 25.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 TPM_CC_Certify is required. Page 270 October 31, 2013 be executed, TPM2_PolicyCommandCode() Published Copyright © TCG 2006-2013 with code set to Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 25.11.2 Part 3: Commands Command and Response Table 129 — TPM2_PolicyCommandCode Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_PolicyCommandCode TPMI_SH_POLICY policySession handle for the policy session being extended Auth Index: None TPM_CC code the allowed commandCode Table 130 — TPM2_PolicyCommandCode Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 271 October 31, 2013 Part 3: Commands 25.11.3 1 2 Trusted Platform Module Library Detailed Actions #include "InternalRoutines.h" #include "PolicyCommandCode_fp.h" Error Returns TPM_RC_VALUE 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 Meaning commandCode of policySession previously set to a different value TPM_RC TPM2_PolicyCommandCode( PolicyCommandCode_In *in // IN: input parameter list ) { SESSION TPM_CC HASH_STATE *session; commandCode = TPM_CC_PolicyCommandCode; hashState; // Input validation // Get pointer to the session structure session = SessionGet(in->policySession); if(session->commandCode != 0 && session->commandCode != in->code) return TPM_RC_VALUE + RC_PolicyCommandCode_code; if(!CommandIsImplemented(in->code)) return TPM_RC_POLICY_CC + RC_PolicyCommandCode_code; // Internal Data Update // Update policy hash // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyCommandCode || code) // Start hash CryptStartHash(session->authHashAlg, &hashState); // add old digest CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); // add commandCode CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); // add input commandCode CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &in->code); // complete the hash and get the results CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); // update commandCode value in session context session->commandCode = in->code; return TPM_RC_SUCCESS; } Page 272 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 25.12 TPM2_PolicyPhysicalPresence 25.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) Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 (27) Page 273 October 31, 2013 Part 3: Commands 25.12.2 Trusted Platform Module Library Command and Response Table 131 — TPM2_PolicyPhysicalPresence Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_PolicyPhysicalPresence TPMI_SH_POLICY policySession handle for the policy session being extended Auth Index: None Table 132 — TPM2_PolicyPhysicalPresence Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode Page 274 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 25.12.3 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 Part 3: Commands Detailed Actions #include "InternalRoutines.h" #include "PolicyPhysicalPresence_fp.h" TPM_RC TPM2_PolicyPhysicalPresence( PolicyPhysicalPresence_In *in // IN: input parameter list ) { SESSION TPM_CC HASH_STATE *session; commandCode = TPM_CC_PolicyPhysicalPresence; hashState; // Internal Data Update // Get pointer to the session structure session = SessionGet(in->policySession); // Update policy hash // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyPhysicalPresence) // Start hash CryptStartHash(session->authHashAlg, &hashState); // add old digest CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); // add commandCode CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); // complete the digest CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); // update session attribute session->attributes.isPPRequired = SET; return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 275 October 31, 2013 Part 3: Commands Trusted Platform Module Library 25.13 TPM2_PolicyCpHash 25.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 policySession→policyDigest is updated with is set to cpHashA policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyCpHash || cpHashA) Page 276 October 31, 2013 Published Copyright © TCG 2006-2013 and (28) Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 25.13.2 Part 3: Commands Command and Response Table 133 — TPM2_PolicyCpHash Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_PolicyCpHash TPMI_SH_POLICY policySession handle for the policy session being extended 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 8 UINT32 responseSize TPM_RC responseCode Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 277 October 31, 2013 Part 3: Commands 25.13.3 1 2 Trusted Platform Module Library Detailed Actions #include "InternalRoutines.h" #include "PolicyCpHash_fp.h" Error Returns TPM_RC_CPHASH cpHash of policySession has previously been set to a different value TPM_RC_SIZE 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 Meaning cpHashA is not the size of a digest produced by the hash algorithm associated with policySession TPM_RC TPM2_PolicyCpHash( PolicyCpHash_In *in // IN: input parameter list ) { SESSION TPM_CC HASH_STATE *session; commandCode = TPM_CC_PolicyCpHash; hashState; // Input Validation // Get pointer to the session structure session = SessionGet(in->policySession); // A new cpHash is given in input parameter, but cpHash in session context // is not empty, or is not the same as the new cpHash if( in->cpHashA.t.size != 0 && session->u1.cpHash.t.size != 0 && !Memory2BEqual(&in->cpHashA.b, &session->u1.cpHash.b) ) return TPM_RC_CPHASH; // A valid cpHash must have the same size as session hash digest if(in->cpHashA.t.size != CryptGetHashDigestSize(session->authHashAlg)) return TPM_RC_SIZE + RC_PolicyCpHash_cpHashA; // Internal Data Update // Update policy hash // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyCpHash || cpHashA) // Start hash CryptStartHash(session->authHashAlg, &hashState); // add old digest CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); // add commandCode CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); // add cpHashA CryptUpdateDigest2B(&hashState, &in->cpHashA.b); // complete the digest and get the results CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); // update cpHash in session context session->u1.cpHash = in->cpHashA; session->attributes.iscpHashDefined = SET; return TPM_RC_SUCCESS; Page 278 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 53 Part 3: Commands } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 279 October 31, 2013 Part 3: Commands Trusted Platform Module Library 25.14 TPM2_PolicyNameHash 25.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 handles 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 policySession→nameHash instead. used to hold policySession→cpHash to be used for The policySession→policyDigest will be updated with policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyNameHash || nameHash) NOTE 2 (29) 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. Page 280 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 25.14.2 Part 3: Commands Command and Response Table 135 — TPM2_PolicyNameHash Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_PolicyNameHash TPMI_SH_POLICY policySession handle for the policy session being extended 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 8 UINT32 responseSize TPM_RC responseCode Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 281 October 31, 2013 Part 3: Commands 25.14.3 1 2 Trusted Platform Module Library Detailed Actions #include "InternalRoutines.h" #include "PolicyNameHash_fp.h" Error Returns TPM_RC_CPHASH nameHash has been previously set to a different value TPM_RC_SIZE 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 Meaning nameHash is not the size of the digest produced by the hash algorithm associated with policySession TPM_RC TPM2_PolicyNameHash( PolicyNameHash_In *in // IN: input parameter list SESSION TPM_CC HASH_STATE *session; commandCode = TPM_CC_PolicyNameHash; hashState; ) { // Input Validation // Get pointer to the session structure session = SessionGet(in->policySession); // A new nameHash is given in input parameter, but cpHash in session context // is not empty if(in->nameHash.t.size != 0 && session->u1.cpHash.t.size != 0) return TPM_RC_CPHASH; // A valid nameHash must have the same size as session hash digest if(in->nameHash.t.size != CryptGetHashDigestSize(session->authHashAlg)) return TPM_RC_SIZE + RC_PolicyNameHash_nameHash; // Internal Data Update // Update policy hash // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyNameHash || nameHash) // Start hash CryptStartHash(session->authHashAlg, &hashState); // add old digest CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); // add commandCode CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); // add nameHash CryptUpdateDigest2B(&hashState, &in->nameHash.b); // complete the digest CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); // clear iscpHashDefined bit to indicate now this field contains a nameHash session->attributes.iscpHashDefined = CLEAR; // update nameHash in session context session->u1.cpHash = in->nameHash; return TPM_RC_SUCCESS; } Page 282 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 25.15 TPM2_PolicyDuplicationSelect 25.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, then 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) It is allowed that policySesion→nameHash and policySession→cpHash share the same memory space. NOTE 3 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) NOTE 4 (32) 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, commandCode in the policy session context 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 only 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” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 283 October 31, 2013 Part 3: Commands 25.15.2 Trusted Platform Module Library Command and Response Table 137 — TPM2_PolicyDuplicationSelect Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_PolicyDuplicationSelect TPMI_SH_POLICY policySession handle for the policy session being extended Auth Index: None TPM2B_NAME objectName the Name of the object to be duplicated TPM2B_NAME newParentName the Name of the new parent TPMI_YES_NO includeObject if YES, the objectName will be included in the value in policySession→policyDigest Table 138 — TPM2_PolicyDuplicationSelect Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode Page 284 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 25.15.3 1 2 Part 3: Commands Detailed Actions #include "InternalRoutines.h" #include "PolicyDuplicationSelect_fp.h" Error Returns TPM_RC_COMMAND_CODE commandCode of 'policySession; is not empty TPM_RC_CPHASH 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 Meaning cpHash of policySession is not empty TPM_RC TPM2_PolicyDuplicationSelect( PolicyDuplicationSelect_In *in // IN: input parameter list ) { SESSION HASH_STATE TPM_CC *session; hashState; commandCode = TPM_CC_PolicyDuplicationSelect; // Input Validation // Get pointer to the session structure session = SessionGet(in->policySession); // cpHash in session context must be empty if(session->u1.cpHash.t.size != 0) return TPM_RC_CPHASH; // commandCode in session context must be empty if(session->commandCode != 0) return TPM_RC_COMMAND_CODE; // Internal Data Update // Update name hash session->u1.cpHash.t.size = CryptStartHash(session->authHashAlg, &hashState); // add objectName CryptUpdateDigest2B(&hashState, &in->objectName.b); // add new parent name CryptUpdateDigest2B(&hashState, &in->newParentName.b); // complete hash CryptCompleteHash2B(&hashState, &session->u1.cpHash.b); // update policy hash // Old policyDigest size should be the same as the new policyDigest size since // they are using the same hash algorithm session->u2.policyDigest.t.size = CryptStartHash(session->authHashAlg, &hashState); // add old policy CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); // add command code CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); // add objectName if(in->includeObject == YES) CryptUpdateDigest2B(&hashState, &in->objectName.b); Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 285 October 31, 2013 Part 3: Commands 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 Trusted Platform Module Library // add new parent name CryptUpdateDigest2B(&hashState, &in->newParentName.b); // add includeObject CryptUpdateDigestInt(&hashState, sizeof(TPMI_YES_NO), &in->includeObject); // complete digest CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); // clear iscpHashDefined bit to indicate now this field contains a nameHash session->attributes.iscpHashDefined = CLEAR; // set commandCode in session context session->commandCode = TPM_CC_Duplicate; return TPM_RC_SUCCESS; } Page 286 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 25.16 TPM2_PolicyAuthorize 25.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)) NOTE (34) 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 chec k 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 create a TPM2B_NAME (keyName) using keySign and update policySession→policyDigest with PolicyUpdate() (see 25.2.3). PolicyUpdate(TPM_CC_PolicyAuthorize, keyName, 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 The unmarshaling process requires that a proper TPMT_TK_VERIFIED be provided for checkTicket but it may be a NULL Ticket. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 287 October 31, 2013 Part 3: Commands 25.16.2 Trusted Platform Module Library Command and Response Table 139 — TPM2_PolicyAuthorize Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_PolicyAuthorize TPMI_SH_POLICY policySession handle for the policy session being extended 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 TPMT_TK_VERIFIED checkTicket ticket validating that approvedPolicy and policyRef were signed by keySign Table 140 — TPM2_PolicyAuthorize Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode Page 288 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 25.16.3 1 2 3 Part 3: Commands Detailed Actions #include "InternalRoutines.h" #include "PolicyAuthorize_fp.h" #include "Policy_spt_fp.h" Error Returns 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 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 Meaning the current policyDigest of policySession does not match approvedPolicy; or checkTicket doesn't match the provided values TPM_RC TPM2_PolicyAuthorize( PolicyAuthorize_In *in // IN: input parameter list SESSION TPM2B_DIGEST HASH_STATE TPMT_TK_VERIFIED TPM_ALG_ID UINT16 *session; authHash; hashState; ticket; hashAlg; digestSize; ) { // Input Validation // Get pointer to the session structure session = SessionGet(in->policySession); // Extract from the Name of the key, the algorithm used to compute it's Name hashAlg = BYTE_ARRAY_TO_UINT16(in->keySign.t.name); // 'keySign' parameter needs to use a supported hash algorithm, otherwise // can't tell how large the digest should be digestSize = CryptGetHashDigestSize(hashAlg); if(digestSize == 0) return TPM_RC_HASH + RC_PolicyAuthorize_keySign; if(digestSize != (in->keySign.t.size - 2)) return TPM_RC_SIZE + RC_PolicyAuthorize_keySign; //If this is a trial policy, skip all validations if(session->attributes.isTrialPolicy == CLEAR) { // Check that "approvedPolicy" matches the current value of the // policyDigest in policy session if(!Memory2BEqual(&session->u2.policyDigest.b, &in->approvedPolicy.b)) return TPM_RC_VALUE + RC_PolicyAuthorize_approvedPolicy; // Validate ticket TPMT_TK_VERIFIED // Compute aHash. The authorizing object sign a digest // aHash := hash(approvedPolicy || policyRef). // Start hash authHash.t.size = CryptStartHash(hashAlg, &hashState); // add approvedPolicy CryptUpdateDigest2B(&hashState, &in->approvedPolicy.b); Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 289 October 31, 2013 Part 3: Commands 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 Trusted Platform Module Library // add policyRef CryptUpdateDigest2B(&hashState, &in->policyRef.b); // complete hash CryptCompleteHash2B(&hashState, &authHash.b); // re-compute TPMT_TK_VERIFIED TicketComputeVerified(in->checkTicket.hierarchy, &authHash, &in->keySign, &ticket); // Compare ticket digest. If not match, return error if(!Memory2BEqual(&in->checkTicket.digest.b, &ticket.digest.b)) return TPM_RC_VALUE+ RC_PolicyAuthorize_checkTicket; } // Internal Data Update // Set policyDigest to zero digest MemorySet(session->u2.policyDigest.t.buffer, 0, session->u2.policyDigest.t.size); // Update policyDigest PolicyContextUpdate(TPM_CC_PolicyAuthorize, &in->keySign, &in->policyRef, NULL, 0, session); return TPM_RC_SUCCESS; } Page 290 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 25.17 TPM2_PolicyAuthValue 25.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 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) Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 (36) Page 291 October 31, 2013 Part 3: Commands 25.17.2 Trusted Platform Module Library Command and Response Table 141 — TPM2_PolicyAuthValue Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_PolicyAuthValue TPMI_SH_POLICY policySession handle for the policy session being extended Auth Index: None Table 142 — TPM2_PolicyAuthValue Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode Page 292 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 25.17.3 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 Part 3: Commands Detailed Actions #include "InternalRoutines.h" #include "PolicyAuthValue_fp.h" #include "Policy_spt_fp.h" TPM_RC TPM2_PolicyAuthValue( PolicyAuthValue_In *in // IN: input parameter list SESSION TPM_CC HASH_STATE *session; commandCode = TPM_CC_PolicyAuthValue; hashState; ) { // Internal Data Update // Get pointer to the session structure session = SessionGet(in->policySession); // Update policy hash // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyAuthValue) // Start hash CryptStartHash(session->authHashAlg, &hashState); // add old digest CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); // add commandCode CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); // complete the hash and get the results CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); // update isAuthValueNeeded bit in the session context session->attributes.isAuthValueNeeded = SET; session->attributes.isPasswordNeeded = CLEAR; return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 293 October 31, 2013 Part 3: Commands Trusted Platform Module Library 25.18 TPM2_PolicyPassword 25.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 contain a password and not an HMAC. If successful, policySession→policyDigest will be updated with policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyAuthValue) NOTE 2 (37) 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 294 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 25.18.2 Part 3: Commands Command and Response Table 143 — TPM2_PolicyPassword Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_PolicyPassword TPMI_SH_POLICY policySession handle for the policy session being extended Auth Index: None Table 144 — TPM2_PolicyPassword Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 295 October 31, 2013 Part 3: Commands 25.18.3 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 Trusted Platform Module Library Detailed Actions #include "InternalRoutines.h" #include "PolicyPassword_fp.h" #include "Policy_spt_fp.h" TPM_RC TPM2_PolicyPassword( PolicyPassword_In *in // IN: input parameter list SESSION TPM_CC HASH_STATE *session; commandCode = TPM_CC_PolicyAuthValue; hashState; ) { // Internal Data Update // Get pointer to the session structure session = SessionGet(in->policySession); // Update policy hash // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyAuthValue) // Start hash CryptStartHash(session->authHashAlg, &hashState); // add old digest CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); // add commandCode CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); // complete the digest CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); // Update isPasswordNeeded bit session->attributes.isPasswordNeeded = SET; session->attributes.isAuthValueNeeded = CLEAR; return TPM_RC_SUCCESS; } Page 296 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 25.19 TPM2_PolicyGetDigest 25.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” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 297 October 31, 2013 Part 3: Commands 25.19.2 Trusted Platform Module Library Command and Response Table 145 — TPM2_PolicyGetDigest Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_PolicyGetDigest TPMI_SH_POLICY policySession handle for the policy session Auth Index: None Table 146 — TPM2_PolicyGetDigest Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode TPM2B_DIGEST policyDigest Page 298 October 31, 2013 the current value of the policySession→policyDigest Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 25.19.3 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 Part 3: Commands Detailed Actions #include "InternalRoutines.h" #include "PolicyGetDigest_fp.h" TPM_RC TPM2_PolicyGetDigest( PolicyGetDigest_In PolicyGetDigest_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { SESSION *session; // Command Output // Get pointer to the session structure session = SessionGet(in->policySession); out->policyDigest = session->u2.policyDigest; return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 299 October 31, 2013 Part 3: Commands Trusted Platform Module Library 25.20 TPM2_PolicyNvWritten 25.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 and 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 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. Page 300 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 25.20.2 Part 3: Commands Command and Response Table 147 — TPM2_PolicyNvWritten Command Type Name Description TPMI_ST_COMMAND_TAG Tag UINT32 commandSize TPM_CC commandCode TPM_CC_PolicyNVWritten TPMI_SH_POLICY policySession handle for the policy session being extended Auth Index: None TPMI_YES_NO writtenSet YES if NV Index is required to have been written NO if NV Index is required not to have been written Table 148 — TPM2_PolicyNvWritten Response Type Name Description TPM_ST Tag see clause 8 UINT32 responseSize TPM_RC responseCode Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 301 October 31, 2013 Part 3: Commands 25.20.3 1 2 Trusted Platform Module Library Detailed Actions #include "InternalRoutines.h" #include "PolicyNvWritten_fp.h" Make an NV Index policy dependent on the state of the TPMA_NV_WRITTEN attribute of the index. Error Returns TPM_RC_VALUE 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 Meaning a conflicting request for the attribute has already been processed TPM_RC TPM2_PolicyNvWritten( PolicyNvWritten_In *in // IN: input parameter list ) { SESSION TPM_CC HASH_STATE *session; commandCode = TPM_CC_PolicyNvWritten; hashState; // Input Validation // Get pointer to the session structure session = SessionGet(in->policySession); // If already set is this a duplicate (the same setting)? If it // is a conflicting setting, it is an error if(session->attributes.checkNvWritten == SET) { if(( (session->attributes.nvWrittenState == SET) != (in->writtenSet == YES))) return TPM_RC_VALUE + RC_PolicyNvWritten_writtenSet; } // Internal Data Update // Set session attributes so that the NV Index needs to be checked session->attributes.checkNvWritten = SET; session->attributes.nvWrittenState = (in->writtenSet == YES); // Update policy hash // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyNvWritten // || writtenSet) // Start hash CryptStartHash(session->authHashAlg, &hashState); // add old digest CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); // add commandCode CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); // add the byte of writtenState CryptUpdateDigestInt(&hashState, sizeof(TPMI_YES_NO), &in->writtenSet); // complete the digest CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); return TPM_RC_SUCCESS; } Page 302 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Family “2.0” Level 00 Revision 00.99 Part 3: Commands Published Copyright © TCG 2006-2013 Page 303 October 31, 2013 Part 3: Commands 26 Trusted Platform Module Library Hierarchy Commands 26.1 TPM2_CreatePrimary 26.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: Since the sensitive data is not returned, the key cannot be reloaded. persistent or it can be recreated. It can either be made 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, userWithAuth, adminWithPolicy, encrypt, 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 Part 1 of this specification and implemented in 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 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 304 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 26.1.2 Command and Response Table 149 — TPM2_CreatePrimary Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_CreatePrimary TPMI_RH_HIERARCHY+ @primaryHandle TPM_RH_ENDORSEMENT, TPM_RH_OWNER, TPM_RH_PLATFORM+{PP}, or TPM_RH_NULL Auth Index: 1 Auth Role: USER TPM2B_SENSITIVE_CREATE inSensitive the sensitive data, see Part 1 Sensitive Values TPM2B_PUBLIC inPublic the public template TPM2B_DATA outsideInfo data that will be included in the creation data for this 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 8 UINT32 responseSize TPM_RC responseCode TPM_HANDLE objectHandle Handle for created 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 TPMT_TK_CREATION creationTicket ticket used by TPM2_CertifyCreation() to validate that the creation data was produced by the TPM TPM2B_NAME name the name of the created object Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 305 October 31, 2013 Part 3: Commands Trusted Platform Module Library 26.1.3 Detailed Actions 1 2 3 4 #include #include #include #include "InternalRoutines.h" "CreatePrimary_fp.h" "Object_spt_fp.h" Error Returns 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 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 Meaning unknown object type; TPM_RC TPM2_CreatePrimary( CreatePrimary_In CreatePrimary_Out ) { // Local variables TPM_RC TPMT_SENSITIVE *in, *out // IN: input parameter list // OUT: output parameter list result = TPM_RC_SUCCESS; sensitive; // Input Validation // The sensitiveDataOrigin attribute must be consistent with the setting of // the size of the data object in inSensitive. if( (in->inPublic.t.publicArea.objectAttributes.sensitiveDataOrigin == SET) != (in->inSensitive.t.sensitive.data.t.size == 0 )) // Mismatch between the object attributes and the parameter. return TPM_RC_ATTRIBUTES + RC_CreatePrimary_inSensitive; // Check attributes in input public area. TPM_RC_ATTRIBUTES, TPM_RC_KDF, // TPM_RC_SCHEME, TPM_RC_SIZE, TPM_RC_SYMMETRIC, or TPM_RC_TYPE error may // be returned at this point. result = PublicAttributesValidation(FALSE, in->primaryHandle, &in->inPublic.t.publicArea); if(result != TPM_RC_SUCCESS) return RcSafeAddToResult(result, RC_CreatePrimary_inPublic); // Validate the sensitive area values if( MemoryRemoveTrailingZeros(&in->inSensitive.t.sensitive.userAuth) > CryptGetHashDigestSize(in->inPublic.t.publicArea.nameAlg)) Page 306 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 Part 3: Commands return TPM_RC_SIZE + RC_CreatePrimary_inSensitive; // Command output // Generate Primary Object // The primary key generation process uses the Name of the input public // template to compute the key. The keys are generated from the template // before anything in the template is allowed to be changed. // A TPM_RC_KDF, TPM_RC_SIZE error may be returned at this point result = CryptCreateObject(in->primaryHandle, &in->inPublic.t.publicArea, &in->inSensitive.t.sensitive,&sensitive); if(result != TPM_RC_SUCCESS) return result; // Fill in creation data FillInCreationData(in->primaryHandle, in->inPublic.t.publicArea.nameAlg, &in->creationPCR, &in->outsideInfo, &out->creationData, &out->creationHash); // Copy public area out->outPublic = in->inPublic; // Fill in private area for output ObjectComputeName(&(out->outPublic.t.publicArea), &out->name); // Compute creation ticket TicketComputeCreation(EntityGetHierarchy(in->primaryHandle), &out->name, &out->creationHash, &out->creationTicket); // Create a internal object. A TPM_RC_OBJECT_MEMORY error may be returned // at this point. result = ObjectLoad(in->primaryHandle, &in->inPublic.t.publicArea, &sensitive, &out->name, in->primaryHandle, TRUE, &out->objectHandle); return result; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 307 October 31, 2013 Part 3: Commands 26.2 Trusted Platform Module Library TPM2_HierarchyControl 26.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 ownerAuth/ownerPolicy is provided. shEnable may be SET if platformAuth/platformPolicy is provided. or 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 ownerAuth). 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 platformAuth). 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 308 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 26.2.2 Command and Response Table 151 — TPM2_HierarchyControl Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_HierarchyControl {NV E} TPMI_RH_HIERARCHY @authHandle TPM_RH_ENDORSEMENT, TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} Auth Index: 1 Auth Role: USER TPMI_RH_ENABLES enable the enable being modified TPM_RH_ENDORSEMENT, TPM_RH_OWNER, TPM_RH_PLATFORM, or TPM_RH_PLATFORM_NV TPMI_YES_NO state YES if the enable should be SET, NO if the enable should be CLEAR Table 152 — TPM2_HierarchyControl Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 309 October 31, 2013 Part 3: Commands Trusted Platform Module Library 26.2.3 Detailed Actions 1 2 #include "InternalRoutines.h" #include "HierarchyControl_fp.h" Error Returns TPM_RC_AUTH_TYPE 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 Meaning authHandle is not applicable to hierarchy in its current state TPM_RC TPM2_HierarchyControl( HierarchyControl_In *in // IN: input parameter list ) { TPM_RC BOOL BOOL result; select = (in->state == YES); *selected = NULL; // Input Validation switch(in->enable) { // Platform hierarchy has to be disabled by platform auth // If the platform hierarchy has already been disabled, only a reboot // can enable it again case TPM_RH_PLATFORM: case TPM_RH_PLATFORM_NV: if(in->authHandle != TPM_RH_PLATFORM) return TPM_RC_AUTH_TYPE; break; // ShEnable may be disabled if PlatformAuth/PlatformPolicy or // OwnerAuth/OwnerPolicy is provided. If ShEnable is disabled, then it // may only be enabled if PlatformAuth/PlatformPolicy is provided. case TPM_RH_OWNER: if( in->authHandle != TPM_RH_PLATFORM && in->authHandle != TPM_RH_OWNER) return TPM_RC_AUTH_TYPE; if( gc.shEnable == FALSE && in->state == YES && in->authHandle != TPM_RH_PLATFORM) return TPM_RC_AUTH_TYPE; break; // EhEnable may be disabled if either PlatformAuth/PlatformPolicy or // EndosementAuth/EndorsementPolicy is provided. If EhEnable is disabled, // then it may only be enabled if PlatformAuth/PlatformPolicy is // provided. case TPM_RH_ENDORSEMENT: if( in->authHandle != TPM_RH_PLATFORM && in->authHandle != TPM_RH_ENDORSEMENT) return TPM_RC_AUTH_TYPE; if( gc.ehEnable == FALSE && in->state == YES && in->authHandle != TPM_RH_PLATFORM) return TPM_RC_AUTH_TYPE; break; default: pAssert(FALSE); break; } // Internal Data Update Page 310 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 Part 3: Commands // Enable or disable the selected hierarchy // Note: the authorization processing for this command may keep these // command actions from being executed. For example, if phEnable is // CLEAR, then platformAuth cannot be used for authorization. This // means that would not be possible to use platformAuth to change the // state of phEnable from CLEAR to SET. // If it is decided that platformPolicy can still be used when phEnable // is CLEAR, then this code could SET phEnable when proper platform // policy is provided. switch(in->enable) { case TPM_RH_OWNER: selected = &gc.shEnable; break; case TPM_RH_ENDORSEMENT: selected = &gc.ehEnable; break; case TPM_RH_PLATFORM: selected = &g_phEnable; break; case TPM_RH_PLATFORM_NV: selected = &gc.phEnableNV; break; default: pAssert(FALSE); break; } if(selected != NULL && *selected != select) { // Before changing the internal state, make sure that NV is available. // Only need to update NV if changing the orderly state if(gp.orderlyState != SHUTDOWN_NONE) { // The command needs NV update. Check if NV is available. // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at // this point result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; } // state is changing and NV is available so modify *selected = select; // If a hierarchy was just disabled, flush it if(select == CLEAR && in->enable != TPM_RH_PLATFORM_NV) // Flush hierarchy ObjectFlushHierarchy(in->enable); // orderly state should be cleared because of the update to state clear data // This gets processed in ExecuteCommand() on the way out. g_clearOrderly = TRUE; } return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 311 October 31, 2013 Part 3: Commands 26.3 Trusted Platform Module Library TPM2_SetPrimaryPolicy 26.3.1 General Description This command allows setting of the authorization policy for 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 312 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 26.3.2 Command and Response Table 153 — TPM2_SetPrimaryPolicy Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_SetPrimaryPolicy {NV} TPMI_RH_HIERARCHY @authHandle TPM_RH_ENDORSEMENT, TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} Auth Index: 1 Auth Role: USER TPM2B_DIGEST authPolicy an authorization policy digest; may be the Empty Buffer If hashAlg is TPM_ALG_NULL, then this shall be an Empty Buffer. TPMI_ALG_HASH+ hashAlg the hash algorithm to use for the policy 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 8 UINT32 responseSize TPM_RC responseCode Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 313 October 31, 2013 Part 3: Commands Trusted Platform Module Library 26.3.3 Detailed Actions 1 2 #include "InternalRoutines.h" #include "SetPrimaryPolicy_fp.h" Error Returns TPM_RC_SIZE 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 Meaning size of input authPolicy is not consistent with input hash algorithm TPM_RC TPM2_SetPrimaryPolicy( SetPrimaryPolicy_In *in // IN: input parameter list ) { TPM_RC result; // Input Validation // Check the authPolicy consistent with hash algorithm if( in->authPolicy.t.size != 0 && in->authPolicy.t.size != CryptGetHashDigestSize(in->hashAlg)) return TPM_RC_SIZE + RC_SetPrimaryPolicy_authPolicy; // The command need NV update for OWNER and ENDORSEMENT hierarchy, and // might need orderlyState update for PLATFROM hierarchy. // Check if NV is available. A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE // error may be returned at this point result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; // Internal Data Update // Set hierarchy policy switch(in->authHandle) { case TPM_RH_OWNER: gp.ownerAlg = in->hashAlg; gp.ownerPolicy = in->authPolicy; NvWriteReserved(NV_OWNER_ALG, &gp.ownerAlg); NvWriteReserved(NV_OWNER_POLICY, &gp.ownerPolicy); break; case TPM_RH_ENDORSEMENT: gp.endorsementAlg = in->hashAlg; gp.endorsementPolicy = in->authPolicy; NvWriteReserved(NV_ENDORSEMENT_ALG, &gp.endorsementAlg); NvWriteReserved(NV_ENDORSEMENT_POLICY, &gp.endorsementPolicy); break; case TPM_RH_PLATFORM: gc.platformAlg = in->hashAlg; gc.platformPolicy = in->authPolicy; // need to update orderly state g_clearOrderly = TRUE; break; default: pAssert(FALSE); break; } return TPM_RC_SUCCESS; } Page 314 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 26.4 Part 3: Commands TPM2_ChangePPS 26.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 platformAuth is not changed. All loaded 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 platformAuth. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 315 October 31, 2013 Part 3: Commands Trusted Platform Module Library 26.4.2 Command and Response Table 155 — TPM2_ChangePPS Command Type Name TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_ChangePPS {NV E} TPMI_RH_PLATFORM @authHandle TPM_RH_PLATFORM+{PP} Auth Index: 1 Auth Role: USER Description Table 156 — TPM2_ChangePPS Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode Page 316 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 26.4.3 Detailed Actions 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 #include "InternalRoutines.h" #include "ChangePPS_fp.h" TPM_RC TPM2_ChangePPS( ChangePPS_In *in // IN: input parameter list ) { UINT32 TPM_RC i; result; // Check if NV is available. A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE // error may be returned at this point result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; // Input parameter is not reference in command action in = NULL; // Internal Data Update // Reset platform hierarchy seed from RNG CryptGenerateRandom(PRIMARY_SEED_SIZE, gp.PPSeed.t.buffer); // Create a new phProof value from RNG to prevent the saved platform // hierarchy contexts being loaded CryptGenerateRandom(PROOF_SIZE, gp.phProof.t.buffer); // Set platform authPolicy to null gc.platformAlg = TPM_ALG_NULL; gc.platformPolicy.t.size = 0; // Flush loaded object in platform hierarchy ObjectFlushHierarchy(TPM_RH_PLATFORM); // Flush platform evict object and index in NV NvFlushHierarchy(TPM_RH_PLATFORM); // Save hierarchy changes to NV NvWriteReserved(NV_PP_SEED, &gp.PPSeed); NvWriteReserved(NV_PH_PROOF, &gp.phProof); // Re-initialize PCR policies for(i = 0; i < NUM_POLICY_PCR_GROUP; i++) { gp.pcrPolicies.hashAlg[i] = TPM_ALG_NULL; gp.pcrPolicies.policy[i].t.size = 0; } NvWriteReserved(NV_PCR_POLICIES, &gp.pcrPolicies); // orderly state should be cleared because of the update to state clear data g_clearOrderly = TRUE; return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 317 October 31, 2013 Part 3: Commands 26.5 Trusted Platform Module Library TPM2_ChangeEPS 26.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 loaded objects 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 platformAuth. Page 318 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 26.5.2 Command and Response Table 157 — TPM2_ChangeEPS Command Type Name TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_ChangeEPS {NV E} TPMI_RH_PLATFORM @authHandle TPM_RH_PLATFORM+{PP} Auth Handle: 1 Auth Role: USER Description Table 158 — TPM2_ChangeEPS Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 319 October 31, 2013 Part 3: Commands Trusted Platform Module Library 26.5.3 Detailed Actions 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 #include "InternalRoutines.h" #include "ChangeEPS_fp.h" TPM_RC TPM2_ChangeEPS( ChangeEPS_In *in // IN: input parameter list ) { TPM_RC result; // The command needs NV update. Check if NV is available. // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at // this point result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; // Input parameter is not reference in command action in = NULL; // Internal Data Update // Reset endorsement hierarchy seed from RNG CryptGenerateRandom(PRIMARY_SEED_SIZE, gp.EPSeed.t.buffer); // Create new ehProof value from RNG CryptGenerateRandom(PROOF_SIZE, gp.ehProof.t.buffer); // Enable endorsement hierarchy gc.ehEnable = TRUE; // set authValue buffer to zeros MemorySet(gp.endorsementAuth.t.buffer, 0, gp.endorsementAuth.t.size); // Set endorsement authValue to null gp.endorsementAuth.t.size = 0; // Set endorsement authPolicy to null gp.endorsementAlg = TPM_ALG_NULL; gp.endorsementPolicy.t.size = 0; // Flush loaded object in endorsement hierarchy ObjectFlushHierarchy(TPM_RH_ENDORSEMENT); // Flush evict object of endorsement hierarchy stored in NV NvFlushHierarchy(TPM_RH_ENDORSEMENT); // Save hierarchy changes to NV NvWriteReserved(NV_EP_SEED, &gp.EPSeed); NvWriteReserved(NV_EH_PROOF, &gp.ehProof); NvWriteReserved(NV_ENDORSEMENT_AUTH, &gp.endorsementAuth); NvWriteReserved(NV_ENDORSEMENT_ALG, &gp.endorsementAlg); NvWriteReserved(NV_ENDORSEMENT_POLICY, &gp.endorsementPolicy); // orderly state should be cleared because of the update to state clear data g_clearOrderly = TRUE; return TPM_RC_SUCCESS; } Page 320 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 26.6 Part 3: Commands TPM2_Clear 26.6.1 General Description This command removes all TPM context associated with a specific Owner. The clear operation will:  flush loaded 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 and endorsementPolicy to the Empty Buffer;  set Clock to zero;  set resetCount to zero;  set restartCount to zero; and  set Safe to YES. This command requires platformAuth or lockoutAuth. 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. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 321 October 31, 2013 Part 3: Commands Trusted Platform Module Library 26.6.2 Command and Response Table 159 — TPM2_Clear Command Type Name TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_Clear {NV E} TPMI_RH_CLEAR @authHandle TPM_RH_LOCKOUT or TPM_RH_PLATFORM+{PP} Auth Handle: 1 Auth Role: USER Description Table 160 — TPM2_Clear Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode Page 322 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 26.6.3 Detailed Actions 1 2 #include "InternalRoutines.h" #include "Clear_fp.h" Error Returns TPM_RC_DISABLED 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 Meaning Clear command has been disabled TPM_RC TPM2_Clear( Clear_In *in // IN: input parameter list ) { TPM_RC result; // Input parameter is not reference in command action in = NULL; // The command needs NV update. Check if NV is available. // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at // this point result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; // Input Validation // If Clear command is disabled, return an error if(gp.disableClear) return TPM_RC_DISABLED; // Internal Data Update // Reset storage hierarchy seed from RNG CryptGenerateRandom(PRIMARY_SEED_SIZE, gp.SPSeed.t.buffer); // Create new shProof and ehProof value from RNG CryptGenerateRandom(PROOF_SIZE, gp.shProof.t.buffer); CryptGenerateRandom(PROOF_SIZE, gp.ehProof.t.buffer); // Enable storage and endorsement hierarchy gc.shEnable = gc.ehEnable = TRUE; // set the authValue buffers to zero MemorySet(gp.ownerAuth.t.buffer, 0, gp.ownerAuth.t.size); MemorySet(gp.endorsementAuth.t.buffer, 0, gp.endorsementAuth.t.size); MemorySet(gp.lockoutAuth.t.buffer, 0, gp.lockoutAuth.t.size); // Set storage, endorsement and lockout authValue to null gp.ownerAuth.t.size = gp.endorsementAuth.t.size = gp.lockoutAuth.t.size = 0; // Set storage and endorsement authPolicy to null gp.ownerAlg = gp.endorsementAlg = TPM_ALG_NULL; gp.ownerPolicy.t.size = gp.endorsementPolicy.t.size = 0; // Flush loaded object in storage and endorsement hierarchy ObjectFlushHierarchy(TPM_RH_OWNER); ObjectFlushHierarchy(TPM_RH_ENDORSEMENT); // Flush owner and endorsement object and owner index in NV NvFlushHierarchy(TPM_RH_OWNER); NvFlushHierarchy(TPM_RH_ENDORSEMENT); Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 323 October 31, 2013 Part 3: Commands 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 Trusted Platform Module Library // Save hierarchy changes to NV NvWriteReserved(NV_SP_SEED, &gp.SPSeed); NvWriteReserved(NV_SH_PROOF, &gp.shProof); NvWriteReserved(NV_EH_PROOF, &gp.ehProof); NvWriteReserved(NV_OWNER_AUTH, &gp.ownerAuth); NvWriteReserved(NV_ENDORSEMENT_AUTH, &gp.endorsementAuth); NvWriteReserved(NV_LOCKOUT_AUTH, &gp.lockoutAuth); NvWriteReserved(NV_OWNER_ALG, &gp.ownerAlg); NvWriteReserved(NV_ENDORSEMENT_ALG, &gp.endorsementAlg); NvWriteReserved(NV_OWNER_POLICY, &gp.ownerPolicy); NvWriteReserved(NV_ENDORSEMENT_POLICY, &gp.endorsementPolicy); // Initialize dictionary attack parameters DAPreInstall_Init(); // Reset clock go.clock = 0; go.clockSafe = YES; // Update the DRBG state whenever writing orderly state to NV CryptDrbgGetPutState(GET_STATE); NvWriteReserved(NV_ORDERLY_DATA, &go); // Reset counters gp.resetCount = gr.restartCount = gr.clearCount = 0; gp.auditCounter = 0; NvWriteReserved(NV_RESET_COUNT, &gp.resetCount); NvWriteReserved(NV_AUDIT_COUNTER, &gp.auditCounter); // orderly state should be cleared because of the update to state clear data g_clearOrderly = TRUE; return TPM_RC_SUCCESS; } Page 324 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 26.7 Part 3: Commands TPM2_ClearControl 26.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 platformAuth to CLEAR the disableClear attribute and then execute TPM2_Clear(). LockoutAuth may be used to SET disableClear but not to CLEAR it. PlatformAuth may be used to SET or CLEAR disableClear. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 325 October 31, 2013 Part 3: Commands Trusted Platform Module Library 26.7.2 Command and Response Table 161 — TPM2_ClearControl Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_ClearControl {NV} TPMI_RH_CLEAR @auth TPM_RH_LOCKOUT or TPM_RH_PLATFORM+{PP} Auth Handle: 1 Auth Role: USER TPMI_YES_NO disable YES if the disableOwnerClear flag is to be SET, NO if the flag is to be CLEAR. Table 162 — TPM2_ClearControl Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode Page 326 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 26.7.3 Detailed Actions 1 2 #include "InternalRoutines.h" #include "ClearControl_fp.h" Error Returns TPM_RC_AUTH_FAIL 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 Meaning authorization is not properly given TPM_RC TPM2_ClearControl( ClearControl_In *in // IN: input parameter list ) { TPM_RC result; // The command needs NV update. Check if NV is available. // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at // this point result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; // Input Validation // LockoutAuth may be used to set disableLockoutClear to TRUE but not to FALSE if(in->auth == TPM_RH_LOCKOUT && in->disable == NO) return TPM_RC_AUTH_FAIL; // Internal Data Update if(in->disable == YES) gp.disableClear = TRUE; else gp.disableClear = FALSE; // Record the change to NV NvWriteReserved(NV_DISABLE_CLEAR, &gp.disableClear); return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 327 October 31, 2013 Part 3: Commands 26.8 Trusted Platform Module Library TPM2_HierarchyChangeAuth 26.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 28.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. Page 328 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 26.8.2 Command and Response Table 163 — TPM2_HierarchyChangeAuth Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_HierarchyChangeAuth {NV} TPMI_RH_HIERARCHY_AUTH @authHandle TPM_RH_LOCKOUT, TPM_RH_ENDORSEMENT, TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} 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 8 UINT32 responseSize TPM_RC responseCode Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 329 October 31, 2013 Part 3: Commands Trusted Platform Module Library 26.8.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "HierarchyChangeAuth_fp.h" #include "Object_spt_fp.h" Error Returns TPM_RC_SIZE 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 Meaning newAuth size is greater than that of integrity hash digest TPM_RC TPM2_HierarchyChangeAuth( HierarchyChangeAuth_In *in // IN: input parameter list ) { TPM_RC result; // The command needs NV update. Check if NV is available. // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at // this point result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; // Make sure the the auth value is a reasonable size (not larger than // the size of the digest produced by the integrity hash. The integrity // hash is assumed to produce the longest digest of any hash implemented // on the TPM. if( MemoryRemoveTrailingZeros(&in->newAuth) > CryptGetHashDigestSize(CONTEXT_INTEGRITY_HASH_ALG)) return TPM_RC_SIZE + RC_HierarchyChangeAuth_newAuth; // Set hierarchy authValue switch(in->authHandle) { case TPM_RH_OWNER: gp.ownerAuth = in->newAuth; NvWriteReserved(NV_OWNER_AUTH, &gp.ownerAuth); break; case TPM_RH_ENDORSEMENT: gp.endorsementAuth = in->newAuth; NvWriteReserved(NV_ENDORSEMENT_AUTH, &gp.endorsementAuth); break; case TPM_RH_PLATFORM: gc.platformAuth = in->newAuth; // orderly state should be cleared g_clearOrderly = TRUE; break; case TPM_RH_LOCKOUT: gp.lockoutAuth = in->newAuth; NvWriteReserved(NV_LOCKOUT_AUTH, &gp.lockoutAuth); break; default: pAssert(FALSE); break; } return TPM_RC_SUCCESS; } Page 330 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 27 Part 3: Commands Dictionary Attack Functions 27.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). 27.2 TPM2_DictionaryAttackLockReset 27.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 authorization failure is allowed for this command during a lockoutRecovery interval (set using TPM2_DictionaryAttackParameters(). Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 331 October 31, 2013 Part 3: Commands Trusted Platform Module Library 27.2.2 Command and Response Table 165 — TPM2_DictionaryAttackLockReset Command Type Name TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_DictionaryAttackLockReset {NV} TPMI_RH_LOCKOUT @lockHandle TPM_RH_LOCKOUT Auth Index: 1 Auth Role: USER Description Table 166 — TPM2_DictionaryAttackLockReset Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode Page 332 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 27.2.3 Detailed Actions 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 #include "InternalRoutines.h" #include "DictionaryAttackLockReset_fp.h" TPM_RC TPM2_DictionaryAttackLockReset( DictionaryAttackLockReset_In *in // IN: input parameter list ) { TPM_RC result; // Input parameter is not reference in command action in = NULL; // The command needs NV update. Check if NV is available. // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at // this point result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; // Internal Data Update // Set failed tries to 0 gp.failedTries = 0; // Record the changes to NV NvWriteReserved(NV_FAILED_TRIES, &gp.failedTries); return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 333 October 31, 2013 Part 3: Commands 27.3 Trusted Platform Module Library TPM2_DictionaryAttackParameters 27.3.1 General Description This command changes the lockout parameters. The command requires lockoutAuth. 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 authorization failure is allowed for this command during a lockoutRecovery interval. Page 334 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 27.3.2 Command and Response Table 167 — TPM2_DictionaryAttackParameters Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_DictionaryAttackParameters {NV} TPMI_RH_LOCKOUT @lockHandle TPM_RH_LOCKOUT Auth Index: 1 Auth Role: USER UINT32 newMaxTries count of authorization failures before the lockout is imposed UINT32 newRecoveryTime time in seconds before the authorization failure count is automatically decremented A value of zero indicates that DA protection is disabled. UINT32 lockoutRecovery time in seconds after a lockoutAuth failure before use 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 8 UINT32 responseSize TPM_RC responseCode Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 335 October 31, 2013 Part 3: Commands Trusted Platform Module Library 27.3.3 Detailed Actions 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 #include "InternalRoutines.h" #include "DictionaryAttackParameters_fp.h" TPM_RC TPM2_DictionaryAttackParameters( DictionaryAttackParameters_In *in // IN: input parameter list ) { TPM_RC result; // The command needs NV update. Check if NV is available. // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at // this point result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; // Internal Data Update // Set dictionary attack parameters gp.maxTries = in->newMaxTries; gp.recoveryTime = in->newRecoveryTime; gp.lockoutRecovery = in->lockoutRecovery; // Set failed tries to 0 gp.failedTries = 0; // Record the changes to NV NvWriteReserved(NV_FAILED_TRIES, &gp.failedTries); NvWriteReserved(NV_MAX_TRIES, &gp.maxTries); NvWriteReserved(NV_RECOVERY_TIME, &gp.recoveryTime); NvWriteReserved(NV_LOCKOUT_RECOVERY, &gp.lockoutRecovery); return TPM_RC_SUCCESS; } Page 336 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 28 Part 3: Commands Miscellaneous Management Functions 28.1 Introduction This clause contains commands that do not logically group with any other commands. 28.2 TPM2_PP_Commands 28.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. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 337 October 31, 2013 Part 3: Commands Trusted Platform Module Library 28.2.2 Command and Response Table 169 — TPM2_PP_Commands Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_PP_Commands {NV} TPMI_RH_PLATFORM @auth TPM_RH_PLATFORM+PP Auth Index: 1 Auth Role: USER + Physical Presence TPML_CC setList list of commands to be added to those that will require that Physical Presence be asserted TPML_CC clearList list of commands that will no longer require that Physical Presence be asserted Table 170 — TPM2_PP_Commands Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode Page 338 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 28.2.3 Detailed Actions 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 #include "InternalRoutines.h" #include "PP_Commands_fp.h" TPM_RC TPM2_PP_Commands( PP_Commands_In *in // IN: input parameter list ) { UINT32 TPM_RC i; result; // The command needs NV update. Check if NV is available. // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at // this point result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; // Internal Data Update // Process set list for(i = 0; i < in->setList.count; i++) // If command is implemented, set it as PP required. If the input // command is not a PP command, it will be ignored at // PhysicalPresenceCommandSet(). if(CommandIsImplemented(in->setList.commandCodes[i])) PhysicalPresenceCommandSet(in->setList.commandCodes[i]); // Process clear list for(i = 0; i < in->clearList.count; i++) // If command is implemented, clear it as PP required. If the input // command is not a PP command, it will be ignored at // PhysicalPresenceCommandClear(). If the input command is // TPM2_PP_Commands, it will be ignored as well if(CommandIsImplemented(in->clearList.commandCodes[i])) PhysicalPresenceCommandClear(in->clearList.commandCodes[i]); // Save the change of PP list NvWriteReserved(NV_PP_LIST, &gp.ppList); return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 339 October 31, 2013 Part 3: Commands 28.3 Trusted Platform Module Library TPM2_SetAlgorithmSet 28.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 wo uld require modification of the unmarshaling code so that each time an algorithm is unmarshaled, it would be verified as being enabled. Page 340 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 28.3.2 Command and Response Table 171 — TPM2_SetAlgorithmSet Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_SetAlgorithmSet {NV} TPMI_RH_PLATFORM @authHandle TPM_RH_PLATFORM Auth Index: 1 Auth Role: USER UINT32 algorithmSet a TPM vendor-dependent value indicating the algorithm set selection Table 172 — TPM2_SetAlgorithmSet Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 341 October 31, 2013 Part 3: Commands Trusted Platform Module Library 28.3.3 Detailed Actions 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 #include "InternalRoutines.h" #include "SetAlgorithmSet_fp.h" TPM_RC TPM2_SetAlgorithmSet( SetAlgorithmSet_In *in // IN: input parameter list ) { TPM_RC result; // The command needs NV update. Check if NV is available. // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at // this point result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; // Internal Data Update gp.algorithmSet = in->algorithmSet; // Write the algorithm set changes to NV NvWriteReserved(NV_ALGORITHM_SET, &gp.algorithmSet); return TPM_RC_SUCCESS; } Page 342 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands Field Upgrade 29 29.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 algorithm 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. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 343 October 31, 2013 Part 3: Commands NOTE 2 Trusted Platform Module Library 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 res ponse 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, 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. Page 344 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 29.2 Part 3: Commands TPM2_FieldUpgradeStart 29.2.1 General Description This command uses platformPolicy and a TPM Vendor Authorization Key to authorize a Field Upgrade Manifest. If the signature checks TPM2_FieldUpgradeData(). succeed, the authorization is valid and the TPM will accept 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. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 345 October 31, 2013 Part 3: Commands Trusted Platform Module Library 29.2.2 Command and Response Table 173 — TPM2_FieldUpgradeStart Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_FieldUpgradeStart TPMI_RH_PLATFORM @authorization TPM_RH_PLATFORM+{PP} Auth Index:1 Auth Role: ADMIN TPMI_DH_OBJECT keyHandle handle of a public area that contains the TPM Vendor Authorization Key that will be used to validate manifestSignature Auth Index: None TPM2B_DIGEST fuDigest digest of the first block in the field upgrade sequence TPMT_SIGNATURE manifestSignature signature over fuDigest using the key associated with keyHandle (not optional) Table 174 — TPM2_FieldUpgradeStart Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode Page 346 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 29.2.3 Detailed Actions 1 2 3 4 5 6 7 8 9 10 11 12 13 #include "InternalRoutines.h" #include "FieldUpgradeStart_fp.h" #if CC_FieldUpgradeStart == YES TPM_RC TPM2_FieldUpgradeStart( FieldUpgradeStart_In *in // IN: input parameter list ) { // Not implemented UNUSED_PARAMETER(in); return TPM_RC_SUCCESS; } #endif Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 347 October 31, 2013 Part 3: Commands 29.3 Trusted Platform Module Library TPM2_FieldUpgradeData 29.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. Page 348 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 29.3.2 Command and Response Table 175 — TPM2_FieldUpgradeData Command Type Name Description TPMI_ST_COMMAND_TAG tag 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 8 UINT32 responseSize TPM_RC responseCode TPMT_HA+ nextDigest tagged digest of the next block TPM_ALG_NULL if field update is complete TPMT_HA firstDigest tagged digest of the first block of the sequence Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 349 October 31, 2013 Part 3: Commands Trusted Platform Module Library 29.3.3 Detailed Actions 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 #include "InternalRoutines.h" #include "FieldUpgradeData_fp.h" #if CC_FieldUpgradeData == YES TPM_RC TPM2_FieldUpgradeData( FieldUpgradeData_In FieldUpgradeData_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { // Not implemented UNUSED_PARAMETER(in); UNUSED_PARAMETER(out); return TPM_RC_SUCCESS; } #endif Page 350 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 29.4 Part 3: Commands TPM2_FirmwareRead 29.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() and TPM2_FieldUpgradeData(). Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 351 October 31, 2013 Part 3: Commands Trusted Platform Module Library 29.4.2 Command and Response Table 177 — TPM2_FirmwareRead Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_FirmwareRead UINT32 sequenceNumber the number of previous calls to this command in this sequence set to 0 on the first call Table 178 — TPM2_FirmwareRead Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode TPM2B_MAX_BUFFER fuData Page 352 October 31, 2013 field upgrade image data Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 29.4.3 Detailed Actions 1 2 3 4 5 6 7 8 9 10 11 12 13 #include "InternalRoutines.h" #include "FirmwareRead_fp.h" TPM_RC TPM2_FirmwareRead( FirmwareRead_In FirmwareRead_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { // Not implemented UNUSED_PARAMETER(in); UNUSED_PARAMETER(out); return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 353 October 31, 2013 Part 3: Commands 30 Trusted Platform Module Library Context Management 30.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 Part 1. The fourth command in this clause (TPM2_EvictControl()) is used to control the persistence of a loadable objects in TPM memory. Background for this command may be found in the "Owner and Platform Evict Objects" clause in Part 1. 30.2 TPM2_ContextSave 30.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 ses sions for audit or encryption is prohibited. The TPM shall encrypt and integrity protect the context as described in the "Context Protection" clause in Part 1. See the “Context Data” clause in Part 2 for a description of the context structure in the response. Page 354 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 30.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 TPMI_DH_CONTEXT saveHandle handle of the resource to save Auth Index: None Table 180 — TPM2_ContextSave Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode TPMS_CONTEXT context Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 355 October 31, 2013 Part 3: Commands Trusted Platform Module Library 30.2.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "ContextSave_fp.h" #include "Context_spt_fp.h" Error Returns TPM_RC_CONTEXT_GAP a contextID could not be assigned for a session context save TPM_RC_TOO_MANY_CONTEXTS 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 Meaning no more contexts can be saved as the counter has maxed out TPM_RC TPM2_ContextSave( ContextSave_In ContextSave_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { TPM_RC UINT16 // blob. UINT64 TPM2B_SYM_KEY TPM2B_IV result; fingerprintSize; TPM2B_DIGEST UINT16 BYTE integrity; integritySize; *buffer; contextID = 0; symKey; iv; // The size of fingerprint in context // session context ID // This command may cause the orderlyState to be cleared due to // the update of state reset data. If this is the case, check if NV is // available first if(gp.orderlyState != SHUTDOWN_NONE) { // The command needs NV update. Check if NV is available. // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at // this point result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; } // Internal Data Update // Initialize output handle. At the end of command action, the output // handle of an object will be replaced, while the output handle // for a session will be the same as input out->context.savedHandle = in->saveHandle; // Get the size of fingerprint in context blob. The sequence value in // TPMS_CONTEXT structure is used as the fingerprint fingerprintSize = sizeof(out->context.sequence); // Compute the integrity size at the beginning of context blob integritySize = sizeof(integrity.t.size) + CryptGetHashDigestSize(CONTEXT_INTEGRITY_HASH_ALG); // Perform object or session specific context save switch(HandleGetType(in->saveHandle)) { case TPM_HT_TRANSIENT: { Page 356 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 OBJECT OBJECT Part 3: Commands *object = ObjectGet(in->saveHandle); *outObject = (OBJECT *)(out->context.contextBlob.t.buffer + integritySize + fingerprintSize); // Set size of the context data. The contents of context blob is vendor // defined. In this implementation, the size is size of integrity // plus fingerprint plus the whole internal OBJECT structure out->context.contextBlob.t.size = integritySize + fingerprintSize + sizeof(*object); // Copy the whole internal OBJECT structure to context blob, leave // the size for fingerprint *outObject = *object; // Increment object context ID gr.objectContextID++; // If object context ID overflows, TPM should be put in failure mode if(gr.objectContextID == 0) FAIL(FATAL_ERROR_INTERNAL); // Fill in other return values for an object. out->context.sequence = gr.objectContextID; // For regular object, savedHandle is 0x80000000. For sequence object, // savedHandle is 0x80000001. For object with stClear, savedHandle // is 0x80000002 if(ObjectIsSequence(object)) { out->context.savedHandle = 0x80000001; SequenceDataImportExport(object, outObject, EXPORT_STATE); } else if(object->attributes.stClear == SET) { out->context.savedHandle = 0x80000002; } else { out->context.savedHandle = 0x80000000; } // Get object hierarchy out->context.hierarchy = ObjectDataGetHierarchy(object); break; } case TPM_HT_HMAC_SESSION: case TPM_HT_POLICY_SESSION: { SESSION *session = SessionGet(in->saveHandle); // Set size of the context data. The contents of context blob is vendor // defined. In this implementation, the size of context blob is the // size of a internal session structure plus the size of // fingerprint plus the size of integrity out->context.contextBlob.t.size = integritySize + fingerprintSize + sizeof(*session); // Copy the whole internal SESSION structure to context blob. // Save space for fingerprint at the beginning of the buffer // This is done before anything else so that the actual context // can be reclaimed after this call MemoryCopy(out->context.contextBlob.t.buffer + integritySize + fingerprintSize, session, sizeof(*session), Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 357 October 31, 2013 Part 3: Commands 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 Trusted Platform Module Library sizeof(out->context.contextBlob.t.buffer) - integritySize - fingerprintSize); // Fill in the other return parameters for a session // Get a context ID and set the session tracking values appropriately // TPM_RC_CONTEXT_GAP is a possible error. // SessionContextSave() will flush the in-memory context // so no additional errors may occur after this call. result = SessionContextSave(out->context.savedHandle, &contextID); if(result != TPM_RC_SUCCESS) return result; // sequence number is the current session contextID out->context.sequence = contextID; // use TPM_RH_NULL as hierarchy for session context out->context.hierarchy = TPM_RH_NULL; break; } default: // SaveContext may only take an object handle or a session handle. // All the other handle type should be filtered out at unmarshal pAssert(FALSE); break; } // Save fingerprint at the beginning of encrypted area of context blob. // Reserve the integrity space MemoryCopy(out->context.contextBlob.t.buffer + integritySize, &out->context.sequence, sizeof(out->context.sequence), sizeof(out->context.contextBlob.t.buffer) - integritySize); // Compute context encryption key ComputeContextProtectionKey(&out->context, &symKey, &iv); // Encrypt context blob CryptSymmetricEncrypt(out->context.contextBlob.t.buffer + integritySize, CONTEXT_ENCRYPT_ALG, CONTEXT_ENCRYPT_KEY_BITS, TPM_ALG_CFB, symKey.t.buffer, &iv, out->context.contextBlob.t.size - integritySize, out->context.contextBlob.t.buffer + integritySize); // Compute integrity hash for the object // In this implementation, the same routine is used for both sessions // and objects. ComputeContextIntegrity(&out->context, &integrity); // add integrity at the beginning of context blob buffer = out->context.contextBlob.t.buffer; TPM2B_DIGEST_Marshal(&integrity, &buffer, NULL); // orderly state should be cleared because of the update of state reset and // state clear data g_clearOrderly = TRUE; return TPM_RC_SUCCESS; } Page 358 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 30.3 Part 3: Commands TPM2_ContextLoad 30.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 30.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 object s belong to the NULL hierarchy which is never disabled. See the “Context Data” clause in 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 Part 1 and enter failure mode if the check fails. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 359 October 31, 2013 Part 3: Commands Trusted Platform Module Library 30.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 8 UINT32 responseSize TPM_RC responseCode TPMI_DH_CONTEXT loadedHandle Page 360 October 31, 2013 the handle assigned to the resource after it has been successfully loaded Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 30.3.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "ContextLoad_fp.h" #include "Context_spt_fp.h" Error Returns 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 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 Meaning incorrect context blob size TPM_RC TPM2_ContextLoad( ContextLoad_In ContextLoad_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { // Local Variables TPM_RC result = TPM_RC_SUCCESS; TPM2B_DIGEST TPM2B_DIGEST UINT16 UINT64 BYTE INT32 ingerityToCompare; integrity; integritySize; fingerprint; *buffer; size; TPM_HT TPM2B_SYM_KEY TPM2B_IV handleType; symKey; iv; // Input Validation // Check context blob size handleType = HandleGetType(in->context.savedHandle); // Check integrity // In this implementation, the same routine is used for both sessions // and objects. integritySize = sizeof(integrity.t.size) + CryptGetHashDigestSize(CONTEXT_INTEGRITY_HASH_ALG); // Get integrity from context blob buffer = in->context.contextBlob.t.buffer; size = (INT32) in->context.contextBlob.t.size; result = TPM2B_DIGEST_Unmarshal(&integrity, &buffer, &size); if(result != TPM_RC_SUCCESS) return result; // Compute context integrity ComputeContextIntegrity(&in->context, &ingerityToCompare); Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 361 October 31, 2013 Part 3: Commands 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 Trusted Platform Module Library // Compare integrity if(!Memory2BEqual(&integrity.b, &ingerityToCompare.b)) return TPM_RC_INTEGRITY + RC_ContextLoad_context; // Compute context encryption key ComputeContextProtectionKey(&in->context, &symKey, &iv); // Decrypt context data in place CryptSymmetricDecrypt(in->context.contextBlob.t.buffer + integritySize, CONTEXT_ENCRYPT_ALG, CONTEXT_ENCRYPT_KEY_BITS, TPM_ALG_CFB, symKey.t.buffer, &iv, in->context.contextBlob.t.size - integritySize, in->context.contextBlob.t.buffer + integritySize); // Read the fingerprint value, skip the leading integrity size MemoryCopy(&fingerprint, in->context.contextBlob.t.buffer + integritySize, sizeof(fingerprint), sizeof(fingerprint)); // Check fingerprint. If the check fails, TPM should be put to failure mode if(fingerprint != in->context.sequence) FAIL(FATAL_ERROR_INTERNAL); // Perform object or session specific input check switch(handleType) { case TPM_HT_TRANSIENT: { // Get a pointer to the object in the context blob OBJECT *outObject = (OBJECT *)(in->context.contextBlob.t.buffer + integritySize + sizeof(fingerprint)); // Discard any changes to the handle that the TRM might have made in->context.savedHandle = TRANSIENT_FIRST; // If hierarchy is disabled, no object context can be loaded in this // hierarchy if(!HierarchyIsEnabled(in->context.hierarchy)) return TPM_RC_HIERARCHY + RC_ContextLoad_context; // Restore object. A TPM_RC_OBJECT_MEMORY error may be returned at // this point result = ObjectContextLoad(outObject, &out->loadedHandle); if(result != TPM_RC_SUCCESS) return result; // If this is a sequence object, the crypto library may need to // reformat the data into an internal format if(ObjectIsSequence(outObject)) SequenceDataImportExport(ObjectGet(out->loadedHandle), outObject, IMPORT_STATE); break; } case TPM_HT_POLICY_SESSION: case TPM_HT_HMAC_SESSION: { SESSION *session = (SESSION *)(in->context.contextBlob.t.buffer + integritySize + sizeof(fingerprint)); // This command may cause the orderlyState to be cleared due to // the update of state reset data. If this is the case, check if NV is // available first Page 362 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 Part 3: Commands if(gp.orderlyState != SHUTDOWN_NONE) { // The command needs NV update. Check if NV is available. // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned // at this point result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; } // Check if input handle points to a valid saved session if(!SessionIsSaved(in->context.savedHandle)) return TPM_RC_HANDLE + RC_ContextLoad_context; // Restore session. A TPM_RC_SESSION_MEMORY, TPM_RC_CONTEXT_GAP error // may be returned at this point result = SessionContextLoad(session, &in->context.savedHandle); if(result != TPM_RC_SUCCESS) return result; out->loadedHandle = in->context.savedHandle; // orderly state should be cleared because of the update of state // reset and state clear data g_clearOrderly = TRUE; break; } default: // Context blob may only have an object handle or a session handle. // All the other handle type should be filtered out at unmarshal pAssert(FALSE); break; } return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 363 October 31, 2013 Part 3: Commands 30.4 Trusted Platform Module Library TPM2_FlushContext 30.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 TPM_ST_NO_SESSIONS (see note in 30.2.1). this command and tag is required to be 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 . Page 364 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 30.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 TPMI_DH_CONTEXT flushHandle TPM_CC_FlushContext the handle of the item to flush NOTE This is a use of a handle as a parameter. Table 184 — TPM2_FlushContext Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 365 October 31, 2013 Part 3: Commands Trusted Platform Module Library 30.4.3 Detailed Actions 1 2 #include "InternalRoutines.h" #include "FlushContext_fp.h" Error Returns TPM_RC_HANDLE 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 Meaning flushHandle does not reference a loaded object or session TPM_RC TPM2_FlushContext( FlushContext_In ) { // Internal Data Update *in // IN: input parameter list // Call object or session specific routine to flush switch(HandleGetType(in->flushHandle)) { case TPM_HT_TRANSIENT: if(!ObjectIsPresent(in->flushHandle)) return TPM_RC_HANDLE; // Flush object ObjectFlush(in->flushHandle); break; case TPM_HT_HMAC_SESSION: case TPM_HT_POLICY_SESSION: if( !SessionIsLoaded(in->flushHandle) && !SessionIsSaved(in->flushHandle) ) return TPM_RC_HANDLE; // If the session to be flushed is the exclusive audit session, then // indicate that there is no exclusive audit session any longer. if(in->flushHandle == g_exclusiveAuditSession) g_exclusiveAuditSession = TPM_RH_UNASSIGNED; // Flush session SessionFlush(in->flushHandle); break; default: // This command only take object or session handle. // should be filtered out at handle unmarshal pAssert(FALSE); break; } Other handles return TPM_RC_SUCCESS; } Page 366 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 30.5 Part 3: Commands TPM2_EvictControl 30.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 such 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 move objects to/from TPM memory in order to ensure that the objects required for command execution can be context restored. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 367 October 31, 2013 Part 3: Commands Trusted Platform Module Library 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. If objectHandle references a persistent object: h) 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. i) 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. Page 368 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 30.5.2 Command and Response Table 185 — TPM2_EvictControl Command Type Name TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_EvictControl {NV} TPMI_RH_PROVISION @auth TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} Auth Handle: 1 Auth Role: USER TPMI_DH_OBJECT objectHandle the handle of a loaded object Auth Index: None TPMI_DH_PERSISTENT persistentHandle if objectHandle is a transient object handle, then this is the persistent handle for the object if objectHandle is a persistent object handle, then this shall be the same value as persistentHandle Description Table 186 — TPM2_EvictControl Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 369 October 31, 2013 Part 3: Commands Trusted Platform Module Library 30.5.3 Detailed Actions 1 2 #include "InternalRoutines.h" #include "EvictControl_fp.h" Error Returns 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 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 Meaning persistentHandle is not in the range corresponding to the hierarchy of evictObject TPM_RC TPM2_EvictControl( EvictControl_In *in // IN: input parameter list ) { TPM_RC OBJECT result; *evictObject; // The command needs NV update. Check if NV is available. // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at // this point result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; // Input Validation // Get internal object pointer evictObject = ObjectGet(in->objectHandle); // Temporary, stClear or public only objects can not be made persistent if( evictObject->attributes.temporary == SET || evictObject->attributes.stClear == SET || evictObject->attributes.publicOnly == SET ) return TPM_RC_ATTRIBUTES + RC_EvictControl_objectHandle; // If objectHandle refers to a persistent object, it should be the same as // input persistentHandle if( evictObject->attributes.evict == SET && evictObject->evictHandle != in->persistentHandle ) return TPM_RC_HANDLE + RC_EvictControl_objectHandle; // Additional auth validation if(in->auth == TPM_RH_PLATFORM) { // To make persistent if(evictObject->attributes.evict == CLEAR) { // Platform auth can not set evict object in storage or endorsement // hierarchy Page 370 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 Part 3: Commands if(evictObject->attributes.ppsHierarchy == CLEAR) return TPM_RC_HIERARCHY + RC_EvictControl_objectHandle; // Platform cannot use a handle outside of platform persistent range. if(!NvIsPlatformPersistentHandle(in->persistentHandle)) return TPM_RC_RANGE + RC_EvictControl_persistentHandle; } // Platform auth can delete any persistent object } else if(in->auth == TPM_RH_OWNER) { // Owner auth can not set or clear evict object in platform hierarchy if(evictObject->attributes.ppsHierarchy == SET) return TPM_RC_HIERARCHY + RC_EvictControl_objectHandle; // Owner cannot use a handle outside of owner persistent range. if( evictObject->attributes.evict == CLEAR && !NvIsOwnerPersistentHandle(in->persistentHandle) ) return TPM_RC_RANGE + RC_EvictControl_persistentHandle; } else { // Other auth is not allowed in this command and should be filtered out // at unmarshal process pAssert(FALSE); } // Internal Data Update // Change evict state if(evictObject->attributes.evict == CLEAR) { // Make object persistent // A TPM_RC_NV_HANDLE or TPM_RC_NV_SPACE error may be returned at this // point result = NvAddEvictObject(in->persistentHandle, evictObject); if(result != TPM_RC_SUCCESS) return result; } else { // Delete the persistent object in NV NvDeleteEntity(evictObject->evictHandle); } return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 371 October 31, 2013 Part 3: Commands 31 Trusted Platform Module Library Clocks and Timers 31.1 TPM2_ReadClock 31.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. Page 372 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 31.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 8 UINT32 responseSize TPM_RC returnCode TPMS_TIME_INFO currentTime Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 373 October 31, 2013 Part 3: Commands Trusted Platform Module Library 31.1.3 Detailed Actions 1 2 3 4 5 6 7 8 9 10 11 12 13 14 #include "InternalRoutines.h" #include "ReadClock_fp.h" TPM_RC TPM2_ReadClock( ReadClock_Out *out ) { // Command Output // OUT: output parameter list out->currentTime.time = g_time; TimeFillInfo(&out->currentTime.clockInfo); return TPM_RC_SUCCESS; } Page 374 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 31.2 Part 3: Commands TPM2_ClockSet 31.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 years 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 platformAuth or ownerAuth. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 375 October 31, 2013 Part 3: Commands Trusted Platform Module Library 31.2.2 Command and Response Table 189 — TPM2_ClockSet Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_ClockSet {NV} TPMI_RH_PROVISION @auth TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} 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 8 UINT32 responseSize TPM_RC returnCode Page 376 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 31.2.3 Detailed Actions 1 2 #include "InternalRoutines.h" #include "ClockSet_fp.h" Read the current TPMS_TIMER_INFO structure settings Error Returns TPM_RC_VALUE 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 Meaning invalid new clock TPM_RC TPM2_ClockSet( ClockSet_In *in ) { #define CLOCK_UPDATE_MASK UINT64 clockNow; // IN: input parameter list ((1ULL << NV_CLOCK_UPDATE_INTERVAL)- 1) // Input Validation // new time can not be bigger than 0xFFFF000000000000 or smaller than // current clock if(in->newTime > 0xFFFF000000000000ULL || in->newTime < go.clock) return TPM_RC_VALUE + RC_ClockSet_newTime; // Internal Data Update // Internal Data Update clockNow = go.clock; // grab the old value go.clock = in->newTime; // set the new value // Check to see if the update has caused a need for an nvClock update if((in->newTime & CLOCK_UPDATE_MASK) > (clockNow & CLOCK_UPDATE_MASK)) { CryptDrbgGetPutState(GET_STATE); NvWriteReserved(NV_ORDERLY_DATA, &go); // Now the time state is safe go.clockSafe = YES; } return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 377 October 31, 2013 Part 3: Commands 31.3 Trusted Platform Module Library TPM2_ClockRateAdjust 31.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 m ake 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. Page 378 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 31.3.2 Command and Response Table 191 — TPM2_ClockRateAdjust Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_ClockRateAdjust TPMI_RH_PROVISION @auth TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} 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 8 UINT32 responseSize TPM_RC returnCode Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 379 October 31, 2013 Part 3: Commands Trusted Platform Module Library 31.3.3 Detailed Actions 1 2 3 4 5 6 7 8 9 10 11 12 #include "InternalRoutines.h" #include "ClockRateAdjust_fp.h" TPM_RC TPM2_ClockRateAdjust( ClockRateAdjust_In *in ) { // Internal Data Update TimeSetAdjustRate(in->rateAdjust); // IN: input parameter list return TPM_RC_SUCCESS; } Page 380 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 32 Part 3: Commands Capability Commands 32.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 32.2 TPM2_TestParms()is used to determine if a TPM supports a particular combination of algorithm parameters TPM2_GetCapability 32.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. On 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, use 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. 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 2 The moreData parameter will be YES if there are more properties e ven 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 may 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: Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 381 October 31, 2013 Part 3: Commands Trusted Platform Module Library  TPM_PT_MANUFACTURER  TPM_PT_VENDOR_STRING_1  TPM_PT_VENDOR_STRING_2 (3)  TPM_PT_VENDOR_STRING_3 (3)  TPM_PT_VENDOR_STRING_4 (3)  TPM_PT_VENDOR_TPM_TYPE  TPM_PT_FIRMWARE_VERSION_1  TPM_PT_FIRMWARE_VERSION_2 NOTE 3 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_M ANUFACTURER, 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 Return Type property (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 TPM_CAP_VENDOR_PROPERTY manufacturer specific TPML_ECC_CURVE manufacturer-specific values NOTES: (1) The TPM_ALG_ID or TPM_ECC_CURVE is cast to a UINT32 Page 382 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands  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 EXAMPLE 5  If the MSO of property is TPM_HT_NV_INDEX, then the TPM will return a list of NV Index values. 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 2  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 4 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 256value 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 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. NOTE 5 If the propertyCount selects an unimplemented property, the next higher implemented property is returned. Each item in the list is a TPMS_PCR_SELECT structure that contains a bitmap of all PCR. NOTE 6 A PCR index in all banks (all hash algorithms) has the same properties, so the hash algorithm is not specified here. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 383 October 31, 2013 Part 3: Commands  Trusted Platform Module Library 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. Page 384 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 32.2.2 Command and Response Table 193 — TPM2_GetCapability Command Type Name Description TPMI_ST_COMMAND_TAG tag 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 8 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 Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 385 October 31, 2013 Part 3: Commands Trusted Platform Module Library 32.2.3 Detailed Actions 1 2 #include "InternalRoutines.h" #include "GetCapability_fp.h" Error Returns TPM_RC_HANDLE value of property is in an unsupported handle range for the TPM_CAP_HANDLES capability value TPM_RC_VALUE 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 Meaning invalid capability; or property is not 0 for the TPM_CAP_PCRS capability value TPM_RC TPM2_GetCapability( GetCapability_In GetCapability_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { // Command Output // Set output capability type the same as input type out->capabilityData.capability = in->capability; switch(in->capability) { case TPM_CAP_ALGS: out->moreData = AlgorithmCapGetImplemented((TPM_ALG_ID) in->property, in->propertyCount, &out->capabilityData.data.algorithms); break; case TPM_CAP_HANDLES: switch(HandleGetType((TPM_HANDLE) in->property)) { case TPM_HT_TRANSIENT: // Get list of handles of loaded transient objects out->moreData = ObjectCapGetLoaded((TPM_HANDLE) in->property, in->propertyCount, &out->capabilityData.data.handles); break; case TPM_HT_PERSISTENT: // Get list of handles of persistent objects out->moreData = NvCapGetPersistent((TPM_HANDLE) in->property, in->propertyCount, &out->capabilityData.data.handles); break; case TPM_HT_NV_INDEX: // Get list of defined NV index out->moreData = NvCapGetIndex((TPM_HANDLE) in->property, in->propertyCount, &out->capabilityData.data.handles); break; case TPM_HT_LOADED_SESSION: // Get list of handles of loaded sessions out->moreData = SessionCapGetLoaded((TPM_HANDLE) in->property, in->propertyCount, &out->capabilityData.data.handles); break; case TPM_HT_ACTIVE_SESSION: // Get list of handles of out->moreData = SessionCapGetSaved((TPM_HANDLE) in->property, in->propertyCount, &out->capabilityData.data.handles); Page 386 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 Part 3: Commands break; case TPM_HT_PCR: // Get list of handles of PCR out->moreData = PCRCapGetHandles((TPM_HANDLE) in->property, in->propertyCount, &out->capabilityData.data.handles); break; case TPM_HT_PERMANENT: // Get list of permanent handles out->moreData = PermanentCapGetHandles( (TPM_HANDLE) in->property, in->propertyCount, &out->capabilityData.data.handles); break; default: // Unsupported input handle type return TPM_RC_HANDLE + RC_GetCapability_property; break; } break; case TPM_CAP_COMMANDS: out->moreData = CommandCapGetCCList((TPM_CC) in->property, in->propertyCount, &out->capabilityData.data.command); break; case TPM_CAP_PP_COMMANDS: out->moreData = PhysicalPresenceCapGetCCList((TPM_CC) in->property, in->propertyCount, &out->capabilityData.data.ppCommands); break; case TPM_CAP_AUDIT_COMMANDS: out->moreData = CommandAuditCapGetCCList((TPM_CC) in->property, in->propertyCount, &out->capabilityData.data.auditCommands); break; case TPM_CAP_PCRS: // Input property must be 0 if(in->property != 0) return TPM_RC_VALUE + RC_GetCapability_property; out->moreData = PCRCapGetAllocation(in->propertyCount, &out->capabilityData.data.assignedPCR); break; case TPM_CAP_PCR_PROPERTIES: out->moreData = PCRCapGetProperties((TPM_PT_PCR) in->property, in->propertyCount, &out->capabilityData.data.pcrProperties); break; case TPM_CAP_TPM_PROPERTIES: out->moreData = TPMCapGetProperties((TPM_PT) in->property, in->propertyCount, &out->capabilityData.data.tpmProperties); break; #ifdef TPM_ALG_ECC case TPM_CAP_ECC_CURVES: out->moreData = CryptCapGetECCCurve((TPM_ECC_CURVE ) in->property, in->propertyCount, &out->capabilityData.data.eccCurves); break; #endif // TPM_ALG_ECC case TPM_CAP_VENDOR_PROPERTY: // vendor property is not implemented default: // Unexpected TPM_CAP value return TPM_RC_VALUE; break; Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 387 October 31, 2013 Part 3: Commands 116 117 118 119 Trusted Platform Module Library } return TPM_RC_SUCCESS; } Page 388 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 32.3 Part 3: Commands TPM2_TestParms 32.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. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 389 October 31, 2013 Part 3: Commands Trusted Platform Module Library 32.3.2 Command and Response Table 195 — TPM2_TestParms Command Type Name Description TPMI_ST_COMMAND_TAG tag 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 8 UINT32 responseSize TPM_RC responseCode Page 390 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 32.3.3 Detailed Actions 1 2 3 4 5 6 7 8 9 10 11 12 13 14 #include "InternalRoutines.h" #include "TestParms_fp.h" TPM_RC TPM2_TestParms( TestParms_In *in // IN: input parameter list ) { // Input parameter is not reference in command action in = NULL; // The parameters are tested at unmarshal process. // action return TPM_RC_SUCCESS; We do nothing in command } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 391 October 31, 2013 Part 3: Commands 33 Trusted Platform Module Library Non-volatile Storage 33.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. 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, ownerAuth may not be used if shEnable is CLEAR and platformAuth may not be used if phEnableNV is CLEAR. If an Index was defined using platformAuth, then that Index is not accessible when phEnableNV is CLEAR. If an Index was defined using ownerAuth, 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 implementationdependent 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 Ind ex. Page 392 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 33.2 Part 3: Commands 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 nonvolatile 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 counters 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 p rocess (orderly or not) of the TPM. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 393 October 31, 2013 Part 3: Commands 33.3 Trusted Platform Module Library TPM2_NV_DefineSpace 33.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 TPMA_NV_BITS, or TPMA_NV_EXTEND is SET in publicInfo. NOTE than one of TPMA_NV_COUNTER, 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 The limit for the data size may vary according to the type of the index. For example, if the index is has TPMA_NV_ORDERLY SET, then the maximum size of an ordin ary 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, TPMA_NV_POLICYREAD shall be SET or the TPM shall return TPM_RC_ATTRIBUTES. or 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 platformAuth or the TPM shall return TPM_RC_ATTRIBUTES. If the implementation does not support TPM2_NV_Increment(), TPM_RC_ATTRIBUTES if TPMA_NV_COUNTER is SET. the TPM shall return If the implementation does not support TPM2_NV_SetBits(), TPM_RC_ATTRIBUTES if TPMA_NV_BITS is SET. the TPM shall return If the implementation does not support TPM2_NV_Extend(), TPM_RC_ATTRIBUTES if TPMA_NV_EXTEND is SET. the TPM shall return 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. Page 394 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 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). Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 395 October 31, 2013 Part 3: Commands Trusted Platform Module Library 33.3.2 Command and Response Table 197 — TPM2_NV_DefineSpace Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_NV_DefineSpace {NV} TPMI_RH_PROVISION @authHandle TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} 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 8 UINT32 responseSize TPM_RC responseCode Page 396 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 33.3.3 Detailed Actions 1 2 #include "InternalRoutines.h" #include "NV_DefineSpace_fp.h" Error Returns 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 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 Meaning 'auth->size' or 'publicInfo->authPolicy. size' is larger than the digest size of 'publicInfo->nameAlg', or 'publicInfo->dataSize' is not consistent with 'publicInfo->attributes'. TPM_RC TPM2_NV_DefineSpace( NV_DefineSpace_In *in // IN: input parameter list ) { TPM_RC TPMA_NV UINT16 result; attributes; nameSize; nameSize = CryptGetHashDigestSize(in->publicInfo.t.nvPublic.nameAlg); // Check if NV is available. NvIsAvailable may return TPM_RC_NV_UNAVAILABLE // TPM_RC_NV_RATE or TPM_RC_SUCCESS. result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; // Input Validation // If an index is being created by the owner and shEnable is // clear, then we would not reach this point because ownerAuth // can't be given when shEnable is CLEAR. However, if phEnable // is SET but phEnableNV is CLEAR, we have to check here if(in->authHandle == TPM_RH_PLATFORM && gc.phEnableNV == CLEAR) return TPM_RC_HIERARCHY + RC_NV_DefineSpace_authHandle; attributes = in->publicInfo.t.nvPublic.attributes; //TPMS_NV_PUBLIC validation. // Counters and bit fields must have a size of 8 if ( (attributes.TPMA_NV_COUNTER == SET || attributes.TPMA_NV_BITS == SET) && (in->publicInfo.t.nvPublic.dataSize != 8)) return TPM_RC_SIZE + RC_NV_DefineSpace_publicInfo; // check that the authPolicy consistent with hash algorithm if( in->publicInfo.t.nvPublic.authPolicy.t.size != 0 && in->publicInfo.t.nvPublic.authPolicy.t.size != nameSize) return TPM_RC_SIZE + RC_NV_DefineSpace_publicInfo; // make sure that the authValue is not too large MemoryRemoveTrailingZeros(&in->auth); if(in->auth.t.size > nameSize) return TPM_RC_SIZE + RC_NV_DefineSpace_auth; Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 397 October 31, 2013 Part 3: Commands 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 Trusted Platform Module Library //TPMA_NV validation. // Locks may not be SET and written cannot be SET if( attributes.TPMA_NV_WRITTEN == SET || attributes.TPMA_NV_WRITELOCKED == SET || attributes.TPMA_NV_READLOCKED == SET) return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; // There must be a way to read the index if( attributes.TPMA_NV_OWNERREAD == CLEAR && attributes.TPMA_NV_PPREAD == CLEAR && attributes.TPMA_NV_AUTHREAD == CLEAR && attributes.TPMA_NV_POLICYREAD == CLEAR) return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; // There must be a way to write the index if( attributes.TPMA_NV_OWNERWRITE == CLEAR && attributes.TPMA_NV_PPWRITE == CLEAR && attributes.TPMA_NV_AUTHWRITE == CLEAR && attributes.TPMA_NV_POLICYWRITE == CLEAR) return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; // Make sure that no attribute is used that is not supported by the proper // command #if CC_NV_Increment == NO if( attributes.TPMA_NV_COUNTER == SET) return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; #endif #if CC_NV_SetBits == NO if( attributes.TPMA_NV_BITS == SET) return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; #endif #if CC_NV_Extend == NO if( attributes.TPMA_NV_EXTEND == SET) return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; #endif #if CC_NV_UndefineSpaceSpecial == NO if( attributes.TPMA_NV_POLICY_DELETE == SET) return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; #endif // Can be COUNTER or BITS or EXTEND but not more than one if( attributes.TPMA_NV_COUNTER == SET && attributes.TPMA_NV_BITS == SET) return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; if( attributes.TPMA_NV_COUNTER == SET && attributes.TPMA_NV_EXTEND == SET) return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; if( attributes.TPMA_NV_BITS == SET && attributes.TPMA_NV_EXTEND == SET) return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; // An index with TPMA_NV_CLEAR_STCLEAR can't be a counter if( attributes.TPMA_NV_CLEAR_STCLEAR == SET && attributes.TPMA_NV_COUNTER == SET) return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; // The index is allowed to have one of GLOBALLOCK or WRITEDEFINE SET if( attributes.TPMA_NV_GLOBALLOCK == SET && attributes.TPMA_NV_WRITEDEFINE == SET) return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; // Make sure that the creator of the index can delete the index Page 398 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 if( Part 3: Commands ( in->publicInfo.t.nvPublic.attributes.TPMA_NV_PLATFORMCREATE == SET && in->authHandle == TPM_RH_OWNER ) || ( in->publicInfo.t.nvPublic.attributes.TPMA_NV_PLATFORMCREATE == CLEAR && in->authHandle == TPM_RH_PLATFORM ) ) return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_authHandle; // If TPMA_NV_POLICY_DELETE is SET, then the index must be defined by // the platform if( in->publicInfo.t.nvPublic.attributes.TPMA_NV_POLICY_DELETE == SET && TPM_RH_PLATFORM != in->authHandle ) return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; // If the NV index is used as a PCR, the data size must match the digest // size if( in->publicInfo.t.nvPublic.attributes.TPMA_NV_EXTEND == SET && in->publicInfo.t.nvPublic.dataSize != nameSize ) return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; // See if the index is already defined. if(NvIsUndefinedIndex(in->publicInfo.t.nvPublic.nvIndex)) return TPM_RC_NV_DEFINED; // Internal Data Update // define the space. A TPM_RC_NV_SPACE error may be returned at this point result = NvDefineIndex(&in->publicInfo.t.nvPublic, &in->auth); if(result != TPM_RC_SUCCESS) return result; return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 399 October 31, 2013 Part 3: Commands 33.4 Trusted Platform Module Library TPM2_NV_UndefineSpace 33.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_AUTHORITY unless platformAuth is provided. NOTE An Index with TPMA_NV_PLATFORMCREATE CLEAR may be deleted with platformAuth as long as shEnable is SET. If shEnable is CLEAR, indexes created using ownerAuth are not accessible even for deletion by the platform. Page 400 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 33.4.2 Command and Response Table 199 — TPM2_NV_UndefineSpace Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_NV_UndefineSpace {NV} TPMI_RH_PROVISION @authHandle TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} Auth Index: 1 Auth Role: USER TPMI_RH_NV_INDEX nvIndex the NV Index to remove from NV space Auth Index: None Table 200 — TPM2_NV_UndefineSpace Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 401 October 31, 2013 Part 3: Commands Trusted Platform Module Library 33.4.3 Detailed Actions 1 2 #include "InternalRoutines.h" #include "NV_UndefineSpace_fp.h" Error Returns 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 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 Meaning attempt to use ownerAuth to delete an index created by the platform TPM_RC TPM2_NV_UndefineSpace( NV_UndefineSpace_In *in // IN: input parameter list ) { TPM_RC NV_INDEX result; nvIndex; // The command needs NV update. Check if NV is available. // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at // this point result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; // Input Validation // Get NV index info NvGetIndexInfo(in->nvIndex, &nvIndex); // This command can't be used to delete an index with TPMA_NV_POLICY_DELETE SET if(SET == nvIndex.publicArea.attributes.TPMA_NV_POLICY_DELETE) return TPM_RC_ATTRIBUTES + RC_NV_UndefineSpace_nvIndex; // The owner may only delete an index that was defined with ownerAuth. The // platform may delete an index that was created with either auth. if( in->authHandle == TPM_RH_OWNER && nvIndex.publicArea.attributes.TPMA_NV_PLATFORMCREATE == SET) return TPM_RC_NV_AUTHORIZATION; // Internal Data Update // Call implementation dependent internal routine to delete NV index NvDeleteEntity(in->nvIndex); return TPM_RC_SUCCESS; } Page 402 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 33.5 Part 3: Commands TPM2_NV_UndefineSpaceSpecial 33.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 undefined 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 TPMA_NV_POLICY_DELETE attribute CLEAR, the TPM shall return TPM_RC_NV_ATTRIBUTES. NOTE or 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 ownerAuth are not accessible even for deletion by the platform . Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 403 October 31, 2013 Part 3: Commands Trusted Platform Module Library 33.5.2 Command and Response Table 201 — TPM2_NV_UndefineSpaceSpecial Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_NV_UndefineSpaceSpecial {NV} TPMI_RH_NV_INDEX @nvIndex Index to be deleted Auth Index: 1 Auth Role: ADMIN TPMI_RH_PLATFORM @platform TPM_RH_PLATFORM + {PP} Auth Index: 2 Auth Role: USER Table 202 — TPM2_NV_UndefineSpaceSpecial Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode Page 404 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 33.5.3 Detailed Actions 1 2 #include "InternalRoutines.h" #include "NV_UndefineSpaceSpecial_fp.h" Error Returns TPM_RC_ATTRIBUTES 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 Meaning TPMA_NV_POLICY_DELETE is not SET in the Index referenced by nvIndex TPM_RC TPM2_NV_UndefineSpaceSpecial( NV_UndefineSpaceSpecial_In *in // IN: input parameter list ) { TPM_RC NV_INDEX result; nvIndex; // The command needs NV update. Check if NV is available. // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at // this point result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; // Input Validation // Get NV index info NvGetIndexInfo(in->nvIndex, &nvIndex); // This operation only applies when the TPMA_NV_POLICY_DELETE attribute is SET if(CLEAR == nvIndex.publicArea.attributes.TPMA_NV_POLICY_DELETE) return TPM_RC_ATTRIBUTES + RC_NV_UndefineSpaceSpecial_nvIndex; // Internal Data Update // Call implementation dependent internal routine to delete NV index NvDeleteEntity(in->nvIndex); return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 405 October 31, 2013 Part 3: Commands 33.6 Trusted Platform Module Library TPM2_NV_ReadPublic 33.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. Page 406 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 33.6.2 Command and Response Table 203 — TPM2_NV_ReadPublic Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_NV_ReadPublic TPMI_RH_NV_INDEX nvIndex the NV Index Auth Index: None Table 204 — TPM2_NV_ReadPublic Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode TPM2B_NV_PUBLIC nvPublic the public area of the NV Index TPM2B_NAME nvName the Name of the nvIndex Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 407 October 31, 2013 Part 3: Commands Trusted Platform Module Library 33.6.3 Detailed Actions 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 #include "InternalRoutines.h" #include "NV_ReadPublic_fp.h" TPM_RC TPM2_NV_ReadPublic( NV_ReadPublic_In NV_ReadPublic_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { NV_INDEX nvIndex; // Command Output // Get NV index info NvGetIndexInfo(in->nvIndex, &nvIndex); // Copy data to output out->nvPublic.t.nvPublic = nvIndex.publicArea; // Compute NV name out->nvName.t.size = NvGetName(in->nvIndex, &out->nvName.t.name); return TPM_RC_SUCCESS; } Page 408 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 33.7 Part 3: Commands TPM2_NV_Write 33.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_NV_ATTRIBUTE. 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. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 409 October 31, 2013 Part 3: Commands Trusted Platform Module Library 33.7.2 Command and Response Table 205 — TPM2_NV_Write Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_NV_Write {NV} TPMI_RH_NV_AUTH @authHandle handle indicating the source of the authorization value Auth Index: 1 Auth Role: USER TPMI_RH_NV_INDEX nvIndex the NV Index of the area to write 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 8 UINT32 responseSize TPM_RC responseCode Page 410 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 33.7.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "NV_Write_fp.h" #include "NV_spt_fp.h" Error Returns 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 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 Meaning 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 TPM_RC TPM2_NV_Write( NV_Write_In *in // IN: input parameter list ) { NV_INDEX TPM_RC nvIndex; result; // Input Validation // Get NV index info NvGetIndexInfo(in->nvIndex, &nvIndex); // common access checks. NvWrtieAccessChecks() may return // TPM_RC_NV_AUTHORIZATION or TPM_RC_NV_LOCKED result = NvWriteAccessChecks(in->authHandle, in->nvIndex); if(result != TPM_RC_SUCCESS) return result; // Bits index, extend index or counter index may not be updated by // TPM2_NV_Write if( nvIndex.publicArea.attributes.TPMA_NV_COUNTER == SET || nvIndex.publicArea.attributes.TPMA_NV_BITS == SET || nvIndex.publicArea.attributes.TPMA_NV_EXTEND == SET) return TPM_RC_ATTRIBUTES; // Too much data if((in->data.t.size + in->offset) > nvIndex.publicArea.dataSize) return TPM_RC_NV_RANGE; // If this index requires a full sized write, make sure that input range is // full sized if( nvIndex.publicArea.attributes.TPMA_NV_WRITEALL == SET && in->data.t.size < nvIndex.publicArea.dataSize) return TPM_RC_NV_RANGE; // Internal Data Update // Perform the write. This called routine will SET the TPMA_NV_WRITTEN // attribute if it has not already been SET. If NV isn't available, an error // will be returned. return NvWriteIndexData(in->nvIndex, &nvIndex, in->offset, Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 411 October 31, 2013 Part 3: Commands 46 47 48 Trusted Platform Module Library in->data.t.size, in->data.t.buffer); } Page 412 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 33.8 Part 3: Commands TPM2_NV_Increment 33.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 TPM_RC_ATTRIBUTES. is not SET in the indicated NV Index, the TPM shall return 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. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 413 October 31, 2013 Part 3: Commands Trusted Platform Module Library 33.8.2 Command and Response Table 207 — TPM2_NV_Increment Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_NV_Increment {NV} TPMI_RH_NV_AUTH @authHandle handle indicating the source of the authorization value Auth Index: 1 Auth Role: USER TPMI_RH_NV_INDEX nvIndex the NV Index to increment Auth Index: None Table 208 — TPM2_NV_Increment Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode Page 414 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 33.8.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "NV_Increment_fp.h" #include "NV_spt_fp.h" Error Returns TPM_RC_ATTRIBUTES NV index is not a counter TPM_RC_NV_AUTHORIZATION authorization failure TPM_RC_NV_LOCKED 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 Meaning Index is write locked TPM_RC TPM2_NV_Increment( NV_Increment_In *in // IN: input parameter list ) { TPM_RC NV_INDEX UINT64 result; nvIndex; countValue; // Input Validation // Common access checks, a TPM_RC_NV_AUTHORIZATION or TPM_RC_NV_LOCKED // error may be returned at this point result = NvWriteAccessChecks(in->authHandle, in->nvIndex); if(result != TPM_RC_SUCCESS) return result; // Get NV index info NvGetIndexInfo(in->nvIndex, &nvIndex); // Make sure that this is a counter if(nvIndex.publicArea.attributes.TPMA_NV_COUNTER != SET) return TPM_RC_ATTRIBUTES + RC_NV_Increment_nvIndex; // Internal Data Update // If counter index is not been written, initialize it if(nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == CLEAR) countValue = NvInitialCounter(); else // Read NV data in native format for TPM CPU. NvGetIntIndexData(in->nvIndex, &nvIndex, &countValue); // Do the increment countValue++; // If this is an orderly counter that just rolled over, need to be able to // write to NV to proceed. This check is done here, because NvWriteIndexData() // does not see if the update is for counter rollover. if( nvIndex.publicArea.attributes.TPMA_NV_ORDERLY == SET && (countValue & MAX_ORDERLY_COUNT) == 0) { result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; // Need to force an NV update Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 415 October 31, 2013 Part 3: Commands 52 53 54 55 56 57 58 59 60 Trusted Platform Module Library g_updateNV = TRUE; } // Write NV data back. A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may // be returned at this point. If necessary, this function will set the // TPMA_NV_WRITTEN attribute return NvWriteIndexData(in->nvIndex, &nvIndex, 0, 8, &countValue); } Page 416 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 33.9 Part 3: Commands TPM2_NV_Extend 33.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 or the NV Index is cleared. 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. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 417 October 31, 2013 Part 3: Commands Trusted Platform Module Library 33.9.2 Command and Response Table 209 — TPM2_NV_Extend Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_NV_Extend {NV} TPMI_RH_NV_AUTH @authHandle handle indicating the source of the authorization value Auth Index: 1 Auth Role: USER TPMI_RH_NV_INDEX nvIndex the NV Index to extend 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 8 UINT32 responseSize TPM_RC responseCode Page 418 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 33.9.3 Detailed Actions 1 2 3 #include "InternalRoutines.h" #include "NV_Extend_fp.h" #include "NV_spt_fp.h" Error Returns 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 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 Meaning the Index referenced by nvIndex is locked for writing TPM_RC TPM2_NV_Extend( NV_Extend_In *in // IN: input parameter list ) { TPM_RC NV_INDEX result; nvIndex; TPM2B_DIGEST TPM2B_DIGEST HASH_STATE oldDigest; newDigest; hashState; // Input Validation // Common access checks, NvWriteAccessCheck() may return TPM_RC_NV_AUTHORIZATION // or TPM_RC_NV_LOCKED result = NvWriteAccessChecks(in->authHandle, in->nvIndex); if(result != TPM_RC_SUCCESS) return result; // Get NV index info NvGetIndexInfo(in->nvIndex, &nvIndex); // Make sure that this is an extend index if(nvIndex.publicArea.attributes.TPMA_NV_EXTEND != SET) return TPM_RC_ATTRIBUTES + RC_NV_Extend_nvIndex; // If the Index is not-orderly, or if this is the first write, NV will // need to be updated. if( nvIndex.publicArea.attributes.TPMA_NV_ORDERLY == CLEAR || nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == CLEAR) { // Check if NV is available. NvIsAvailable may return TPM_RC_NV_UNAVAILABLE // TPM_RC_NV_RATE or TPM_RC_SUCCESS. result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; } // Internal Data Update // Perform the write. oldDigest.t.size = CryptGetHashDigestSize(nvIndex.publicArea.nameAlg); if(nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == SET) { NvGetIndexData(in->nvIndex, &nvIndex, 0, Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 419 October 31, 2013 Part 3: Commands 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 Trusted Platform Module Library oldDigest.t.size, oldDigest.t.buffer); } else { MemorySet(oldDigest.t.buffer, 0, oldDigest.t.size); } // Start hash newDigest.t.size = CryptStartHash(nvIndex.publicArea.nameAlg, &hashState); // Adding old digest CryptUpdateDigest2B(&hashState, &oldDigest.b); // Adding new data CryptUpdateDigest2B(&hashState, &in->data.b); // Complete hash CryptCompleteHash2B(&hashState, &newDigest.b); // Write extended hash back. // Note, this routine will SET the TPMA_NV_WRITTEN attribute if necessary return NvWriteIndexData(in->nvIndex, &nvIndex, 0, newDigest.t.size, newDigest.t.buffer); } Page 420 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 33.10 TPM2_NV_SetBits 33.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. The checks on data and offset are the same as for TPM2_NV_Write. 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. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 421 October 31, 2013 Part 3: Commands 33.10.2 Trusted Platform Module Library Command and Response Table 211 — TPM2_NV_SetBits Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_NV_SetBits {NV} TPMI_RH_NV_AUTH @authHandle handle indicating the source of the authorization value Auth Index: 1 Auth Role: USER TPMI_RH_NV_INDEX nvIndex NV Index of the area in which the bit is to be set 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 8 UINT32 responseSize TPM_RC responseCode Page 422 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 33.10.3 1 2 3 Part 3: Commands Detailed Actions #include "InternalRoutines.h" #include "NV_SetBits_fp.h" #include "NV_spt_fp.h" Error Returns 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 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 Meaning the Index referenced by nvIndex is locked for writing TPM_RC TPM2_NV_SetBits( NV_SetBits_In *in // IN: input parameter list ) { TPM_RC NV_INDEX UINT64 result; nvIndex; bitValue; // Input Validation // Common access checks, NvWriteAccessCheck() may return TPM_RC_NV_AUTHORIZATION // or TPM_RC_NV_LOCKED // error may be returned at this point result = NvWriteAccessChecks(in->authHandle, in->nvIndex); if(result != TPM_RC_SUCCESS) return result; // Get NV index info NvGetIndexInfo(in->nvIndex, &nvIndex); // Make sure that this is a bit field if(nvIndex.publicArea.attributes.TPMA_NV_BITS != SET) return TPM_RC_ATTRIBUTES + RC_NV_SetBits_nvIndex; // If the Index is not-orderly, or if this is the first write, NV will // need to be updated. if( nvIndex.publicArea.attributes.TPMA_NV_ORDERLY == CLEAR || nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == CLEAR) { // Check if NV is available. NvIsAvailable may return TPM_RC_NV_UNAVAILABLE // TPM_RC_NV_RATE or TPM_RC_SUCCESS. result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; } // Internal Data Update // If index is not been written, initialize it if(nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == CLEAR) bitValue = 0; else // Read index data Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 423 October 31, 2013 Part 3: Commands 50 51 52 53 54 55 56 57 58 59 Trusted Platform Module Library NvGetIntIndexData(in->nvIndex, &nvIndex, &bitValue); // OR in the new bit setting bitValue |= in->bits; // Write index data back. If necessary, this function will SET // TPMA_NV_WRITTEN. return NvWriteIndexData(in->nvIndex, &nvIndex, 0, 8, &bitValue); } Page 424 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 33.11 TPM2_NV_WriteLock 33.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. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 425 October 31, 2013 Part 3: Commands 33.11.2 Trusted Platform Module Library Command and Response Table 213 — TPM2_NV_WriteLock Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_NV_WriteLock {NV} TPMI_RH_NV_AUTH @authHandle handle indicating the source of the authorization value Auth Index: 1 Auth Role: USER TPMI_RH_NV_INDEX nvIndex the NV Index of the area to lock Auth Index: None Table 214 — TPM2_NV_WriteLock Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode Page 426 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 33.11.3 1 2 3 Part 3: Commands Detailed Actions #include "InternalRoutines.h" #include "NV_WriteLock_fp.h" #include "NV_spt_fp.h" Error Returns TPM_RC_ATTRIBUTES neither TPMA_NV_WRITEDEFINE nor TPMA_NV_WRITE_STCLEAR is SET in Index referenced by nvIndex TPM_RC_NV_AUTHORIZATION 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 Meaning the authorization was valid but the authorizing entity (authHandle) is not allowed to write to the Index referenced by nvIndex TPM_RC TPM2_NV_WriteLock( NV_WriteLock_In *in // IN: input parameter list ) { TPM_RC NV_INDEX result; nvIndex; // The command needs NV update. Check if NV is available. // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at // this point result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; // Input Validation: // Common write access checks, a TPM_RC_NV_AUTHORIZATION or TPM_RC_NV_LOCKED // error may be returned at this point result = NvWriteAccessChecks(in->authHandle, in->nvIndex); if(result != TPM_RC_SUCCESS) { if(result == TPM_RC_NV_AUTHORIZATION) return TPM_RC_NV_AUTHORIZATION; // If write access failed because the index is already locked, then it is // no error. return TPM_RC_SUCCESS; } // Get NV index info NvGetIndexInfo(in->nvIndex, &nvIndex); // if non of TPMA_NV_WRITEDEFINE or TPMA_NV_WRITE_STCLEAR is set, the index // can not be write-locked if( nvIndex.publicArea.attributes.TPMA_NV_WRITEDEFINE == CLEAR && nvIndex.publicArea.attributes.TPMA_NV_WRITE_STCLEAR == CLEAR) return TPM_RC_ATTRIBUTES + RC_NV_WriteLock_nvIndex; // Internal Data Update // Set the WRITELOCK attribute nvIndex.publicArea.attributes.TPMA_NV_WRITELOCKED = SET; // Write index info back NvWriteIndexInfo(in->nvIndex, &nvIndex); Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 427 October 31, 2013 Part 3: Commands 51 52 Trusted Platform Module Library return TPM_RC_SUCCESS; } Page 428 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 33.12 TPM2_NV_GlobalWriteLock 33.12.1 General Description The command will SET TPMA_NV_WRITELOCKED TPMA_NV_GLOBALLOCK attribute SET. for all indexes that have their If an Index has both TPMA_NV_WRITELOCKED and TPMA_NV_WRITEDEFINE SET, then this command will permanently lock the NV Index for writing. 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. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 429 October 31, 2013 Part 3: Commands 33.12.2 Trusted Platform Module Library Command and Response Table 215 — TPM2_NV_GlobalWriteLock Command Type Name TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_NV_GlobalWriteLock TPMI_RH_PROVISION @authHandle TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} Auth Index: 1 Auth Role: USER Description Table 216 — TPM2_NV_GlobalWriteLock Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode Page 430 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 33.12.3 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 Part 3: Commands Detailed Actions #include "InternalRoutines.h" #include "NV_GlobalWriteLock_fp.h" TPM_RC TPM2_NV_GlobalWriteLock( NV_GlobalWriteLock_In *in // IN: input parameter list ) { TPM_RC result; // Input parameter is not reference in command action in = NULL; // to silence compiler warnings. // The command needs NV update. Check if NV is available. // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at // this point result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; // Internal Data Update // Implementation dependent method of setting the global lock NvSetGlobalLock(); return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 431 October 31, 2013 Part 3: Commands Trusted Platform Module Library 33.13 TPM2_NV_Read 33.13.1 General Description This command reads a TPM2_NV_DefineSpace(). value from an area in NV memory previously defined by 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. Page 432 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 33.13.2 Part 3: Commands Command and Response Table 217 — TPM2_NV_Read Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_NV_Read TPMI_RH_NV_AUTH @authHandle the handle indicating the source of the authorization value Auth Index: 1 Auth Role: USER TPMI_RH_NV_INDEX nvIndex the NV Index to be read Auth Index: None UINT16 size number of octets to read UINT16 offset octet offset into the area 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 8 UINT32 responseSize TPM_RC responseCode TPM2B_MAX_NV_BUFFER data Family “2.0” Level 00 Revision 00.99 the data read Published Copyright © TCG 2006-2013 Page 433 October 31, 2013 Part 3: Commands 33.13.3 1 2 3 Trusted Platform Module Library Detailed Actions #include "InternalRoutines.h" #include "NV_Read_fp.h" #include "NV_spt_fp.h" Error Returns 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 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 Meaning the Index referenced by nvIndex has not been initialized (written) TPM_RC TPM2_NV_Read( NV_Read_In NV_Read_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { NV_INDEX TPM_RC nvIndex; result; // Input Validation // Get NV index info NvGetIndexInfo(in->nvIndex, &nvIndex); // Common read access checks. NvReadAccessChecks() returns // TPM_RC_NV_AUTHORIZATION, TPM_RC_NV_LOCKED, or TPM_RC_NV_UNINITIALIZED // error may be returned at this point result = NvReadAccessChecks(in->authHandle, in->nvIndex); if(result != TPM_RC_SUCCESS) return result; // Too much data if((in->size + in->offset) > nvIndex.publicArea.dataSize) return TPM_RC_NV_RANGE; // Command Output // Set the return size out->data.t.size = in->size; // Perform the read NvGetIndexData(in->nvIndex, &nvIndex, in->offset, in->size, out->data.t.buffer); return TPM_RC_SUCCESS; } Page 434 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 33.14 TPM2_NV_ReadLock 33.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_NV_ATTRIBUTE. 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. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 435 October 31, 2013 Part 3: Commands 33.14.2 Trusted Platform Module Library Command and Response Table 219 — TPM2_NV_ReadLock Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_NV_ReadLock TPMI_RH_NV_AUTH @authHandle the handle indicating the source of the authorization value Auth Index: 1 Auth Role: USER TPMI_RH_NV_INDEX nvIndex the NV Index to be locked Auth Index: None Table 220 — TPM2_NV_ReadLock Response Type Name Description TPM_ST tag see clause 8 UINT32 responseSize TPM_RC responseCode Page 436 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 33.14.3 1 2 3 Part 3: Commands Detailed Actions #include "InternalRoutines.h" #include "NV_ReadLock_fp.h" #include "NV_spt_fp.h" Error Returns TPM_RC_ATTRIBUTES TPMA_NV_READ_STCLEAR is not SET so Index referenced by nvIndex may not be write locked TPM_RC_NV_AUTHORIZATION 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 Meaning the authorization was valid but the authorizing entity (authHandle) is not allowed to read from the Index referenced by nvIndex TPM_RC TPM2_NV_ReadLock( NV_ReadLock_In *in // IN: input parameter list ) { TPM_RC NV_INDEX result; nvIndex; // The command needs NV update. Check if NV is available. // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at // this point result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; // Input Validation // Common read access checks. NvReadAccessChecks() returns // TPM_RC_NV_AUTHORIZATION, TPM_RC_NV_LOCKED, or TPM_RC_NV_UNINITIALIZED // error may be returned at this point result = NvReadAccessChecks(in->authHandle, in->nvIndex); if(result != TPM_RC_SUCCESS) { if(result == TPM_RC_NV_AUTHORIZATION) return TPM_RC_NV_AUTHORIZATION; // Index is already locked for write else if(result == TPM_RC_NV_LOCKED) return TPM_RC_SUCCESS; // If NvReadAccessChecks return TPM_RC_NV_UNINITALIZED, then continue. // It is not an error to read lock an uninitialized Index. } // Get NV index info NvGetIndexInfo(in->nvIndex, &nvIndex); // if TPMA_NV_READ_STCLEAR is not set, the index can not be read-locked if(nvIndex.publicArea.attributes.TPMA_NV_READ_STCLEAR == CLEAR) return TPM_RC_ATTRIBUTES + RC_NV_ReadLock_nvIndex; // Internal Data Update // Set the READLOCK attribute nvIndex.publicArea.attributes.TPMA_NV_READLOCKED = SET; // Write NV info back NvWriteIndexInfo(in->nvIndex, &nvIndex); return TPM_RC_SUCCESS; } Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 437 October 31, 2013 Part 3: Commands Trusted Platform Module Library 33.15 TPM2_NV_ChangeAuth 33.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 admin istrative 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 Part 4 ComputeResponseHMAC(). Page 438 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 33.15.2 Part 3: Commands Command and Response Table 221 — TPM2_NV_ChangeAuth Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_NV_ChangeAuth {NV} TPMI_RH_NV_INDEX @nvIndex handle of the object 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 8 UINT32 responseSize TPM_RC responseCode Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 439 October 31, 2013 Part 3: Commands 33.15.3 1 2 Trusted Platform Module Library Detailed Actions #include "InternalRoutines.h" #include "NV_ChangeAuth_fp.h" Error Returns TPM_RC_SIZE 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 Meaning newAuth size is larger than the digest size of the Name algorithm for the Index referenced by 'nvIndex TPM_RC TPM2_NV_ChangeAuth( NV_ChangeAuth_In *in // IN: input parameter list ) { TPM_RC NV_INDEX result; nvIndex; // Input Validation // Check if NV is available. NvIsAvailable may return TPM_RC_NV_UNAVAILABLE // TPM_RC_NV_RATE or TPM_RC_SUCCESS. result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; // Read index info from NV NvGetIndexInfo(in->nvIndex, &nvIndex); // Remove any trailing zeros that might have been added by the caller // to obfuscate the size. MemoryRemoveTrailingZeros(&(in->newAuth)); // Make sure that the authValue is no larger than the nameAlg of the Index if(in->newAuth.t.size > CryptGetHashDigestSize(nvIndex.publicArea.nameAlg)) return TPM_RC_SIZE + RC_NV_ChangeAuth_newAuth; // Internal Data Update // Change auth nvIndex.authValue = in->newAuth; // Write index info back to NV NvWriteIndexInfo(in->nvIndex, &nvIndex); return TPM_RC_SUCCESS; } Page 440 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library Part 3: Commands 33.16 TPM2_NV_Certify 33.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 See 20.1 for description of how the signing scheme is selected. Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 441 October 31, 2013 Part 3: Commands 33.16.2 Trusted Platform Module Library Command and Response Table 223 — TPM2_NV_Certify Command Type Name Description TPMI_ST_COMMAND_TAG tag UINT32 commandSize TPM_CC commandCode TPM_CC_NV_Certify TPMI_DH_OBJECT+ @signHandle handle of the key used to sign the attestation structure Auth Index: 1 Auth Role: USER TPMI_RH_NV_AUTH @authHandle handle indicating the source of the authorization value for the NV Index Auth Index: 2 Auth Role: USER TPMI_RH_NV_INDEX nvIndex Index for the area to be certified Auth Index: None TPM2B_DATA qualifyingData user-provided qualifying data TPMT_SIG_SCHEME+ inScheme signing scheme to use if the scheme for signHandle is TPM_ALG_NULL UINT16 size number of octets to certify UINT16 offset octet offset into the area 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 8 UINT32 responseSize TPM_RC responseCode . TPM2B_ATTEST certifyInfo the structure that was signed TPMT_SIGNATURE signature the asymmetric signature over certifyInfo using the key referenced by signHandle Page 442 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99 Trusted Platform Module Library 33.16.3 1 2 3 4 Detailed Actions #include #include #include #include Part 3: Commands "InternalRoutines.h" "Attest_spt_fp.h" "NV_spt_fp.h" "NV_Certify_fp.h" Error Returns 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 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 Meaning inScheme is not an allowed value for the key definition TPM_RC TPM2_NV_Certify( NV_Certify_In NV_Certify_Out *in, *out // IN: input parameter list // OUT: output parameter list ) { TPM_RC NV_INDEX TPMS_ATTEST result; nvIndex; certifyInfo; // Attestation command may cause the orderlyState to be cleared due to // the reporting of clock info. If this is the case, check if NV is // available first if(gp.orderlyState != SHUTDOWN_NONE) { // The command needs NV update. Check if NV is available. // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at // this point result = NvIsAvailable(); if(result != TPM_RC_SUCCESS) return result; } // Input Validation // Get NV index info NvGetIndexInfo(in->nvIndex, &nvIndex); // Common access checks. A TPM_RC_NV_AUTHORIZATION or TPM_RC_NV_LOCKED // error may be returned at this point result = NvReadAccessChecks(in->authHandle, in->nvIndex); if(result != TPM_RC_SUCCESS) return result; // See if the range to be certified is out of the bounds of the defined // Index if((in->size + in->offset) > nvIndex.publicArea.dataSize) return TPM_RC_NV_RANGE; // Command Output Family “2.0” Level 00 Revision 00.99 Published Copyright © TCG 2006-2013 Page 443 October 31, 2013 Part 3: Commands 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 Trusted Platform Module Library // Filling in attest information // Common fields // FillInAttestInfo can return TPM_RC_SCHEME or TPM_RC_KEY result = FillInAttestInfo(in->signHandle, &in->inScheme, &in->qualifyingData, &certifyInfo); if(result != TPM_RC_SUCCESS) { if(result == TPM_RC_KEY) return TPM_RC_KEY + RC_NV_Certify_signHandle; else return RcSafeAddToResult(result, RC_NV_Certify_inScheme); } // NV certify specific fields // Attestation type certifyInfo.type = TPM_ST_ATTEST_NV; // Get the name of the index certifyInfo.attested.nv.indexName.t.size = NvGetName(in->nvIndex, &certifyInfo.attested.nv.indexName.t.name); // Set the return size certifyInfo.attested.nv.nvContents.t.size = in->size; // Set the offset certifyInfo.attested.nv.offset = in->offset; // Perform the read NvGetIndexData(in->nvIndex, &nvIndex, in->offset, in->size, certifyInfo.attested.nv.nvContents.t.buffer); // Sign attestation structure. A NULL signature will be returned if // signHandle is TPM_RH_NULL. SignAttestInfo() may return TPM_RC_VALUE, // TPM_RC_SCHEME or TPM_RC_ATTRUBUTES. // Note: SignAttestInfo may return TPM_RC_ATTRIBUTES if the key is not a // signing key but that was checked above. TPM_RC_VALUE would mean that the // data to sign is too large but the data to sign is a digest result = SignAttestInfo(in->signHandle, &in->inScheme, &certifyInfo, &in->qualifyingData, &out->certifyInfo, &out->signature); if(result != TPM_RC_SUCCESS) return result; // orderly state should be cleared because of the reporting of clock info // if signing happens if(in->signHandle != TPM_RH_NULL) g_clearOrderly = TRUE; return TPM_RC_SUCCESS; } Page 444 October 31, 2013 Published Copyright © TCG 2006-2013 Family “2.0” Level 00 Revision 00.99