Vadim Bendebury | 5679752 | 2015-05-20 10:32:25 -0700 | [diff] [blame] | 1 | Trusted Platform Module Library |
| 2 | Part 3: Commands |
| 3 | |
| 4 | Family “2.0” |
| 5 | |
| 6 | Level 00 Revision 01.16 |
| 7 | |
| 8 | October 30, 2014 |
| 9 | |
| 10 | |
| 11 | |
| 12 | |
| 13 | Contact: admin@trustedcomputinggroup.org |
| 14 | |
| 15 | |
| 16 | |
| 17 | |
| 18 | TCG Published |
| 19 | Copyright © TCG 2006-2014 |
| 20 | |
| 21 | |
| 22 | |
| 23 | |
| 24 | TCG |
| 25 | Part 3: Commands Trusted Platform Module Library |
| 26 | |
| 27 | |
| 28 | Licenses and Notices |
| 29 | |
| 30 | 1. Copyright Licenses: |
| 31 | Trusted Computing Group (TCG) grants to the user of the source code in this specification (the |
| 32 | “Source Code”) a worldwide, irrevocable, nonexclusive, royalty free, copyright license to |
| 33 | reproduce, create derivative works, distribute, display and perform the Source Code and |
| 34 | derivative works thereof, and to grant others the rights granted herein. |
| 35 | The TCG grants to the user of the other parts of the specification (other than the Source Code) |
| 36 | the rights to reproduce, distribute, display, and perform the specification solely for the purpose of |
| 37 | developing products based on such documents. |
| 38 | 2. Source Code Distribution Conditions: |
| 39 | Redistributions of Source Code must retain the above copyright licenses, this list of conditions |
| 40 | and the following disclaimers. |
| 41 | Redistributions in binary form must reproduce the above copyright licenses, this list of conditions |
| 42 | and the following disclaimers in the documentation and/or other materials provided with the |
| 43 | distribution. |
| 44 | 3. Disclaimers: |
| 45 | THE COPYRIGHT LICENSES SET FORTH ABOVE DO NOT REPRESENT ANY FORM OF |
| 46 | LICENSE OR WAIVER, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, WITH |
| 47 | RESPECT TO PATENT RIGHTS HELD BY TCG MEMBERS (OR OTHER THIRD PARTIES) |
| 48 | THAT MAY BE NECESSARY TO IMPLEMENT THIS SPECIFICATION OR OTHERWISE. |
| 49 | Contact TCG Administration (admin@trustedcomputinggroup.org) for information on specification |
| 50 | licensing rights available through TCG membership agreements. |
| 51 | THIS SPECIFICATION IS PROVIDED "AS IS" WITH NO EXPRESS OR IMPLIED WARRANTIES |
| 52 | WHATSOEVER, INCLUDING ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A |
| 53 | PARTICULAR PURPOSE, ACCURACY, COMPLETENESS, OR NONINFRINGEMENT OF |
| 54 | INTELLECTUAL PROPERTY RIGHTS, OR ANY WARRANTY OTHERWISE ARISING OUT OF |
| 55 | ANY PROPOSAL, SPECIFICATION OR SAMPLE. |
| 56 | Without limitation, TCG and its members and licensors disclaim all liability, including liability for |
| 57 | infringement of any proprietary rights, relating to use of information in this specification and to the |
| 58 | implementation of this specification, and TCG disclaims all liability for cost of procurement of |
| 59 | substitute goods or services, lost profits, loss of use, loss of data or any incidental, consequential, |
| 60 | direct, indirect, or special damages, whether under contract, tort, warranty or otherwise, arising in |
| 61 | any way out of use or reliance upon this specification or any information herein. |
| 62 | Any marks and brands contained herein are the property of their respective owner. |
| 63 | |
| 64 | |
| 65 | |
| 66 | |
| 67 | Page ii TCG Published Family “2.0” |
| 68 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 69 | Trusted Platform Module Library Part 3: Commands |
| 70 | |
| 71 | |
| 72 | CONTENTS |
| 73 | |
| 74 | 1 Scope .................................................................................................................................................... 1 |
| 75 | 2 Terms and Definitions ........................................................................................................................... 1 |
| 76 | 3 Symbols and abbreviated terms ............................................................................................................ 1 |
| 77 | 4 Notation ................................................................................................................................................. 1 |
| 78 | 4.1 Introduction ..................................................................................................................................... 1 |
| 79 | 4.2 Table Decorations ........................................................................................................................... 1 |
| 80 | 4.3 Handle and Parameter Demarcation .............................................................................................. 3 |
| 81 | 4.4 AuthorizationSize and ParameterSize ............................................................................................ 3 |
| 82 | 5 Command Processing ........................................................................................................................... 4 |
| 83 | 5.1 Introduction ..................................................................................................................................... 4 |
| 84 | 5.2 Command Header Validation .......................................................................................................... 4 |
| 85 | 5.3 Mode Checks .................................................................................................................................. 4 |
| 86 | 5.4 Handle Area Validation ................................................................................................................... 5 |
| 87 | 5.5 Session Area Validation .................................................................................................................. 6 |
| 88 | 5.6 Authorization Checks ...................................................................................................................... 7 |
| 89 | 5.7 Parameter Decryption ..................................................................................................................... 8 |
| 90 | 5.8 Parameter Unmarshaling ................................................................................................................ 8 |
| 91 | 5.9 Command Post Processing .......................................................................................................... 10 |
| 92 | 6 Response Values ................................................................................................................................ 12 |
| 93 | 6.1 Tag ................................................................................................................................................ 12 |
| 94 | 6.2 Response Codes .......................................................................................................................... 12 |
| 95 | 7 Implementation Dependent ................................................................................................................. 15 |
| 96 | 8 Detailed Actions Assumptions ............................................................................................................. 16 |
| 97 | 8.1 Introduction ................................................................................................................................... 16 |
| 98 | 8.2 Pre-processing .............................................................................................................................. 16 |
| 99 | 8.3 Post Processing ............................................................................................................................ 16 |
| 100 | 9 Start-up ................................................................................................................................................ 17 |
| 101 | 9.1 Introduction ................................................................................................................................... 17 |
| 102 | 9.2 _TPM_Init...................................................................................................................................... 17 |
| 103 | 9.3 TPM2_Startup ............................................................................................................................... 19 |
| 104 | 9.4 TPM2_Shutdown .......................................................................................................................... 26 |
| 105 | 10 Testing ................................................................................................................................................. 30 |
| 106 | 10.1 Introduction ................................................................................................................................... 30 |
| 107 | 10.2 TPM2_SelfTest ............................................................................................................................. 31 |
| 108 | 10.3 TPM2_IncrementalSelfTest .......................................................................................................... 34 |
| 109 | 10.4 TPM2_GetTestResult ................................................................................................................... 37 |
| 110 | 11 Session Commands ............................................................................................................................ 40 |
| 111 | 11.1 TPM2_StartAuthSession .............................................................................................................. 40 |
| 112 | 11.2 TPM2_PolicyRestart ..................................................................................................................... 45 |
| 113 | 12 Object Commands............................................................................................................................... 48 |
| 114 | 12.1 TPM2_Create................................................................................................................................ 48 |
| 115 | 12.2 TPM2_Load .................................................................................................................................. 54 |
| 116 | |
| 117 | Family “2.0” TCG Published Page iii |
| 118 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 119 | Part 3: Commands Trusted Platform Module Library |
| 120 | |
| 121 | |
| 122 | 12.3 TPM2_LoadExternal ..................................................................................................................... 58 |
| 123 | 12.4 TPM2_ReadPublic ........................................................................................................................ 63 |
| 124 | 12.5 TPM2_ActivateCredential ............................................................................................................. 66 |
| 125 | 12.6 TPM2_MakeCredential ................................................................................................................. 70 |
| 126 | 12.7 TPM2_Unseal ............................................................................................................................... 73 |
| 127 | 12.8 TPM2_ObjectChangeAuth ............................................................................................................ 76 |
| 128 | 13 Duplication Commands ....................................................................................................................... 80 |
| 129 | 13.1 TPM2_Duplicate ........................................................................................................................... 80 |
| 130 | 13.2 TPM2_Rewrap .............................................................................................................................. 84 |
| 131 | 13.3 TPM2_Import ................................................................................................................................ 88 |
| 132 | 14 Asymmetric Primitives ......................................................................................................................... 94 |
| 133 | 14.1 Introduction ................................................................................................................................... 94 |
| 134 | 14.2 TPM2_RSA_Encrypt ..................................................................................................................... 94 |
| 135 | 14.3 TPM2_RSA_Decrypt .................................................................................................................... 99 |
| 136 | 14.4 TPM2_ECDH_KeyGen ............................................................................................................... 103 |
| 137 | 14.5 TPM2_ECDH_ZGen ................................................................................................................... 107 |
| 138 | 14.6 TPM2_ECC_Parameters ............................................................................................................ 110 |
| 139 | 14.7 TPM2_ZGen_2Phase ................................................................................................................. 112 |
| 140 | 15 Symmetric Primitives ......................................................................................................................... 116 |
| 141 | 15.1 Introduction ................................................................................................................................. 116 |
| 142 | 15.2 TPM2_EncryptDecrypt ................................................................................................................ 118 |
| 143 | 15.3 TPM2_Hash ................................................................................................................................ 122 |
| 144 | 15.4 TPM2_HMAC .............................................................................................................................. 125 |
| 145 | 16 Random Number Generator .............................................................................................................. 129 |
| 146 | 16.1 TPM2_GetRandom ..................................................................................................................... 129 |
| 147 | 16.2 TPM2_StirRandom ..................................................................................................................... 132 |
| 148 | 17 Hash/HMAC/Event Sequences ......................................................................................................... 135 |
| 149 | 17.1 Introduction ................................................................................................................................. 135 |
| 150 | 17.2 TPM2_HMAC_Start .................................................................................................................... 135 |
| 151 | 17.3 TPM2_HashSequenceStart ........................................................................................................ 139 |
| 152 | 17.4 TPM2_SequenceUpdate ............................................................................................................ 142 |
| 153 | 17.5 TPM2_SequenceComplete......................................................................................................... 146 |
| 154 | 17.6 TPM2_EventSequenceComplete ............................................................................................... 150 |
| 155 | 18 Attestation Commands ...................................................................................................................... 154 |
| 156 | 18.1 Introduction ................................................................................................................................. 154 |
| 157 | 18.2 TPM2_Certify .............................................................................................................................. 156 |
| 158 | 18.3 TPM2_CertifyCreation ................................................................................................................ 160 |
| 159 | 18.4 TPM2_Quote............................................................................................................................... 164 |
| 160 | 18.5 TPM2_GetSessionAuditDigest ................................................................................................... 168 |
| 161 | 18.6 TPM2_GetCommandAuditDigest ............................................................................................... 172 |
| 162 | 18.7 TPM2_GetTime........................................................................................................................... 176 |
| 163 | 19 Ephemeral EC Keys .......................................................................................................................... 180 |
| 164 | 19.1 Introduction ................................................................................................................................. 180 |
| 165 | 19.2 TPM2_Commit ............................................................................................................................ 181 |
| 166 | |
| 167 | |
| 168 | Page iv TCG Published Family “2.0” |
| 169 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 170 | Trusted Platform Module Library Part 3: Commands |
| 171 | |
| 172 | |
| 173 | 19.3 TPM2_EC_Ephemeral ................................................................................................................ 186 |
| 174 | 20 Signing and Signature Verification .................................................................................................... 189 |
| 175 | 20.1 TPM2_VerifySignature ................................................................................................................ 189 |
| 176 | 20.2 TPM2_Sign ................................................................................................................................. 193 |
| 177 | 21 Command Audit ................................................................................................................................. 197 |
| 178 | 21.1 Introduction ................................................................................................................................. 197 |
| 179 | 21.2 TPM2_SetCommandCodeAuditStatus ....................................................................................... 198 |
| 180 | 22 Integrity Collection (PCR) .................................................................................................................. 202 |
| 181 | 22.1 Introduction ................................................................................................................................. 202 |
| 182 | 22.2 TPM2_PCR_Extend ................................................................................................................... 203 |
| 183 | 22.3 TPM2_PCR_Event ..................................................................................................................... 206 |
| 184 | 22.4 TPM2_PCR_Read ...................................................................................................................... 209 |
| 185 | 22.5 TPM2_PCR_Allocate .................................................................................................................. 212 |
| 186 | 22.6 TPM2_PCR_SetAuthPolicy ........................................................................................................ 215 |
| 187 | 22.7 TPM2_PCR_SetAuthValue ......................................................................................................... 218 |
| 188 | 22.8 TPM2_PCR_Reset ..................................................................................................................... 221 |
| 189 | 22.9 _TPM_Hash_Start ...................................................................................................................... 224 |
| 190 | 22.10 _TPM_Hash_Data ...................................................................................................................... 226 |
| 191 | 22.11 _TPM_Hash_End ....................................................................................................................... 228 |
| 192 | 23 Enhanced Authorization (EA) Commands ........................................................................................ 231 |
| 193 | 23.1 Introduction ................................................................................................................................. 231 |
| 194 | 23.2 Signed Authorization Actions ...................................................................................................... 232 |
| 195 | 23.3 TPM2_PolicySigned ................................................................................................................... 236 |
| 196 | 23.4 TPM2_PolicySecret .................................................................................................................... 242 |
| 197 | 23.5 TPM2_PolicyTicket ..................................................................................................................... 246 |
| 198 | 23.6 TPM2_PolicyOR ......................................................................................................................... 250 |
| 199 | 23.7 TPM2_PolicyPCR ....................................................................................................................... 254 |
| 200 | 23.8 TPM2_PolicyLocality .................................................................................................................. 259 |
| 201 | 23.9 TPM2_PolicyNV .......................................................................................................................... 263 |
| 202 | 23.10 TPM2_PolicyCounterTimer......................................................................................................... 268 |
| 203 | 23.11 TPM2_PolicyCommandCode ..................................................................................................... 273 |
| 204 | 23.12 TPM2_PolicyPhysicalPresence .................................................................................................. 276 |
| 205 | 23.13 TPM2_PolicyCpHash .................................................................................................................. 279 |
| 206 | 23.14 TPM2_PolicyNameHash ............................................................................................................. 283 |
| 207 | 23.15 TPM2_PolicyDuplicationSelect ................................................................................................... 287 |
| 208 | 23.16 TPM2_PolicyAuthorize ............................................................................................................... 291 |
| 209 | 23.17 TPM2_PolicyAuthValue .............................................................................................................. 295 |
| 210 | 23.18 TPM2_PolicyPassword ............................................................................................................... 298 |
| 211 | 23.19 TPM2_PolicyGetDigest ............................................................................................................... 301 |
| 212 | 23.20 TPM2_PolicyNvWritten ............................................................................................................... 304 |
| 213 | 24 Hierarchy Commands........................................................................................................................ 308 |
| 214 | 24.1 TPM2_CreatePrimary ................................................................................................................. 308 |
| 215 | 24.2 TPM2_HierarchyControl ............................................................................................................. 312 |
| 216 | 24.3 TPM2_SetPrimaryPolicy ............................................................................................................. 316 |
| 217 | 24.4 TPM2_ChangePPS .................................................................................................................... 320 |
| 218 | 24.5 TPM2_ChangeEPS .................................................................................................................... 323 |
| 219 | |
| 220 | Family “2.0” TCG Published Page v |
| 221 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 222 | Part 3: Commands Trusted Platform Module Library |
| 223 | |
| 224 | |
| 225 | 24.6 TPM2_Clear ................................................................................................................................ 326 |
| 226 | 24.7 TPM2_ClearControl .................................................................................................................... 330 |
| 227 | 24.8 TPM2_HierarchyChangeAuth ..................................................................................................... 333 |
| 228 | 25 Dictionary Attack Functions ............................................................................................................... 336 |
| 229 | 25.1 Introduction ................................................................................................................................. 336 |
| 230 | 25.2 TPM2_DictionaryAttackLockReset ............................................................................................. 336 |
| 231 | 25.3 TPM2_DictionaryAttackParameters............................................................................................ 339 |
| 232 | 26 Miscellaneous Management Functions ............................................................................................. 342 |
| 233 | 26.1 Introduction ................................................................................................................................. 342 |
| 234 | 26.2 TPM2_PP_Commands ............................................................................................................... 342 |
| 235 | 26.3 TPM2_SetAlgorithmSet .............................................................................................................. 345 |
| 236 | 27 Field Upgrade .................................................................................................................................... 348 |
| 237 | 27.1 Introduction ................................................................................................................................. 348 |
| 238 | 27.2 TPM2_FieldUpgradeStart ........................................................................................................... 350 |
| 239 | 27.3 TPM2_FieldUpgradeData ........................................................................................................... 353 |
| 240 | 27.4 TPM2_FirmwareRead ................................................................................................................. 356 |
| 241 | 28 Context Management ........................................................................................................................ 359 |
| 242 | 28.1 Introduction ................................................................................................................................. 359 |
| 243 | 28.2 TPM2_ContextSave .................................................................................................................... 359 |
| 244 | 28.3 TPM2_ContextLoad .................................................................................................................... 364 |
| 245 | 28.4 TPM2_FlushContext ................................................................................................................... 369 |
| 246 | 28.5 TPM2_EvictControl ..................................................................................................................... 372 |
| 247 | 29 Clocks and Timers............................................................................................................................. 377 |
| 248 | 29.1 TPM2_ReadClock ....................................................................................................................... 377 |
| 249 | 29.2 TPM2_ClockSet .......................................................................................................................... 380 |
| 250 | 29.3 TPM2_ClockRateAdjust .............................................................................................................. 383 |
| 251 | 30 Capability Commands ....................................................................................................................... 386 |
| 252 | 30.1 Introduction ................................................................................................................................. 386 |
| 253 | 30.2 TPM2_GetCapability ................................................................................................................... 386 |
| 254 | 30.3 TPM2_TestParms ....................................................................................................................... 394 |
| 255 | 31 Non-volatile Storage .......................................................................................................................... 397 |
| 256 | 31.1 Introduction ................................................................................................................................. 397 |
| 257 | 31.2 NV Counters ............................................................................................................................... 398 |
| 258 | 31.3 TPM2_NV_DefineSpace ............................................................................................................. 399 |
| 259 | 31.4 TPM2_NV_UndefineSpace ......................................................................................................... 405 |
| 260 | 31.5 TPM2_NV_UndefineSpaceSpecial ............................................................................................. 408 |
| 261 | 31.6 TPM2_NV_ReadPublic ............................................................................................................... 411 |
| 262 | 31.7 TPM2_NV_Write ......................................................................................................................... 414 |
| 263 | 31.8 TPM2_NV_Increment ................................................................................................................. 418 |
| 264 | 31.9 TPM2_NV_Extend ...................................................................................................................... 422 |
| 265 | 31.10 TPM2_NV_SetBits ...................................................................................................................... 426 |
| 266 | 31.11 TPM2_NV_WriteLock ................................................................................................................. 430 |
| 267 | 31.12 TPM2_NV_GlobalWriteLock ....................................................................................................... 434 |
| 268 | 31.13 TPM2_NV_Read ......................................................................................................................... 437 |
| 269 | |
| 270 | |
| 271 | Page vi TCG Published Family “2.0” |
| 272 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 273 | Trusted Platform Module Library Part 3: Commands |
| 274 | |
| 275 | |
| 276 | 31.14 TPM2_NV_ReadLock ................................................................................................................. 440 |
| 277 | 31.15 TPM2_NV_ChangeAuth ............................................................................................................. 444 |
| 278 | 31.16 TPM2_NV_Certify ....................................................................................................................... 447 |
| 279 | |
| 280 | |
| 281 | |
| 282 | |
| 283 | Family “2.0” TCG Published Page vii |
| 284 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 285 | Part 3: Commands Trusted Platform Module Library |
| 286 | |
| 287 | Tables |
| 288 | Table 1 — Command Modifiers and Decoration ........................................................................................... 2 |
| 289 | Table 2 — Separators ................................................................................................................................... 3 |
| 290 | Table 3 — Unmarshaling Errors ................................................................................................................. 10 |
| 291 | Table 4 — Command-Independent Response Codes ................................................................................ 13 |
| 292 | Table 5 — TPM2_Startup Command .......................................................................................................... 22 |
| 293 | Table 6 — TPM2_Startup Response .......................................................................................................... 22 |
| 294 | Table 7 — TPM2_Shutdown Command ..................................................................................................... 27 |
| 295 | Table 8 — TPM2_Shutdown Response ...................................................................................................... 27 |
| 296 | Table 9 — TPM2_SelfTest Command ........................................................................................................ 32 |
| 297 | Table 10 — TPM2_SelfTest Response ...................................................................................................... 32 |
| 298 | Table 11 — TPM2_IncrementalSelfTest Command ................................................................................... 35 |
| 299 | Table 12 — TPM2_IncrementalSelfTest Response ................................................................................... 35 |
| 300 | Table 13 — TPM2_GetTestResult Command ............................................................................................ 38 |
| 301 | Table 14 — TPM2_GetTestResult Response............................................................................................. 38 |
| 302 | Table 15 — TPM2_StartAuthSession Command ....................................................................................... 42 |
| 303 | Table 16 — TPM2_StartAuthSession Response ........................................................................................ 42 |
| 304 | Table 17 — TPM2_PolicyRestart Command .............................................................................................. 46 |
| 305 | Table 18 — TPM2_PolicyRestart Response .............................................................................................. 46 |
| 306 | Table 19 — TPM2_Create Command ........................................................................................................ 51 |
| 307 | Table 20 — TPM2_Create Response ......................................................................................................... 51 |
| 308 | Table 21 — TPM2_Load Command ........................................................................................................... 55 |
| 309 | Table 22 — TPM2_Load Response ............................................................................................................ 55 |
| 310 | Table 23 — TPM2_LoadExternal Command .............................................................................................. 60 |
| 311 | Table 24 — TPM2_LoadExternal Response .............................................................................................. 60 |
| 312 | Table 25 — TPM2_ReadPublic Command ................................................................................................. 64 |
| 313 | Table 26 — TPM2_ReadPublic Response ................................................................................................. 64 |
| 314 | Table 27 — TPM2_ActivateCredential Command ...................................................................................... 67 |
| 315 | Table 28 — TPM2_ActivateCredential Response ...................................................................................... 67 |
| 316 | Table 29 — TPM2_MakeCredential Command .......................................................................................... 71 |
| 317 | Table 30 — TPM2_MakeCredential Response .......................................................................................... 71 |
| 318 | Table 31 — TPM2_Unseal Command ........................................................................................................ 74 |
| 319 | Table 32 — TPM2_Unseal Response ........................................................................................................ 74 |
| 320 | Table 33 — TPM2_ObjectChangeAuth Command ..................................................................................... 77 |
| 321 | Table 34 — TPM2_ObjectChangeAuth Response ..................................................................................... 77 |
| 322 | Table 35 — TPM2_Duplicate Command .................................................................................................... 81 |
| 323 | Table 36 — TPM2_Duplicate Response ..................................................................................................... 81 |
| 324 | Table 37 — TPM2_Rewrap Command ....................................................................................................... 85 |
| 325 | Table 38 — TPM2_Rewrap Response ....................................................................................................... 85 |
| 326 | |
| 327 | Page viii TCG Published Family “2.0” |
| 328 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 329 | Trusted Platform Module Library Part 3: Commands |
| 330 | |
| 331 | Table 39 — TPM2_Import Command ......................................................................................................... 90 |
| 332 | Table 40 — TPM2_Import Response ......................................................................................................... 90 |
| 333 | Table 41 — Padding Scheme Selection ..................................................................................................... 94 |
| 334 | Table 42 — Message Size Limits Based on Padding ................................................................................. 95 |
| 335 | Table 43 — TPM2_RSA_Encrypt Command.............................................................................................. 96 |
| 336 | Table 44 — TPM2_RSA_Encrypt Response .............................................................................................. 96 |
| 337 | Table 45 — TPM2_RSA_Decrypt Command ........................................................................................... 100 |
| 338 | Table 46 — TPM2_RSA_Decrypt Response ............................................................................................ 100 |
| 339 | Table 47 — TPM2_ECDH_KeyGen Command ........................................................................................ 104 |
| 340 | Table 48 — TPM2_ECDH_KeyGen Response ........................................................................................ 104 |
| 341 | Table 49 — TPM2_ECDH_ZGen Command ............................................................................................ 108 |
| 342 | Table 50 — TPM2_ECDH_ZGen Response ............................................................................................ 108 |
| 343 | Table 51 — TPM2_ECC_Parameters Command ..................................................................................... 110 |
| 344 | Table 52 — TPM2_ECC_Parameters Response ..................................................................................... 110 |
| 345 | Table 53 — TPM2_ZGen_2Phase Command .......................................................................................... 113 |
| 346 | Table 54 — TPM2_ZGen_2Phase Response .......................................................................................... 113 |
| 347 | Table 55 — Symmetric Chaining Process ................................................................................................ 117 |
| 348 | Table 56 — TPM2_EncryptDecrypt Command......................................................................................... 119 |
| 349 | Table 57 — TPM2_EncryptDecrypt Response ......................................................................................... 119 |
| 350 | Table 58 — TPM2_Hash Command ......................................................................................................... 123 |
| 351 | Table 59 — TPM2_Hash Response ......................................................................................................... 123 |
| 352 | Table 60 — TPM2_HMAC Command ....................................................................................................... 126 |
| 353 | Table 61 — TPM2_HMAC Response ....................................................................................................... 126 |
| 354 | Table 62 — TPM2_GetRandom Command .............................................................................................. 130 |
| 355 | Table 63 — TPM2_GetRandom Response .............................................................................................. 130 |
| 356 | Table 64 — TPM2_StirRandom Command .............................................................................................. 133 |
| 357 | Table 65 — TPM2_StirRandom Response ............................................................................................... 133 |
| 358 | Table 66 — Hash Selection Matrix ........................................................................................................... 135 |
| 359 | Table 67 — TPM2_HMAC_Start Command ............................................................................................. 136 |
| 360 | Table 68 — TPM2_HMAC_Start Response ............................................................................................. 136 |
| 361 | Table 69 — TPM2_HashSequenceStart Command ................................................................................. 140 |
| 362 | Table 70 — TPM2_HashSequenceStart Response ................................................................................. 140 |
| 363 | Table 71 — TPM2_SequenceUpdate Command ..................................................................................... 143 |
| 364 | Table 72 — TPM2_SequenceUpdate Response ...................................................................................... 143 |
| 365 | Table 73 — TPM2_SequenceComplete Command ................................................................................. 147 |
| 366 | Table 74 — TPM2_SequenceComplete Response .................................................................................. 147 |
| 367 | Table 75 — TPM2_EventSequenceComplete Command ........................................................................ 151 |
| 368 | Table 76 — TPM2_EventSequenceComplete Response ......................................................................... 151 |
| 369 | Table 77 — TPM2_Certify Command ....................................................................................................... 157 |
| 370 | Family “2.0” TCG Published Page ix |
| 371 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 372 | Part 3: Commands Trusted Platform Module Library |
| 373 | |
| 374 | Table 78 — TPM2_Certify Response ....................................................................................................... 157 |
| 375 | Table 79 — TPM2_CertifyCreation Command ......................................................................................... 161 |
| 376 | Table 80 — TPM2_CertifyCreation Response .......................................................................................... 161 |
| 377 | Table 81 — TPM2_Quote Command ....................................................................................................... 165 |
| 378 | Table 82 — TPM2_Quote Response ........................................................................................................ 165 |
| 379 | Table 83 — TPM2_GetSessionAuditDigest Command ............................................................................ 169 |
| 380 | Table 84 — TPM2_GetSessionAuditDigest Response ............................................................................ 169 |
| 381 | Table 85 — TPM2_GetCommandAuditDigest Command ........................................................................ 173 |
| 382 | Table 86 — TPM2_GetCommandAuditDigest Response ......................................................................... 173 |
| 383 | Table 87 — TPM2_GetTime Command ................................................................................................... 177 |
| 384 | Table 88 — TPM2_GetTime Response .................................................................................................... 177 |
| 385 | Table 89 — TPM2_Commit Command ..................................................................................................... 182 |
| 386 | Table 90 — TPM2_Commit Response ..................................................................................................... 182 |
| 387 | Table 91 — TPM2_EC_Ephemeral Command ......................................................................................... 187 |
| 388 | Table 92 — TPM2_EC_Ephemeral Response ......................................................................................... 187 |
| 389 | Table 93 — TPM2_VerifySignature Command......................................................................................... 190 |
| 390 | Table 94 — TPM2_VerifySignature Response ......................................................................................... 190 |
| 391 | Table 95 — TPM2_Sign Command .......................................................................................................... 194 |
| 392 | Table 96 — TPM2_Sign Response .......................................................................................................... 194 |
| 393 | Table 97 — TPM2_SetCommandCodeAuditStatus Command ................................................................ 199 |
| 394 | Table 98 — TPM2_SetCommandCodeAuditStatus Response ................................................................ 199 |
| 395 | Table 99 — TPM2_PCR_Extend Command ............................................................................................ 204 |
| 396 | Table 100 — TPM2_PCR_Extend Response ........................................................................................... 204 |
| 397 | Table 101 — TPM2_PCR_Event Command ............................................................................................ 207 |
| 398 | Table 102 — TPM2_PCR_Event Response ............................................................................................. 207 |
| 399 | Table 103 — TPM2_PCR_Read Command ............................................................................................. 210 |
| 400 | Table 104 — TPM2_PCR_Read Response ............................................................................................. 210 |
| 401 | Table 105 — TPM2_PCR_Allocate Command ......................................................................................... 213 |
| 402 | Table 106 — TPM2_PCR_Allocate Response ......................................................................................... 213 |
| 403 | Table 107 — TPM2_PCR_SetAuthPolicy Command ............................................................................... 216 |
| 404 | Table 108 — TPM2_PCR_SetAuthPolicy Response ............................................................................... 216 |
| 405 | Table 109 — TPM2_PCR_SetAuthValue Command ............................................................................... 219 |
| 406 | Table 110 — TPM2_PCR_SetAuthValue Response ................................................................................ 219 |
| 407 | Table 111 — TPM2_PCR_Reset Command ............................................................................................ 222 |
| 408 | Table 112 — TPM2_PCR_Reset Response ............................................................................................. 222 |
| 409 | Table 113 — TPM2_PolicySigned Command .......................................................................................... 238 |
| 410 | Table 114 — TPM2_PolicySigned Response ........................................................................................... 238 |
| 411 | Table 115 — TPM2_PolicySecret Command ........................................................................................... 243 |
| 412 | Table 116 — TPM2_PolicySecret Response ............................................................................................ 243 |
| 413 | Page x TCG Published Family “2.0” |
| 414 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 415 | Trusted Platform Module Library Part 3: Commands |
| 416 | |
| 417 | Table 117 — TPM2_PolicyTicket Command ............................................................................................ 247 |
| 418 | Table 118 — TPM2_PolicyTicket Response ............................................................................................ 247 |
| 419 | Table 119 — TPM2_PolicyOR Command ................................................................................................ 251 |
| 420 | Table 120 — TPM2_PolicyOR Response ................................................................................................. 251 |
| 421 | Table 121 — TPM2_PolicyPCR Command .............................................................................................. 256 |
| 422 | Table 122 — TPM2_PolicyPCR Response .............................................................................................. 256 |
| 423 | Table 123 — TPM2_PolicyLocality Command ......................................................................................... 260 |
| 424 | Table 124 — TPM2_PolicyLocality Response .......................................................................................... 260 |
| 425 | Table 125 — TPM2_PolicyNV Command ................................................................................................. 264 |
| 426 | Table 126 — TPM2_PolicyNV Response ................................................................................................. 264 |
| 427 | Table 127 — TPM2_PolicyCounterTimer Command ............................................................................... 269 |
| 428 | Table 128 — TPM2_PolicyCounterTimer Response ................................................................................ 269 |
| 429 | Table 129 — TPM2_PolicyCommandCode Command ............................................................................ 274 |
| 430 | Table 130 — TPM2_PolicyCommandCode Response ............................................................................. 274 |
| 431 | Table 131 — TPM2_PolicyPhysicalPresence Command ......................................................................... 277 |
| 432 | Table 132 — TPM2_PolicyPhysicalPresence Response ......................................................................... 277 |
| 433 | Table 133 — TPM2_PolicyCpHash Command......................................................................................... 280 |
| 434 | Table 134 — TPM2_PolicyCpHash Response ......................................................................................... 280 |
| 435 | Table 135 — TPM2_PolicyNameHash Command.................................................................................... 284 |
| 436 | Table 136 — TPM2_PolicyNameHash Response .................................................................................... 284 |
| 437 | Table 137 — TPM2_PolicyDuplicationSelect Command .......................................................................... 288 |
| 438 | Table 138 — TPM2_PolicyDuplicationSelect Response .......................................................................... 288 |
| 439 | Table 139 — TPM2_PolicyAuthorize Command ...................................................................................... 292 |
| 440 | Table 140 — TPM2_PolicyAuthorize Response ....................................................................................... 292 |
| 441 | Table 141 — TPM2_PolicyAuthValue Command ..................................................................................... 296 |
| 442 | Table 142 — TPM2_PolicyAuthValue Response ..................................................................................... 296 |
| 443 | Table 143 — TPM2_PolicyPassword Command ...................................................................................... 299 |
| 444 | Table 144 — TPM2_PolicyPassword Response ...................................................................................... 299 |
| 445 | Table 145 — TPM2_PolicyGetDigest Command...................................................................................... 302 |
| 446 | Table 146 — TPM2_PolicyGetDigest Response ...................................................................................... 302 |
| 447 | Table 147 — TPM2_PolicyNvWritten Command ...................................................................................... 305 |
| 448 | Table 148 — TPM2_PolicyNvWritten Response ...................................................................................... 305 |
| 449 | Table 149 — TPM2_CreatePrimary Command ........................................................................................ 309 |
| 450 | Table 150 — TPM2_CreatePrimary Response ........................................................................................ 309 |
| 451 | Table 151 — TPM2_HierarchyControl Command .................................................................................... 313 |
| 452 | Table 152 — TPM2_HierarchyControl Response .................................................................................... 313 |
| 453 | Table 153 — TPM2_SetPrimaryPolicy Command .................................................................................... 317 |
| 454 | Table 154 — TPM2_SetPrimaryPolicy Response .................................................................................... 317 |
| 455 | Table 155 — TPM2_ChangePPS Command ........................................................................................... 321 |
| 456 | Family “2.0” TCG Published Page xi |
| 457 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 458 | Part 3: Commands Trusted Platform Module Library |
| 459 | |
| 460 | Table 156 — TPM2_ChangePPS Response ............................................................................................ 321 |
| 461 | Table 157 — TPM2_ChangeEPS Command ........................................................................................... 324 |
| 462 | Table 158 — TPM2_ChangeEPS Response ............................................................................................ 324 |
| 463 | Table 159 — TPM2_Clear Command ....................................................................................................... 327 |
| 464 | Table 160 — TPM2_Clear Response ....................................................................................................... 327 |
| 465 | Table 161 — TPM2_ClearControl Command ........................................................................................... 331 |
| 466 | Table 162 — TPM2_ClearControl Response ........................................................................................... 331 |
| 467 | Table 163 — TPM2_HierarchyChangeAuth Command ............................................................................ 334 |
| 468 | Table 164 — TPM2_HierarchyChangeAuth Response ............................................................................ 334 |
| 469 | Table 165 — TPM2_DictionaryAttackLockReset Command .................................................................... 337 |
| 470 | Table 166 — TPM2_DictionaryAttackLockReset Response .................................................................... 337 |
| 471 | Table 167 — TPM2_DictionaryAttackParameters Command .................................................................. 340 |
| 472 | Table 168 — TPM2_DictionaryAttackParameters Response ................................................................... 340 |
| 473 | Table 169 — TPM2_PP_Commands Command ...................................................................................... 343 |
| 474 | Table 170 — TPM2_PP_Commands Response ...................................................................................... 343 |
| 475 | Table 171 — TPM2_SetAlgorithmSet Command ..................................................................................... 346 |
| 476 | Table 172 — TPM2_SetAlgorithmSet Response...................................................................................... 346 |
| 477 | Table 173 — TPM2_FieldUpgradeStart Command .................................................................................. 351 |
| 478 | Table 174 — TPM2_FieldUpgradeStart Response .................................................................................. 351 |
| 479 | Table 175 — TPM2_FieldUpgradeData Command .................................................................................. 354 |
| 480 | Table 176 — TPM2_FieldUpgradeData Response .................................................................................. 354 |
| 481 | Table 177 — TPM2_FirmwareRead Command........................................................................................ 357 |
| 482 | Table 178 — TPM2_FirmwareRead Response ........................................................................................ 357 |
| 483 | Table 179 — TPM2_ContextSave Command........................................................................................... 360 |
| 484 | Table 180 — TPM2_ContextSave Response ........................................................................................... 360 |
| 485 | Table 181 — TPM2_ContextLoad Command ........................................................................................... 365 |
| 486 | Table 182 — TPM2_ContextLoad Response ........................................................................................... 365 |
| 487 | Table 183 — TPM2_FlushContext Command .......................................................................................... 370 |
| 488 | Table 184 — TPM2_FlushContext Response .......................................................................................... 370 |
| 489 | Table 185 — TPM2_EvictControl Command ............................................................................................ 374 |
| 490 | Table 186 — TPM2_EvictControl Response ............................................................................................ 374 |
| 491 | Table 187 — TPM2_ReadClock Command.............................................................................................. 378 |
| 492 | Table 188 — TPM2_ReadClock Response .............................................................................................. 378 |
| 493 | Table 189 — TPM2_ClockSet Command ................................................................................................. 381 |
| 494 | Table 190 — TPM2_ClockSet Response ................................................................................................. 381 |
| 495 | Table 191 — TPM2_ClockRateAdjust Command..................................................................................... 384 |
| 496 | Table 192 — TPM2_ClockRateAdjust Response ..................................................................................... 384 |
| 497 | Table 193 — TPM2_GetCapability Command.......................................................................................... 390 |
| 498 | Table 194 — TPM2_GetCapability Response .......................................................................................... 390 |
| 499 | Page xii TCG Published Family “2.0” |
| 500 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 501 | Trusted Platform Module Library Part 3: Commands |
| 502 | |
| 503 | Table 195 — TPM2_TestParms Command .............................................................................................. 395 |
| 504 | Table 196 — TPM2_TestParms Response .............................................................................................. 395 |
| 505 | Table 197 — TPM2_NV_DefineSpace Command ................................................................................... 401 |
| 506 | Table 198 — TPM2_NV_DefineSpace Response .................................................................................... 401 |
| 507 | Table 199 — TPM2_NV_UndefineSpace Command ............................................................................... 406 |
| 508 | Table 200 — TPM2_NV_UndefineSpace Response ................................................................................ 406 |
| 509 | Table 201 — TPM2_NV_UndefineSpaceSpecial Command .................................................................... 409 |
| 510 | Table 202 — TPM2_NV_UndefineSpaceSpecial Response .................................................................... 409 |
| 511 | Table 203 — TPM2_NV_ReadPublic Command ...................................................................................... 412 |
| 512 | Table 204 — TPM2_NV_ReadPublic Response ...................................................................................... 412 |
| 513 | Table 205 — TPM2_NV_Write Command ................................................................................................ 415 |
| 514 | Table 206 — TPM2_NV_Write Response ................................................................................................ 415 |
| 515 | Table 207 — TPM2_NV_Increment Command ........................................................................................ 419 |
| 516 | Table 208 — TPM2_NV_Increment Response......................................................................................... 419 |
| 517 | Table 209 — TPM2_NV_Extend Command ............................................................................................. 423 |
| 518 | Table 210 — TPM2_NV_Extend Response ............................................................................................. 423 |
| 519 | Table 211 — TPM2_NV_SetBits Command ............................................................................................. 427 |
| 520 | Table 212 — TPM2_NV_SetBits Response ............................................................................................. 427 |
| 521 | Table 213 — TPM2_NV_WriteLock Command ........................................................................................ 431 |
| 522 | Table 214 — TPM2_NV_WriteLock Response......................................................................................... 431 |
| 523 | Table 215 — TPM2_NV_GlobalWriteLock Command .............................................................................. 435 |
| 524 | Table 216 — TPM2_NV_GlobalWriteLock Response .............................................................................. 435 |
| 525 | Table 217 — TPM2_NV_Read Command................................................................................................ 438 |
| 526 | Table 218 — TPM2_NV_Read Response ................................................................................................ 438 |
| 527 | Table 219 — TPM2_NV_ReadLock Command ........................................................................................ 441 |
| 528 | Table 220 — TPM2_NV_ReadLock Response ........................................................................................ 441 |
| 529 | Table 221 — TPM2_NV_ChangeAuth Command .................................................................................... 445 |
| 530 | Table 222 — TPM2_NV_ChangeAuth Response .................................................................................... 445 |
| 531 | Table 223 — TPM2_NV_Certify Command .............................................................................................. 448 |
| 532 | Table 224 — TPM2_NV_Certify Response .............................................................................................. 448 |
| 533 | |
| 534 | |
| 535 | |
| 536 | |
| 537 | Family “2.0” TCG Published Page xiii |
| 538 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 539 | Trusted Platform Module Library Part 3: Commands |
| 540 | |
| 541 | |
| 542 | Trusted Platform Module Library |
| 543 | Part 3: Commands |
| 544 | |
| 545 | 1 Scope |
| 546 | |
| 547 | This TPM 2.0 Part 3 of the Trusted Platform Module Library specification contains the definitions of the |
| 548 | TPM commands. These commands make use of the constants, flags, structures, and union definitions |
| 549 | defined in TPM 2.0 Part 2. |
| 550 | The detailed description of the operation of the commands is written in the C language with extensive |
| 551 | comments. The behavior of the C code in this TPM 2.0 Part 3 is normative but does not fully describe the |
| 552 | behavior of a TPM. The combination of this TPM 2.0 Part 3 and TPM 2.0 Part 4 is sufficient to fully |
| 553 | describe the required behavior of a TPM. |
| 554 | The code in parts 3 and 4 is written to define the behavior of a compliant TPM. In some cases (e.g., |
| 555 | firmware update), it is not possible to provide a compliant implementation. In those cases, any |
| 556 | implementation provided by the vendor that meets the general description of the function provided in TPM |
| 557 | 2.0 Part 3 would be compliant. |
| 558 | The code in parts 3 and 4 is not written to meet any particular level of conformance nor does this |
| 559 | specification require that a TPM meet any particular level of conformance. |
| 560 | |
| 561 | |
| 562 | 2 Terms and Definitions |
| 563 | |
| 564 | For the purposes of this document, the terms and definitions given in TPM 2.0 Part 1 apply. |
| 565 | |
| 566 | |
| 567 | 3 Symbols and abbreviated terms |
| 568 | |
| 569 | For the purposes of this document, the symbols and abbreviated terms given in TPM 2.0 Part 1 apply. |
| 570 | |
| 571 | |
| 572 | 4 Notation |
| 573 | |
| 574 | 4.1 Introduction |
| 575 | |
| 576 | For the purposes of this document, the notation given in TPM 2.0 Part 1 applies. |
| 577 | Command and response tables use various decorations to indicate the fields of the command and the |
| 578 | allowed types. These decorations are described in this clause. |
| 579 | |
| 580 | 4.2 Table Decorations |
| 581 | |
| 582 | The symbols and terms in the Notation column of Table 1 are used in the tables for the command |
| 583 | schematics. These values indicate various qualifiers for the parameters or descriptions with which they |
| 584 | are associated. |
| 585 | |
| 586 | |
| 587 | |
| 588 | |
| 589 | Family “2.0” TCG Published Page 1 |
| 590 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 591 | Part 3: Commands Trusted Platform Module Library |
| 592 | |
| 593 | Table 1 — Command Modifiers and Decoration |
| 594 | Notation Meaning |
| 595 | |
| 596 | + A Type decoration – When appended to a value in the Type column of a command, this symbol |
| 597 | indicates that the parameter is allowed to use the “null” value of the data type (see "Conditional |
| 598 | Types" in TPM 2.0 Part 2). The null value is usually TPM_RH_NULL for a handle or |
| 599 | TPM_ALG_NULL for an algorithm selector. |
| 600 | @ A Name decoration – When this symbol precedes a handle parameter in the “Name” column, it |
| 601 | indicates that an authorization session is required for use of the entity associated with the handle. |
| 602 | If a handle does not have this symbol, then an authorization session is not allowed. |
| 603 | +PP A Description modifier – This modifier may follow TPM_RH_PLATFORM in the “Description” |
| 604 | column to indicate that Physical Presence is required when platformAuth/platformPolicy is |
| 605 | provided. |
| 606 | +{PP} A Description modifier – This modifier may follow TPM_RH_PLATFORM to indicate that Physical |
| 607 | Presence may be required when platformAuth/platformPolicy is provided. The commands with this |
| 608 | notation may be in the setList or clearList of TPM2_PP_Commands(). |
| 609 | {NV} A Description modifier – This modifier may follow the commandCode in the “Description” column |
| 610 | to indicate that the command may result in an update of NV memory and be subject to rate |
| 611 | throttling by the TPM. If the command code does not have this notation, then a write to NV |
| 612 | memory does not occur as part of the command actions. |
| 613 | NOTE Any command that uses authorization may cause a write to NV if there is an authorization failure. |
| 614 | A TPM may use the occasion of command execution to update the NV copy of clock. |
| 615 | |
| 616 | {F} A Description modifier – This modifier indicates that the “flushed” attribute will be SET in the |
| 617 | TPMA_CC for the command. The modifier may follow the commandCode in the “Description” |
| 618 | column to indicate that any transient handle context used by the command will be flushed from the |
| 619 | TPM when the command completes. This may be combined with the {NV} modifier but not with the |
| 620 | {E} modifier. |
| 621 | EXAMPLE 1 {NV F} |
| 622 | EXAMPLE 2 TPM2_SequenceComplete() will flush the context associated with the sequenceHandle. |
| 623 | |
| 624 | {E} A Description modifier – This modifier indicates that the “extensive” attribute will be SET in the |
| 625 | TPMA_CC for the command. This modifier may follow the commandCode in the “Description” |
| 626 | column to indicate that the command may flush many objects and re-enumeration of the loaded |
| 627 | context likely will be required. This may be combined with the {NV} modifier but not with the {F} |
| 628 | modifier. |
| 629 | EXAMPLE 1 {NV E} |
| 630 | EXAMPLE 2 TPM2_Clear() will flush all contexts associated with the Storage hierarchy and the |
| 631 | Endorsement hierarchy. |
| 632 | |
| 633 | Auth Index: A Description modifier – When a handle has a “@” decoration, the “Description” column will |
| 634 | contain an “Auth Index:” entry for the handle. This entry indicates the number of the authorization |
| 635 | session. The authorization sessions associated with handles will occur in the session area in the |
| 636 | order of the handles with the “@” modifier. Sessions used only for encryption/decryption or only for |
| 637 | audit will follow the handles used for authorization. |
| 638 | |
| 639 | |
| 640 | |
| 641 | |
| 642 | Page 2 TCG Published Family “2.0” |
| 643 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 644 | Trusted Platform Module Library Part 3: Commands |
| 645 | |
| 646 | |
| 647 | Notation Meaning |
| 648 | |
| 649 | Auth Role: A Description modifier – This will be in the “Description” column of a handle with the “@” |
| 650 | decoration. It may have a value of USER, ADMIN or DUP. |
| 651 | If the handle has the Auth Role of USER and the handle is an Object, the type of authorization is |
| 652 | determined by the setting of userWithAuth in the Object's attributes. If the handle is |
| 653 | TPM_RH_OWNER, TPM_RH_ENDORSEMENT, or TPM_RH_PLATFORM, operation is as if |
| 654 | userWithAuth is SET. If the handle references an NV Index, then the allowed authorizations are |
| 655 | determined by the settings of the attributes of the NV Index as described in TPM 2.0 Part 2, |
| 656 | "TPMA_NV (NV Index Attributes)." |
| 657 | If the Auth Role is ADMIN and the handle is an Object, the type of authorization is determined by |
| 658 | the setting of adminWithPolicy in the Object's attributes. If the handle is TPM_RH_OWNER, |
| 659 | TPM_RH_ENDORSEMENT, or TPM_RH_PLATFORM, operation is as if adminWithPolicy is SET. |
| 660 | If the handle is an NV index, operation is as if adminWithPolicy is SET (see 5.6 e)2)). |
| 661 | If the DUP role is selected, authorization may only be with a policy session (DUP role only applies |
| 662 | to Objects). |
| 663 | When either ADMIN or DUP role is selected, a policy command that selects the command being |
| 664 | authorized is required to be part of the policy. |
| 665 | EXAMPLE TPM2_Certify requires the ADMIN role for the first handle (objectHandle). The policy authorization |
| 666 | for objectHandle is required to contain TPM2_PolicyCommandCode(commandCode == |
| 667 | TPM_CC_Certify). This sets the state of the policy so that it can be used for ADMIN role |
| 668 | authorization in TPM2_Certify(). |
| 669 | |
| 670 | |
| 671 | |
| 672 | |
| 673 | 4.3 Handle and Parameter Demarcation |
| 674 | |
| 675 | The demarcations between the header, handle, and parameter parts are indicated by: |
| 676 | |
| 677 | Table 2 — Separators |
| 678 | Separator Meaning |
| 679 | the values immediately following are in the handle area |
| 680 | |
| 681 | the values immediately following are in the parameter area |
| 682 | |
| 683 | |
| 684 | 4.4 AuthorizationSize and ParameterSize |
| 685 | |
| 686 | Authorization sessions are not shown in the command or response schematics. When the tag of a |
| 687 | command or response is TPM_ST_SESSIONS, then a 32-bit value will be present in the |
| 688 | command/response buffer to indicate the size of the authorization field or the parameter field. This value |
| 689 | shall immediately follow the handle area (which may contain no handles). For a command, this value |
| 690 | (authorizationSize) indicates the size of the Authorization Area and shall have a value of 9 or more. For a |
| 691 | response, this value (parameterSize) indicates the size of the parameter area and may have a value of |
| 692 | zero. |
| 693 | If the authorizationSize field is present in the command, parameterSize will be present in the response, |
| 694 | but only if the responseCode is TPM_RC_SUCCESS. |
| 695 | When authorization is required to use the TPM entity associated with a handle, then at least one session |
| 696 | will be present. To indicate this, the command tag Description field contains TPM_ST_SESSIONS. |
| 697 | Addional sessions for audit, encrypt, and decrypt may be present. |
| 698 | When the command tag Description field contains TPM_ST_NO_SESSIONS, then no sessions are |
| 699 | allowed and the authorizationSize field is not present. |
| 700 | When a command allows use of sessions when not required, the command tag Description field will |
| 701 | indicate the types of sessions that may be used with the command. |
| 702 | |
| 703 | |
| 704 | Family “2.0” TCG Published Page 3 |
| 705 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 706 | Part 3: Commands Trusted Platform Module Library |
| 707 | |
| 708 | |
| 709 | 5 Command Processing |
| 710 | |
| 711 | 5.1 Introduction |
| 712 | |
| 713 | This clause defines the command validations that are required of any implementation and the response |
| 714 | code returned if the indicated check fails. Unless stated otherwise, the order of the checks is not |
| 715 | normative and different TPM may give different responses when a command has multiple errors. |
| 716 | In the description below, some statements that describe a check may be followed by a response code in |
| 717 | parentheses. This is the normative response code should the indicated check fail. A normative response |
| 718 | code may also be included in the statement. |
| 719 | |
| 720 | 5.2 Command Header Validation |
| 721 | |
| 722 | Before a TPM may begin the actions associated with a command, a set of command format and |
| 723 | consistency checks shall be performed. These checks are listed below and should be performed in the |
| 724 | indicated order. |
| 725 | a) The TPM shall successfully unmarshal a TPMI_ST_COMMAND_TAG and verify that it is either |
| 726 | TPM_ST_SESSIONS or TPM_ST_NO_SESSIONS (TPM_RC_BAD_TAG). |
| 727 | b) The TPM shall successfully unmarshal a UINT32 as the commandSize. If the TPM has an interface |
| 728 | buffer that is loaded by some hardware process, the number of octets in the input buffer for the |
| 729 | command reported by the hardware process shall exactly match the value in commandSize |
| 730 | (TPM_RC_COMMAND_SIZE). |
| 731 | |
| 732 | NOTE A TPM may have direct access to system memory and unmarshal direc tly from that memory. |
| 733 | |
| 734 | c) The TPM shall successfully unmarshal a TPM_CC and verify that the command is implemented |
| 735 | (TPM_RC_COMMAND_CODE). |
| 736 | |
| 737 | 5.3 Mode Checks |
| 738 | |
| 739 | The following mode checks shall be performed in the order listed: |
| 740 | a) If the TPM is in Failure mode, then the commandCode is TPM_CC_GetTestResult or |
| 741 | TPM_CC_GetCapability (TPM_RC_FAILURE) and the command tag is TPM_ST_NO_SESSIONS |
| 742 | (TPM_RC_FAILURE). |
| 743 | |
| 744 | NOTE 1 In Failure mode, the TPM has no cryptographic capability and processing of sessions is not |
| 745 | supported. |
| 746 | |
| 747 | b) The TPM is in Field Upgrade mode (FUM), the commandCode is TPM_CC_FieldUpgradeData |
| 748 | (TPM_RC_UPGRADE). |
| 749 | c) If the TPM has not been initialized (TPM2_Startup()), then the commandCode is TPM_CC_Startup |
| 750 | (TPM_RC_INITIALIZE). |
| 751 | |
| 752 | NOTE 2 The TPM may enter Failure mode during _TPM_Init processing, before TPM2_Startup(). Since |
| 753 | the platform firmware cannot know that the TPM is in Failure mode without accessing it, and |
| 754 | since the first command is required to be TPM2_Startup(), the expected sequence will be that |
| 755 | platform firmware (the CRTM) will issue TPM2_Startup() and receive TPM_RC_FAILURE |
| 756 | indicating that the TPM is in Failure mode. |
| 757 | |
| 758 | There may be failures where a TPM cannot record that it received TPM2_Startup(). In those |
| 759 | cases, a TPM in failure mode may process TPM2_GetTestResult(), TPM2_GetCapability(), or |
| 760 | the field upgrade commands. As a side effect, that TPM may process TPM2_GetTestResult(), |
| 761 | TPM2_GetCapability() or the field upgrade commands before TPM2_Startup(). |
| 762 | |
| 763 | This is a corner case exception to the rule that TPM2_Startup() must be the first command. |
| 764 | |
| 765 | Page 4 TCG Published Family “2.0” |
| 766 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 767 | Trusted Platform Module Library Part 3: Commands |
| 768 | |
| 769 | The mode checks may be performed before or after the command header validation. |
| 770 | |
| 771 | 5.4 Handle Area Validation |
| 772 | |
| 773 | After successfully unmarshaling and validating the command header, the TPM shall perform the following |
| 774 | checks on the handles and sessions. These checks may be performed in any order. |
| 775 | |
| 776 | NOTE 1 A TPM is required to perform the handle area validation before the authorization checks because an |
| 777 | authorization cannot be performed unless the authorization values and attributes for the referenc ed |
| 778 | entity are known by the TPM. For them to be known, the referenced entity must be in the TPM and |
| 779 | accessible. |
| 780 | |
| 781 | a) The TPM shall successfully unmarshal the number of handles required by the command and validate |
| 782 | that the value of the handle is consistent with the command syntax. If not, the TPM shall return |
| 783 | TPM_RC_VALUE. |
| 784 | |
| 785 | NOTE 2 The TPM may unmarshal a handle and validate that it references an entity on the TPM before |
| 786 | unmarshaling a subsequent handle. |
| 787 | |
| 788 | NOTE 3 If the submitted command contains fewer handles than re quired by the syntax of the command, |
| 789 | the TPM may continue to read into the next area and attempt to interpret the data as a handle. |
| 790 | |
| 791 | b) For all handles in the handle area of the command, the TPM will validate that the referenced entity is |
| 792 | present in the TPM. |
| 793 | 1) If the handle references a transient object, the handle shall reference a loaded object |
| 794 | (TPM_RC_REFERENCE_H0 + N where N is the number of the handle in the command). |
| 795 | |
| 796 | NOTE 3 If the hierarchy for a transient object is disabled, then the transient objects will be flushed |
| 797 | so this check will fail. |
| 798 | |
| 799 | 2) If the handle references a persistent object, then |
| 800 | i) the hierarchy associated with the object (platform or storage, based on the handle value) is |
| 801 | enabled (TPM_RC_HANDLE); |
| 802 | ii) the handle shall reference a persistent object that is currently in TPM non-volatile memory |
| 803 | (TPM_RC_HANDLE); |
| 804 | iii) if the handle references a persistent object that is associated with the endorsement hierarchy, |
| 805 | that the endorsement hierarchy is not disabled (TPM_RC_HANDLE); and |
| 806 | |
| 807 | NOTE 4 The reference implementation keeps an internal attribute, passed down from a primary |
| 808 | key to its descendents, indicating the object's hierarchy. |
| 809 | |
| 810 | iv) if the TPM implementation moves a persistent object to RAM for command processing then |
| 811 | sufficient RAM space is available (TPM_RC_OBJECT_MEMORY). |
| 812 | 3) If the handle references an NV Index, then |
| 813 | i) an Index exists that corresponds to the handle (TPM_RC_HANDLE); and |
| 814 | ii) the hierarchy associated with the existing NV Index is not disabled (TPM_RC_HANDLE). |
| 815 | iii) If the command requires write access to the index data then TPMA_NV_WRITELOCKED is |
| 816 | not SET (TPM_RC_LOCKED) |
| 817 | iv) If the command requires read access to the index data then TPMA_NV_READLOCKED is |
| 818 | not SET (TPM_RC_LOCKED) |
| 819 | 4) If the handle references a session, then the session context shall be present in TPM memory |
| 820 | (TPM_RC_REFERENCE_S0 + N). |
| 821 | |
| 822 | |
| 823 | |
| 824 | Family “2.0” TCG Published Page 5 |
| 825 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 826 | Part 3: Commands Trusted Platform Module Library |
| 827 | |
| 828 | 5) If the handle references a primary seed for a hierarchy (TPM_RH_ENDORSEMENT, |
| 829 | TPM_RH_OWNER, or TPM_RH_PLATFORM) then the enable for the hierarchy is SET |
| 830 | (TPM_RC_HIERARCHY). |
| 831 | 6) If the handle references a PCR, then the value is within the range of PCR supported by the TPM |
| 832 | (TPM_RC_VALUE) |
| 833 | |
| 834 | NOTE 5 In the reference implementation, this TPM_RC_VALUE is returned by the unmarshaling |
| 835 | code for a TPMI_DH_PCR. |
| 836 | |
| 837 | |
| 838 | 5.5 Session Area Validation |
| 839 | |
| 840 | a) If the tag is TPM_ST_SESSIONS and the command requires TPM_ST_NO_SESSIONS, the TPM will |
| 841 | return TPM_RC_AUTH_CONTEXT. |
| 842 | b) If the tag is TPM_ST_NO_SESSIONS and the command requires TPM_ST_SESSIONS, the TPM will |
| 843 | return TPM_RC_AUTH_MISSING. |
| 844 | c) If the tag is TPM_ST_SESSIONS, the TPM will attempt to unmarshal an authorizationSize and return |
| 845 | TPM_RC_AUTHSIZE if the value is not within an acceptable range. |
| 846 | 1) The minimum value is (sizeof(TPM_HANDLE) + sizeof(UINT16) + sizeof(TPMA_SESSION) + |
| 847 | sizeof(UINT16)). |
| 848 | 2) The maximum value of authorizationSize is equal to commandSize – (sizeof(TPM_ST) + |
| 849 | sizeof(UINT32) + sizeof(TPM_CC) + (N * sizeof(TPM_HANDLE)) + sizeof(UINT32)) where N is |
| 850 | the number of handles associated with the commandCode and may be zero. |
| 851 | |
| 852 | NOTE 1 (sizeof(TPM_ST) + sizeof(UINT32) + sizeof(TPM_CC)) is the size of a command header. |
| 853 | The last UINT32 contains the authorizationSize octets, which are not counted as being in |
| 854 | the authorization session area. |
| 855 | |
| 856 | d) The TPM will unmarshal the authorization sessions and perform the following validations: |
| 857 | 1) If the session handle is not a handle for an HMAC session, a handle for a policy session, or, |
| 858 | TPM_RS_PW then the TPM shall return TPM_RC_HANDLE. |
| 859 | 2) If the session is not loaded, the TPM will return the warning TPM_RC_REFERENCE_S0 + N |
| 860 | where N is the number of the session. The first session is session zero, N = 0. |
| 861 | |
| 862 | NOTE 2 If the HMAC and policy session contexts use the same memory, the type of the context |
| 863 | must match the type of the handle. |
| 864 | |
| 865 | 3) If the maximum allowed number of sessions have been unmarshaled and fewer octets than |
| 866 | indicated in authorizationSize were unmarshaled (that is, authorizationSize is too large), the TPM |
| 867 | shall return TPM_RC_AUTHSIZE. |
| 868 | 4) The consistency of the authorization session attributes is checked. |
| 869 | i) Only one session is allowed for: |
| 870 | (a) session auditing (TPM_RC_ATTRIBUTES) – this session may be used for encrypt or |
| 871 | decrypt but may not be a session that is also used for authorization; |
| 872 | (b) decrypting a command parameter (TPM_RC_ATTRIBUTES) – this may be any of the |
| 873 | authorization sessions, or the audit session, or a session may be added for the single |
| 874 | purpose of decrypting a command parameter, as long as the total number of sessions |
| 875 | does not exceed three; and |
| 876 | (c) encrypting a response parameter (TPM_RC_ATTRIBUTES) – this may be any of the |
| 877 | authorization sessions, or the audit session if present, ora session may be added for the |
| 878 | single purpose of encrypting a response parameter, as long as the total number of |
| 879 | sessions does not exceed three. |
| 880 | |
| 881 | Page 6 TCG Published Family “2.0” |
| 882 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 883 | Trusted Platform Module Library Part 3: Commands |
| 884 | |
| 885 | NOTE 3 A session used for decrypting a command parameter may also be used for |
| 886 | encrypting a response parameter. |
| 887 | |
| 888 | ii) If a session is not being used for authorization, at least one of decrypt, encrypt, or audit must |
| 889 | be SET. (TPM_RC_ATTRIBUTES). |
| 890 | |
| 891 | |
| 892 | 5) An authorization session is present for each of the handles with the “@” decoration |
| 893 | (TPM_RC_AUTH_MISSING). |
| 894 | |
| 895 | |
| 896 | |
| 897 | 5.6 Authorization Checks |
| 898 | |
| 899 | After unmarshaling and validating the handles and the consistency of the authorization sessions, the |
| 900 | authorizations shall be checked. Authorization checks only apply to handles if the handle in the command |
| 901 | schematic has the “@” decoration. |
| 902 | a) The public and sensitive portions of the object shall be present on the TPM |
| 903 | (TPM_RC_AUTH_UNAVAILABLE). |
| 904 | b) If the associated handle is TPM_RH_PLATFORM, and the command requires confirmation with |
| 905 | physical presence, then physical presence is asserted (TPM_RC_PP). |
| 906 | c) If the object or NV Index is subject to DA protection, and the authorization is with an HMAC or |
| 907 | password, then the TPM is not in lockout (TPM_RC_LOCKOUT). |
| 908 | |
| 909 | NOTE 1 An object is subject to DA protection if its noDA attribute is CLEAR. An NV Index is subject to |
| 910 | DA protection if its TPMA_NV_NO_DA attribute is CLEAR. |
| 911 | |
| 912 | NOTE 2 An HMAC or password is required in a policy session when the policy contains |
| 913 | TPM2_PolicyAuthValue() or TPM2_PolicyPassword(). |
| 914 | |
| 915 | d) If the command requires a handle to have DUP role authorization, then the associated authorization |
| 916 | session is a policy session (TPM_RC_POLICY_FAIL). |
| 917 | e) If the command requires a handle to have ADMIN role authorization: |
| 918 | 1) If the entity being authorized is an object and its adminWithPolicy attribute is SET, or a hierarchy, |
| 919 | then the authorization session is a policy session (TPM_RC_POLICY_FAIL). |
| 920 | |
| 921 | NOTE 3 If adminWithPolicy is CLEAR, then any type of authorization session is allowed . |
| 922 | |
| 923 | 2) If the entity being authorized is an NV Index, then the associated authorization session is a policy |
| 924 | session. |
| 925 | |
| 926 | NOTE 4 The only commands that are currently defined that require use of ADMIN role authorization |
| 927 | are commands that operate on objects and NV Indices. |
| 928 | |
| 929 | f) If the command requires a handle to have USER role authorization: |
| 930 | 1) If the entity being authorized is an object and its userWithAuth attribute is CLEAR, then the |
| 931 | associated authorization session is a policy session (TPM_RC_POLICY_FAIL). |
| 932 | |
| 933 | NOTE 5 There is no check for a hierarchy, because a hierarchy operates as if userWithAuth is SET. |
| 934 | |
| 935 | 2) If the entity being authorized is an NV Index; |
| 936 | i) if the authorization session is a policy session; |
| 937 | (a) the TPMA_NV_POLICYWRITE attribute of the NV Index is SET if the command modifies |
| 938 | the NV Index data (TPM_RC_AUTH_UNAVAILABLE); |
| 939 | |
| 940 | Family “2.0” TCG Published Page 7 |
| 941 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 942 | Part 3: Commands Trusted Platform Module Library |
| 943 | |
| 944 | (b) the TPMA_NV_POLICYREAD attribute of the NV Index is SET if the command reads the |
| 945 | NV Index data (TPM_RC_AUTH_UNAVAILABLE); |
| 946 | ii) if the authorization is an HMAC session or a password; |
| 947 | (a) the TPMA_NV_AUTHWRITE attribute of the NV Index is SET if the command modifies |
| 948 | the NV Index data (TPM_RC_AUTH_UNAVAILABLE); |
| 949 | (b) the TPMA_NV_AUTHREAD attribute of the NV Index is SET if the command reads the |
| 950 | NV Index data (TPM_RC_AUTH_UNAVAILABLE). |
| 951 | g) If the authorization is provided by a policy session, then: |
| 952 | 1) if policySession→timeOut has been set, the session shall not have expired |
| 953 | (TPM_RC_EXPIRED); |
| 954 | 2) if policySession→cpHash has been set, it shall match the cpHash of the command |
| 955 | (TPM_RC_POLICY_FAIL); |
| 956 | 3) if policySession→commandCode has been set, then commandCode of the command shall match |
| 957 | (TPM_RC_POLICY_CC); |
| 958 | 4) policySession→policyDigest shall match the authPolicy associated with the handle |
| 959 | (TPM_RC_POLICY_FAIL); |
| 960 | 5) if policySession→pcrUpdateCounter has been set, then it shall match the value of |
| 961 | pcrUpdateCounter (TPM_RC_PCR_CHANGED); |
| 962 | 6) if policySession->commandLocality has been set, it shall match the locality of the command |
| 963 | (TPM_RC_LOCALITY), and |
| 964 | h) if the authorization uses an HMAC, then the HMAC is properly constructed using the authValue |
| 965 | associated with the handle and/or the session secret (TPM_RC_AUTH_FAIL or |
| 966 | TPM_RC_BAD_AUTH). |
| 967 | |
| 968 | NOTE 6 A policy session may require proof of knowledge of the authValue of the object being |
| 969 | authorized. |
| 970 | |
| 971 | i) if the authorization uses a password, then the password matches the authValue associated with the |
| 972 | handle (TPM_RC_AUTH_FAIL or TPM_RC_BAD_AUTH). |
| 973 | If the TPM returns an error other than TPM_RC_AUTH_FAIL then the TPM shall not alter any TPM state. |
| 974 | If the TPM return TPM_RC_AUTH_FAIL, then the TPM shall not alter any TPM state other than |
| 975 | lockoutCount. |
| 976 | |
| 977 | NOTE 7 The TPM may decrease failedTries regardless of any other processing performed by the TPM. That |
| 978 | is, the TPM may exit Lockout mode, regardless of the return code. |
| 979 | |
| 980 | |
| 981 | 5.7 Parameter Decryption |
| 982 | |
| 983 | If an authorization session has the TPMA_SESSION.decrypt attribute SET, and the command does not |
| 984 | allow a command parameter to be encrypted, then the TPM will return TPM_RC_ATTRIBUTES. |
| 985 | Otherwise, the TPM will decrypt the parameter using the values associated with the session before |
| 986 | parsing parameters. |
| 987 | |
| 988 | 5.8 Parameter Unmarshaling |
| 989 | |
| 990 | 5.8.1 Introduction |
| 991 | |
| 992 | The detailed actions for each command assume that the input parameters of the command have been |
| 993 | unmarshaled into a command-specific structure with the structure defined by the command schematic. |
| 994 | |
| 995 | |
| 996 | Page 8 TCG Published Family “2.0” |
| 997 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 998 | Trusted Platform Module Library Part 3: Commands |
| 999 | |
| 1000 | Additionally, a response-specific output structure is assumed which will receive the values produced by |
| 1001 | the detailed actions. |
| 1002 | |
| 1003 | NOTE An implementation is not required to process parameters in this manner or to separate the |
| 1004 | parameter parsing from the command actions. This method was chosen for the specification so that |
| 1005 | the normative behavior described by the detailed actions would be clear and unencumbered. |
| 1006 | |
| 1007 | Unmarshaling is the process of processing the parameters in the input buffer and preparing the |
| 1008 | parameters for use by the command-specific action code. No data movement need take place but it is |
| 1009 | required that the TPM validate that the parameters meet the requirements of the expected data type as |
| 1010 | defined in TPM 2.0 Part 2. |
| 1011 | |
| 1012 | 5.8.2 Unmarshaling Errors |
| 1013 | |
| 1014 | When an error is encountered while unmarshaling a command parameter, an error response code is |
| 1015 | returned and no command processing occurs. A table defining a data type may have response codes |
| 1016 | embedded in the table to indicate the error returned when the input value does not match the parameters |
| 1017 | of the table. |
| 1018 | |
| 1019 | NOTE In the reference implementation, a parameter number is added to the response code so that the |
| 1020 | offending parameter can be isolated. This is optional. |
| 1021 | |
| 1022 | In many cases, the table contains no specific response code value and the return code will be determined |
| 1023 | as defined in Table 3. |
| 1024 | |
| 1025 | |
| 1026 | |
| 1027 | |
| 1028 | Family “2.0” TCG Published Page 9 |
| 1029 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 1030 | Part 3: Commands Trusted Platform Module Library |
| 1031 | |
| 1032 | Table 3 — Unmarshaling Errors |
| 1033 | Response Code Meaning |
| 1034 | |
| 1035 | TPM_RC_ASYMMETRIC a parameter that should be an asymmetric algorithm selection does not have a |
| 1036 | value that is supported by the TPM |
| 1037 | TPM_RC_BAD_TAG a parameter that should be a command tag selection has a value that is not |
| 1038 | supported by the TPM |
| 1039 | TPM_RC_COMMAND_CODE a parameter that should be a command code does not have a value that is |
| 1040 | supported by the TPM |
| 1041 | TPM_RC_HASH a parameter that should be a hash algorithm selection does not have a value that |
| 1042 | is supported by the TPM |
| 1043 | TPM_RC_INSUFFICIENT the input buffer did not contain enough octets to allow unmarshaling of the |
| 1044 | expected data type; |
| 1045 | TPM_RC_KDF a parameter that should be a key derivation scheme (KDF) selection does not |
| 1046 | have a value that is supported by the TPM |
| 1047 | TPM_RC_KEY_SIZE a parameter that is a key size has a value that is not supported by the TPM |
| 1048 | TPM_RC_MODE a parameter that should be a symmetric encryption mode selection does not have |
| 1049 | a value that is supported by the TPM |
| 1050 | TPM_RC_RESERVED a non-zero value was found in a reserved field of an attribute structure (TPMA_) |
| 1051 | TPM_RC_SCHEME a parameter that should be signing or encryption scheme selection does not have |
| 1052 | a value that is supported by the TPM |
| 1053 | TPM_RC_SIZE the value of a size parameter is larger or smaller than allowed |
| 1054 | TPM_RC_SYMMETRIC a parameter that should be a symmetric algorithm selection does not have a |
| 1055 | value that is supported by the TPM |
| 1056 | TPM_RC_TAG a parameter that should be a structure tag has a value that is not supported by |
| 1057 | the TPM |
| 1058 | TPM_RC_TYPE The type parameter of a TPMT_PUBLIC or TPMT_SENSITIVE has a value that is |
| 1059 | not supported by the TPM |
| 1060 | TPM_RC_VALUE a parameter does not have one of its allowed values |
| 1061 | |
| 1062 | In some commands, a parameter may not be used because of various options of that command. |
| 1063 | However, the unmarshaling code is required to validate that all parameters have values that are allowed |
| 1064 | by the TPM 2.0 Part 2 definition of the parameter type even if that parameter is not used in the command |
| 1065 | actions. |
| 1066 | |
| 1067 | 5.9 Command Post Processing |
| 1068 | |
| 1069 | When the code that implements the detailed actions of the command completes, it returns a response |
| 1070 | code. If that code is not TPM_RC_SUCCESS, the post processing code will not update any session or |
| 1071 | audit data and will return a 10-octet response packet. |
| 1072 | If the command completes successfully, the tag of the command determines if any authorization sessions |
| 1073 | will be in the response. If so, the TPM will encrypt the first parameter of the response if indicated by the |
| 1074 | authorization attributes. The TPM will then generate a new nonce value for each session and, if |
| 1075 | appropriate, generate an HMAC. |
| 1076 | If authorization HMAC computations are performed on the response, the HMAC keys used in the |
| 1077 | response will be the same as the HMAC keys used in processing the HMAC in the command. |
| 1078 | |
| 1079 | |
| 1080 | |
| 1081 | |
| 1082 | Page 10 TCG Published Family “2.0” |
| 1083 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 1084 | Trusted Platform Module Library Part 3: Commands |
| 1085 | |
| 1086 | NOTE 1 This primarily affects authorizations associated with a first write to an NV Index using a bound |
| 1087 | session. The computation of the HMAC in the response is performed as if the Name of the Index did |
| 1088 | not change as a consequence of the command actions. The session binding to the NV Index will not |
| 1089 | persist to any subsequent command. |
| 1090 | |
| 1091 | NOTE 2 The authorization attributes were validated during the session area validation to ensure that only |
| 1092 | one session was used for parameter encryption of the response and that the command allowed |
| 1093 | encryption in the response. |
| 1094 | |
| 1095 | NOTE 3 No session nonce value is used for a password authorization but the session data is present. |
| 1096 | |
| 1097 | Additionally, if the command is being audited by Command Audit, the audit digest is updated with the |
| 1098 | cpHash of the command and rpHash of the response. |
| 1099 | |
| 1100 | |
| 1101 | |
| 1102 | |
| 1103 | Family “2.0” TCG Published Page 11 |
| 1104 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 1105 | Part 3: Commands Trusted Platform Module Library |
| 1106 | |
| 1107 | |
| 1108 | |
| 1109 | 6 Response Values |
| 1110 | |
| 1111 | 6.1 Tag |
| 1112 | |
| 1113 | When a command completes successfully, the tag parameter in the response shall have the same value |
| 1114 | as the tag parameter in the command (TPM_ST_SESSIONS or TPM_RC_NO_SESSIONS). When a |
| 1115 | command fails (the responseCode is not TPM_RC_SUCCESS), then the tag parameter in the response |
| 1116 | shall be TPM_ST_NO_SESSIONS. |
| 1117 | A special case exists when the command tag parameter is not an allowed value (TPM_ST_SESSIONS or |
| 1118 | TPM_ST_NO_SESSIONS). For this case, it is assumed that the system software is attempting to send a |
| 1119 | command formatted for a TPM 1.2 but the TPM is not capable of executing TPM 1.2 commands. So that |
| 1120 | the TPM 1.2 compatible software will have a recognizable response, the TPM sets tag to |
| 1121 | TPM_ST_RSP_COMMAND, responseSize to 00 00 00 0A16 and responseCode to TPM_RC_BAD_TAG. |
| 1122 | This is the same response as the TPM 1.2 fatal error for TPM_BADTAG. |
| 1123 | |
| 1124 | 6.2 Response Codes |
| 1125 | |
| 1126 | The normal response for any command is TPM_RC_SUCCESS. Any other value indicates that the |
| 1127 | command did not complete and the state of the TPM is unchanged. An exception to this general rule is |
| 1128 | that the logic associated with dictionary attack protection is allowed to be modified when an authorization |
| 1129 | failure occurs. |
| 1130 | Commands have response codes that are specific to that command, and those response codes are |
| 1131 | enumerated in the detailed actions of each command. The codes associated with the unmarshaling of |
| 1132 | parameters are documented Table 3. Another set of response code values are not command specific and |
| 1133 | indicate a problem that is not specific to the command. That is, if the indicated problem is remedied, the |
| 1134 | same command could be resubmitted and may complete normally. |
| 1135 | The response codes that are not command specific are listed and described in Table 4. |
| 1136 | The reference code for the command actions may have code that generates specific response codes |
| 1137 | associated with a specific check but the listing of responses may not have that response code listed. |
| 1138 | |
| 1139 | |
| 1140 | |
| 1141 | |
| 1142 | Page 12 TCG Published Family “2.0” |
| 1143 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 1144 | Trusted Platform Module Library Part 3: Commands |
| 1145 | |
| 1146 | Table 4 — Command-Independent Response Codes |
| 1147 | Response Code Meaning |
| 1148 | |
| 1149 | This response code may be returned by a TPM that supports command cancel. |
| 1150 | When the TPM receives an indication that the current command should be |
| 1151 | TPM_RC_CANCELED cancelled, the TPM may complete the command or return this code. If this code |
| 1152 | is returned, then the TPM state is not changed and the same command may be |
| 1153 | retried. |
| 1154 | This response code can be returned for commands that manage session |
| 1155 | contexts. It indicates that the gap between the lowest numbered active session |
| 1156 | TPM_RC_CONTEXT_GAP and the highest numbered session is at the limits of the session tracking logic. |
| 1157 | The remedy is to load the session context with the lowest number so that its |
| 1158 | tracking number can be updated. |
| 1159 | This response indicates that authorizations for objects subject to DA protection |
| 1160 | TPM_RC_LOCKOUT are not allowed at this time because the TPM is in DA lockout mode. The remedy |
| 1161 | is to wait or to exeucte TPM2_DictionaryAttackLockoutReset(). |
| 1162 | A TPM may use a common pool of memory for objects, sessions, and other |
| 1163 | purposes. When the TPM does not have enough memory available to perform |
| 1164 | the actions of the command, it may return TPM_RC_MEMORY. This indicates |
| 1165 | TPM_RC_MEMORY that the TPM resource manager may flush either sessions or objects in order to |
| 1166 | make memory available for the command execution. A TPM may choose to |
| 1167 | return TPM_RC_OBJECT_MEMORY or TPM_RC_SESSION_MEMORY if it |
| 1168 | needs contexts of a particular type to be flushed. |
| 1169 | This response code indicates that the TPM is rate-limiting writes to the NV |
| 1170 | memory in order to prevent wearout. This response is possible for any command |
| 1171 | TPM_RC_NV_RATE that explicity writes to NV or commands that incidentally use NV such as a |
| 1172 | command that uses authorization session that may need to update the dictionary |
| 1173 | attack logic. |
| 1174 | This response code is similar to TPM_RC_NV_RATE but indicates that access to |
| 1175 | NV memory is currently not available and the command is not allowed to proceed |
| 1176 | TPM_RC_NV_UNAVAILABLE |
| 1177 | until it is. This would occur in a system where the NV memory used by the TPM |
| 1178 | is not exclusive to the TPM and is a shared system resource. |
| 1179 | This response code indicates that the TPM has exhausted its handle space and |
| 1180 | no new objects can be loaded unless the TPM is rebooted. This does not occur in |
| 1181 | the reference implementation because of the way that object handles are |
| 1182 | TPM_RC_OBJECT_HANDLES |
| 1183 | allocated. However, other implementations are allowed to assign each object a |
| 1184 | unique handle each time the object is loaded. A TPM using this implementation |
| 1185 | 24 |
| 1186 | would be able to load 2 objects before the object space is exhausted. |
| 1187 | This response code can be returned by any command that causes the TPM to |
| 1188 | need an object 'slot'. The most common case where this might be returned is |
| 1189 | when an object is loaded (TPM2_Load, TPM2_CreatePrimary(), or |
| 1190 | TPM2_ContextLoad()). However, the TPM implementation is allowed to use |
| 1191 | object slots for other reasons. In the reference implementation, the TPM copies a |
| 1192 | TPM_RC_OBJECT_MEMORY |
| 1193 | referenced persistent object into RAM for the duration of the commannd. If all the |
| 1194 | slots are previously occupied, the TPM may return this value. A TPM is allowed |
| 1195 | to use object slots for other purposes and return this value. The remedy when |
| 1196 | this response is returned is for the TPM resource manager to flush a transient |
| 1197 | object. |
| 1198 | This response code indicates that a handle in the handle area of the command is |
| 1199 | not associated with a loaded object. The value of 'x' is in the range 0 to 6 with a |
| 1200 | st th |
| 1201 | value of 0 indicating the 1 handle and 6 representing the 7 . Upper values are |
| 1202 | TPM_RC_REFERENCE_Hx provided for future use. The TPM resource manager needs to find the correct |
| 1203 | object and load it. It may then adjust the handle and retry the command. |
| 1204 | NOTE Usually, this error indicates that the TPM resource manager has a corrupted |
| 1205 | database. |
| 1206 | |
| 1207 | |
| 1208 | |
| 1209 | |
| 1210 | Family “2.0” TCG Published Page 13 |
| 1211 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 1212 | Part 3: Commands Trusted Platform Module Library |
| 1213 | |
| 1214 | |
| 1215 | Response Code Meaning |
| 1216 | |
| 1217 | This response code indicates that a handle in the session area of the command |
| 1218 | is not associated with a loaded session. The value of 'x' is in the range 0 to 6 with |
| 1219 | st th |
| 1220 | a value of 0 indicating the 1 session handle and 6 representing the 7 . Upper |
| 1221 | TPM_RC_REFERENCE_Sx values are provided for future use. The TPM resource manager needs to find the |
| 1222 | correct session and load it. It may then retry the command. |
| 1223 | NOTE Usually, this error indicates that the TPM resource manager has a |
| 1224 | corrupted database. |
| 1225 | TPM_RC_RETRY the TPM was not able to start the command |
| 1226 | This response code indicates that the TPM does not have a handle to assign to a |
| 1227 | new session. This respose is only returned by TPM2_StartAuthSession(). It is |
| 1228 | TPM_RC_SESSION_HANDLES |
| 1229 | listed here because the command is not in error and the TPM resource manager |
| 1230 | can remedy the situation by flushing a session (TPM2_FlushContext(). |
| 1231 | This response code can be returned by any command that causes the TPM to |
| 1232 | need a session 'slot'. The most common case where this might be returned is |
| 1233 | when a session is loaded (TPM2_StartAuthSession() or TPM2_ContextLoad()). |
| 1234 | TPM_RC_SESSION_MEMORY |
| 1235 | However, the TPM implementation is allowed to use object slots for other |
| 1236 | purposes. The remedy when this response is returned is for the TPM resource |
| 1237 | manager to flush a transient object. |
| 1238 | Normal completion for any command. If the responseCode is |
| 1239 | TPM_RC_SUCCESS, then the rest of the response has the format indicated in |
| 1240 | TPM_RC_SUCCESS |
| 1241 | the response schematic. Otherwise, the response is a 10 octet value indicating |
| 1242 | an error. |
| 1243 | This response code indicates that the TPM is performing tests and cannot |
| 1244 | TPM_RC_TESTING |
| 1245 | respond to the request at this time. The command may be retried. |
| 1246 | the TPM has suspended operation on the command; forward progress was made |
| 1247 | and the command may be retried. |
| 1248 | TPM_RC_YIELDED |
| 1249 | See TPM 2.0 Part 1, “Multi-tasking.” |
| 1250 | NOTE This cannot occur on the reference implementation. |
| 1251 | |
| 1252 | |
| 1253 | |
| 1254 | |
| 1255 | Page 14 TCG Published Family “2.0” |
| 1256 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 1257 | Trusted Platform Module Library Part 3: Commands |
| 1258 | |
| 1259 | |
| 1260 | |
| 1261 | 7 Implementation Dependent |
| 1262 | |
| 1263 | The actions code for each command makes assumptions about the behavior of various sub-systems. |
| 1264 | There are many possible implementations of the subsystems that would achieve equivalent results. The |
| 1265 | actions code is not written to anticipate all possible implementations of the sub-systems. Therefore, it is |
| 1266 | the responsibility of the implementer to ensure that the necessary changes are made to the actions code |
| 1267 | when the sub-system behavior changes. |
| 1268 | |
| 1269 | |
| 1270 | |
| 1271 | |
| 1272 | Family “2.0” TCG Published Page 15 |
| 1273 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 1274 | Part 3: Commands Trusted Platform Module Library |
| 1275 | |
| 1276 | |
| 1277 | |
| 1278 | 8 Detailed Actions Assumptions |
| 1279 | |
| 1280 | 8.1 Introduction |
| 1281 | |
| 1282 | The C code in the Detailed Actions for each command is written with a set of assumptions about the |
| 1283 | processing performed before the action code is called and the processing that will be done after the |
| 1284 | action code completes. |
| 1285 | |
| 1286 | 8.2 Pre-processing |
| 1287 | |
| 1288 | Before calling the command actions code, the following actions have occurred. |
| 1289 | Verification that the handles in the handle area reference entities that are resident on the TPM. |
| 1290 | |
| 1291 | NOTE If a handle is in the parameter portion of the command, the associated entity does not have to |
| 1292 | be loaded, but the handle is required to be the correct type. |
| 1293 | |
| 1294 | If use of a handle requires authorization, the Password, HMAC, or Policy session associated with |
| 1295 | the handle has been verified. |
| 1296 | If a command parameter was encrypted using parameter encryption, it was decrypted before |
| 1297 | being unmarshaled. |
| 1298 | If the command uses handles or parameters, the calling stack contains a pointer to a data |
| 1299 | structure (in) that holds the unmarshaled values for the handles and command parameters. If |
| 1300 | the response has handles or parameters, the calling stack contains a pointer to a data structure |
| 1301 | (out) to hold the handles and response parameters generated by the command. |
| 1302 | All parameters of the in structure have been validated and meet the requirements of the |
| 1303 | parameter type as defined in TPM 2.0 Part 2. |
| 1304 | Space set aside for the out structure is sufficient to hold the largest out structure that could be |
| 1305 | produced by the command |
| 1306 | |
| 1307 | 8.3 Post Processing |
| 1308 | |
| 1309 | When the function implementing the command actions completes, |
| 1310 | response parameters that require parameter encryption will be encrypted after the command |
| 1311 | actions complete; |
| 1312 | audit and session contexts will be updated if the command response is TPM_RC_SUCCESS; |
| 1313 | and |
| 1314 | the command header and command response parameters will be marshaled to the response |
| 1315 | buffer. |
| 1316 | |
| 1317 | |
| 1318 | |
| 1319 | |
| 1320 | Page 16 TCG Published Family “2.0” |
| 1321 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 1322 | Trusted Platform Module Library Part 3: Commands |
| 1323 | |
| 1324 | |
| 1325 | |
| 1326 | 9 Start-up |
| 1327 | |
| 1328 | 9.1 Introduction |
| 1329 | |
| 1330 | This clause contains the commands used to manage the startup and restart state of a TPM. |
| 1331 | |
| 1332 | 9.2 _TPM_Init |
| 1333 | |
| 1334 | 9.2.1 General Description |
| 1335 | |
| 1336 | _TPM_Init initializes a TPM. |
| 1337 | Initialization actions include testing code required to execute the next expected command. If the TPM is in |
| 1338 | FUM, the next expected command is TPM2_FieldUpgradeData(); otherwise, the next expected command |
| 1339 | is TPM2_Startup(). |
| 1340 | |
| 1341 | NOTE 1 If the TPM performs self-tests after receiving _TPM_Init() and the TPM enters Failure mode before |
| 1342 | receiving TPM2_Startup() or TPM2_FieldUpgradeData(), then the TPM may be able to accept |
| 1343 | TPM2_GetTestResult() or TPM2_GetCapability(). |
| 1344 | |
| 1345 | The means of signaling _TPM_Init shall be defined in the platform-specific specifications that define the |
| 1346 | physical interface to the TPM. The platform shall send this indication whenever the platform starts its boot |
| 1347 | process and only when the platform starts its boot process. |
| 1348 | There shall be no software method of generating this indication that does not also reset the platform and |
| 1349 | begin execution of the CRTM. |
| 1350 | |
| 1351 | NOTE 2 In the reference implementation, this signal causes an internal flag ( s_initialized) to be CLEAR. |
| 1352 | While this flag is CLEAR, the TPM will only accept the next expected command described above. |
| 1353 | |
| 1354 | |
| 1355 | |
| 1356 | |
| 1357 | Family “2.0” TCG Published Page 17 |
| 1358 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 1359 | Part 3: Commands Trusted Platform Module Library |
| 1360 | |
| 1361 | |
| 1362 | 9.2.2 Detailed Actions |
| 1363 | |
| 1364 | This function is used to process a _TPM_Init() indication. |
| 1365 | |
| 1366 | 1 #include "InternalRoutines.h" |
| 1367 | 2 LIB_EXPORT void |
| 1368 | 3 _TPM_Init( |
| 1369 | 4 void |
| 1370 | 5 ) |
| 1371 | 6 { |
| 1372 | 7 // Clear the failure mode flags |
| 1373 | 8 g_inFailureMode = FALSE; |
| 1374 | 9 g_forceFailureMode = FALSE; |
| 1375 | 10 |
| 1376 | 11 // Initialize the NvEnvironment. |
| 1377 | 12 g_nvOk = NvPowerOn(); |
| 1378 | 13 |
| 1379 | 14 // Initialize crypto engine |
| 1380 | 15 CryptInitUnits(); |
| 1381 | 16 |
| 1382 | 17 // Start clock |
| 1383 | 18 TimePowerOn(); |
| 1384 | 19 |
| 1385 | 20 // Set initialization state |
| 1386 | 21 TPMInit(); |
| 1387 | 22 |
| 1388 | 23 // Initialize object table |
| 1389 | 24 ObjectStartup(); |
| 1390 | 25 |
| 1391 | 26 // Set g_DRTMHandle as unassigned |
| 1392 | 27 g_DRTMHandle = TPM_RH_UNASSIGNED; |
| 1393 | 28 |
| 1394 | 29 // No H-CRTM, yet. |
| 1395 | 30 g_DrtmPreStartup = FALSE; |
| 1396 | 31 |
| 1397 | 32 return; |
| 1398 | 33 } |
| 1399 | |
| 1400 | |
| 1401 | |
| 1402 | |
| 1403 | Page 18 TCG Published Family “2.0” |
| 1404 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 1405 | Trusted Platform Module Library Part 3: Commands |
| 1406 | |
| 1407 | |
| 1408 | |
| 1409 | 9.3 TPM2_Startup |
| 1410 | |
| 1411 | 9.3.1 General Description |
| 1412 | |
| 1413 | TPM2_Startup() is always preceded by _TPM_Init, which is the physical indication that TPM initialization |
| 1414 | is necessary because of a system-wide reset. TPM2_Startup() is only valid after _TPM_Init. Additional |
| 1415 | TPM2_Startup() commands are not allowed after it has completed successfully. If a TPM requires |
| 1416 | TPM2_Startup() and another command is received, or if the TPM receives TPM2_Startup() when it is not |
| 1417 | required, the TPM shall return TPM_RC_INITIALIZE. |
| 1418 | |
| 1419 | NOTE 1 See 9.2.1 for other command options for a TPM supporting field upgrade mode. |
| 1420 | |
| 1421 | NOTE 2 _TPM_Hash_Start, _TPM_Hash_Data, and _TPM_Hash_End are not commands and a platform - |
| 1422 | specific specification may allow t hese indications between _TPM_Init and TPM2_Startup(). |
| 1423 | |
| 1424 | If in Failure mode, the TPM shall accept TPM2_GetTestResult() and TPM2_GetCapability() even if |
| 1425 | TPM2_Startup() is not completed successfully or processed at all. |
| 1426 | A platform-specific specification may restrict the localities at which TPM2_Startup() may be received. |
| 1427 | A Shutdown/Startup sequence determines the way in which the TPM will operate in response to |
| 1428 | TPM2_Startup(). The three sequences are: |
| 1429 | 1) TPM Reset – This is a Startup(CLEAR) preceded by either Shutdown(CLEAR) or no |
| 1430 | TPM2_Shutdown(). On TPM Reset, all variables go back to their default initialization state. |
| 1431 | |
| 1432 | NOTE 3 Only those values that are specified as having a default initialization state are changed by TPM |
| 1433 | Reset. Persistent values that have no defa ult initialization state are not changed by this |
| 1434 | command. Values such as seeds have no default initialization state and only change due to |
| 1435 | specific commands. |
| 1436 | |
| 1437 | 2) TPM Restart – This is a Startup(CLEAR) preceded by Shutdown(STATE). This preserves much of the |
| 1438 | previous state of the TPM except that PCR and the controls associated with the Platform hierarchy |
| 1439 | are all returned to their default initialization state; |
| 1440 | 3) TPM Resume – This is a Startup(STATE) preceded by Shutdown(STATE). This preserves the |
| 1441 | previous state of the TPM including the static Root of Trust for Measurement (S-RTM) PCR and the |
| 1442 | platform controls other than the phEnable and phEnableNV. |
| 1443 | If a TPM receives Startup(STATE) and that was not preceded by Shutdown(STATE), the TPM shall return |
| 1444 | TPM_RC_VALUE. |
| 1445 | If, during TPM Restart or TPM Resume, the TPM fails to restore the state saved at the last |
| 1446 | Shutdown(STATE), the TPM shall enter Failure Mode and return TPM_RC_FAILURE. |
| 1447 | On any TPM2_Startup(), |
| 1448 | phEnable and phEnableNV shall be SET; |
| 1449 | all transient contexts (objects, sessions, and sequences) shall be flushed from TPM memory; |
| 1450 | TPMS_TIME_INFO.time shall be reset to zero; and |
| 1451 | use of lockoutAuth shall be enabled if lockoutRecovery is zero. |
| 1452 | Additional actions are performed based on the Shutdown/Startup sequence. |
| 1453 | On TPM Reset |
| 1454 | |
| 1455 | |
| 1456 | |
| 1457 | |
| 1458 | Family “2.0” TCG Published Page 19 |
| 1459 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 1460 | Part 3: Commands Trusted Platform Module Library |
| 1461 | |
| 1462 | |
| 1463 | platformAuth and platformPolicy shall be set to the Empty Buffer, |
| 1464 | For each NV index with TPMA_NV_WRITE_DEFINE CLEAR or TPMA_NV_WRITTEN CLEAR, |
| 1465 | TPMA_NV_WRITELOCKED shall be CLEAR, |
| 1466 | For each NV index with TPMA_NV_CLEAR_STCLEAR SET, TPMA_NV_WRITTEN shall be |
| 1467 | CLEAR, |
| 1468 | tracking data for saved session contexts shall be set to its initial value, |
| 1469 | the object context sequence number is reset to zero, |
| 1470 | a new context encryption key shall be generated, |
| 1471 | TPMS_CLOCK_INFO.restartCount shall be reset to zero, |
| 1472 | TPMS_CLOCK_INFO.resetCount shall be incremented, |
| 1473 | the PCR Update Counter shall be clear to zero, |
| 1474 | shEnable and ehEnable shall be SET, and |
| 1475 | PCR in all banks are reset to their default initial conditions as determined by the relevant |
| 1476 | platform-specific specification and the H-CRTM state (for exceptions, see TPM 2.0 Part 1, H- |
| 1477 | CRTM before TPM2_Startup() and TPM2_Startup without H-CRTM) |
| 1478 | |
| 1479 | NOTE 4 PCR may be initialized any time between _TPM_Init and the end of TPM2_Startup(). PCR that |
| 1480 | are preserved by TPM Resume will need to be restored during TPM2_Startup(). |
| 1481 | |
| 1482 | NOTE 5 See "Initializing PCR" in TPM 2.0 Part 1 for a description of the default initial conditions for a |
| 1483 | PCR. |
| 1484 | |
| 1485 | On TPM Restart |
| 1486 | TPMS_CLOCK_INFO.restartCount shall be incremented, |
| 1487 | shEnable and ehEnable shall be SET, |
| 1488 | platformAuth and platformPolicy shall be set to the Empty Buffer, |
| 1489 | For each NV index with TPMA_NV_WRITE_DEFINE CLEAR or TPMA_NV_WRITTEN CLEAR, |
| 1490 | TPMA_NV_WRITELOCKED shall be CLEAR, |
| 1491 | For each NV index with TPMA_NV_CLEAR_STCLEAR SET, TPMA_NV_WRITTEN shall be |
| 1492 | CLEAR, and |
| 1493 | PCR in all banks are reset to their default initial conditions. |
| 1494 | If an H-CRTM Event Sequence is active, extend the PCR designated by the platform-specific |
| 1495 | specification. |
| 1496 | On TPM Resume |
| 1497 | the H-CRTM startup method is the same for this TPM2_Startup() as for the previous |
| 1498 | TPM2_Startup(); (TPM_RC_LOCALITY) |
| 1499 | TPMS_CLOCK_INFO.restartCount shall be incremented; and |
| 1500 | PCR that are specified in a platform-specific specification to be preserved on TPM Resume are |
| 1501 | restored to their saved state and other PCR are set to their initial value as determined by a |
| 1502 | platform-specific specification. For constraints, see TPM 2.0 Part 1, H-CRTM before |
| 1503 | TPM2_Startup() and TPM2_Startup without H-CRTM. |
| 1504 | Other TPM state may change as required to meet the needs of the implementation. |
| 1505 | If the startupType is TPM_SU_STATE and the TPM requires TPM_SU_CLEAR, then the TPM shall return |
| 1506 | TPM_RC_VALUE. |
| 1507 | |
| 1508 | |
| 1509 | |
| 1510 | Page 20 TCG Published Family “2.0” |
| 1511 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 1512 | Trusted Platform Module Library Part 3: Commands |
| 1513 | |
| 1514 | NOTE 6 The TPM will require TPM_SU_CLEAR when no shutdown was performed or after |
| 1515 | Shutdown(CLEAR). |
| 1516 | |
| 1517 | NOTE 7 If startupType is neither TPM_SU_STATE nor TPM_SU_CLEAR, then the unmarshaling code returns |
| 1518 | TPM_RC_VALUE. |
| 1519 | |
| 1520 | |
| 1521 | |
| 1522 | |
| 1523 | Family “2.0” TCG Published Page 21 |
| 1524 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 1525 | Part 3: Commands Trusted Platform Module Library |
| 1526 | |
| 1527 | |
| 1528 | 9.3.2 Command and Response |
| 1529 | |
| 1530 | Table 5 — TPM2_Startup Command |
| 1531 | Type Name Description |
| 1532 | |
| 1533 | TPMI_ST_COMMAND_TAG tag TPM_ST_NO_SESSIONS |
| 1534 | UINT32 commandSize |
| 1535 | TPM_CC commandCode TPM_CC_Startup {NV} |
| 1536 | |
| 1537 | TPM_SU startupType TPM_SU_CLEAR or TPM_SU_STATE |
| 1538 | |
| 1539 | |
| 1540 | Table 6 — TPM2_Startup Response |
| 1541 | Type Name Description |
| 1542 | |
| 1543 | TPM_ST tag see clause 6 |
| 1544 | UINT32 responseSize |
| 1545 | TPM_RC responseCode |
| 1546 | |
| 1547 | |
| 1548 | |
| 1549 | |
| 1550 | Page 22 TCG Published Family “2.0” |
| 1551 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 1552 | Trusted Platform Module Library Part 3: Commands |
| 1553 | |
| 1554 | |
| 1555 | |
| 1556 | 9.3.3 Detailed Actions |
| 1557 | |
| 1558 | 1 #include "InternalRoutines.h" |
| 1559 | 2 #include "Startup_fp.h" |
| 1560 | 3 #ifdef TPM_CC_Startup // Conditional expansion of this file |
| 1561 | |
| 1562 | |
| 1563 | Error Returns Meaning |
| 1564 | |
| 1565 | TPM_RC_LOCALITY a Startup(STATE) does not have the same H-CRTM state as the |
| 1566 | previous Startup() or the locality of the startup is not 0 pr 3 |
| 1567 | TPM_RC_NV_UNINITIALIZED the saved state cannot be recovered and a Startup(CLEAR) is |
| 1568 | requried. |
| 1569 | TPM_RC_VALUE start up type is not compatible with previous shutdown sequence |
| 1570 | |
| 1571 | 4 TPM_RC |
| 1572 | 5 TPM2_Startup( |
| 1573 | 6 Startup_In *in // IN: input parameter list |
| 1574 | 7 ) |
| 1575 | 8 { |
| 1576 | 9 STARTUP_TYPE startup; |
| 1577 | 10 TPM_RC result; |
| 1578 | 11 BOOL prevDrtmPreStartup; |
| 1579 | 12 BOOL prevStartupLoc3; |
| 1580 | 13 BYTE locality = _plat__LocalityGet(); |
| 1581 | 14 |
| 1582 | 15 // In the PC Client specification, only locality 0 and 3 are allowed |
| 1583 | 16 if(locality != 0 && locality != 3) |
| 1584 | 17 return TPM_RC_LOCALITY; |
| 1585 | 18 // Indicate that the locality was 3 unless there was an H-CRTM |
| 1586 | 19 if(g_DrtmPreStartup) |
| 1587 | 20 locality = 0; |
| 1588 | 21 g_StartupLocality3 = (locality == 3); |
| 1589 | 22 |
| 1590 | 23 // The command needs NV update. Check if NV is available. |
| 1591 | 24 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at |
| 1592 | 25 // this point |
| 1593 | 26 result = NvIsAvailable(); |
| 1594 | 27 if(result != TPM_RC_SUCCESS) |
| 1595 | 28 return result; |
| 1596 | 29 |
| 1597 | 30 // Input Validation |
| 1598 | 31 |
| 1599 | 32 // Read orderly shutdown states from previous power cycle |
| 1600 | 33 NvReadReserved(NV_ORDERLY, &g_prevOrderlyState); |
| 1601 | 34 |
| 1602 | 35 // See if the orderly state indicates that state was saved |
| 1603 | 36 if( (g_prevOrderlyState & ~(PRE_STARTUP_FLAG | STARTUP_LOCALITY_3)) |
| 1604 | 37 == TPM_SU_STATE) |
| 1605 | 38 { |
| 1606 | 39 // If so, extrat the saved flags (HACK) |
| 1607 | 40 prevDrtmPreStartup = (g_prevOrderlyState & PRE_STARTUP_FLAG) != 0; |
| 1608 | 41 prevStartupLoc3 = (g_prevOrderlyState & STARTUP_LOCALITY_3) != 0; |
| 1609 | 42 g_prevOrderlyState = TPM_SU_STATE; |
| 1610 | 43 } |
| 1611 | 44 else |
| 1612 | 45 { |
| 1613 | 46 prevDrtmPreStartup = 0; |
| 1614 | 47 prevStartupLoc3 = 0; |
| 1615 | 48 } |
| 1616 | 49 // if this startup is a TPM Resume, then the H-CRTM states have to match. |
| 1617 | 50 if(in->startupType == TPM_SU_STATE) |
| 1618 | |
| 1619 | Family “2.0” TCG Published Page 23 |
| 1620 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 1621 | Part 3: Commands Trusted Platform Module Library |
| 1622 | |
| 1623 | 51 { |
| 1624 | 52 if(g_DrtmPreStartup != prevDrtmPreStartup) |
| 1625 | 53 return TPM_RC_VALUE + RC_Startup_startupType; |
| 1626 | 54 if(g_StartupLocality3 != prevStartupLoc3) |
| 1627 | 55 return TPM_RC_LOCALITY; |
| 1628 | 56 } |
| 1629 | 57 |
| 1630 | 58 // if the previous power cycle was shut down with no StateSave command, or |
| 1631 | 59 // with StateSave command for CLEAR, or the part of NV used for TPM_SU_STATE |
| 1632 | 60 // cannot be recovered, then this cycle can not startup up with STATE |
| 1633 | 61 if(in->startupType == TPM_SU_STATE) |
| 1634 | 62 { |
| 1635 | 63 if( g_prevOrderlyState == SHUTDOWN_NONE |
| 1636 | 64 || g_prevOrderlyState == TPM_SU_CLEAR) |
| 1637 | 65 return TPM_RC_VALUE + RC_Startup_startupType; |
| 1638 | 66 |
| 1639 | 67 if(g_nvOk == FALSE) |
| 1640 | 68 return TPM_RC_NV_UNINITIALIZED; |
| 1641 | 69 } |
| 1642 | 70 |
| 1643 | 71 // Internal Date Update |
| 1644 | 72 |
| 1645 | 73 // Translate the TPM2_ShutDown and TPM2_Startup sequence into the startup |
| 1646 | 74 // types. Will only be a SU_RESTART if the NV is OK |
| 1647 | 75 if( in->startupType == TPM_SU_CLEAR |
| 1648 | 76 && g_prevOrderlyState == TPM_SU_STATE |
| 1649 | 77 && g_nvOk == TRUE) |
| 1650 | 78 { |
| 1651 | 79 startup = SU_RESTART; |
| 1652 | 80 // Read state reset data |
| 1653 | 81 NvReadReserved(NV_STATE_RESET, &gr); |
| 1654 | 82 } |
| 1655 | 83 // In this check, we don't need to look at g_nvOk because that was checked |
| 1656 | 84 // above |
| 1657 | 85 else if(in->startupType == TPM_SU_STATE && g_prevOrderlyState == TPM_SU_STATE) |
| 1658 | 86 { |
| 1659 | 87 // Read state clear and state reset data |
| 1660 | 88 NvReadReserved(NV_STATE_CLEAR, &gc); |
| 1661 | 89 NvReadReserved(NV_STATE_RESET, &gr); |
| 1662 | 90 startup = SU_RESUME; |
| 1663 | 91 } |
| 1664 | 92 else |
| 1665 | 93 { |
| 1666 | 94 startup = SU_RESET; |
| 1667 | 95 } |
| 1668 | 96 |
| 1669 | 97 // Read persistent data from NV |
| 1670 | 98 NvReadPersistent(); |
| 1671 | 99 |
| 1672 | 100 // Crypto Startup |
| 1673 | 101 CryptUtilStartup(startup); |
| 1674 | 102 |
| 1675 | 103 // Read the platform unique value that is used as VENDOR_PERMANENT auth value |
| 1676 | 104 g_platformUniqueDetails.t.size = (UINT16)_plat__GetUnique(1, |
| 1677 | 105 sizeof(g_platformUniqueDetails.t.buffer), |
| 1678 | 106 g_platformUniqueDetails.t.buffer); |
| 1679 | 107 |
| 1680 | 108 // Start up subsystems |
| 1681 | 109 // Start counters and timers |
| 1682 | 110 TimeStartup(startup); |
| 1683 | 111 |
| 1684 | 112 // Start dictionary attack subsystem |
| 1685 | 113 DAStartup(startup); |
| 1686 | 114 |
| 1687 | 115 // Enable hierarchies |
| 1688 | 116 HierarchyStartup(startup); |
| 1689 | |
| 1690 | Page 24 TCG Published Family “2.0” |
| 1691 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 1692 | Trusted Platform Module Library Part 3: Commands |
| 1693 | |
| 1694 | 117 |
| 1695 | 118 // Restore/Initialize PCR |
| 1696 | 119 PCRStartup(startup, locality); |
| 1697 | 120 |
| 1698 | 121 // Restore/Initialize command audit information |
| 1699 | 122 CommandAuditStartup(startup); |
| 1700 | 123 |
| 1701 | 124 // Object context variables |
| 1702 | 125 if(startup == SU_RESET) |
| 1703 | 126 { |
| 1704 | 127 // Reset object context ID to 0 |
| 1705 | 128 gr.objectContextID = 0; |
| 1706 | 129 // Reset clearCount to 0 |
| 1707 | 130 gr.clearCount= 0; |
| 1708 | 131 } |
| 1709 | 132 |
| 1710 | 133 // Initialize session table |
| 1711 | 134 SessionStartup(startup); |
| 1712 | 135 |
| 1713 | 136 // Initialize index/evict data. This function clear read/write locks |
| 1714 | 137 // in NV index |
| 1715 | 138 NvEntityStartup(startup); |
| 1716 | 139 |
| 1717 | 140 // Initialize the orderly shut down flag for this cycle to SHUTDOWN_NONE. |
| 1718 | 141 gp.orderlyState = SHUTDOWN_NONE; |
| 1719 | 142 NvWriteReserved(NV_ORDERLY, &gp.orderlyState); |
| 1720 | 143 |
| 1721 | 144 // Update TPM internal states if command succeeded. |
| 1722 | 145 // Record a TPM2_Startup command has been received. |
| 1723 | 146 TPMRegisterStartup(); |
| 1724 | 147 |
| 1725 | 148 // The H-CRTM state no longer matters |
| 1726 | 149 g_DrtmPreStartup = FALSE; |
| 1727 | 150 |
| 1728 | 151 return TPM_RC_SUCCESS; |
| 1729 | 152 |
| 1730 | 153 } |
| 1731 | 154 #endif // CC_Startup |
| 1732 | |
| 1733 | |
| 1734 | |
| 1735 | |
| 1736 | Family “2.0” TCG Published Page 25 |
| 1737 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 1738 | Part 3: Commands Trusted Platform Module Library |
| 1739 | |
| 1740 | |
| 1741 | 9.4 TPM2_Shutdown |
| 1742 | |
| 1743 | 9.4.1 General Description |
| 1744 | |
| 1745 | This command is used to prepare the TPM for a power cycle. The shutdownType parameter indicates |
| 1746 | how the subsequent TPM2_Startup() will be processed. |
| 1747 | For a shutdownType of any type, the volatile portion of Clock is saved to NV memory and the orderly |
| 1748 | shutdown indication is SET. NV with the TPMA_NV_ORDERY attribute will be updated. |
| 1749 | For a shutdownType of TPM_SU_STATE, the following additional items are saved: |
| 1750 | tracking information for saved session contexts; |
| 1751 | the session context counter; |
| 1752 | PCR that are designated as being preserved by TPM2_Shutdown(TPM_SU_STATE); |
| 1753 | the PCR Update Counter; |
| 1754 | flags associated with supporting the TPMA_NV_WRITESTCLEAR and |
| 1755 | TPMA_NV_READSTCLEAR attributes; and |
| 1756 | the command audit digest and count. |
| 1757 | The following items shall not be saved and will not be in TPM memory after the next TPM2_Startup: |
| 1758 | TPM-memory-resident session contexts; |
| 1759 | TPM-memory-resident transient objects; or |
| 1760 | TPM-memory-resident hash contexts created by TPM2_HashSequenceStart(). |
| 1761 | Some values may be either derived from other values or saved to NV memory. |
| 1762 | This command saves TPM state but does not change the state other than the internal indication that the |
| 1763 | context has been saved. The TPM shall continue to accept commands. If a subsequent command |
| 1764 | changes TPM state saved by this command, then the effect of this command is nullified. The TPM MAY |
| 1765 | nullify this command for any subsequent command rather than check whether the command changed |
| 1766 | state saved by this command. If this command is nullified. and if no TPM2_Shutdown() occurs before the |
| 1767 | next TPM2_Startup(), then the next TPM2_Startup() shall be TPM2_Startup(CLEAR). |
| 1768 | |
| 1769 | |
| 1770 | |
| 1771 | |
| 1772 | Page 26 TCG Published Family “2.0” |
| 1773 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 1774 | Trusted Platform Module Library Part 3: Commands |
| 1775 | |
| 1776 | |
| 1777 | |
| 1778 | 9.4.2 Command and Response |
| 1779 | |
| 1780 | Table 7 — TPM2_Shutdown Command |
| 1781 | Type Name Description |
| 1782 | |
| 1783 | TPM_ST_SESSIONS if an audit session is present; |
| 1784 | TPMI_ST_COMMAND_TAG tag |
| 1785 | otherwise, TPM_ST_NO_SESSIONS |
| 1786 | UINT32 commandSize |
| 1787 | TPM_CC commandCode TPM_CC_Shutdown {NV} |
| 1788 | |
| 1789 | TPM_SU shutdownType TPM_SU_CLEAR or TPM_SU_STATE |
| 1790 | |
| 1791 | |
| 1792 | Table 8 — TPM2_Shutdown Response |
| 1793 | Type Name Description |
| 1794 | |
| 1795 | TPM_ST tag see clause 6 |
| 1796 | UINT32 responseSize |
| 1797 | TPM_RC responseCode |
| 1798 | |
| 1799 | |
| 1800 | |
| 1801 | |
| 1802 | Family “2.0” TCG Published Page 27 |
| 1803 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 1804 | Part 3: Commands Trusted Platform Module Library |
| 1805 | |
| 1806 | |
| 1807 | |
| 1808 | 9.4.3 Detailed Actions |
| 1809 | |
| 1810 | 1 #include "InternalRoutines.h" |
| 1811 | 2 #include "Shutdown_fp.h" |
| 1812 | 3 #ifdef TPM_CC_Shutdown // Conditional expansion of this file |
| 1813 | |
| 1814 | |
| 1815 | Error Returns Meaning |
| 1816 | |
| 1817 | TPM_RC_TYPE if PCR bank has been re-configured, a CLEAR StateSave() is |
| 1818 | required |
| 1819 | |
| 1820 | 4 TPM_RC |
| 1821 | 5 TPM2_Shutdown( |
| 1822 | 6 Shutdown_In *in // IN: input parameter list |
| 1823 | 7 ) |
| 1824 | 8 { |
| 1825 | 9 TPM_RC result; |
| 1826 | 10 |
| 1827 | 11 // The command needs NV update. Check if NV is available. |
| 1828 | 12 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at |
| 1829 | 13 // this point |
| 1830 | 14 result = NvIsAvailable(); |
| 1831 | 15 if(result != TPM_RC_SUCCESS) return result; |
| 1832 | 16 |
| 1833 | 17 // Input Validation |
| 1834 | 18 |
| 1835 | 19 // If PCR bank has been reconfigured, a CLEAR state save is required |
| 1836 | 20 if(g_pcrReConfig && in->shutdownType == TPM_SU_STATE) |
| 1837 | 21 return TPM_RC_TYPE + RC_Shutdown_shutdownType; |
| 1838 | 22 |
| 1839 | 23 // Internal Data Update |
| 1840 | 24 |
| 1841 | 25 // PCR private date state save |
| 1842 | 26 PCRStateSave(in->shutdownType); |
| 1843 | 27 |
| 1844 | 28 // Get DRBG state |
| 1845 | 29 CryptDrbgGetPutState(GET_STATE); |
| 1846 | 30 |
| 1847 | 31 // Save all orderly data |
| 1848 | 32 NvWriteReserved(NV_ORDERLY_DATA, &go); |
| 1849 | 33 |
| 1850 | 34 // Save RAM backed NV index data |
| 1851 | 35 NvStateSave(); |
| 1852 | 36 |
| 1853 | 37 if(in->shutdownType == TPM_SU_STATE) |
| 1854 | 38 { |
| 1855 | 39 // Save STATE_RESET and STATE_CLEAR data |
| 1856 | 40 NvWriteReserved(NV_STATE_CLEAR, &gc); |
| 1857 | 41 NvWriteReserved(NV_STATE_RESET, &gr); |
| 1858 | 42 } |
| 1859 | 43 else if(in->shutdownType == TPM_SU_CLEAR) |
| 1860 | 44 { |
| 1861 | 45 // Save STATE_RESET data |
| 1862 | 46 NvWriteReserved(NV_STATE_RESET, &gr); |
| 1863 | 47 } |
| 1864 | 48 |
| 1865 | 49 // Write orderly shut down state |
| 1866 | 50 if(in->shutdownType == TPM_SU_CLEAR) |
| 1867 | 51 gp.orderlyState = TPM_SU_CLEAR; |
| 1868 | 52 else if(in->shutdownType == TPM_SU_STATE) |
| 1869 | 53 { |
| 1870 | 54 gp.orderlyState = TPM_SU_STATE; |
| 1871 | 55 // Hack for the H-CRTM and Startup locality settings |
| 1872 | |
| 1873 | Page 28 TCG Published Family “2.0” |
| 1874 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 1875 | Trusted Platform Module Library Part 3: Commands |
| 1876 | |
| 1877 | 56 if(g_DrtmPreStartup) |
| 1878 | 57 gp.orderlyState |= PRE_STARTUP_FLAG; |
| 1879 | 58 else if(g_StartupLocality3) |
| 1880 | 59 gp.orderlyState |= STARTUP_LOCALITY_3; |
| 1881 | 60 } |
| 1882 | 61 else |
| 1883 | 62 pAssert(FALSE); |
| 1884 | 63 |
| 1885 | 64 NvWriteReserved(NV_ORDERLY, &gp.orderlyState); |
| 1886 | 65 |
| 1887 | 66 // If PRE_STARTUP_FLAG was SET, then it will stay set in gp.orderlyState even |
| 1888 | 67 // if the TPM isn't actually shut down. This is OK because all other checks |
| 1889 | 68 // of gp.orderlyState are to see if it is SHUTDOWN_NONE. So, having |
| 1890 | 69 // gp.orderlyState set to another value that is also not SHUTDOWN_NONE, is not |
| 1891 | 70 // an issue. This must be the case, otherwise, it would be impossible to add |
| 1892 | 71 // an additional shutdown type without major changes to the code. |
| 1893 | 72 |
| 1894 | 73 return TPM_RC_SUCCESS; |
| 1895 | 74 } |
| 1896 | 75 #endif // CC_Shutdown |
| 1897 | |
| 1898 | |
| 1899 | |
| 1900 | |
| 1901 | Family “2.0” TCG Published Page 29 |
| 1902 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 1903 | Part 3: Commands Trusted Platform Module Library |
| 1904 | |
| 1905 | |
| 1906 | 10 Testing |
| 1907 | |
| 1908 | 10.1 Introduction |
| 1909 | |
| 1910 | Compliance to standards for hardware security modules may require that the TPM test its functions |
| 1911 | before the results that depend on those functions may be returned. The TPM may perform operations |
| 1912 | using testable functions before those functions have been tested as long as the TPM returns no value |
| 1913 | that depends on the correctness of the testable function. |
| 1914 | |
| 1915 | EXAMPLE TPM2_PCR_Event() may be executed before the hash algorithms have been tested. However, until |
| 1916 | the hash algorithms have been tested, the contents of a PCR may not be used in any command if |
| 1917 | that command may result in a value being returned to the TPM user. This means that |
| 1918 | TPM2_PCR_Read() or TPM2_PolicyPCR() could not complete until the hashes have been checked |
| 1919 | but other TPM2_PCR_Event() commands may be executed even though the operation uses previous |
| 1920 | PCR values. |
| 1921 | |
| 1922 | If a command is received that requires return of a value that depends on untested functions, the TPM |
| 1923 | shall test the required functions before completing the command. |
| 1924 | Once the TPM has received TPM2_SelfTest() and before completion of all tests, the TPM is required to |
| 1925 | return TPM_RC_TESTING for any command that uses a function that requires a test. |
| 1926 | If a self-test fails at any time, the TPM will enter Failure mode. While in Failure mode, the TPM will return |
| 1927 | TPM_RC_FAILURE for any command other than TPM2_GetTestResult() and TPM2_GetCapability(). The |
| 1928 | TPM will remain in Failure mode until the next _TPM_Init. |
| 1929 | |
| 1930 | |
| 1931 | |
| 1932 | |
| 1933 | Page 30 TCG Published Family “2.0” |
| 1934 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 1935 | Trusted Platform Module Library Part 3: Commands |
| 1936 | |
| 1937 | |
| 1938 | |
| 1939 | 10.2 TPM2_SelfTest |
| 1940 | |
| 1941 | 10.2.1 General Description |
| 1942 | |
| 1943 | This command causes the TPM to perform a test of its capabilities. If the fullTest is YES, the TPM will test |
| 1944 | all functions. If fullTest = NO, the TPM will only test those functions that have not previously been tested. |
| 1945 | If any tests are required, the TPM shall either |
| 1946 | a) return TPM_RC_TESTING and begin self-test of the required functions, or |
| 1947 | |
| 1948 | NOTE 1 If fullTest is NO, and all functions have been tested, the TPM shall return TPM_RC_SUCCESS. |
| 1949 | |
| 1950 | b) perform the tests and return the test result when complete. |
| 1951 | If the TPM uses option a), the TPM shall return TPM_RC_TESTING for any command that requires use |
| 1952 | of a testable function, even if the functions required for completion of the command have already been |
| 1953 | tested. |
| 1954 | |
| 1955 | NOTE 2 This command may cause the TPM to continue processing after it has returned the response. So |
| 1956 | that software can be notified of the completion of the testing, the interface may include controls that |
| 1957 | would allow the TPM to generate an interrupt when th e “background” processing is complete. This |
| 1958 | would be in addition to the interrupt that may be available for signaling normal command completion. |
| 1959 | It is not necessary that there be two interrupts, but the interface should provide a way to indicate the |
| 1960 | nature of the interrupt (normal command or deferred command). |
| 1961 | |
| 1962 | |
| 1963 | |
| 1964 | |
| 1965 | Family “2.0” TCG Published Page 31 |
| 1966 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 1967 | Part 3: Commands Trusted Platform Module Library |
| 1968 | |
| 1969 | |
| 1970 | 10.2.2 Command and Response |
| 1971 | |
| 1972 | Table 9 — TPM2_SelfTest Command |
| 1973 | Type Name Description |
| 1974 | |
| 1975 | TPM_ST_SESSIONS if an audit session is present; |
| 1976 | TPMI_ST_COMMAND_TAG tag |
| 1977 | otherwise, TPM_ST_NO_SESSIONS |
| 1978 | UINT32 commandSize |
| 1979 | TPM_CC commandCode TPM_CC_SelfTest {NV} |
| 1980 | |
| 1981 | YES if full test to be performed |
| 1982 | TPMI_YES_NO fullTest |
| 1983 | NO if only test of untested functions required |
| 1984 | |
| 1985 | |
| 1986 | Table 10 — TPM2_SelfTest Response |
| 1987 | Type Name Description |
| 1988 | |
| 1989 | TPM_ST tag see clause 6 |
| 1990 | UINT32 responseSize |
| 1991 | TPM_RC responseCode |
| 1992 | |
| 1993 | |
| 1994 | |
| 1995 | |
| 1996 | Page 32 TCG Published Family “2.0” |
| 1997 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 1998 | Trusted Platform Module Library Part 3: Commands |
| 1999 | |
| 2000 | |
| 2001 | |
| 2002 | 10.2.3 Detailed Actions |
| 2003 | |
| 2004 | 1 #include "InternalRoutines.h" |
| 2005 | 2 #include "SelfTest_fp.h" |
| 2006 | 3 #ifdef TPM_CC_SelfTest // Conditional expansion of this file |
| 2007 | |
| 2008 | |
| 2009 | Error Returns Meaning |
| 2010 | |
| 2011 | TPM_RC_CANCELED the command was canceled (some incremental process may have |
| 2012 | been made) |
| 2013 | TPM_RC_TESTING self test in process |
| 2014 | |
| 2015 | 4 TPM_RC |
| 2016 | 5 TPM2_SelfTest( |
| 2017 | 6 SelfTest_In *in // IN: input parameter list |
| 2018 | 7 ) |
| 2019 | 8 { |
| 2020 | 9 // Command Output |
| 2021 | 10 |
| 2022 | 11 // Call self test function in crypt module |
| 2023 | 12 return CryptSelfTest(in->fullTest); |
| 2024 | 13 } |
| 2025 | 14 #endif // CC_SelfTest |
| 2026 | |
| 2027 | |
| 2028 | |
| 2029 | |
| 2030 | Family “2.0” TCG Published Page 33 |
| 2031 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 2032 | Part 3: Commands Trusted Platform Module Library |
| 2033 | |
| 2034 | |
| 2035 | 10.3 TPM2_IncrementalSelfTest |
| 2036 | |
| 2037 | 10.3.1 General Description |
| 2038 | |
| 2039 | This command causes the TPM to perform a test of the selected algorithms. |
| 2040 | |
| 2041 | NOTE 1 The toTest list indicates the algorithms that software would like the TPM to test in anticipation of |
| 2042 | future use. This allows tests to be done so that a future commands will not be delayed due to |
| 2043 | testing. |
| 2044 | |
| 2045 | The implementation may treat algorithms on the toTest list as either 'test each completely' or 'test |
| 2046 | this combination.' |
| 2047 | |
| 2048 | EXAMPLE If the toTest list includes AES and CTR mode, it may be interpreted as a request to test only AES in |
| 2049 | CTR mode. Alternatively, it may be interpreted as a request to test AES in all modes and CTR mode |
| 2050 | for all symmetric algorithms. |
| 2051 | |
| 2052 | |
| 2053 | If toTest contains an algorithm that has already been tested, it will not be tested again. |
| 2054 | |
| 2055 | NOTE 2 The only way to force retesting of an algorithm is with TPM2_SelfTest( fullTest = YES). |
| 2056 | |
| 2057 | The TPM will return in toDoList a list of algorithms that are yet to be tested. This list is not the list of |
| 2058 | algorithms that are scheduled to be tested but the algorithms/functions that have not been tested. Only |
| 2059 | the algorithms on the toTest list are scheduled to be tested by this command. |
| 2060 | |
| 2061 | NOTE 3 An algorithm remains on the toDoList while any part of it remains untested. |
| 2062 | |
| 2063 | EXAMPLE A symmetric algorithm remains untested until it is tested with all its modes. |
| 2064 | |
| 2065 | Making toTest an empty list allows the determination of the algorithms that remain untested without |
| 2066 | triggering any testing. |
| 2067 | If toTest is not an empty list, the TPM shall return TPM_RC_SUCCESS for this command and then return |
| 2068 | TPM_RC_TESTING for any subsequent command (including TPM2_IncrementalSelfTest()) until the |
| 2069 | requested testing is complete. |
| 2070 | |
| 2071 | NOTE 4 If toDoList is empty, then no additional tests are required and TPM_RC_TESTING will not be |
| 2072 | returned in subsequent commands and no additional delay will occur in a command due to testing. |
| 2073 | |
| 2074 | NOTE 5 If none of the algorithms listed in toTest is in the toDoList, then no tests will be performed. |
| 2075 | |
| 2076 | NOTE 6 The TPM cannot return TPM_RC_TESTING for this command, even when testing is not complete, |
| 2077 | because response parameters can only returned with the TPM_RC_SUCCESS return code. |
| 2078 | |
| 2079 | If all the parameters in this command are valid, the TPM returns TPM_RC_SUCCESS and the toDoList |
| 2080 | (which may be empty). |
| 2081 | |
| 2082 | NOTE 7 An implementation may perform all requested tests before returning TPM_RC_SUCCESS, or it may |
| 2083 | return TPM_RC_SUCCESS for this command and then return TPM_RC_TESTING for all |
| 2084 | subsequence commands (including TPM2_IncrementatSelfTest()) until the requested tests are |
| 2085 | complete. |
| 2086 | |
| 2087 | |
| 2088 | |
| 2089 | |
| 2090 | Page 34 TCG Published Family “2.0” |
| 2091 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 2092 | Trusted Platform Module Library Part 3: Commands |
| 2093 | |
| 2094 | |
| 2095 | |
| 2096 | 10.3.2 Command and Response |
| 2097 | |
| 2098 | Table 11 — TPM2_IncrementalSelfTest Command |
| 2099 | Type Name Description |
| 2100 | |
| 2101 | TPM_ST_SESSIONS if an audit session is present; |
| 2102 | TPMI_ST_COMMAND_TAG tag |
| 2103 | otherwise, TPM_ST_NO_SESSIONS |
| 2104 | UINT32 commandSize |
| 2105 | TPM_CC commandCode TPM_CC_IncrementalSelfTest {NV} |
| 2106 | |
| 2107 | TPML_ALG toTest list of algorithms that should be tested |
| 2108 | |
| 2109 | |
| 2110 | Table 12 — TPM2_IncrementalSelfTest Response |
| 2111 | Type Name Description |
| 2112 | |
| 2113 | TPM_ST tag see clause 6 |
| 2114 | UINT32 responseSize |
| 2115 | TPM_RC responseCode |
| 2116 | |
| 2117 | TPML_ALG toDoList list of algorithms that need testing |
| 2118 | |
| 2119 | |
| 2120 | |
| 2121 | |
| 2122 | Family “2.0” TCG Published Page 35 |
| 2123 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 2124 | Part 3: Commands Trusted Platform Module Library |
| 2125 | |
| 2126 | |
| 2127 | |
| 2128 | 10.3.3 Detailed Actions |
| 2129 | |
| 2130 | 1 #include "InternalRoutines.h" |
| 2131 | 2 #include "IncrementalSelfTest_fp.h" |
| 2132 | 3 #ifdef TPM_CC_IncrementalSelfTest // Conditional expansion of this file |
| 2133 | |
| 2134 | |
| 2135 | Error Returns Meaning |
| 2136 | |
| 2137 | TPM_RC_CANCELED the command was canceled (some tests may have completed) |
| 2138 | TPM_RC_VALUE an algorithm in the toTest list is not implemented |
| 2139 | |
| 2140 | 4 TPM_RC |
| 2141 | 5 TPM2_IncrementalSelfTest( |
| 2142 | 6 IncrementalSelfTest_In *in, // IN: input parameter list |
| 2143 | 7 IncrementalSelfTest_Out *out // OUT: output parameter list |
| 2144 | 8 ) |
| 2145 | 9 { |
| 2146 | 10 TPM_RC result; |
| 2147 | 11 // Command Output |
| 2148 | 12 |
| 2149 | 13 // Call incremental self test function in crypt module. If this function |
| 2150 | 14 // returns TPM_RC_VALUE, it means that an algorithm on the 'toTest' list is |
| 2151 | 15 // not implemented. |
| 2152 | 16 result = CryptIncrementalSelfTest(&in->toTest, &out->toDoList); |
| 2153 | 17 if(result == TPM_RC_VALUE) |
| 2154 | 18 return TPM_RCS_VALUE + RC_IncrementalSelfTest_toTest; |
| 2155 | 19 return result; |
| 2156 | 20 } |
| 2157 | 21 #endif // CC_IncrementalSelfTest |
| 2158 | |
| 2159 | |
| 2160 | |
| 2161 | |
| 2162 | Page 36 TCG Published Family “2.0” |
| 2163 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 2164 | Trusted Platform Module Library Part 3: Commands |
| 2165 | |
| 2166 | |
| 2167 | 10.4 TPM2_GetTestResult |
| 2168 | |
| 2169 | 10.4.1 General Description |
| 2170 | |
| 2171 | This command returns manufacturer-specific information regarding the results of a self-test and an |
| 2172 | indication of the test status. |
| 2173 | If TPM2_SelfTest() has not been executed and a testable function has not been tested, testResult will be |
| 2174 | TPM_RC_NEEDS_TEST. If TPM2_SelfTest() has been received and the tests are not complete, |
| 2175 | testResult will be TPM_RC_TESTING. If testing of all functions is complete without functional failures, |
| 2176 | testResult will be TPM_RC_SUCCESS. If any test failed, testResult will be TPM_RC_FAILURE. |
| 2177 | This command will operate when the TPM is in Failure mode so that software can determine the test |
| 2178 | status of the TPM and so that diagnostic information can be obtained for use in failure analysis. If the |
| 2179 | TPM is in Failure mode, then tag is required to be TPM_ST_NO_SESSIONS or the TPM shall return |
| 2180 | TPM_RC_FAILURE. |
| 2181 | |
| 2182 | |
| 2183 | |
| 2184 | |
| 2185 | Family “2.0” TCG Published Page 37 |
| 2186 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 2187 | Part 3: Commands Trusted Platform Module Library |
| 2188 | |
| 2189 | |
| 2190 | |
| 2191 | 10.4.2 Command and Response |
| 2192 | |
| 2193 | Table 13 — TPM2_GetTestResult Command |
| 2194 | Type Name Description |
| 2195 | |
| 2196 | TPM_ST_SESSIONS if an audit session is present; |
| 2197 | TPMI_ST_COMMAND_TAG tag |
| 2198 | otherwise, TPM_ST_NO_SESSIONS |
| 2199 | UINT32 commandSize |
| 2200 | TPM_CC commandCode TPM_CC_GetTestResult |
| 2201 | |
| 2202 | |
| 2203 | Table 14 — TPM2_GetTestResult Response |
| 2204 | Type Name Description |
| 2205 | |
| 2206 | TPMI_ST_COMMAND_TAG tag see clause 6 |
| 2207 | UINT32 responseSize |
| 2208 | TPM_RC responseCode |
| 2209 | |
| 2210 | test result data |
| 2211 | TPM2B_MAX_BUFFER outData |
| 2212 | contains manufacturer-specific information |
| 2213 | TPM_RC testResult |
| 2214 | |
| 2215 | |
| 2216 | |
| 2217 | |
| 2218 | Page 38 TCG Published Family “2.0” |
| 2219 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 2220 | Trusted Platform Module Library Part 3: Commands |
| 2221 | |
| 2222 | |
| 2223 | |
| 2224 | 10.4.3 Detailed Actions |
| 2225 | |
| 2226 | 1 #include "InternalRoutines.h" |
| 2227 | 2 #include "GetTestResult_fp.h" |
| 2228 | 3 #ifdef TPM_CC_GetTestResult // Conditional expansion of this file |
| 2229 | |
| 2230 | In the reference implementation, this function is only reachable if the TPM is not in failure mode meaning |
| 2231 | that all tests that have been run have completed successfully. There is not test data and the test result is |
| 2232 | TPM_RC_SUCCESS. |
| 2233 | |
| 2234 | 4 TPM_RC |
| 2235 | 5 TPM2_GetTestResult( |
| 2236 | 6 GetTestResult_Out *out // OUT: output parameter list |
| 2237 | 7 ) |
| 2238 | 8 { |
| 2239 | 9 // Command Output |
| 2240 | 10 |
| 2241 | 11 // Call incremental self test function in crypt module |
| 2242 | 12 out->testResult = CryptGetTestResult(&out->outData); |
| 2243 | 13 |
| 2244 | 14 return TPM_RC_SUCCESS; |
| 2245 | 15 } |
| 2246 | 16 #endif // CC_GetTestResult |
| 2247 | |
| 2248 | |
| 2249 | |
| 2250 | |
| 2251 | Family “2.0” TCG Published Page 39 |
| 2252 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 2253 | Part 3: Commands Trusted Platform Module Library |
| 2254 | |
| 2255 | |
| 2256 | 11 Session Commands |
| 2257 | |
| 2258 | 11.1 TPM2_StartAuthSession |
| 2259 | |
| 2260 | 11.1.1 General Description |
| 2261 | |
| 2262 | This command is used to start an authorization session using alternative methods of establishing the |
| 2263 | session key (sessionKey). The session key is then used to derive values used for authorization and for |
| 2264 | encrypting parameters. |
| 2265 | This command allows injection of a secret into the TPM using either asymmetric or symmetric encryption. |
| 2266 | The type of tpmKey determines how the value in encryptedSalt is encrypted. The decrypted secret value |
| 2267 | is used to compute the sessionKey. |
| 2268 | |
| 2269 | NOTE 1 If tpmKey Is TPM_RH_NULL, then encryptedSalt is required to be an Empty Buffer. |
| 2270 | |
| 2271 | The label value of “SECRET” (see “Terms and Definitions” in TPM 2.0 Part 1) is used in the recovery of |
| 2272 | the secret value. |
| 2273 | The TPM generates the sessionKey from the recovered secret value. |
| 2274 | No authorization is required for tpmKey or bind. |
| 2275 | |
| 2276 | NOTE 2 The justification for using tpmKey without providing authorization is that the result of using the key is |
| 2277 | not available to the caller, except indirectly through the sessionKey. This does not represent a point |
| 2278 | of attack on the value of the key. If th e caller attempts to use the session without knowing the |
| 2279 | sessionKey value, it is an authorization failure that will trigger the dictionary attack logic. |
| 2280 | |
| 2281 | The entity referenced with the bind parameter contributes an authorization value to the sessionKey |
| 2282 | generation process. |
| 2283 | If both tpmKey and bind are TPM_ALG_NULL, then sessionKey is set to the Empty Buffer. If tpmKey is |
| 2284 | not TPM_ALG_NULL, then encryptedSalt is used in the computation of sessionKey. If bind is not |
| 2285 | TPM_ALG_NULL, the authValue of bind is used in the sessionKey computation. |
| 2286 | If symmetric specifies a block cipher, then TPM_ALG_CFB is the only allowed value for the mode field in |
| 2287 | the symmetric parameter (TPM_RC_MODE). |
| 2288 | This command starts an authorization session and returns the session handle along with an initial |
| 2289 | nonceTPM in the response. |
| 2290 | If the TPM does not have a free slot for an authorization session, it shall return |
| 2291 | TPM_RC_SESSION_HANDLES. |
| 2292 | If the TPM implements a “gap” scheme for assigning contextID values, then the TPM shall return |
| 2293 | TPM_RC_CONTEXT_GAP if creating the session would prevent recycling of old saved contexts (See |
| 2294 | “Context Management” in TPM 2.0 Part 1). |
| 2295 | If tpmKey is not TPM_ALG_NULL then encryptedSalt shall be a TPM2B_ENCRYPTED_SECRET of the |
| 2296 | proper type for tpmKey. The TPM shall return TPM_RC_HANDLE if the sensitive portion of tpmKey is not |
| 2297 | loaded. The TPM shall return TPM_RC_VALUE if: |
| 2298 | a) tpmKey references an RSA key and |
| 2299 | 1) encryptedSalt does not contain a value that is the size of the public modulus of tpmKey, |
| 2300 | 2) encryptedSalt has a value that is greater than the public modulus of tpmKey, |
| 2301 | 3) encryptedSalt is not a properly encoded OAEP value, or |
| 2302 | 4) the decrypted salt value is larger than the size of the digest produced by the nameAlg of tpmKey; |
| 2303 | or |
| 2304 | |
| 2305 | |
| 2306 | Page 40 TCG Published Family “2.0” |
| 2307 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 2308 | Trusted Platform Module Library Part 3: Commands |
| 2309 | |
| 2310 | b) tpmKey references an ECC key and encryptedSalt |
| 2311 | 1) does not contain a TPMS_ECC_POINT or |
| 2312 | 2) is not a point on the curve of tpmKey; |
| 2313 | |
| 2314 | NOTE 3 When ECC is used, the point multiply process produces a value (Z) that is used in a KDF to |
| 2315 | produce the final secret value. The size of the secret value is an input parameter to the KDF |
| 2316 | and the result will be set to be the size of the digest produced by the nameAlg of tpmKey. |
| 2317 | |
| 2318 | c) tpmKey references a symmetric block cipher or a keyedHash object and encryptedSalt contains a |
| 2319 | value that is larger than the size of the digest produced by the nameAlg of tpmKey. |
| 2320 | If bind references a transient object, then the TPM shall return TPM_RC_HANDLE if the sensitive portion |
| 2321 | of the object is not loaded. |
| 2322 | For all session types, this command will cause initialization of the sessionKey and may establish binding |
| 2323 | between the session and an object (the bind object). If sessionType is TPM_SE_POLICY or |
| 2324 | TPM_SE_TRIAL, the additional session initialization is: |
| 2325 | set policySession→policyDigest to a Zero Digest (the digest size for policySession→policyDigest |
| 2326 | is the size of the digest produced by authHash); |
| 2327 | authorization may be given at any locality; |
| 2328 | authorization may apply to any command code; |
| 2329 | authorization may apply to any command parameters or handles; |
| 2330 | the authorization has no time limit; |
| 2331 | an authValue is not needed when the authorization is used; |
| 2332 | the session is not bound; |
| 2333 | the session is not an audit session; and |
| 2334 | the time at which the policy session was created is recorded. |
| 2335 | Additionally, if sessionType is TPM_SE_TRIAL, the session will not be usable for authorization but can be |
| 2336 | used to compute the authPolicy for an object. |
| 2337 | |
| 2338 | NOTE 4 Although this command changes the session allocation information in the TPM, it does not invalidate |
| 2339 | a saved context. That is, TPM2_Shutdown() is not required after this command in order to re- |
| 2340 | establish the orderly state of the TPM. This is because the created cont ext will occupy an available |
| 2341 | slot in the TPM and sessions in the TPM do not survive any TPM2_Startup(). However, if a created |
| 2342 | session is context saved, the orderly state does change. |
| 2343 | |
| 2344 | The TPM shall return TPM_RC_SIZE if nonceCaller is less than 16 octets or is greater than the size of |
| 2345 | the digest produced by authHash. |
| 2346 | |
| 2347 | |
| 2348 | |
| 2349 | |
| 2350 | Family “2.0” TCG Published Page 41 |
| 2351 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 2352 | Part 3: Commands Trusted Platform Module Library |
| 2353 | |
| 2354 | |
| 2355 | |
| 2356 | 11.1.2 Command and Response |
| 2357 | |
| 2358 | Table 15 — TPM2_StartAuthSession Command |
| 2359 | Type Name Description |
| 2360 | |
| 2361 | TPM_ST_SESSIONS if an audit, decrypt, or encrypt |
| 2362 | TPMI_ST_COMMAND_TAG tag session is present; otherwise, |
| 2363 | TPM_ST_NO_SESSIONS |
| 2364 | UINT32 commandSize |
| 2365 | TPM_CC commandCode TPM_CC_StartAuthSession |
| 2366 | |
| 2367 | handle of a loaded decrypt key used to encrypt salt |
| 2368 | TPMI_DH_OBJECT+ tpmKey may be TPM_RH_NULL |
| 2369 | Auth Index: None |
| 2370 | entity providing the authValue |
| 2371 | TPMI_DH_ENTITY+ bind may be TPM_RH_NULL |
| 2372 | Auth Index: None |
| 2373 | |
| 2374 | initial nonceCaller, sets nonce size for the session |
| 2375 | TPM2B_NONCE nonceCaller |
| 2376 | shall be at least 16 octets |
| 2377 | value encrypted according to the type of tpmKey |
| 2378 | TPM2B_ENCRYPTED_SECRET encryptedSalt If tpmKey is TPM_RH_NULL, this shall be the Empty |
| 2379 | Buffer. |
| 2380 | indicates the type of the session; simple HMAC or policy |
| 2381 | TPM_SE sessionType |
| 2382 | (including a trial policy) |
| 2383 | the algorithm and key size for parameter encryption |
| 2384 | TPMT_SYM_DEF+ symmetric |
| 2385 | may select TPM_ALG_NULL |
| 2386 | hash algorithm to use for the session |
| 2387 | TPMI_ALG_HASH authHash Shall be a hash algorithm supported by the TPM and |
| 2388 | not TPM_ALG_NULL |
| 2389 | |
| 2390 | |
| 2391 | Table 16 — TPM2_StartAuthSession Response |
| 2392 | Type Name Description |
| 2393 | TPM_ST tag see clause 6 |
| 2394 | UINT32 responseSize |
| 2395 | TPM_RC responseCode |
| 2396 | |
| 2397 | TPMI_SH_AUTH_SESSION sessionHandle handle for the newly created session |
| 2398 | |
| 2399 | the initial nonce from the TPM, used in the computation |
| 2400 | TPM2B_NONCE nonceTPM |
| 2401 | of the sessionKey |
| 2402 | |
| 2403 | |
| 2404 | |
| 2405 | |
| 2406 | Page 42 TCG Published Family “2.0” |
| 2407 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 2408 | Trusted Platform Module Library Part 3: Commands |
| 2409 | |
| 2410 | |
| 2411 | |
| 2412 | 11.1.3 Detailed Actions |
| 2413 | |
| 2414 | 1 #include "InternalRoutines.h" |
| 2415 | 2 #include "StartAuthSession_fp.h" |
| 2416 | 3 #ifdef TPM_CC_StartAuthSession // Conditional expansion of this file |
| 2417 | |
| 2418 | |
| 2419 | Error Returns Meaning |
| 2420 | |
| 2421 | TPM_RC_ATTRIBUTES tpmKey does not reference a decrypt key |
| 2422 | TPM_RC_CONTEXT_GAP the difference between the most recently created active context and |
| 2423 | the oldest active context is at the limits of the TPM |
| 2424 | TPM_RC_HANDLE input decrypt key handle only has public portion loaded |
| 2425 | TPM_RC_MODE symmetric specifies a block cipher but the mode is not |
| 2426 | TPM_ALG_CFB. |
| 2427 | TPM_RC_SESSION_HANDLES no session handle is available |
| 2428 | TPM_RC_SESSION_MEMORY no more slots for loading a session |
| 2429 | TPM_RC_SIZE nonce less than 16 octets or greater than the size of the digest |
| 2430 | produced by authHash |
| 2431 | TPM_RC_VALUE secret size does not match decrypt key type; or the recovered secret |
| 2432 | is larger than the digest size of the nameAlg of tpmKey; or, for an |
| 2433 | RSA decrypt key, if encryptedSecret is greater than the public |
| 2434 | exponent of tpmKey. |
| 2435 | |
| 2436 | 4 TPM_RC |
| 2437 | 5 TPM2_StartAuthSession( |
| 2438 | 6 StartAuthSession_In *in, // IN: input parameter buffer |
| 2439 | 7 StartAuthSession_Out *out // OUT: output parameter buffer |
| 2440 | 8 ) |
| 2441 | 9 { |
| 2442 | 10 TPM_RC result = TPM_RC_SUCCESS; |
| 2443 | 11 OBJECT *tpmKey; // TPM key for decrypt salt |
| 2444 | 12 SESSION *session; // session internal data |
| 2445 | 13 TPM2B_DATA salt; |
| 2446 | 14 |
| 2447 | 15 // Input Validation |
| 2448 | 16 |
| 2449 | 17 // Check input nonce size. IT should be at least 16 bytes but not larger |
| 2450 | 18 // than the digest size of session hash. |
| 2451 | 19 if( in->nonceCaller.t.size < 16 |
| 2452 | 20 || in->nonceCaller.t.size > CryptGetHashDigestSize(in->authHash)) |
| 2453 | 21 return TPM_RC_SIZE + RC_StartAuthSession_nonceCaller; |
| 2454 | 22 |
| 2455 | 23 // If an decrypt key is passed in, check its validation |
| 2456 | 24 if(in->tpmKey != TPM_RH_NULL) |
| 2457 | 25 { |
| 2458 | 26 // secret size cannot be 0 |
| 2459 | 27 if(in->encryptedSalt.t.size == 0) |
| 2460 | 28 return TPM_RC_VALUE + RC_StartAuthSession_encryptedSalt; |
| 2461 | 29 |
| 2462 | 30 // Get pointer to loaded decrypt key |
| 2463 | 31 tpmKey = ObjectGet(in->tpmKey); |
| 2464 | 32 |
| 2465 | 33 // Decrypting salt requires accessing the private portion of a key. |
| 2466 | 34 // Therefore, tmpKey can not be a key with only public portion loaded |
| 2467 | 35 if(tpmKey->attributes.publicOnly) |
| 2468 | 36 return TPM_RC_HANDLE + RC_StartAuthSession_tpmKey; |
| 2469 | 37 |
| 2470 | 38 // HMAC session input handle check. |
| 2471 | |
| 2472 | Family “2.0” TCG Published Page 43 |
| 2473 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 2474 | Part 3: Commands Trusted Platform Module Library |
| 2475 | |
| 2476 | 39 // tpmKey should be a decryption key |
| 2477 | 40 if(tpmKey->publicArea.objectAttributes.decrypt != SET) |
| 2478 | 41 return TPM_RC_ATTRIBUTES + RC_StartAuthSession_tpmKey; |
| 2479 | 42 |
| 2480 | 43 // Secret Decryption. A TPM_RC_VALUE, TPM_RC_KEY or Unmarshal errors |
| 2481 | 44 // may be returned at this point |
| 2482 | 45 result = CryptSecretDecrypt(in->tpmKey, &in->nonceCaller, "SECRET", |
| 2483 | 46 &in->encryptedSalt, &salt); |
| 2484 | 47 if(result != TPM_RC_SUCCESS) |
| 2485 | 48 return TPM_RC_VALUE + RC_StartAuthSession_encryptedSalt; |
| 2486 | 49 |
| 2487 | 50 } |
| 2488 | 51 else |
| 2489 | 52 { |
| 2490 | 53 // secret size must be 0 |
| 2491 | 54 if(in->encryptedSalt.t.size != 0) |
| 2492 | 55 return TPM_RC_VALUE + RC_StartAuthSession_encryptedSalt; |
| 2493 | 56 salt.t.size = 0; |
| 2494 | 57 } |
| 2495 | 58 // If the bind handle references a transient object, make sure that the |
| 2496 | 59 // sensitive area is loaded so that the authValue can be accessed. |
| 2497 | 60 if( HandleGetType(in->bind) == TPM_HT_TRANSIENT |
| 2498 | 61 && ObjectGet(in->bind)->attributes.publicOnly == SET) |
| 2499 | 62 return TPM_RC_HANDLE + RC_StartAuthSession_bind; |
| 2500 | 63 |
| 2501 | 64 // If 'symmetric' is a symmetric block cipher (not TPM_ALG_NULL or TPM_ALG_XOR) |
| 2502 | 65 // then the mode must be CFB. |
| 2503 | 66 if( in->symmetric.algorithm != TPM_ALG_NULL |
| 2504 | 67 && in->symmetric.algorithm != TPM_ALG_XOR |
| 2505 | 68 && in->symmetric.mode.sym != TPM_ALG_CFB) |
| 2506 | 69 return TPM_RC_MODE + RC_StartAuthSession_symmetric; |
| 2507 | 70 |
| 2508 | 71 // Internal Data Update |
| 2509 | 72 |
| 2510 | 73 // Create internal session structure. TPM_RC_CONTEXT_GAP, TPM_RC_NO_HANDLES |
| 2511 | 74 // or TPM_RC_SESSION_MEMORY errors may be returned returned at this point. |
| 2512 | 75 // |
| 2513 | 76 // The detailed actions for creating the session context are not shown here |
| 2514 | 77 // as the details are implementation dependent |
| 2515 | 78 // SessionCreate sets the output handle |
| 2516 | 79 result = SessionCreate(in->sessionType, in->authHash, |
| 2517 | 80 &in->nonceCaller, &in->symmetric, |
| 2518 | 81 in->bind, &salt, &out->sessionHandle); |
| 2519 | 82 |
| 2520 | 83 if(result != TPM_RC_SUCCESS) |
| 2521 | 84 return result; |
| 2522 | 85 |
| 2523 | 86 // Command Output |
| 2524 | 87 |
| 2525 | 88 // Get session pointer |
| 2526 | 89 session = SessionGet(out->sessionHandle); |
| 2527 | 90 |
| 2528 | 91 // Copy nonceTPM |
| 2529 | 92 out->nonceTPM = session->nonceTPM; |
| 2530 | 93 |
| 2531 | 94 return TPM_RC_SUCCESS; |
| 2532 | 95 } |
| 2533 | 96 #endif // CC_StartAuthSession |
| 2534 | |
| 2535 | |
| 2536 | |
| 2537 | |
| 2538 | Page 44 TCG Published Family “2.0” |
| 2539 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 2540 | Trusted Platform Module Library Part 3: Commands |
| 2541 | |
| 2542 | |
| 2543 | 11.2 TPM2_PolicyRestart |
| 2544 | |
| 2545 | 11.2.1 General Description |
| 2546 | |
| 2547 | This command allows a policy authorization session to be returned to its initial state. This command is |
| 2548 | used after the TPM returns TPM_RC_PCR_CHANGED. That response code indicates that a policy will |
| 2549 | fail because the PCR have changed after TPM2_PolicyPCR() was executed. Restarting the session |
| 2550 | allows the authorizations to be replayed because the session restarts with the same nonceTPM. If the |
| 2551 | PCR are valid for the policy, the policy may then succeed. |
| 2552 | This command does not reset the policy ID or the policy start time. |
| 2553 | |
| 2554 | |
| 2555 | |
| 2556 | |
| 2557 | Family “2.0” TCG Published Page 45 |
| 2558 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 2559 | Part 3: Commands Trusted Platform Module Library |
| 2560 | |
| 2561 | |
| 2562 | |
| 2563 | 11.2.2 Command and Response |
| 2564 | |
| 2565 | Table 17 — TPM2_PolicyRestart Command |
| 2566 | Type Name Description |
| 2567 | |
| 2568 | TPM_ST_SESSIONS if an audit session is present; |
| 2569 | TPMI_ST_COMMAND_TAG tag |
| 2570 | otherwise, TPM_ST_NO_SESSIONS |
| 2571 | UINT32 commandSize |
| 2572 | TPM_CC commandCode TPM_CC_PolicyRestart |
| 2573 | |
| 2574 | TPMI_SH_POLICY sessionHandle the handle for the policy session |
| 2575 | |
| 2576 | |
| 2577 | Table 18 — TPM2_PolicyRestart Response |
| 2578 | Type Name Description |
| 2579 | |
| 2580 | TPM_ST tag see clause 6 |
| 2581 | UINT32 responseSize |
| 2582 | TPM_RC responseCode |
| 2583 | |
| 2584 | |
| 2585 | |
| 2586 | |
| 2587 | Page 46 TCG Published Family “2.0” |
| 2588 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 2589 | Trusted Platform Module Library Part 3: Commands |
| 2590 | |
| 2591 | |
| 2592 | |
| 2593 | 11.2.3 Detailed Actions |
| 2594 | |
| 2595 | 1 #include "InternalRoutines.h" |
| 2596 | 2 #include "PolicyRestart_fp.h" |
| 2597 | 3 #ifdef TPM_CC_PolicyRestart // Conditional expansion of this file |
| 2598 | 4 TPM_RC |
| 2599 | 5 TPM2_PolicyRestart( |
| 2600 | 6 PolicyRestart_In *in // IN: input parameter list |
| 2601 | 7 ) |
| 2602 | 8 { |
| 2603 | 9 SESSION *session; |
| 2604 | 10 BOOL wasTrialSession; |
| 2605 | 11 |
| 2606 | 12 // Internal Data Update |
| 2607 | 13 |
| 2608 | 14 session = SessionGet(in->sessionHandle); |
| 2609 | 15 wasTrialSession = session->attributes.isTrialPolicy == SET; |
| 2610 | 16 |
| 2611 | 17 // Initialize policy session |
| 2612 | 18 SessionResetPolicyData(session); |
| 2613 | 19 |
| 2614 | 20 session->attributes.isTrialPolicy = wasTrialSession; |
| 2615 | 21 |
| 2616 | 22 return TPM_RC_SUCCESS; |
| 2617 | 23 } |
| 2618 | 24 #endif // CC_PolicyRestart |
| 2619 | |
| 2620 | |
| 2621 | |
| 2622 | |
| 2623 | Family “2.0” TCG Published Page 47 |
| 2624 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 2625 | Part 3: Commands Trusted Platform Module Library |
| 2626 | |
| 2627 | |
| 2628 | 12 Object Commands |
| 2629 | |
| 2630 | 12.1 TPM2_Create |
| 2631 | |
| 2632 | 12.1.1 General Description |
| 2633 | |
| 2634 | This command is used to create an object that can be loaded into a TPM using TPM2_Load(). If the |
| 2635 | command completes successfully, the TPM will create the new object and return the object’s creation |
| 2636 | data (creationData), its public area (outPublic), and its encrypted sensitive area (outPrivate). Preservation |
| 2637 | of the returned data is the responsibility of the caller. The object will need to be loaded (TPM2_Load()) |
| 2638 | before it may be used. |
| 2639 | TPM2B_PUBLIC template (inPublic) contains all of the fields necessary to define the properties of the |
| 2640 | new object. The setting for these fields is defined in “Public Area Template” in TPM 2.0 Part 1 and |
| 2641 | “TPMA_OBJECT” in TPM 2.0 Part 2. |
| 2642 | The parentHandle parameter shall reference a loaded decryption key that has both the public and |
| 2643 | sensitive area loaded. |
| 2644 | When defining the object, the caller provides a template structure for the object in a TPM2B_PUBLIC |
| 2645 | structure (inPublic), an initial value for the object’s authValue (inSensitive.userAuth), and, if the object is a |
| 2646 | symmetric object, an optional initial data value (inSensitive.data). The TPM shall validate the consistency |
| 2647 | of inPublic.attributes according to the Creation rules in “TPMA_OBJECT” in TPM 2.0 Part 2. |
| 2648 | The inSensitive parameter may be encrypted using parameter encryption. |
| 2649 | The methods in this clause are used by both TPM2_Create() and TPM2_CreatePrimary(). When a value |
| 2650 | is indicated as being TPM-generated, the value is filled in by bits from the RNG if the command is |
| 2651 | TPM2_Create() and with values from KDFa() if the command is TPM2_CreatePrimary(). The parameters |
| 2652 | of each creation value are specified in TPM 2.0 Part 1. |
| 2653 | The sensitiveDataOrigin attribute of inPublic shall be SET if inSensitive.data is an Empty Buffer and |
| 2654 | CLEAR if inSensitive.data is not an Empty Buffer or the TPM shall return TPM_RC_ATTRIBUTES. |
| 2655 | The TPM will create new data for the sensitive area and compute a TPMT_PUBLIC.unique from the |
| 2656 | sensitive area based on the object type: |
| 2657 | a) For a symmetric key: |
| 2658 | 1) If inSensitive.sensitive.data is the Empty Buffer, a TPM-generated key value is placed in the new |
| 2659 | object’s TPMT_SENSITIVE.sensitive.sym. The size of the key will be determined by |
| 2660 | inPublic.publicArea.parameters. |
| 2661 | 2) If inSensitive.sensitive.data is not the Empty Buffer, the TPM will validate that the size of |
| 2662 | inSensitive.data is no larger than the key size indicated in the inPublic template (TPM_RC_SIZE) |
| 2663 | and copy the inSensitive.data to TPMT_SENSITIVE.sensitive.sym of the new object. |
| 2664 | 3) A TPM-generated obfuscation value is placed in TPMT_SENSITIVE.sensitive.seedValue. The |
| 2665 | size of the obfuscation value is the size of the digest produced by the nameAlg in inPublic. This |
| 2666 | value prevents the public unique value from leaking information about the sensitive area. |
| 2667 | 4) The TPMT_PUBLIC.unique.sym value for the new object is then generated, as shown in equation |
| 2668 | (1) below, by hashing the key and obfuscation values in the TPMT_SENSITIVE with the nameAlg |
| 2669 | of the object. |
| 2670 | unique ≔ HnameAlg(sensitive.seedValue.buffer || sensitive.any.buffer) (1) |
| 2671 | b) If the Object is an asymmetric key: |
| 2672 | 1) If inSensitive.sensitive.data is not the Empty Buffer, then the TPM shall return TPM_RC_VALUE. |
| 2673 | |
| 2674 | |
| 2675 | |
| 2676 | Page 48 TCG Published Family “2.0” |
| 2677 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 2678 | Trusted Platform Module Library Part 3: Commands |
| 2679 | |
| 2680 | 2) A TPM-generated private key value is created with the size determined by the parameters of |
| 2681 | inPublic.publicArea.parameters. |
| 2682 | 3) If the key is a Storage Key, a TPM-generated TPMT_SENSITIVE.seedValue value is created; |
| 2683 | otherwise, TPMT_SENSITIVE.seedValue.size is set to zero. |
| 2684 | |
| 2685 | NOTE 1 An Object that is not a storage key has no child Objects to encrypt, so it does not need a |
| 2686 | symmetric key. |
| 2687 | |
| 2688 | 4) The public unique value is computed from the private key according to the methods of the key |
| 2689 | type. |
| 2690 | 5) If the key is an ECC key and the scheme required by the curveID is not the same as scheme in |
| 2691 | the public area of the template, then the TPM shall return TPM_RC_SCHEME. |
| 2692 | 6) If the key is an ECC key and the KDF required by the curveID is not the same as kdf in the pubic |
| 2693 | area of the template, then the TPM shall return TPM_RC_KDF. |
| 2694 | |
| 2695 | NOTE 2 There is currently no command in which the caller may specify the KDF to be used with an |
| 2696 | ECC decryption key. Since there is no use for this capability, the reference implementation |
| 2697 | requires that the kdf in the template be set to TPM_ALG_NULL or TPM_RC_KDF is |
| 2698 | returned. |
| 2699 | |
| 2700 | c) If the Object is a keyedHash object: |
| 2701 | 1) If inSensitive.sensitive.data is an Empty Buffer, and neither sign nor decrypt is SET in |
| 2702 | inPublic.attributes, the TPM shall return TPM_RC_ATTRIBUTES. This would be a data object |
| 2703 | with no data. |
| 2704 | 2) If inSensitive.sensitive.data is not an Empty Buffer, the TPM will copy the |
| 2705 | inSensitive.sensitive.data to TPMT_SENSITIVE.sensitive,bits of the new object. |
| 2706 | |
| 2707 | NOTE 3 The size of inSensitive.sensitive.data is limited to be no larger than the largest value of |
| 2708 | TPMT_SENSITIVE.sensitive.bits by MAX_SYM_DATA. |
| 2709 | |
| 2710 | 3) If inSensitive.sensitive.data is an Empty Buffer, a TPM-generated key value that is the size of the |
| 2711 | digest produced by the nameAlg in inPublic is placed in TPMT_SENSITIVE.sensitive.bits. |
| 2712 | 4) A TPM-generated obfuscation value that is the size of the digest produced by the nameAlg of |
| 2713 | inPublic is placed in TPMT_SENSITIVE.seedValue. |
| 2714 | 5) The TPMT_PUBLIC.unique.keyedHash value for the new object is then generated, as shown in |
| 2715 | equation (1) above, by hashing the key and obfuscation values in the TPMT_SENSITIVE with the |
| 2716 | nameAlg of the object. |
| 2717 | For TPM2_Load(), the TPM will apply normal symmetric protections to the created TPMT_SENSITIVE to |
| 2718 | create outPublic. |
| 2719 | |
| 2720 | NOTE 4 The encryption key is derived from the symmetric seed in the sensitive area of the parent. |
| 2721 | |
| 2722 | In addition to outPublic and outPrivate, the TPM will build a TPMS_CREATION_DATA structure for the |
| 2723 | object. TPMS_CREATION_DATA.outsideInfo is set to outsideInfo. This structure is returned in |
| 2724 | creationData. Additionally, the digest of this structure is returned in creationHash, and, finally, a |
| 2725 | TPMT_TK_CREATION is created so that the association between the creation data and the object may |
| 2726 | be validated by TPM2_CertifyCreation(). |
| 2727 | If the object being created is a Storage Key and inPublic.objectAttributes.fixedParent is SET, then the |
| 2728 | algorithms and parameters of inPublic are required to match those of the parent. The algorithms that must |
| 2729 | match are inPublic.type, inPublic.nameAlg, and inPublic.parameters. If inPublic.type does not match, the |
| 2730 | TPM shall return TPM_RC_TYPE. If inPublic.nameAlg does not match, the TPM shall return |
| 2731 | TPM_RC_HASH. If inPublic.parameters does not match, the TPM shall return TPM_RC_ASSYMETRIC. |
| 2732 | The TPM shall not differentiate between mismatches of the components of inPublic.parameters. |
| 2733 | |
| 2734 | |
| 2735 | Family “2.0” TCG Published Page 49 |
| 2736 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 2737 | Part 3: Commands Trusted Platform Module Library |
| 2738 | |
| 2739 | EXAMPLE If the inPublic.parameters.ecc.symmetric.algorithm does not match the parent, the TPM shall return |
| 2740 | TPM_RC_ ASYMMETRIC rather than TPM_RC_SYMMETRIC. |
| 2741 | |
| 2742 | |
| 2743 | |
| 2744 | |
| 2745 | Page 50 TCG Published Family “2.0” |
| 2746 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 2747 | Trusted Platform Module Library Part 3: Commands |
| 2748 | |
| 2749 | |
| 2750 | 12.1.2 Command and Response |
| 2751 | |
| 2752 | Table 19 — TPM2_Create Command |
| 2753 | Type Name Description |
| 2754 | |
| 2755 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 2756 | UINT32 commandSize |
| 2757 | TPM_CC commandCode TPM_CC_Create |
| 2758 | |
| 2759 | handle of parent for new object |
| 2760 | TPMI_DH_OBJECT @parentHandle Auth Index: 1 |
| 2761 | Auth Role: USER |
| 2762 | |
| 2763 | TPM2B_SENSITIVE_CREATE inSensitive the sensitive data |
| 2764 | TPM2B_PUBLIC inPublic the public template |
| 2765 | data that will be included in the creation data for this |
| 2766 | TPM2B_DATA outsideInfo object to provide permanent, verifiable linkage between |
| 2767 | this object and some object owner data |
| 2768 | TPML_PCR_SELECTION creationPCR PCR that will be used in creation data |
| 2769 | |
| 2770 | |
| 2771 | Table 20 — TPM2_Create Response |
| 2772 | Type Name Description |
| 2773 | |
| 2774 | TPM_ST tag see clause 6 |
| 2775 | UINT32 responseSize |
| 2776 | TPM_RC responseCode |
| 2777 | |
| 2778 | TPM2B_PRIVATE outPrivate the private portion of the object |
| 2779 | TPM2B_PUBLIC outPublic the public portion of the created object |
| 2780 | TPM2B_CREATION_DATA creationData contains a TPMS_CREATION_DATA |
| 2781 | TPM2B_DIGEST creationHash digest of creationData using nameAlg of outPublic |
| 2782 | ticket used by TPM2_CertifyCreation() to validate that |
| 2783 | TPMT_TK_CREATION creationTicket |
| 2784 | the creation data was produced by the TPM |
| 2785 | |
| 2786 | |
| 2787 | |
| 2788 | |
| 2789 | Family “2.0” TCG Published Page 51 |
| 2790 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 2791 | Part 3: Commands Trusted Platform Module Library |
| 2792 | |
| 2793 | |
| 2794 | |
| 2795 | 12.1.3 Detailed Actions |
| 2796 | |
| 2797 | 1 #include "InternalRoutines.h" |
| 2798 | 2 #include "Object_spt_fp.h" |
| 2799 | 3 #include "Create_fp.h" |
| 2800 | 4 #ifdef TPM_CC_Create // Conditional expansion of this file |
| 2801 | |
| 2802 | |
| 2803 | Error Returns Meaning |
| 2804 | |
| 2805 | TPM_RC_ASYMMETRIC non-duplicable storage key and its parent have different public |
| 2806 | parameters |
| 2807 | TPM_RC_ATTRIBUTES sensitiveDataOrigin is CLEAR when 'sensitive.data' is an Empty |
| 2808 | Buffer, or is SET when 'sensitive.data' is not empty; fixedTPM, |
| 2809 | fixedParent, or encryptedDuplication attributes are inconsistent |
| 2810 | between themselves or with those of the parent object; inconsistent |
| 2811 | restricted, decrypt and sign attributes; attempt to inject sensitive data |
| 2812 | for an asymmetric key; attempt to create a symmetric cipher key that |
| 2813 | is not a decryption key |
| 2814 | TPM_RC_HASH non-duplicable storage key and its parent have different name |
| 2815 | algorithm |
| 2816 | TPM_RC_KDF incorrect KDF specified for decrypting keyed hash object |
| 2817 | TPM_RC_KEY invalid key size values in an asymmetric key public area |
| 2818 | TPM_RC_KEY_SIZE key size in public area for symmetric key differs from the size in the |
| 2819 | sensitive creation area; may also be returned if the TPM does not |
| 2820 | allow the key size to be used for a Storage Key |
| 2821 | TPM_RC_RANGE the exponent value of an RSA key is not supported. |
| 2822 | TPM_RC_SCHEME inconsistent attributes decrypt, sign, restricted and key's scheme ID; |
| 2823 | or hash algorithm is inconsistent with the scheme ID for keyed hash |
| 2824 | object |
| 2825 | TPM_RC_SIZE size of public auth policy or sensitive auth value does not match |
| 2826 | digest size of the name algorithm sensitive data size for the keyed |
| 2827 | hash object is larger than is allowed for the scheme |
| 2828 | TPM_RC_SYMMETRIC a storage key with no symmetric algorithm specified; or non-storage |
| 2829 | key with symmetric algorithm different from TPM_ALG_NULL |
| 2830 | TPM_RC_TYPE unknown object type; non-duplicable storage key and its parent have |
| 2831 | different types; parentHandle does not reference a restricted |
| 2832 | decryption key in the storage hierarchy with both public and sensitive |
| 2833 | portion loaded |
| 2834 | TPM_RC_VALUE exponent is not prime or could not find a prime using the provided |
| 2835 | parameters for an RSA key; unsupported name algorithm for an ECC |
| 2836 | key |
| 2837 | TPM_RC_OBJECT_MEMORY there is no free slot for the object. This implementation does not |
| 2838 | return this error. |
| 2839 | |
| 2840 | 5 TPM_RC |
| 2841 | 6 TPM2_Create( |
| 2842 | 7 Create_In *in, // IN: input parameter list |
| 2843 | 8 Create_Out *out // OUT: output parameter list |
| 2844 | 9 ) |
| 2845 | 10 { |
| 2846 | 11 TPM_RC result = TPM_RC_SUCCESS; |
| 2847 | 12 TPMT_SENSITIVE sensitive; |
| 2848 | 13 TPM2B_NAME name; |
| 2849 | 14 |
| 2850 | |
| 2851 | Page 52 TCG Published Family “2.0” |
| 2852 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 2853 | Trusted Platform Module Library Part 3: Commands |
| 2854 | |
| 2855 | 15 // Input Validation |
| 2856 | 16 |
| 2857 | 17 OBJECT *parentObject; |
| 2858 | 18 |
| 2859 | 19 parentObject = ObjectGet(in->parentHandle); |
| 2860 | 20 |
| 2861 | 21 // Does parent have the proper attributes? |
| 2862 | 22 if(!AreAttributesForParent(parentObject)) |
| 2863 | 23 return TPM_RC_TYPE + RC_Create_parentHandle; |
| 2864 | 24 |
| 2865 | 25 // The sensitiveDataOrigin attribute must be consistent with the setting of |
| 2866 | 26 // the size of the data object in inSensitive. |
| 2867 | 27 if( (in->inPublic.t.publicArea.objectAttributes.sensitiveDataOrigin == SET) |
| 2868 | 28 != (in->inSensitive.t.sensitive.data.t.size == 0)) |
| 2869 | 29 // Mismatch between the object attributes and the parameter. |
| 2870 | 30 return TPM_RC_ATTRIBUTES + RC_Create_inSensitive; |
| 2871 | 31 |
| 2872 | 32 // Check attributes in input public area. TPM_RC_ASYMMETRIC, TPM_RC_ATTRIBUTES, |
| 2873 | 33 // TPM_RC_HASH, TPM_RC_KDF, TPM_RC_SCHEME, TPM_RC_SIZE, TPM_RC_SYMMETRIC, |
| 2874 | 34 // or TPM_RC_TYPE error may be returned at this point. |
| 2875 | 35 result = PublicAttributesValidation(FALSE, in->parentHandle, |
| 2876 | 36 &in->inPublic.t.publicArea); |
| 2877 | 37 if(result != TPM_RC_SUCCESS) |
| 2878 | 38 return RcSafeAddToResult(result, RC_Create_inPublic); |
| 2879 | 39 |
| 2880 | 40 // Validate the sensitive area values |
| 2881 | 41 if( MemoryRemoveTrailingZeros(&in->inSensitive.t.sensitive.userAuth) |
| 2882 | 42 > CryptGetHashDigestSize(in->inPublic.t.publicArea.nameAlg)) |
| 2883 | 43 return TPM_RC_SIZE + RC_Create_inSensitive; |
| 2884 | 44 |
| 2885 | 45 // Command Output |
| 2886 | 46 |
| 2887 | 47 // Create object crypto data |
| 2888 | 48 result = CryptCreateObject(in->parentHandle, &in->inPublic.t.publicArea, |
| 2889 | 49 &in->inSensitive.t.sensitive, &sensitive); |
| 2890 | 50 if(result != TPM_RC_SUCCESS) |
| 2891 | 51 return result; |
| 2892 | 52 |
| 2893 | 53 // Fill in creation data |
| 2894 | 54 FillInCreationData(in->parentHandle, in->inPublic.t.publicArea.nameAlg, |
| 2895 | 55 &in->creationPCR, &in->outsideInfo, |
| 2896 | 56 &out->creationData, &out->creationHash); |
| 2897 | 57 |
| 2898 | 58 // Copy public area from input to output |
| 2899 | 59 out->outPublic.t.publicArea = in->inPublic.t.publicArea; |
| 2900 | 60 |
| 2901 | 61 // Compute name from public area |
| 2902 | 62 ObjectComputeName(&(out->outPublic.t.publicArea), &name); |
| 2903 | 63 |
| 2904 | 64 // Compute creation ticket |
| 2905 | 65 TicketComputeCreation(EntityGetHierarchy(in->parentHandle), &name, |
| 2906 | 66 &out->creationHash, &out->creationTicket); |
| 2907 | 67 |
| 2908 | 68 // Prepare output private data from sensitive |
| 2909 | 69 SensitiveToPrivate(&sensitive, &name, in->parentHandle, |
| 2910 | 70 out->outPublic.t.publicArea.nameAlg, |
| 2911 | 71 &out->outPrivate); |
| 2912 | 72 |
| 2913 | 73 return TPM_RC_SUCCESS; |
| 2914 | 74 } |
| 2915 | 75 #endif // CC_Create |
| 2916 | |
| 2917 | |
| 2918 | |
| 2919 | |
| 2920 | Family “2.0” TCG Published Page 53 |
| 2921 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 2922 | Part 3: Commands Trusted Platform Module Library |
| 2923 | |
| 2924 | |
| 2925 | 12.2 TPM2_Load |
| 2926 | |
| 2927 | 12.2.1 General Description |
| 2928 | |
| 2929 | This command is used to load objects into the TPM. This command is used when both a TPM2B_PUBLIC |
| 2930 | and TPM2B_PRIVATE are to be loaded. If only a TPM2B_PUBLIC is to be loaded, the |
| 2931 | TPM2_LoadExternal command is used. |
| 2932 | |
| 2933 | NOTE 1 Loading an object is not the same as restoring a saved object context. |
| 2934 | |
| 2935 | The object’s TPMA_OBJECT attributes will be checked according to the rules defined in |
| 2936 | “TPMA_OBJECT” in TPM 2.0 Part 2 of this specification. |
| 2937 | Objects loaded using this command will have a Name. The Name is the concatenation of nameAlg and |
| 2938 | the digest of the public area using the nameAlg. |
| 2939 | |
| 2940 | NOTE 2 nameAlg is a parameter in the public area of the inPublic structure. |
| 2941 | |
| 2942 | If inPrivate.size is zero, the load will fail. |
| 2943 | After inPrivate.buffer is decrypted using the symmetric key of the parent, the integrity value shall be |
| 2944 | checked before the sensitive area is used, or unmarshaled. |
| 2945 | |
| 2946 | NOTE 3 Checking the integrity before the data is used prevents attacks on the sensitive area by fuzzing the |
| 2947 | data and looking at the differences in the response codes. |
| 2948 | |
| 2949 | The command returns a handle for the loaded object and the Name that the TPM computed for |
| 2950 | inPublic.public (that is, the digest of the TPMT_PUBLIC structure in inPublic). |
| 2951 | |
| 2952 | NOTE 4 The TPM-computed Name is provided as a convenience to the caller for those cases where the |
| 2953 | caller does not implement the hash algorithms specified in the nameAlg of the object. |
| 2954 | |
| 2955 | NOTE 5 The returned handle is associated with the object until the object is flushed (TPM2_FlushContext) o r |
| 2956 | until the next TPM2_Startup. |
| 2957 | |
| 2958 | For all objects, the size of the key in the sensitive area shall be consistent with the key size indicated in |
| 2959 | the public area or the TPM shall return TPM_RC_KEY_SIZE. |
| 2960 | Before use, a loaded object shall be checked to validate that the public and sensitive portions are |
| 2961 | properly linked, cryptographically. Use of an object includes use in any policy command. If the parts of the |
| 2962 | object are not properly linked, the TPM shall return TPM_RC_BINDING. |
| 2963 | |
| 2964 | EXAMPLE 1 For a symmetric object, the unique value in the public area shall be the digest of the sensitive key |
| 2965 | and the obfuscation value. |
| 2966 | |
| 2967 | EXAMPLE 2 For a two-prime RSA key, the remainder when dividing the public modulus by the private key shall |
| 2968 | be zero and it shall be possible to form a priv ate exponent from the two prime factors of the public |
| 2969 | modulus. |
| 2970 | |
| 2971 | EXAMPLE 3 For an ECC key, the public point shall be f(x) where x is the private key. |
| 2972 | |
| 2973 | |
| 2974 | |
| 2975 | |
| 2976 | Page 54 TCG Published Family “2.0” |
| 2977 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 2978 | Trusted Platform Module Library Part 3: Commands |
| 2979 | |
| 2980 | |
| 2981 | 12.2.2 Command and Response |
| 2982 | |
| 2983 | Table 21 — TPM2_Load Command |
| 2984 | Type Name Description |
| 2985 | |
| 2986 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 2987 | UINT32 commandSize |
| 2988 | TPM_CC commandCode TPM_CC_Load |
| 2989 | |
| 2990 | TPM handle of parent key; shall not be a reserved |
| 2991 | handle |
| 2992 | TPMI_DH_OBJECT @parentHandle |
| 2993 | Auth Index: 1 |
| 2994 | Auth Role: USER |
| 2995 | |
| 2996 | TPM2B_PRIVATE inPrivate the private portion of the object |
| 2997 | TPM2B_PUBLIC inPublic the public portion of the object |
| 2998 | |
| 2999 | |
| 3000 | Table 22 — TPM2_Load Response |
| 3001 | Type Name Description |
| 3002 | |
| 3003 | TPM_ST tag see clause 6 |
| 3004 | UINT32 responseSize |
| 3005 | TPM_RC responseCode |
| 3006 | |
| 3007 | handle of type TPM_HT_TRANSIENT for the loaded |
| 3008 | TPM_HANDLE objectHandle |
| 3009 | object |
| 3010 | |
| 3011 | TPM2B_NAME name Name of the loaded object |
| 3012 | |
| 3013 | |
| 3014 | |
| 3015 | |
| 3016 | Family “2.0” TCG Published Page 55 |
| 3017 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 3018 | Part 3: Commands Trusted Platform Module Library |
| 3019 | |
| 3020 | |
| 3021 | |
| 3022 | 12.2.3 Detailed Actions |
| 3023 | |
| 3024 | 1 #include "InternalRoutines.h" |
| 3025 | 2 #include "Load_fp.h" |
| 3026 | 3 #ifdef TPM_CC_Load // Conditional expansion of this file |
| 3027 | 4 #include "Object_spt_fp.h" |
| 3028 | |
| 3029 | |
| 3030 | Error Returns Meaning |
| 3031 | |
| 3032 | TPM_RC_ASYMMETRIC storage key with different asymmetric type than parent |
| 3033 | TPM_RC_ATTRIBUTES inPulblic attributes are not allowed with selected parent |
| 3034 | TPM_RC_BINDING inPrivate and inPublic are not cryptographically bound |
| 3035 | TPM_RC_HASH incorrect hash selection for signing key |
| 3036 | TPM_RC_INTEGRITY HMAC on inPrivate was not valid |
| 3037 | TPM_RC_KDF KDF selection not allowed |
| 3038 | TPM_RC_KEY the size of the object's unique field is not consistent with the indicated |
| 3039 | size in the object's parameters |
| 3040 | TPM_RC_OBJECT_MEMORY no available object slot |
| 3041 | TPM_RC_SCHEME the signing scheme is not valid for the key |
| 3042 | TPM_RC_SENSITIVE the inPrivate did not unmarshal correctly |
| 3043 | TPM_RC_SIZE inPrivate missing, or authPolicy size for inPublic or is not valid |
| 3044 | TPM_RC_SYMMETRIC symmetric algorithm not provided when required |
| 3045 | TPM_RC_TYPE parentHandle is not a storage key, or the object to load is a storage |
| 3046 | key but its parameters do not match the parameters of the parent. |
| 3047 | TPM_RC_VALUE decryption failure |
| 3048 | |
| 3049 | 5 TPM_RC |
| 3050 | 6 TPM2_Load( |
| 3051 | 7 Load_In *in, // IN: input parameter list |
| 3052 | 8 Load_Out *out // OUT: output parameter list |
| 3053 | 9 ) |
| 3054 | 10 { |
| 3055 | 11 TPM_RC result = TPM_RC_SUCCESS; |
| 3056 | 12 TPMT_SENSITIVE sensitive; |
| 3057 | 13 TPMI_RH_HIERARCHY hierarchy; |
| 3058 | 14 OBJECT *parentObject = NULL; |
| 3059 | 15 BOOL skipChecks = FALSE; |
| 3060 | 16 |
| 3061 | 17 // Input Validation |
| 3062 | 18 if(in->inPrivate.t.size == 0) |
| 3063 | 19 return TPM_RC_SIZE + RC_Load_inPrivate; |
| 3064 | 20 |
| 3065 | 21 parentObject = ObjectGet(in->parentHandle); |
| 3066 | 22 // Is the object that is being used as the parent actually a parent. |
| 3067 | 23 if(!AreAttributesForParent(parentObject)) |
| 3068 | 24 return TPM_RC_TYPE + RC_Load_parentHandle; |
| 3069 | 25 |
| 3070 | 26 // If the parent is fixedTPM, then the attributes of the object |
| 3071 | 27 // are either "correct by construction" or were validated |
| 3072 | 28 // when the object was imported. If they pass the integrity |
| 3073 | 29 // check, then the values are valid |
| 3074 | 30 if(parentObject->publicArea.objectAttributes.fixedTPM) |
| 3075 | 31 skipChecks = TRUE; |
| 3076 | 32 else |
| 3077 | |
| 3078 | Page 56 TCG Published Family “2.0” |
| 3079 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 3080 | Trusted Platform Module Library Part 3: Commands |
| 3081 | |
| 3082 | 33 { |
| 3083 | 34 // If parent doesn't have fixedTPM SET, then this can't have |
| 3084 | 35 // fixedTPM SET. |
| 3085 | 36 if(in->inPublic.t.publicArea.objectAttributes.fixedTPM == SET) |
| 3086 | 37 return TPM_RC_ATTRIBUTES + RC_Load_inPublic; |
| 3087 | 38 |
| 3088 | 39 // Perform self check on input public area. A TPM_RC_SIZE, TPM_RC_SCHEME, |
| 3089 | 40 // TPM_RC_VALUE, TPM_RC_SYMMETRIC, TPM_RC_TYPE, TPM_RC_HASH, |
| 3090 | 41 // TPM_RC_ASYMMETRIC, TPM_RC_ATTRIBUTES or TPM_RC_KDF error may be returned |
| 3091 | 42 // at this point |
| 3092 | 43 result = PublicAttributesValidation(TRUE, in->parentHandle, |
| 3093 | 44 &in->inPublic.t.publicArea); |
| 3094 | 45 if(result != TPM_RC_SUCCESS) |
| 3095 | 46 return RcSafeAddToResult(result, RC_Load_inPublic); |
| 3096 | 47 } |
| 3097 | 48 |
| 3098 | 49 // Compute the name of object |
| 3099 | 50 ObjectComputeName(&in->inPublic.t.publicArea, &out->name); |
| 3100 | 51 |
| 3101 | 52 // Retrieve sensitive data. PrivateToSensitive() may return TPM_RC_INTEGRITY or |
| 3102 | 53 // TPM_RC_SENSITIVE |
| 3103 | 54 // errors may be returned at this point |
| 3104 | 55 result = PrivateToSensitive(&in->inPrivate, &out->name, in->parentHandle, |
| 3105 | 56 in->inPublic.t.publicArea.nameAlg, |
| 3106 | 57 &sensitive); |
| 3107 | 58 if(result != TPM_RC_SUCCESS) |
| 3108 | 59 return RcSafeAddToResult(result, RC_Load_inPrivate); |
| 3109 | 60 |
| 3110 | 61 // Internal Data Update |
| 3111 | 62 |
| 3112 | 63 // Get hierarchy of parent |
| 3113 | 64 hierarchy = ObjectGetHierarchy(in->parentHandle); |
| 3114 | 65 |
| 3115 | 66 // Create internal object. A lot of different errors may be returned by this |
| 3116 | 67 // loading operation as it will do several validations, including the public |
| 3117 | 68 // binding check |
| 3118 | 69 result = ObjectLoad(hierarchy, &in->inPublic.t.publicArea, &sensitive, |
| 3119 | 70 &out->name, in->parentHandle, skipChecks, |
| 3120 | 71 &out->objectHandle); |
| 3121 | 72 |
| 3122 | 73 if(result != TPM_RC_SUCCESS) |
| 3123 | 74 return result; |
| 3124 | 75 |
| 3125 | 76 return TPM_RC_SUCCESS; |
| 3126 | 77 } |
| 3127 | 78 #endif // CC_Load |
| 3128 | |
| 3129 | |
| 3130 | |
| 3131 | |
| 3132 | Family “2.0” TCG Published Page 57 |
| 3133 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 3134 | Part 3: Commands Trusted Platform Module Library |
| 3135 | |
| 3136 | |
| 3137 | 12.3 TPM2_LoadExternal |
| 3138 | |
| 3139 | 12.3.1 General Description |
| 3140 | |
| 3141 | This command is used to load an object that is not a Protected Object into the TPM. The command allows |
| 3142 | loading of a public area or both a public and sensitive area. |
| 3143 | |
| 3144 | NOTE 1 Typical use for loading a public area is to allow the TPM to validate an asymmetric signature. |
| 3145 | Typical use for loading both a public and sensitive area is to allow the TPM to be used as a crypto |
| 3146 | accelerator. |
| 3147 | |
| 3148 | Load of a public external object area allows the object be associated with a hierarchy so that the correct |
| 3149 | algorithms may be used when creating tickets. The hierarchy parameter provides this association. If the |
| 3150 | public and sensitive portions of the object are loaded, hierarchy is required to be TPM_RH_NULL. |
| 3151 | |
| 3152 | NOTE 2 If both the public and private portions of an object are loaded, the object is not allowed to appear to |
| 3153 | be part of a hierarchy. |
| 3154 | |
| 3155 | The object’s TPMA_OBJECT attributes will be checked according to the rules defined in |
| 3156 | “TPMA_OBJECT” in TPM 2.0 Part 2. In particular, fixedTPM, fixedParent, and restricted shall be CLEAR |
| 3157 | if inPrivate is not the Empty Buffer. |
| 3158 | |
| 3159 | NOTE 3 The duplication status of a public key needs to be able to be the same as the full key which may be |
| 3160 | resident on a different TPM. If both the public and private parts of the key are loaded , then it is not |
| 3161 | possible for the key to be either fixedTPM or fixedParent, since, its private area would not be |
| 3162 | available in the clear to load. |
| 3163 | |
| 3164 | Objects loaded using this command will have a Name. The Name is the nameAlg of the object |
| 3165 | concatenated with the digest of the public area using the nameAlg. The Qualified Name for the object will |
| 3166 | be the same as its Name. The TPM will validate that the authPolicy is either the size of the digest |
| 3167 | produced by nameAlg or the Empty Buffer. |
| 3168 | |
| 3169 | NOTE 4 If nameAlg is TPM_ALG_NULL, then the Name is the Empty Buffer. When the authorization value for |
| 3170 | an object with no Name is computed, no Name value is included in the HMAC. To ensure that these |
| 3171 | unnamed entities are not substituted, they should have an authValue that is statistically unique. |
| 3172 | |
| 3173 | NOTE 5 The digest size for TPM_ALG_NULL is zero. |
| 3174 | |
| 3175 | If the nameAlg is TPM_ALG_NULL, the TPM shall not verify the cryptographic binding between the public |
| 3176 | and sensitive areas, but the TPM will validate that the size of the key in the sensitive area is consistent |
| 3177 | with the size indicated in the public area. If it is not, the TPM shall return TPM_RC_KEY_SIZE. |
| 3178 | |
| 3179 | NOTE 6 For an ECC object, the TPM will verify that the public key is on the curve of the key before the public |
| 3180 | area is used. |
| 3181 | |
| 3182 | If nameAlg is not TPM_ALG_NULL, then the same consistency checks between inPublic and inPrivate |
| 3183 | are made as for TPM2_Load(). |
| 3184 | |
| 3185 | NOTE 7 Consistency checks are necessary because an object with a Name needs to have the public and |
| 3186 | sensitive portions cryptographically bound so that an attacker cannot mix pubic and sensitive areas. |
| 3187 | |
| 3188 | The command returns a handle for the loaded object and the Name that the TPM computed for |
| 3189 | inPublic.public (that is, the TPMT_PUBLIC structure in inPublic). |
| 3190 | |
| 3191 | NOTE 8 The TPM-computed Name is provided as a convenience to the caller for those cases where the |
| 3192 | caller does not implement the hash algorithm specified in the nameAlg of the object. |
| 3193 | |
| 3194 | |
| 3195 | |
| 3196 | |
| 3197 | Page 58 TCG Published Family “2.0” |
| 3198 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 3199 | Trusted Platform Module Library Part 3: Commands |
| 3200 | |
| 3201 | The hierarchy parameter associates the external object with a hierarchy. External objects are flushed |
| 3202 | when their associated hierarchy is disabled. If hierarchy is TPM_RH_NULL, the object is part of no |
| 3203 | hierarchy, and there is no implicit flush. |
| 3204 | If hierarchy is TPM_RH_NULL or nameAlg is TPM_ALG_NULL, a ticket produced using the object shall |
| 3205 | be a NULL Ticket. |
| 3206 | |
| 3207 | EXAMPLE If a key is loaded with hierarchy set to TPM_RH_NULL, then TPM2_VerifySignature() will produce a |
| 3208 | NULL Ticket of the required type. |
| 3209 | |
| 3210 | External objects are Temporary Objects. The saved external object contexts shall be invalidated at the |
| 3211 | next TPM Reset. |
| 3212 | |
| 3213 | |
| 3214 | |
| 3215 | |
| 3216 | Family “2.0” TCG Published Page 59 |
| 3217 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 3218 | Part 3: Commands Trusted Platform Module Library |
| 3219 | |
| 3220 | |
| 3221 | |
| 3222 | 12.3.2 Command and Response |
| 3223 | |
| 3224 | Table 23 — TPM2_LoadExternal Command |
| 3225 | Type Name Description |
| 3226 | |
| 3227 | TPM_ST_SESSIONS if an audit, encrypt, or derypt |
| 3228 | TPMI_ST_COMMAND_TAG tag session is present; otherwise, |
| 3229 | TPM_ST_NO_SESSIONS |
| 3230 | UINT32 commandSize |
| 3231 | TPM_CC commandCode TPM_CC_LoadExternal |
| 3232 | |
| 3233 | TPM2B_SENSITIVE inPrivate the sensitive portion of the object (optional) |
| 3234 | TPM2B_PUBLIC+ inPublic the public portion of the object |
| 3235 | TPMI_RH_HIERARCHY+ hierarchy hierarchy with which the object area is associated |
| 3236 | |
| 3237 | |
| 3238 | Table 24 — TPM2_LoadExternal Response |
| 3239 | Type Name Description |
| 3240 | |
| 3241 | TPM_ST tag see clause 6 |
| 3242 | UINT32 responseSize |
| 3243 | TPM_RC responseCode |
| 3244 | |
| 3245 | handle of type TPM_HT_TRANSIENT for the loaded |
| 3246 | TPM_HANDLE objectHandle |
| 3247 | object |
| 3248 | |
| 3249 | TPM2B_NAME name name of the loaded object |
| 3250 | |
| 3251 | |
| 3252 | |
| 3253 | |
| 3254 | Page 60 TCG Published Family “2.0” |
| 3255 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 3256 | Trusted Platform Module Library Part 3: Commands |
| 3257 | |
| 3258 | |
| 3259 | |
| 3260 | 12.3.3 Detailed Actions |
| 3261 | |
| 3262 | 1 #include "InternalRoutines.h" |
| 3263 | 2 #include "LoadExternal_fp.h" |
| 3264 | 3 #ifdef TPM_CC_LoadExternal // Conditional expansion of this file |
| 3265 | 4 #include "Object_spt_fp.h" |
| 3266 | |
| 3267 | |
| 3268 | Error Returns Meaning |
| 3269 | |
| 3270 | TPM_RC_ATTRIBUTES 'fixedParent" and fixedTPM must be CLEAR on on an external key if |
| 3271 | both public and sensitive portions are loaded |
| 3272 | TPM_RC_BINDING the inPublic and inPrivate structures are not cryptographically bound. |
| 3273 | TPM_RC_HASH incorrect hash selection for signing key |
| 3274 | TPM_RC_HIERARCHY hierarchy is turned off, or only NULL hierarchy is allowed when |
| 3275 | loading public and private parts of an object |
| 3276 | TPM_RC_KDF incorrect KDF selection for decrypting keyedHash object |
| 3277 | TPM_RC_KEY the size of the object's unique field is not consistent with the indicated |
| 3278 | size in the object's parameters |
| 3279 | TPM_RC_OBJECT_MEMORY if there is no free slot for an object |
| 3280 | TPM_RC_SCHEME the signing scheme is not valid for the key |
| 3281 | TPM_RC_SIZE authPolicy is not zero and is not the size of a digest produced by the |
| 3282 | object's nameAlg TPM_RH_NULL hierarchy |
| 3283 | TPM_RC_SYMMETRIC symmetric algorithm not provided when required |
| 3284 | TPM_RC_TYPE inPublic and inPrivate are not the same type |
| 3285 | |
| 3286 | 5 TPM_RC |
| 3287 | 6 TPM2_LoadExternal( |
| 3288 | 7 LoadExternal_In *in, // IN: input parameter list |
| 3289 | 8 LoadExternal_Out *out // OUT: output parameter list |
| 3290 | 9 ) |
| 3291 | 10 { |
| 3292 | 11 TPM_RC result; |
| 3293 | 12 TPMT_SENSITIVE *sensitive; |
| 3294 | 13 BOOL skipChecks; |
| 3295 | 14 |
| 3296 | 15 // Input Validation |
| 3297 | 16 |
| 3298 | 17 // If the target hierarchy is turned off, the object can not be loaded. |
| 3299 | 18 if(!HierarchyIsEnabled(in->hierarchy)) |
| 3300 | 19 return TPM_RC_HIERARCHY + RC_LoadExternal_hierarchy; |
| 3301 | 20 |
| 3302 | 21 // the size of authPolicy is either 0 or the digest size of nameAlg |
| 3303 | 22 if(in->inPublic.t.publicArea.authPolicy.t.size != 0 |
| 3304 | 23 && in->inPublic.t.publicArea.authPolicy.t.size != |
| 3305 | 24 CryptGetHashDigestSize(in->inPublic.t.publicArea.nameAlg)) |
| 3306 | 25 return TPM_RC_SIZE + RC_LoadExternal_inPublic; |
| 3307 | 26 |
| 3308 | 27 // For loading an object with both public and sensitive |
| 3309 | 28 if(in->inPrivate.t.size != 0) |
| 3310 | 29 { |
| 3311 | 30 // An external object can only be loaded at TPM_RH_NULL hierarchy |
| 3312 | 31 if(in->hierarchy != TPM_RH_NULL) |
| 3313 | 32 return TPM_RC_HIERARCHY + RC_LoadExternal_hierarchy; |
| 3314 | 33 // An external object with a sensitive area must have fixedTPM == CLEAR |
| 3315 | 34 // fixedParent == CLEAR, and must have restrict CLEAR so that it does not |
| 3316 | 35 // appear to be a key that was created by this TPM. |
| 3317 | |
| 3318 | Family “2.0” TCG Published Page 61 |
| 3319 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 3320 | Part 3: Commands Trusted Platform Module Library |
| 3321 | |
| 3322 | 36 if( in->inPublic.t.publicArea.objectAttributes.fixedTPM != CLEAR |
| 3323 | 37 || in->inPublic.t.publicArea.objectAttributes.fixedParent != CLEAR |
| 3324 | 38 || in->inPublic.t.publicArea.objectAttributes.restricted != CLEAR |
| 3325 | 39 ) |
| 3326 | 40 return TPM_RC_ATTRIBUTES + RC_LoadExternal_inPublic; |
| 3327 | 41 } |
| 3328 | 42 |
| 3329 | 43 // Validate the scheme parameters |
| 3330 | 44 result = SchemeChecks(TRUE, TPM_RH_NULL, &in->inPublic.t.publicArea); |
| 3331 | 45 if(result != TPM_RC_SUCCESS) |
| 3332 | 46 return RcSafeAddToResult(result, RC_LoadExternal_inPublic); |
| 3333 | 47 |
| 3334 | 48 // Internal Data Update |
| 3335 | 49 // Need the name to compute the qualified name |
| 3336 | 50 ObjectComputeName(&in->inPublic.t.publicArea, &out->name); |
| 3337 | 51 skipChecks = (in->inPublic.t.publicArea.nameAlg == TPM_ALG_NULL); |
| 3338 | 52 |
| 3339 | 53 // If a sensitive area was provided, load it |
| 3340 | 54 if(in->inPrivate.t.size != 0) |
| 3341 | 55 sensitive = &in->inPrivate.t.sensitiveArea; |
| 3342 | 56 else |
| 3343 | 57 sensitive = NULL; |
| 3344 | 58 |
| 3345 | 59 // Create external object. A TPM_RC_BINDING, TPM_RC_KEY, TPM_RC_OBJECT_MEMORY |
| 3346 | 60 // or TPM_RC_TYPE error may be returned by ObjectLoad() |
| 3347 | 61 result = ObjectLoad(in->hierarchy, &in->inPublic.t.publicArea, |
| 3348 | 62 sensitive, &out->name, TPM_RH_NULL, skipChecks, |
| 3349 | 63 &out->objectHandle); |
| 3350 | 64 return result; |
| 3351 | 65 } |
| 3352 | 66 #endif // CC_LoadExternal |
| 3353 | |
| 3354 | |
| 3355 | |
| 3356 | |
| 3357 | Page 62 TCG Published Family “2.0” |
| 3358 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 3359 | Trusted Platform Module Library Part 3: Commands |
| 3360 | |
| 3361 | |
| 3362 | 12.4 TPM2_ReadPublic |
| 3363 | |
| 3364 | 12.4.1 General Description |
| 3365 | |
| 3366 | This command allows access to the public area of a loaded object. |
| 3367 | Use of the objectHandle does not require authorization. |
| 3368 | |
| 3369 | NOTE Since the caller is not likely to know the public area of the object associated with objectHandle, it |
| 3370 | would not be possible to include the Name associated with objectHandle in the cpHash computation. |
| 3371 | |
| 3372 | If objectHandle references a sequence object, the TPM shall return TPM_RC_SEQUENCE. |
| 3373 | |
| 3374 | |
| 3375 | |
| 3376 | |
| 3377 | Family “2.0” TCG Published Page 63 |
| 3378 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 3379 | Part 3: Commands Trusted Platform Module Library |
| 3380 | |
| 3381 | |
| 3382 | |
| 3383 | 12.4.2 Command and Response |
| 3384 | |
| 3385 | Table 25 — TPM2_ReadPublic Command |
| 3386 | Type Name Description |
| 3387 | |
| 3388 | TPM_ST_SESSIONS if an audit or encrypt session is |
| 3389 | TPMI_ST_COMMAND_TAG tag |
| 3390 | present; otherwise, TPM_ST_NO_SESSIONS |
| 3391 | UINT32 commandSize |
| 3392 | TPM_CC commandCode TPM_CC_ReadPublic |
| 3393 | |
| 3394 | TPM handle of an object |
| 3395 | TPMI_DH_OBJECT objectHandle |
| 3396 | Auth Index: None |
| 3397 | |
| 3398 | |
| 3399 | Table 26 — TPM2_ReadPublic Response |
| 3400 | Type Name Description |
| 3401 | |
| 3402 | TPM_ST tag see clause 6 |
| 3403 | UINT32 responseSize |
| 3404 | TPM_RC responseCode |
| 3405 | |
| 3406 | TPM2B_PUBLIC outPublic structure containing the public area of an object |
| 3407 | TPM2B_NAME name name of the object |
| 3408 | TPM2B_NAME qualifiedName the Qualified Name of the object |
| 3409 | |
| 3410 | |
| 3411 | |
| 3412 | |
| 3413 | Page 64 TCG Published Family “2.0” |
| 3414 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 3415 | Trusted Platform Module Library Part 3: Commands |
| 3416 | |
| 3417 | |
| 3418 | |
| 3419 | 12.4.3 Detailed Actions |
| 3420 | |
| 3421 | 1 #include "InternalRoutines.h" |
| 3422 | 2 #include "ReadPublic_fp.h" |
| 3423 | 3 #ifdef TPM_CC_ReadPublic // Conditional expansion of this file |
| 3424 | |
| 3425 | |
| 3426 | Error Returns Meaning |
| 3427 | |
| 3428 | TPM_RC_SEQUENCE can not read the public area of a sequence object |
| 3429 | |
| 3430 | 4 TPM_RC |
| 3431 | 5 TPM2_ReadPublic( |
| 3432 | 6 ReadPublic_In *in, // IN: input parameter list |
| 3433 | 7 ReadPublic_Out *out // OUT: output parameter list |
| 3434 | 8 ) |
| 3435 | 9 { |
| 3436 | 10 OBJECT *object; |
| 3437 | 11 |
| 3438 | 12 // Input Validation |
| 3439 | 13 |
| 3440 | 14 // Get loaded object pointer |
| 3441 | 15 object = ObjectGet(in->objectHandle); |
| 3442 | 16 |
| 3443 | 17 // Can not read public area of a sequence object |
| 3444 | 18 if(ObjectIsSequence(object)) |
| 3445 | 19 return TPM_RC_SEQUENCE; |
| 3446 | 20 |
| 3447 | 21 // Command Output |
| 3448 | 22 |
| 3449 | 23 // Compute size of public area in canonical form |
| 3450 | 24 out->outPublic.t.size = TPMT_PUBLIC_Marshal(&object->publicArea, NULL, NULL); |
| 3451 | 25 |
| 3452 | 26 // Copy public area to output |
| 3453 | 27 out->outPublic.t.publicArea = object->publicArea; |
| 3454 | 28 |
| 3455 | 29 // Copy name to output |
| 3456 | 30 out->name.t.size = ObjectGetName(in->objectHandle, &out->name.t.name); |
| 3457 | 31 |
| 3458 | 32 // Copy qualified name to output |
| 3459 | 33 ObjectGetQualifiedName(in->objectHandle, &out->qualifiedName); |
| 3460 | 34 |
| 3461 | 35 return TPM_RC_SUCCESS; |
| 3462 | 36 } |
| 3463 | 37 #endif // CC_ReadPublic |
| 3464 | |
| 3465 | |
| 3466 | |
| 3467 | |
| 3468 | Family “2.0” TCG Published Page 65 |
| 3469 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 3470 | Part 3: Commands Trusted Platform Module Library |
| 3471 | |
| 3472 | |
| 3473 | 12.5 TPM2_ActivateCredential |
| 3474 | |
| 3475 | 12.5.1 General Description |
| 3476 | |
| 3477 | This command enables the association of a credential with an object in a way that ensures that the TPM |
| 3478 | has validated the parameters of the credentialed object. |
| 3479 | If both the public and private portions of activateHandle and keyHandle are not loaded, then the TPM |
| 3480 | shall return TPM_RC_AUTH_UNAVAILABLE. |
| 3481 | If keyHandle is not a Storage Key, then the TPM shall return TPM_RC_TYPE. |
| 3482 | Authorization for activateHandle requires the ADMIN role. |
| 3483 | The key associated with keyHandle is used to recover a seed from secret, which is the encrypted seed. |
| 3484 | The Name of the object associated with activateHandle and the recovered seed are used in a KDF to |
| 3485 | recover the symmetric key. The recovered seed (but not the Name) is used in a KDF to recover the |
| 3486 | HMAC key. |
| 3487 | The HMAC is used to validate that the credentialBlob is associated with activateHandle and that the data |
| 3488 | in credentialBlob has not been modified. The linkage to the object associated with activateHandle is |
| 3489 | achieved by including the Name in the HMAC calculation. |
| 3490 | If the integrity checks succeed, credentialBlob is decrypted and returned as certInfo. |
| 3491 | |
| 3492 | |
| 3493 | |
| 3494 | |
| 3495 | Page 66 TCG Published Family “2.0” |
| 3496 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 3497 | Trusted Platform Module Library Part 3: Commands |
| 3498 | |
| 3499 | |
| 3500 | |
| 3501 | 12.5.2 Command and Response |
| 3502 | |
| 3503 | Table 27 — TPM2_ActivateCredential Command |
| 3504 | Type Name Description |
| 3505 | |
| 3506 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 3507 | UINT32 commandSize |
| 3508 | TPM_CC commandCode TPM_CC_ActivateCredential |
| 3509 | |
| 3510 | handle of the object associated with certificate in |
| 3511 | credentialBlob |
| 3512 | TPMI_DH_OBJECT @activateHandle |
| 3513 | Auth Index: 1 |
| 3514 | Auth Role: ADMIN |
| 3515 | loaded key used to decrypt the TPMS_SENSITIVE in |
| 3516 | credentialBlob |
| 3517 | TPMI_DH_OBJECT @keyHandle |
| 3518 | Auth Index: 2 |
| 3519 | Auth Role: USER |
| 3520 | |
| 3521 | TPM2B_ID_OBJECT credentialBlob the credential |
| 3522 | keyHandle algorithm-dependent encrypted seed that |
| 3523 | TPM2B_ENCRYPTED_SECRET secret |
| 3524 | protects credentialBlob |
| 3525 | |
| 3526 | |
| 3527 | Table 28 — TPM2_ActivateCredential Response |
| 3528 | Type Name Description |
| 3529 | |
| 3530 | TPM_ST tag see clause 6 |
| 3531 | UINT32 responseSize |
| 3532 | TPM_RC responseCode |
| 3533 | |
| 3534 | the decrypted certificate information |
| 3535 | TPM2B_DIGEST certInfo the data should be no larger than the size of the digest |
| 3536 | of the nameAlg associated with keyHandle |
| 3537 | |
| 3538 | |
| 3539 | |
| 3540 | |
| 3541 | Family “2.0” TCG Published Page 67 |
| 3542 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 3543 | Part 3: Commands Trusted Platform Module Library |
| 3544 | |
| 3545 | |
| 3546 | |
| 3547 | 12.5.3 Detailed Actions |
| 3548 | |
| 3549 | 1 #include "InternalRoutines.h" |
| 3550 | 2 #include "ActivateCredential_fp.h" |
| 3551 | 3 #ifdef TPM_CC_ActivateCredential // Conditional expansion of this file |
| 3552 | 4 #include "Object_spt_fp.h" |
| 3553 | |
| 3554 | |
| 3555 | Error Returns Meaning |
| 3556 | |
| 3557 | TPM_RC_ATTRIBUTES keyHandle does not reference a decryption key |
| 3558 | TPM_RC_ECC_POINT secret is invalid (when keyHandle is an ECC key) |
| 3559 | TPM_RC_INSUFFICIENT secret is invalid (when keyHandle is an ECC key) |
| 3560 | TPM_RC_INTEGRITY credentialBlob fails integrity test |
| 3561 | TPM_RC_NO_RESULT secret is invalid (when keyHandle is an ECC key) |
| 3562 | TPM_RC_SIZE secret size is invalid or the credentialBlob does not unmarshal |
| 3563 | correctly |
| 3564 | TPM_RC_TYPE keyHandle does not reference an asymmetric key. |
| 3565 | TPM_RC_VALUE secret is invalid (when keyHandle is an RSA key) |
| 3566 | |
| 3567 | 5 TPM_RC |
| 3568 | 6 TPM2_ActivateCredential( |
| 3569 | 7 ActivateCredential_In *in, // IN: input parameter list |
| 3570 | 8 ActivateCredential_Out *out // OUT: output parameter list |
| 3571 | 9 ) |
| 3572 | 10 { |
| 3573 | 11 TPM_RC result = TPM_RC_SUCCESS; |
| 3574 | 12 OBJECT *object; // decrypt key |
| 3575 | 13 OBJECT *activateObject;// key associated with |
| 3576 | 14 // credential |
| 3577 | 15 TPM2B_DATA data; // credential data |
| 3578 | 16 |
| 3579 | 17 // Input Validation |
| 3580 | 18 |
| 3581 | 19 // Get decrypt key pointer |
| 3582 | 20 object = ObjectGet(in->keyHandle); |
| 3583 | 21 |
| 3584 | 22 // Get certificated object pointer |
| 3585 | 23 activateObject = ObjectGet(in->activateHandle); |
| 3586 | 24 |
| 3587 | 25 // input decrypt key must be an asymmetric, restricted decryption key |
| 3588 | 26 if( !CryptIsAsymAlgorithm(object->publicArea.type) |
| 3589 | 27 || object->publicArea.objectAttributes.decrypt == CLEAR |
| 3590 | 28 || object->publicArea.objectAttributes.restricted == CLEAR) |
| 3591 | 29 return TPM_RC_TYPE + RC_ActivateCredential_keyHandle; |
| 3592 | 30 |
| 3593 | 31 // Command output |
| 3594 | 32 |
| 3595 | 33 // Decrypt input credential data via asymmetric decryption. A |
| 3596 | 34 // TPM_RC_VALUE, TPM_RC_KEY or unmarshal errors may be returned at this |
| 3597 | 35 // point |
| 3598 | 36 result = CryptSecretDecrypt(in->keyHandle, NULL, |
| 3599 | 37 "IDENTITY", &in->secret, &data); |
| 3600 | 38 if(result != TPM_RC_SUCCESS) |
| 3601 | 39 { |
| 3602 | 40 if(result == TPM_RC_KEY) |
| 3603 | 41 return TPM_RC_FAILURE; |
| 3604 | 42 return RcSafeAddToResult(result, RC_ActivateCredential_secret); |
| 3605 | 43 } |
| 3606 | |
| 3607 | Page 68 TCG Published Family “2.0” |
| 3608 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 3609 | Trusted Platform Module Library Part 3: Commands |
| 3610 | |
| 3611 | 44 |
| 3612 | 45 // Retrieve secret data. A TPM_RC_INTEGRITY error or unmarshal |
| 3613 | 46 // errors may be returned at this point |
| 3614 | 47 result = CredentialToSecret(&in->credentialBlob, |
| 3615 | 48 &activateObject->name, |
| 3616 | 49 (TPM2B_SEED *) &data, |
| 3617 | 50 in->keyHandle, |
| 3618 | 51 &out->certInfo); |
| 3619 | 52 if(result != TPM_RC_SUCCESS) |
| 3620 | 53 return RcSafeAddToResult(result,RC_ActivateCredential_credentialBlob); |
| 3621 | 54 |
| 3622 | 55 return TPM_RC_SUCCESS; |
| 3623 | 56 } |
| 3624 | 57 #endif // CC_ActivateCredential |
| 3625 | |
| 3626 | |
| 3627 | |
| 3628 | |
| 3629 | Family “2.0” TCG Published Page 69 |
| 3630 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 3631 | Part 3: Commands Trusted Platform Module Library |
| 3632 | |
| 3633 | |
| 3634 | 12.6 TPM2_MakeCredential |
| 3635 | |
| 3636 | 12.6.1 General Description |
| 3637 | |
| 3638 | This command allows the TPM to perform the actions required of a Certificate Authority (CA) in creating a |
| 3639 | TPM2B_ID_OBJECT containing an activation credential. |
| 3640 | The TPM will produce a TPM_ID_OBJECT according to the methods in “Credential Protection” in TPM |
| 3641 | 2.0 Part 1. |
| 3642 | The loaded public area referenced by handle is required to be the public area of a Storage key, |
| 3643 | otherwise, the credential cannot be properly sealed. |
| 3644 | This command does not use any TPM secrets nor does it require authorization. It is a convenience |
| 3645 | function, using the TPM to perform cryptographic calculations that could be done externally. |
| 3646 | |
| 3647 | |
| 3648 | |
| 3649 | |
| 3650 | Page 70 TCG Published Family “2.0” |
| 3651 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 3652 | Trusted Platform Module Library Part 3: Commands |
| 3653 | |
| 3654 | |
| 3655 | |
| 3656 | 12.6.2 Command and Response |
| 3657 | |
| 3658 | Table 29 — TPM2_MakeCredential Command |
| 3659 | Type Name Description |
| 3660 | |
| 3661 | TPM_ST_SESSIONS if an audit, encrypt, or decrypt |
| 3662 | TPMI_ST_COMMAND_TAG tag session is present; otherwise, |
| 3663 | TPM_ST_NO_SESSIONS |
| 3664 | UINT32 commandSize |
| 3665 | TPM_CC commandCode TPM_CC_MakeCredential |
| 3666 | |
| 3667 | loaded public area, used to encrypt the sensitive area |
| 3668 | TPMI_DH_OBJECT handle containing the credential key |
| 3669 | Auth Index: None |
| 3670 | |
| 3671 | TPM2B_DIGEST credential the credential information |
| 3672 | TPM2B_NAME objectName Name of the object to which the credential applies |
| 3673 | |
| 3674 | |
| 3675 | Table 30 — TPM2_MakeCredential Response |
| 3676 | Type Name Description |
| 3677 | |
| 3678 | TPM_ST tag see clause 6 |
| 3679 | UINT32 responseSize |
| 3680 | TPM_RC responseCode |
| 3681 | |
| 3682 | TPM2B_ID_OBJECT credentialBlob the credential |
| 3683 | handle algorithm-dependent data that wraps the key |
| 3684 | TPM2B_ENCRYPTED_SECRET secret |
| 3685 | that encrypts credentialBlob |
| 3686 | |
| 3687 | |
| 3688 | |
| 3689 | |
| 3690 | Family “2.0” TCG Published Page 71 |
| 3691 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 3692 | Part 3: Commands Trusted Platform Module Library |
| 3693 | |
| 3694 | |
| 3695 | |
| 3696 | 12.6.3 Detailed Actions |
| 3697 | |
| 3698 | 1 #include "InternalRoutines.h" |
| 3699 | 2 #include "MakeCredential_fp.h" |
| 3700 | 3 #ifdef TPM_CC_MakeCredential // Conditional expansion of this file |
| 3701 | 4 #include "Object_spt_fp.h" |
| 3702 | |
| 3703 | |
| 3704 | Error Returns Meaning |
| 3705 | |
| 3706 | TPM_RC_KEY handle referenced an ECC key that has a unique field that is not a |
| 3707 | point on the curve of the key |
| 3708 | TPM_RC_SIZE credential is larger than the digest size of Name algorithm of handle |
| 3709 | TPM_RC_TYPE handle does not reference an asymmetric decryption key |
| 3710 | |
| 3711 | 5 TPM_RC |
| 3712 | 6 TPM2_MakeCredential( |
| 3713 | 7 MakeCredential_In *in, // IN: input parameter list |
| 3714 | 8 MakeCredential_Out *out // OUT: output parameter list |
| 3715 | 9 ) |
| 3716 | 10 { |
| 3717 | 11 TPM_RC result = TPM_RC_SUCCESS; |
| 3718 | 12 |
| 3719 | 13 OBJECT *object; |
| 3720 | 14 TPM2B_DATA data; |
| 3721 | 15 |
| 3722 | 16 // Input Validation |
| 3723 | 17 |
| 3724 | 18 // Get object pointer |
| 3725 | 19 object = ObjectGet(in->handle); |
| 3726 | 20 |
| 3727 | 21 // input key must be an asymmetric, restricted decryption key |
| 3728 | 22 // NOTE: Needs to be restricted to have a symmetric value. |
| 3729 | 23 if( !CryptIsAsymAlgorithm(object->publicArea.type) |
| 3730 | 24 || object->publicArea.objectAttributes.decrypt == CLEAR |
| 3731 | 25 || object->publicArea.objectAttributes.restricted == CLEAR |
| 3732 | 26 ) |
| 3733 | 27 return TPM_RC_TYPE + RC_MakeCredential_handle; |
| 3734 | 28 |
| 3735 | 29 // The credential information may not be larger than the digest size used for |
| 3736 | 30 // the Name of the key associated with handle. |
| 3737 | 31 if(in->credential.t.size > CryptGetHashDigestSize(object->publicArea.nameAlg)) |
| 3738 | 32 return TPM_RC_SIZE + RC_MakeCredential_credential; |
| 3739 | 33 |
| 3740 | 34 // Command Output |
| 3741 | 35 |
| 3742 | 36 // Make encrypt key and its associated secret structure. |
| 3743 | 37 // Even though CrypeSecretEncrypt() may return |
| 3744 | 38 out->secret.t.size = sizeof(out->secret.t.secret); |
| 3745 | 39 result = CryptSecretEncrypt(in->handle, "IDENTITY", &data, &out->secret); |
| 3746 | 40 if(result != TPM_RC_SUCCESS) |
| 3747 | 41 return result; |
| 3748 | 42 |
| 3749 | 43 // Prepare output credential data from secret |
| 3750 | 44 SecretToCredential(&in->credential, &in->objectName, (TPM2B_SEED *) &data, |
| 3751 | 45 in->handle, &out->credentialBlob); |
| 3752 | 46 |
| 3753 | 47 return TPM_RC_SUCCESS; |
| 3754 | 48 } |
| 3755 | 49 #endif // CC_MakeCredential |
| 3756 | |
| 3757 | |
| 3758 | |
| 3759 | |
| 3760 | Page 72 TCG Published Family “2.0” |
| 3761 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 3762 | Trusted Platform Module Library Part 3: Commands |
| 3763 | |
| 3764 | |
| 3765 | 12.7 TPM2_Unseal |
| 3766 | |
| 3767 | 12.7.1 General Description |
| 3768 | |
| 3769 | This command returns the data in a loaded Sealed Data Object. |
| 3770 | |
| 3771 | NOTE A random, TPM-generated, Sealed Data Object may be created by the TPM with TPM2_Create() or |
| 3772 | TPM2_CreatePrimary() using the template for a Sealed Data Object. |
| 3773 | |
| 3774 | The returned value may be encrypted using authorization session encryption. |
| 3775 | If either restricted, decrypt, or sign is SET in the attributes of itemHandle, then the TPM shall return |
| 3776 | TPM_RC_ATTRIBUTES. If the type of itemHandle is not TPM_ALG_KEYEDHASH, then the TPM shall |
| 3777 | return TPM_RC_TYPE. |
| 3778 | |
| 3779 | |
| 3780 | |
| 3781 | |
| 3782 | Family “2.0” TCG Published Page 73 |
| 3783 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 3784 | Part 3: Commands Trusted Platform Module Library |
| 3785 | |
| 3786 | |
| 3787 | |
| 3788 | 12.7.2 Command and Response |
| 3789 | |
| 3790 | Table 31 — TPM2_Unseal Command |
| 3791 | Type Name Description |
| 3792 | |
| 3793 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 3794 | UINT32 commandSize |
| 3795 | TPM_CC commandCode TPM_CC_Unseal |
| 3796 | |
| 3797 | handle of a loaded data object |
| 3798 | TPMI_DH_OBJECT @itemHandle Auth Index: 1 |
| 3799 | Auth Role: USER |
| 3800 | |
| 3801 | |
| 3802 | Table 32 — TPM2_Unseal Response |
| 3803 | Type Name Description |
| 3804 | |
| 3805 | TPM_ST tag see clause 6 |
| 3806 | UINT32 responseSize |
| 3807 | TPM_RC responseCode |
| 3808 | |
| 3809 | unsealed data |
| 3810 | TPM2B_SENSITIVE_DATA outData |
| 3811 | Size of outData is limited to be no more than 128 octets. |
| 3812 | |
| 3813 | |
| 3814 | |
| 3815 | |
| 3816 | Page 74 TCG Published Family “2.0” |
| 3817 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 3818 | Trusted Platform Module Library Part 3: Commands |
| 3819 | |
| 3820 | |
| 3821 | |
| 3822 | 12.7.3 Detailed Actions |
| 3823 | |
| 3824 | 1 #include "InternalRoutines.h" |
| 3825 | 2 #include "Unseal_fp.h" |
| 3826 | 3 #ifdef TPM_CC_Unseal // Conditional expansion of this file |
| 3827 | |
| 3828 | |
| 3829 | Error Returns Meaning |
| 3830 | |
| 3831 | TPM_RC_ATTRIBUTES itemHandle has wrong attributes |
| 3832 | TPM_RC_TYPE itemHandle is not a KEYEDHASH data object |
| 3833 | |
| 3834 | 4 TPM_RC |
| 3835 | 5 TPM2_Unseal( |
| 3836 | 6 Unseal_In *in, |
| 3837 | 7 Unseal_Out *out |
| 3838 | 8 ) |
| 3839 | 9 { |
| 3840 | 10 OBJECT *object; |
| 3841 | 11 |
| 3842 | 12 // Input Validation |
| 3843 | 13 |
| 3844 | 14 // Get pointer to loaded object |
| 3845 | 15 object = ObjectGet(in->itemHandle); |
| 3846 | 16 |
| 3847 | 17 // Input handle must be a data object |
| 3848 | 18 if(object->publicArea.type != TPM_ALG_KEYEDHASH) |
| 3849 | 19 return TPM_RC_TYPE + RC_Unseal_itemHandle; |
| 3850 | 20 if( object->publicArea.objectAttributes.decrypt == SET |
| 3851 | 21 || object->publicArea.objectAttributes.sign == SET |
| 3852 | 22 || object->publicArea.objectAttributes.restricted == SET) |
| 3853 | 23 return TPM_RC_ATTRIBUTES + RC_Unseal_itemHandle; |
| 3854 | 24 |
| 3855 | 25 // Command Output |
| 3856 | 26 |
| 3857 | 27 // Copy data |
| 3858 | 28 MemoryCopy2B(&out->outData.b, &object->sensitive.sensitive.bits.b, |
| 3859 | 29 sizeof(out->outData.t.buffer)); |
| 3860 | 30 |
| 3861 | 31 return TPM_RC_SUCCESS; |
| 3862 | 32 } |
| 3863 | 33 #endif // CC_Unseal |
| 3864 | |
| 3865 | |
| 3866 | |
| 3867 | |
| 3868 | Family “2.0” TCG Published Page 75 |
| 3869 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 3870 | Part 3: Commands Trusted Platform Module Library |
| 3871 | |
| 3872 | |
| 3873 | 12.8 TPM2_ObjectChangeAuth |
| 3874 | |
| 3875 | 12.8.1 General Description |
| 3876 | |
| 3877 | This command is used to change the authorization secret for a TPM-resident object. |
| 3878 | If successful, a new private area for the TPM-resident object associated with objectHandle is returned, |
| 3879 | which includes the new authorization value. |
| 3880 | This command does not change the authorization of the TPM-resident object on which it operates. |
| 3881 | Therefore, the old authValue (of the TPM-resident object) is used when generating the response HMAC |
| 3882 | key if required. |
| 3883 | |
| 3884 | NOTE 1 The returned outPrivate will need to be loaded before the new authorization will apply. |
| 3885 | |
| 3886 | NOTE 2 The TPM-resident object may be persistent and changing the authorization value of the persistent |
| 3887 | object could prevent other users from accessing the object. This is why this command does not |
| 3888 | change the TPM-resident object. |
| 3889 | |
| 3890 | EXAMPLE If a persistent key is being used as a Storage Root Key and the authorization of the key is a well - |
| 3891 | known value so that the key can be used generally, then changing the authorization value in the |
| 3892 | persistent key would deny access to other users. |
| 3893 | |
| 3894 | This command may not be used to change the authorization value for an NV Index or a Primary Object. |
| 3895 | |
| 3896 | NOTE 3 If an NV Index is to have a new authorization, it is done with TPM2_NV_ChangeAuth(). |
| 3897 | |
| 3898 | NOTE 4 If a Primary Object is to have a new authorization, it needs to be recreated (TPM2_CreatePrimary()). |
| 3899 | |
| 3900 | |
| 3901 | |
| 3902 | |
| 3903 | Page 76 TCG Published Family “2.0” |
| 3904 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 3905 | Trusted Platform Module Library Part 3: Commands |
| 3906 | |
| 3907 | |
| 3908 | 12.8.2 Command and Response |
| 3909 | |
| 3910 | Table 33 — TPM2_ObjectChangeAuth Command |
| 3911 | Type Name Description |
| 3912 | |
| 3913 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 3914 | UINT32 commandSize |
| 3915 | TPM_CC commandCode TPM_CC_ObjectChangeAuth |
| 3916 | |
| 3917 | handle of the object |
| 3918 | TPMI_DH_OBJECT @objectHandle Auth Index: 1 |
| 3919 | Auth Role: ADMIN |
| 3920 | handle of the parent |
| 3921 | TPMI_DH_OBJECT parentHandle |
| 3922 | Auth Index: None |
| 3923 | |
| 3924 | TPM2B_AUTH newAuth new authorization value |
| 3925 | |
| 3926 | |
| 3927 | Table 34 — TPM2_ObjectChangeAuth Response |
| 3928 | Type Name Description |
| 3929 | |
| 3930 | TPM_ST tag see clause 6 |
| 3931 | UINT32 responseSize |
| 3932 | TPM_RC responseCode |
| 3933 | |
| 3934 | TPM2B_PRIVATE outPrivate private area containing the new authorization value |
| 3935 | |
| 3936 | |
| 3937 | |
| 3938 | |
| 3939 | Family “2.0” TCG Published Page 77 |
| 3940 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 3941 | Part 3: Commands Trusted Platform Module Library |
| 3942 | |
| 3943 | |
| 3944 | |
| 3945 | 12.8.3 Detailed Actions |
| 3946 | |
| 3947 | 1 #include "InternalRoutines.h" |
| 3948 | 2 #include "ObjectChangeAuth_fp.h" |
| 3949 | 3 #ifdef TPM_CC_ObjectChangeAuth // Conditional expansion of this file |
| 3950 | 4 #include "Object_spt_fp.h" |
| 3951 | |
| 3952 | |
| 3953 | Error Returns Meaning |
| 3954 | |
| 3955 | TPM_RC_SIZE newAuth is larger than the size of the digest of the Name algorithm of |
| 3956 | objectHandle |
| 3957 | TPM_RC_TYPE the key referenced by parentHandle is not the parent of the object |
| 3958 | referenced by objectHandle; or objectHandle is a sequence object. |
| 3959 | |
| 3960 | 5 TPM_RC |
| 3961 | 6 TPM2_ObjectChangeAuth( |
| 3962 | 7 ObjectChangeAuth_In *in, // IN: input parameter list |
| 3963 | 8 ObjectChangeAuth_Out *out // OUT: output parameter list |
| 3964 | 9 ) |
| 3965 | 10 { |
| 3966 | 11 TPMT_SENSITIVE sensitive; |
| 3967 | 12 |
| 3968 | 13 OBJECT *object; |
| 3969 | 14 TPM2B_NAME objectQN, QNCompare; |
| 3970 | 15 TPM2B_NAME parentQN; |
| 3971 | 16 |
| 3972 | 17 // Input Validation |
| 3973 | 18 |
| 3974 | 19 // Get object pointer |
| 3975 | 20 object = ObjectGet(in->objectHandle); |
| 3976 | 21 |
| 3977 | 22 // Can not change auth on sequence object |
| 3978 | 23 if(ObjectIsSequence(object)) |
| 3979 | 24 return TPM_RC_TYPE + RC_ObjectChangeAuth_objectHandle; |
| 3980 | 25 |
| 3981 | 26 // Make sure that the auth value is consistent with the nameAlg |
| 3982 | 27 if( MemoryRemoveTrailingZeros(&in->newAuth) |
| 3983 | 28 > CryptGetHashDigestSize(object->publicArea.nameAlg)) |
| 3984 | 29 return TPM_RC_SIZE + RC_ObjectChangeAuth_newAuth; |
| 3985 | 30 |
| 3986 | 31 // Check parent for object |
| 3987 | 32 // parent handle must be the parent of object handle. In this |
| 3988 | 33 // implementation we verify this by checking the QN of object. Other |
| 3989 | 34 // implementation may choose different method to verify this attribute. |
| 3990 | 35 ObjectGetQualifiedName(in->parentHandle, &parentQN); |
| 3991 | 36 ObjectComputeQualifiedName(&parentQN, object->publicArea.nameAlg, |
| 3992 | 37 &object->name, &QNCompare); |
| 3993 | 38 |
| 3994 | 39 ObjectGetQualifiedName(in->objectHandle, &objectQN); |
| 3995 | 40 if(!Memory2BEqual(&objectQN.b, &QNCompare.b)) |
| 3996 | 41 return TPM_RC_TYPE + RC_ObjectChangeAuth_parentHandle; |
| 3997 | 42 |
| 3998 | 43 // Command Output |
| 3999 | 44 |
| 4000 | 45 // Copy internal sensitive area |
| 4001 | 46 sensitive = object->sensitive; |
| 4002 | 47 // Copy authValue |
| 4003 | 48 sensitive.authValue = in->newAuth; |
| 4004 | 49 |
| 4005 | 50 // Prepare output private data from sensitive |
| 4006 | 51 SensitiveToPrivate(&sensitive, &object->name, in->parentHandle, |
| 4007 | 52 object->publicArea.nameAlg, |
| 4008 | |
| 4009 | Page 78 TCG Published Family “2.0” |
| 4010 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 4011 | Trusted Platform Module Library Part 3: Commands |
| 4012 | |
| 4013 | 53 &out->outPrivate); |
| 4014 | 54 |
| 4015 | 55 return TPM_RC_SUCCESS; |
| 4016 | 56 } |
| 4017 | 57 #endif // CC_ObjectChangeAuth |
| 4018 | |
| 4019 | |
| 4020 | |
| 4021 | |
| 4022 | Family “2.0” TCG Published Page 79 |
| 4023 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 4024 | Part 3: Commands Trusted Platform Module Library |
| 4025 | |
| 4026 | |
| 4027 | 13 Duplication Commands |
| 4028 | |
| 4029 | 13.1 TPM2_Duplicate |
| 4030 | |
| 4031 | 13.1.1 General Description |
| 4032 | |
| 4033 | This command duplicates a loaded object so that it may be used in a different hierarchy. The new parent |
| 4034 | key for the duplicate may be on the same or different TPM or TPM_RH_NULL. Only the public area of |
| 4035 | newParentHandle is required to be loaded. |
| 4036 | |
| 4037 | NOTE 1 Since the new parent may only be extant on a different TPM, it is likely that the new parent’s |
| 4038 | sensitive area could not be loaded in the TPM from which objectHandle is being duplicated. |
| 4039 | |
| 4040 | If encryptedDuplication is SET in the object being duplicated, then the TPM shall return |
| 4041 | TPM_RC_SYMMETRIC if symmetricAlg is TPM_RH_NULL or TPM_RC_HIERARCHY if |
| 4042 | newParentHandle is TPM_RH_NULL. |
| 4043 | The authorization for this command shall be with a policy session. |
| 4044 | If fixedParent of objectHandle→attributes is SET, the TPM shall return TPM_RC_ATTRIBUTES. If |
| 4045 | objectHandle→nameAlg is TPM_ALG_NULL, the TPM shall return TPM_RC_TYPE. |
| 4046 | The policySession→commandCode parameter in the policy session is required to be TPM_CC_Duplicate |
| 4047 | to indicate that authorization for duplication has been provided. This indicates that the policy that is being |
| 4048 | used is a policy that is for duplication, and not a policy that would approve another use. That is, authority |
| 4049 | to use an object does not grant authority to duplicate the object. |
| 4050 | The policy is likely to include cpHash in order to restrict where duplication can occur. If |
| 4051 | TPM2_PolicyCpHash() has been executed as part of the policy, the policySession→cpHash is compared |
| 4052 | to the cpHash of the command. |
| 4053 | If TPM2_PolicyDuplicationSelect() has been executed as part of the policy, the |
| 4054 | policySession→nameHash is compared to |
| 4055 | HpolicyAlg(objectHandle→Name || newParentHandle→Name) (2) |
| 4056 | If the compared hashes are not the same, then the TPM shall return TPM_RC_POLICY_FAIL. |
| 4057 | |
| 4058 | NOTE 2 It is allowed that policySesion→nameHash and policySession→cpHash share the same memory |
| 4059 | space. |
| 4060 | |
| 4061 | NOTE 3 A duplication policy is not required to have either TPM2_PolicyDuplicationSelect() or |
| 4062 | TPM2_PolicyCpHash() as part of the policy. If neither is present, then the duplication policy may be |
| 4063 | satisfied with a policy that only contains TPM2_PolicyComman dCode(code = TPM_CC_Duplicate). |
| 4064 | |
| 4065 | The TPM shall follow the process of encryption defined in the “Duplication” subclause of “Protected |
| 4066 | Storage Hierarchy” in TPM 2.0 Part 1. |
| 4067 | |
| 4068 | |
| 4069 | |
| 4070 | |
| 4071 | Page 80 TCG Published Family “2.0” |
| 4072 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 4073 | Trusted Platform Module Library Part 3: Commands |
| 4074 | |
| 4075 | |
| 4076 | |
| 4077 | 13.1.2 Command and Response |
| 4078 | |
| 4079 | Table 35 — TPM2_Duplicate Command |
| 4080 | Type Name Description |
| 4081 | |
| 4082 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 4083 | UINT32 commandSize |
| 4084 | TPM_CC commandCode TPM_CC_Duplicate |
| 4085 | |
| 4086 | loaded object to duplicate |
| 4087 | TPMI_DH_OBJECT @objectHandle Auth Index: 1 |
| 4088 | Auth Role: DUP |
| 4089 | shall reference the public area of an asymmetric key |
| 4090 | TPMI_DH_OBJECT+ newParentHandle |
| 4091 | Auth Index: None |
| 4092 | |
| 4093 | optional symmetric encryption key |
| 4094 | TPM2B_DATA encryptionKeyIn The size for this key is set to zero when the TPM is to |
| 4095 | generate the key. This parameter may be encrypted. |
| 4096 | definition for the symmetric algorithm to be used for the |
| 4097 | TPMT_SYM_DEF_OBJECT+ symmetricAlg inner wrapper |
| 4098 | may be TPM_ALG_NULL if no inner wrapper is applied |
| 4099 | |
| 4100 | |
| 4101 | Table 36 — TPM2_Duplicate Response |
| 4102 | Type Name Description |
| 4103 | |
| 4104 | TPM_ST tag see clause 6 |
| 4105 | UINT32 responseSize |
| 4106 | TPM_RC responseCode |
| 4107 | |
| 4108 | If the caller provided an encryption key or if |
| 4109 | symmetricAlg was TPM_ALG_NULL, then this will be |
| 4110 | TPM2B_DATA encryptionKeyOut the Empty Buffer; otherwise, it shall contain the TPM- |
| 4111 | generated, symmetric encryption key for the inner |
| 4112 | wrapper. |
| 4113 | private area that may be encrypted by encryptionKeyIn; |
| 4114 | TPM2B_PRIVATE duplicate |
| 4115 | and may be doubly encrypted |
| 4116 | seed protected by the asymmetric algorithms of new |
| 4117 | TPM2B_ENCRYPTED_SECRET outSymSeed |
| 4118 | parent (NP) |
| 4119 | |
| 4120 | |
| 4121 | |
| 4122 | |
| 4123 | Family “2.0” TCG Published Page 81 |
| 4124 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 4125 | Part 3: Commands Trusted Platform Module Library |
| 4126 | |
| 4127 | |
| 4128 | |
| 4129 | 13.1.3 Detailed Actions |
| 4130 | |
| 4131 | 1 #include "InternalRoutines.h" |
| 4132 | 2 #include "Duplicate_fp.h" |
| 4133 | 3 #ifdef TPM_CC_Duplicate // Conditional expansion of this file |
| 4134 | 4 #include "Object_spt_fp.h" |
| 4135 | |
| 4136 | |
| 4137 | Error Returns Meaning |
| 4138 | |
| 4139 | TPM_RC_ATTRIBUTES key to duplicate has fixedParent SET |
| 4140 | TPM_RC_HIERARCHY encryptedDuplication is SET and newParentHandle specifies Null |
| 4141 | Hierarchy |
| 4142 | TPM_RC_KEY newParentHandle references invalid ECC key (public point not on the |
| 4143 | curve) |
| 4144 | TPM_RC_SIZE input encryption key size does not match the size specified in |
| 4145 | symmetric algorithm |
| 4146 | TPM_RC_SYMMETRIC encryptedDuplication is SET but no symmetric algorithm is provided |
| 4147 | TPM_RC_TYPE newParentHandle is neither a storage key nor TPM_RH_NULL; or |
| 4148 | the object has a NULL nameAlg |
| 4149 | |
| 4150 | 5 TPM_RC |
| 4151 | 6 TPM2_Duplicate( |
| 4152 | 7 Duplicate_In *in, // IN: input parameter list |
| 4153 | 8 Duplicate_Out *out // OUT: output parameter list |
| 4154 | 9 ) |
| 4155 | 10 { |
| 4156 | 11 TPM_RC result = TPM_RC_SUCCESS; |
| 4157 | 12 TPMT_SENSITIVE sensitive; |
| 4158 | 13 |
| 4159 | 14 UINT16 innerKeySize = 0; // encrypt key size for inner wrap |
| 4160 | 15 |
| 4161 | 16 OBJECT *object; |
| 4162 | 17 TPM2B_DATA data; |
| 4163 | 18 |
| 4164 | 19 // Input Validation |
| 4165 | 20 |
| 4166 | 21 // Get duplicate object pointer |
| 4167 | 22 object = ObjectGet(in->objectHandle); |
| 4168 | 23 |
| 4169 | 24 // duplicate key must have fixParent bit CLEAR. |
| 4170 | 25 if(object->publicArea.objectAttributes.fixedParent == SET) |
| 4171 | 26 return TPM_RC_ATTRIBUTES + RC_Duplicate_objectHandle; |
| 4172 | 27 |
| 4173 | 28 // Do not duplicate object with NULL nameAlg |
| 4174 | 29 if(object->publicArea.nameAlg == TPM_ALG_NULL) |
| 4175 | 30 return TPM_RC_TYPE + RC_Duplicate_objectHandle; |
| 4176 | 31 |
| 4177 | 32 // new parent key must be a storage object or TPM_RH_NULL |
| 4178 | 33 if(in->newParentHandle != TPM_RH_NULL |
| 4179 | 34 && !ObjectIsStorage(in->newParentHandle)) |
| 4180 | 35 return TPM_RC_TYPE + RC_Duplicate_newParentHandle; |
| 4181 | 36 |
| 4182 | 37 // If the duplicates object has encryptedDuplication SET, then there must be |
| 4183 | 38 // an inner wrapper and the new parent may not be TPM_RH_NULL |
| 4184 | 39 if(object->publicArea.objectAttributes.encryptedDuplication == SET) |
| 4185 | 40 { |
| 4186 | 41 if(in->symmetricAlg.algorithm == TPM_ALG_NULL) |
| 4187 | 42 return TPM_RC_SYMMETRIC + RC_Duplicate_symmetricAlg; |
| 4188 | 43 if(in->newParentHandle == TPM_RH_NULL) |
| 4189 | |
| 4190 | Page 82 TCG Published Family “2.0” |
| 4191 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 4192 | Trusted Platform Module Library Part 3: Commands |
| 4193 | |
| 4194 | 44 return TPM_RC_HIERARCHY + RC_Duplicate_newParentHandle; |
| 4195 | 45 } |
| 4196 | 46 |
| 4197 | 47 if(in->symmetricAlg.algorithm == TPM_ALG_NULL) |
| 4198 | 48 { |
| 4199 | 49 // if algorithm is TPM_ALG_NULL, input key size must be 0 |
| 4200 | 50 if(in->encryptionKeyIn.t.size != 0) |
| 4201 | 51 return TPM_RC_SIZE + RC_Duplicate_encryptionKeyIn; |
| 4202 | 52 } |
| 4203 | 53 else |
| 4204 | 54 { |
| 4205 | 55 // Get inner wrap key size |
| 4206 | 56 innerKeySize = in->symmetricAlg.keyBits.sym; |
| 4207 | 57 |
| 4208 | 58 // If provided the input symmetric key must match the size of the algorithm |
| 4209 | 59 if(in->encryptionKeyIn.t.size != 0 |
| 4210 | 60 && in->encryptionKeyIn.t.size != (innerKeySize + 7) / 8) |
| 4211 | 61 return TPM_RC_SIZE + RC_Duplicate_encryptionKeyIn; |
| 4212 | 62 } |
| 4213 | 63 |
| 4214 | 64 // Command Output |
| 4215 | 65 |
| 4216 | 66 if(in->newParentHandle != TPM_RH_NULL) |
| 4217 | 67 { |
| 4218 | 68 |
| 4219 | 69 // Make encrypt key and its associated secret structure. A TPM_RC_KEY |
| 4220 | 70 // error may be returned at this point |
| 4221 | 71 out->outSymSeed.t.size = sizeof(out->outSymSeed.t.secret); |
| 4222 | 72 result = CryptSecretEncrypt(in->newParentHandle, |
| 4223 | 73 "DUPLICATE", &data, &out->outSymSeed); |
| 4224 | 74 pAssert(result != TPM_RC_VALUE); |
| 4225 | 75 if(result != TPM_RC_SUCCESS) |
| 4226 | 76 return result; |
| 4227 | 77 } |
| 4228 | 78 else |
| 4229 | 79 { |
| 4230 | 80 // Do not apply outer wrapper |
| 4231 | 81 data.t.size = 0; |
| 4232 | 82 out->outSymSeed.t.size = 0; |
| 4233 | 83 } |
| 4234 | 84 |
| 4235 | 85 // Copy sensitive area |
| 4236 | 86 sensitive = object->sensitive; |
| 4237 | 87 |
| 4238 | 88 // Prepare output private data from sensitive |
| 4239 | 89 SensitiveToDuplicate(&sensitive, &object->name, in->newParentHandle, |
| 4240 | 90 object->publicArea.nameAlg, (TPM2B_SEED *) &data, |
| 4241 | 91 &in->symmetricAlg, &in->encryptionKeyIn, |
| 4242 | 92 &out->duplicate); |
| 4243 | 93 |
| 4244 | 94 out->encryptionKeyOut = in->encryptionKeyIn; |
| 4245 | 95 |
| 4246 | 96 return TPM_RC_SUCCESS; |
| 4247 | 97 } |
| 4248 | 98 #endif // CC_Duplicate |
| 4249 | |
| 4250 | |
| 4251 | |
| 4252 | |
| 4253 | Family “2.0” TCG Published Page 83 |
| 4254 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 4255 | Part 3: Commands Trusted Platform Module Library |
| 4256 | |
| 4257 | |
| 4258 | 13.2 TPM2_Rewrap |
| 4259 | |
| 4260 | 13.2.1 General Description |
| 4261 | |
| 4262 | This command allows the TPM to serve in the role as a Duplication Authority. If proper authorization for |
| 4263 | use of the oldParent is provided, then an HMAC key and a symmetric key are recovered from inSymSeed |
| 4264 | and used to integrity check and decrypt inDuplicate. A new protection seed value is generated according |
| 4265 | to the methods appropriate for newParent and the blob is re-encrypted and a new integrity value is |
| 4266 | computed. The re-encrypted blob is returned in outDuplicate and the symmetric key returned in |
| 4267 | outSymKey. |
| 4268 | In the rewrap process, L is “DUPLICATE” (see “Terms and Definitions” in TPM 2.0 Part 1). |
| 4269 | If inSymSeed has a zero length, then oldParent is required to be TPM_RH_NULL and no decryption of |
| 4270 | inDuplicate takes place. |
| 4271 | If newParent is TPM_RH_NULL, then no encryption is performed on outDuplicate. outSymSeed will have |
| 4272 | a zero length. See TPM 2.0 Part 2 encryptedDuplication. |
| 4273 | |
| 4274 | |
| 4275 | |
| 4276 | |
| 4277 | Page 84 TCG Published Family “2.0” |
| 4278 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 4279 | Trusted Platform Module Library Part 3: Commands |
| 4280 | |
| 4281 | |
| 4282 | |
| 4283 | 13.2.2 Command and Response |
| 4284 | |
| 4285 | Table 37 — TPM2_Rewrap Command |
| 4286 | Type Name Description |
| 4287 | |
| 4288 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 4289 | UINT32 commandSize |
| 4290 | TPM_CC commandCode TPM_CC_Rewrap |
| 4291 | |
| 4292 | parent of object |
| 4293 | TPMI_DH_OBJECT+ @oldParent Auth Index: 1 |
| 4294 | Auth Role: User |
| 4295 | new parent of the object |
| 4296 | TPMI_DH_OBJECT+ newParent |
| 4297 | Auth Index: None |
| 4298 | |
| 4299 | an object encrypted using symmetric key derived from |
| 4300 | TPM2B_PRIVATE inDuplicate |
| 4301 | inSymSeed |
| 4302 | TPM2B_NAME name the Name of the object being rewrapped |
| 4303 | seed for symmetric key |
| 4304 | TPM2B_ENCRYPTED_SECRET inSymSeed needs oldParent private key to recover the seed and |
| 4305 | generate the symmetric key |
| 4306 | |
| 4307 | |
| 4308 | Table 38 — TPM2_Rewrap Response |
| 4309 | Type Name Description |
| 4310 | |
| 4311 | TPM_ST tag see clause 6 |
| 4312 | UINT32 responseSize |
| 4313 | TPM_RC responseCode |
| 4314 | |
| 4315 | an object encrypted using symmetric key derived from |
| 4316 | TPM2B_PRIVATE outDuplicate |
| 4317 | outSymSeed |
| 4318 | seed for a symmetric key protected by newParent |
| 4319 | TPM2B_ENCRYPTED_SECRET outSymSeed |
| 4320 | asymmetric key |
| 4321 | |
| 4322 | |
| 4323 | |
| 4324 | |
| 4325 | Family “2.0” TCG Published Page 85 |
| 4326 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 4327 | Part 3: Commands Trusted Platform Module Library |
| 4328 | |
| 4329 | |
| 4330 | |
| 4331 | 13.2.3 Detailed Actions |
| 4332 | |
| 4333 | 1 #include "InternalRoutines.h" |
| 4334 | 2 #include "Rewrap_fp.h" |
| 4335 | 3 #ifdef TPM_CC_Rewrap // Conditional expansion of this file |
| 4336 | 4 #include "Object_spt_fp.h" |
| 4337 | |
| 4338 | |
| 4339 | Error Returns Meaning |
| 4340 | |
| 4341 | TPM_RC_ATTRIBUTES newParent is not a decryption key |
| 4342 | TPM_RC_HANDLE oldParent does not consistent with inSymSeed |
| 4343 | TPM_RC_INTEGRITY the integrity check of inDuplicate failed |
| 4344 | TPM_RC_KEY for an ECC key, the public key is not on the curve of the curve ID |
| 4345 | TPM_RC_KEY_SIZE the decrypted input symmetric key size does not matches the |
| 4346 | symmetric algorithm key size of oldParent |
| 4347 | TPM_RC_TYPE oldParent is not a storage key, or 'newParent is not a storage key |
| 4348 | TPM_RC_VALUE for an 'oldParent; RSA key, the data to be decrypted is greater than |
| 4349 | the public exponent |
| 4350 | Unmarshal errors errors during unmarshaling the input encrypted buffer to a ECC public |
| 4351 | key, or unmarshal the private buffer to sensitive |
| 4352 | |
| 4353 | 5 TPM_RC |
| 4354 | 6 TPM2_Rewrap( |
| 4355 | 7 Rewrap_In *in, // IN: input parameter list |
| 4356 | 8 Rewrap_Out *out // OUT: output parameter list |
| 4357 | 9 ) |
| 4358 | 10 { |
| 4359 | 11 TPM_RC result = TPM_RC_SUCCESS; |
| 4360 | 12 OBJECT *oldParent; |
| 4361 | 13 TPM2B_DATA data; // symmetric key |
| 4362 | 14 UINT16 hashSize = 0; |
| 4363 | 15 TPM2B_PRIVATE privateBlob; // A temporary private blob |
| 4364 | 16 // to transit between old |
| 4365 | 17 // and new wrappers |
| 4366 | 18 |
| 4367 | 19 // Input Validation |
| 4368 | 20 |
| 4369 | 21 if((in->inSymSeed.t.size == 0 && in->oldParent != TPM_RH_NULL) |
| 4370 | 22 || (in->inSymSeed.t.size != 0 && in->oldParent == TPM_RH_NULL)) |
| 4371 | 23 return TPM_RC_HANDLE + RC_Rewrap_oldParent; |
| 4372 | 24 |
| 4373 | 25 if(in->oldParent != TPM_RH_NULL) |
| 4374 | 26 { |
| 4375 | 27 // Get old parent pointer |
| 4376 | 28 oldParent = ObjectGet(in->oldParent); |
| 4377 | 29 |
| 4378 | 30 // old parent key must be a storage object |
| 4379 | 31 if(!ObjectIsStorage(in->oldParent)) |
| 4380 | 32 return TPM_RC_TYPE + RC_Rewrap_oldParent; |
| 4381 | 33 |
| 4382 | 34 // Decrypt input secret data via asymmetric decryption. A |
| 4383 | 35 // TPM_RC_VALUE, TPM_RC_KEY or unmarshal errors may be returned at this |
| 4384 | 36 // point |
| 4385 | 37 result = CryptSecretDecrypt(in->oldParent, NULL, |
| 4386 | 38 "DUPLICATE", &in->inSymSeed, &data); |
| 4387 | 39 if(result != TPM_RC_SUCCESS) |
| 4388 | 40 return TPM_RC_VALUE + RC_Rewrap_inSymSeed; |
| 4389 | 41 |
| 4390 | |
| 4391 | Page 86 TCG Published Family “2.0” |
| 4392 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 4393 | Trusted Platform Module Library Part 3: Commands |
| 4394 | |
| 4395 | 42 // Unwrap Outer |
| 4396 | 43 result = UnwrapOuter(in->oldParent, &in->name, |
| 4397 | 44 oldParent->publicArea.nameAlg, (TPM2B_SEED *) &data, |
| 4398 | 45 FALSE, |
| 4399 | 46 in->inDuplicate.t.size, in->inDuplicate.t.buffer); |
| 4400 | 47 if(result != TPM_RC_SUCCESS) |
| 4401 | 48 return RcSafeAddToResult(result, RC_Rewrap_inDuplicate); |
| 4402 | 49 |
| 4403 | 50 // Copy unwrapped data to temporary variable, remove the integrity field |
| 4404 | 51 hashSize = sizeof(UINT16) + |
| 4405 | 52 CryptGetHashDigestSize(oldParent->publicArea.nameAlg); |
| 4406 | 53 privateBlob.t.size = in->inDuplicate.t.size - hashSize; |
| 4407 | 54 MemoryCopy(privateBlob.t.buffer, in->inDuplicate.t.buffer + hashSize, |
| 4408 | 55 privateBlob.t.size, sizeof(privateBlob.t.buffer)); |
| 4409 | 56 } |
| 4410 | 57 else |
| 4411 | 58 { |
| 4412 | 59 // No outer wrap from input blob. Direct copy. |
| 4413 | 60 privateBlob = in->inDuplicate; |
| 4414 | 61 } |
| 4415 | 62 |
| 4416 | 63 if(in->newParent != TPM_RH_NULL) |
| 4417 | 64 { |
| 4418 | 65 OBJECT *newParent; |
| 4419 | 66 newParent = ObjectGet(in->newParent); |
| 4420 | 67 |
| 4421 | 68 // New parent must be a storage object |
| 4422 | 69 if(!ObjectIsStorage(in->newParent)) |
| 4423 | 70 return TPM_RC_TYPE + RC_Rewrap_newParent; |
| 4424 | 71 |
| 4425 | 72 // Make new encrypt key and its associated secret structure. A |
| 4426 | 73 // TPM_RC_VALUE error may be returned at this point if RSA algorithm is |
| 4427 | 74 // enabled in TPM |
| 4428 | 75 out->outSymSeed.t.size = sizeof(out->outSymSeed.t.secret); |
| 4429 | 76 result = CryptSecretEncrypt(in->newParent, |
| 4430 | 77 "DUPLICATE", &data, &out->outSymSeed); |
| 4431 | 78 if(result != TPM_RC_SUCCESS) return result; |
| 4432 | 79 |
| 4433 | 80 // Command output |
| 4434 | 81 // Copy temporary variable to output, reserve the space for integrity |
| 4435 | 82 hashSize = sizeof(UINT16) + |
| 4436 | 83 CryptGetHashDigestSize(newParent->publicArea.nameAlg); |
| 4437 | 84 out->outDuplicate.t.size = privateBlob.t.size; |
| 4438 | 85 MemoryCopy(out->outDuplicate.t.buffer + hashSize, privateBlob.t.buffer, |
| 4439 | 86 privateBlob.t.size, sizeof(out->outDuplicate.t.buffer)); |
| 4440 | 87 |
| 4441 | 88 // Produce outer wrapper for output |
| 4442 | 89 out->outDuplicate.t.size = ProduceOuterWrap(in->newParent, &in->name, |
| 4443 | 90 newParent->publicArea.nameAlg, |
| 4444 | 91 (TPM2B_SEED *) &data, |
| 4445 | 92 FALSE, |
| 4446 | 93 out->outDuplicate.t.size, |
| 4447 | 94 out->outDuplicate.t.buffer); |
| 4448 | 95 |
| 4449 | 96 } |
| 4450 | 97 else // New parent is a null key so there is no seed |
| 4451 | 98 { |
| 4452 | 99 out->outSymSeed.t.size = 0; |
| 4453 | 100 |
| 4454 | 101 // Copy privateBlob directly |
| 4455 | 102 out->outDuplicate = privateBlob; |
| 4456 | 103 } |
| 4457 | 104 |
| 4458 | 105 return TPM_RC_SUCCESS; |
| 4459 | 106 } |
| 4460 | 107 #endif // CC_Rewrap |
| 4461 | |
| 4462 | Family “2.0” TCG Published Page 87 |
| 4463 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 4464 | Part 3: Commands Trusted Platform Module Library |
| 4465 | |
| 4466 | |
| 4467 | 13.3 TPM2_Import |
| 4468 | |
| 4469 | 13.3.1 General Description |
| 4470 | |
| 4471 | This command allows an object to be encrypted using the symmetric encryption values of a Storage Key. |
| 4472 | After encryption, the object may be loaded and used in the new hierarchy. The imported object (duplicate) |
| 4473 | may be singly encrypted, multiply encrypted, or unencrypted. |
| 4474 | If fixedTPM or fixedParent is SET in objectPublic, the TPM shall return TPM_RC_ATTRIBUTES. |
| 4475 | If encryptedDuplication is SET in the object referenced by parentHandle, then encryptedDuplication shall |
| 4476 | be SET in objectPublic (TPM_RC_ATTRIBUTES). |
| 4477 | If encryptedDuplication is SET in objectPublic, then inSymSeed and encryptionKey shall not be Empty |
| 4478 | buffers (TPM_RC_ATTRIBUTES). Recovery of the sensitive data of the object occurs in the TPM in a |
| 4479 | multi--step process in the following order: |
| 4480 | a) If inSymSeed has a non-zero size: |
| 4481 | 1) The asymmetric parameters and private key of parentHandle are used to recover the seed used |
| 4482 | in the creation of the HMAC key and encryption keys used to protect the duplication blob. |
| 4483 | |
| 4484 | NOTE 1 When recovering the seed from inSymSeed, L is “DUPLICATE”. |
| 4485 | |
| 4486 | 2) The integrity value in duplicate.buffer.integrityOuter is used to verify the integrity of the inner data |
| 4487 | blob, which is the remainder of duplicate.buffer (TPM_RC_INTEGRITY). |
| 4488 | |
| 4489 | NOTE 2 The inner data blob will contain a TPMT_SENSITIVE and may contain a TPM2B_DIGEST |
| 4490 | for the innerIntegrity. |
| 4491 | |
| 4492 | 3) The symmetric key recovered in 1) (2)is used to decrypt the inner data blob. |
| 4493 | |
| 4494 | NOTE 3 Checking the integrity before the data is used prevents attacks on the sensitive area by |
| 4495 | fuzzing the data and looking at the differences in the response codes. |
| 4496 | |
| 4497 | b) If encryptionKey is not an Empty Buffer: |
| 4498 | 1) Use encryptionKey to decrypt the inner blob. |
| 4499 | 2) Use the TPM2B_DIGEST at the start of the inner blob to verify the integrity of the inner blob |
| 4500 | (TPM_RC_INTEGRITY). |
| 4501 | c) Unmarshal the sensitive area |
| 4502 | |
| 4503 | NOTE 4 It is not necessary to validate that the sensitive area data is cryptographically bound to the public |
| 4504 | area other than that the Name of the public area is included in the HMAC. However, if the binding is |
| 4505 | not validated by this command, the binding must be checked each time the object is loaded. For an |
| 4506 | object that is imported under a parent with fixedTPM SET, binding need only be checked at import. If |
| 4507 | the parent has fixedTPM CLEAR, then the binding needs to be checked each time the object is |
| 4508 | loaded, or before the TPM performs an operation for which the binding affects the outcome of the |
| 4509 | operation (for example, TPM2_PolicySigned() or TPM2_Certify()). |
| 4510 | |
| 4511 | Similarly, if the new parent's fixedTPM is set, the encryptedDuplication state need only be checked |
| 4512 | at import. |
| 4513 | |
| 4514 | If the new parent is not fixedTPM, then that object will be loadable on any TPM (including SW |
| 4515 | versions) on which the new parent exists. This means that, each time an object is loaded under a |
| 4516 | parent that is not fixedTPM, it is necessary to validate all of the properties of that object. If the |
| 4517 | parent is fixedTPM, then the new private blob is integrity protec ted by the TPM that “owns” the |
| 4518 | parent. So, it is sufficient to validate the object’s properties (attribute and public -private binding) on |
| 4519 | import and not again. |
| 4520 | |
| 4521 | After integrity checks and decryption, the TPM will create a new symmetrically encrypted private area |
| 4522 | using the encryption key of the parent. |
| 4523 | |
| 4524 | Page 88 TCG Published Family “2.0” |
| 4525 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 4526 | Trusted Platform Module Library Part 3: Commands |
| 4527 | |
| 4528 | NOTE 5 The symmetric re-encryption is the normal integrity generation and symmetric encryption applied to |
| 4529 | a child object. |
| 4530 | |
| 4531 | |
| 4532 | |
| 4533 | |
| 4534 | Family “2.0” TCG Published Page 89 |
| 4535 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 4536 | Part 3: Commands Trusted Platform Module Library |
| 4537 | |
| 4538 | |
| 4539 | 13.3.2 Command and Response |
| 4540 | |
| 4541 | Table 39 — TPM2_Import Command |
| 4542 | Type Name Description |
| 4543 | |
| 4544 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 4545 | UINT32 commandSize |
| 4546 | TPM_CC commandCode TPM_CC_Import |
| 4547 | |
| 4548 | the handle of the new parent for the object |
| 4549 | TPMI_DH_OBJECT @parentHandle Auth Index: 1 |
| 4550 | Auth Role: USER |
| 4551 | |
| 4552 | the optional symmetric encryption key used as the inner |
| 4553 | wrapper for duplicate |
| 4554 | TPM2B_DATA encryptionKey |
| 4555 | If symmetricAlg is TPM_ALG_NULL, then this |
| 4556 | parameter shall be the Empty Buffer. |
| 4557 | the public area of the object to be imported |
| 4558 | This is provided so that the integrity value for duplicate |
| 4559 | TPM2B_PUBLIC objectPublic and the object attributes can be checked. |
| 4560 | NOTE Even if the integrity value of the object is not |
| 4561 | checked on input, the object Name is required to |
| 4562 | create the integrity value for the imported object. |
| 4563 | |
| 4564 | the symmetrically encrypted duplicate object that may |
| 4565 | TPM2B_PRIVATE duplicate |
| 4566 | contain an inner symmetric wrapper |
| 4567 | symmetric key used to encrypt duplicate |
| 4568 | TPM2B_ENCRYPTED_SECRET inSymSeed inSymSeed is encrypted/encoded using the algorithms |
| 4569 | of newParent. |
| 4570 | definition for the symmetric algorithm to use for the inner |
| 4571 | wrapper |
| 4572 | TPMT_SYM_DEF_OBJECT+ symmetricAlg |
| 4573 | If this algorithm is TPM_ALG_NULL, no inner wrapper is |
| 4574 | present and encryptionKey shall be the Empty Buffer. |
| 4575 | |
| 4576 | |
| 4577 | Table 40 — TPM2_Import Response |
| 4578 | Type Name Description |
| 4579 | |
| 4580 | TPM_ST tag see clause 6 |
| 4581 | UINT32 responseSize |
| 4582 | TPM_RC responseCode |
| 4583 | |
| 4584 | the sensitive area encrypted with the symmetric key of |
| 4585 | TPM2B_PRIVATE outPrivate |
| 4586 | parentHandle |
| 4587 | |
| 4588 | |
| 4589 | |
| 4590 | |
| 4591 | Page 90 TCG Published Family “2.0” |
| 4592 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 4593 | Trusted Platform Module Library Part 3: Commands |
| 4594 | |
| 4595 | |
| 4596 | |
| 4597 | 13.3.3 Detailed Actions |
| 4598 | |
| 4599 | 1 #include "InternalRoutines.h" |
| 4600 | 2 #include "Import_fp.h" |
| 4601 | 3 #ifdef TPM_CC_Import // Conditional expansion of this file |
| 4602 | 4 #include "Object_spt_fp.h" |
| 4603 | |
| 4604 | |
| 4605 | Error Returns Meaning |
| 4606 | |
| 4607 | TPM_RC_ASYMMETRIC non-duplicable storage key represented by objectPublic and its |
| 4608 | parent referenced by parentHandle have different public parameters |
| 4609 | TPM_RC_ATTRIBUTES attributes FixedTPM and fixedParent of objectPublic are not both |
| 4610 | CLEAR; or inSymSeed is nonempty and parentHandle does not |
| 4611 | reference a decryption key; or objectPublic and parentHandle have |
| 4612 | incompatible or inconsistent attributes; or encrytpedDuplication is |
| 4613 | SET in objectPublic but the inner or outer wrapper is missing. |
| 4614 | |
| 4615 | NOTE: if the TPM provides parameter values, the parameter number will indicate symmetricKey (missing |
| 4616 | inner wrapper) or inSymSeed (missing outer wrapper). |
| 4617 | |
| 4618 | |
| 4619 | TPM_RC_BINDING duplicate and objectPublic are not cryptographically |
| 4620 | bound |
| 4621 | |
| 4622 | TPM_RC_ECC_POINT inSymSeed is nonempty and ECC point in inSymSeed is not on the |
| 4623 | curve |
| 4624 | TPM_RC_HASH non-duplicable storage key represented by objectPublic and its |
| 4625 | parent referenced by parentHandle have different name algorithm |
| 4626 | TPM_RC_INSUFFICIENT inSymSeed is nonempty and failed to retrieve ECC point from the |
| 4627 | secret; or unmarshaling sensitive value from duplicate failed the |
| 4628 | result of inSymSeed decryption |
| 4629 | TPM_RC_INTEGRITY duplicate integrity is broken |
| 4630 | TPM_RC_KDF objectPublic representing decrypting keyed hash object specifies |
| 4631 | invalid KDF |
| 4632 | TPM_RC_KEY inconsistent parameters of objectPublic; or inSymSeed is nonempty |
| 4633 | and parentHandle does not reference a key of supported type; or |
| 4634 | invalid key size in objectPublic representing an asymmetric key |
| 4635 | TPM_RC_NO_RESULT inSymSeed is nonempty and multiplication resulted in ECC point at |
| 4636 | infinity |
| 4637 | TPM_RC_OBJECT_MEMORY no available object slot |
| 4638 | TPM_RC_SCHEME inconsistent attributes decrypt, sign, restricted and key's scheme ID |
| 4639 | in objectPublic; or hash algorithm is inconsistent with the scheme ID |
| 4640 | for keyed hash object |
| 4641 | TPM_RC_SIZE authPolicy size does not match digest size of the name algorithm in |
| 4642 | objectPublic; or symmetricAlg and encryptionKey have different |
| 4643 | sizes; or inSymSeed is nonempty and it size is not consistent with the |
| 4644 | type of parentHandle; or unmarshaling sensitive value from duplicate |
| 4645 | failed |
| 4646 | TPM_RC_SYMMETRIC objectPublic is either a storage key with no symmetric algorithm or a |
| 4647 | non-storage key with symmetric algorithm different from |
| 4648 | TPM_ALG_NULL |
| 4649 | TPM_RC_TYPE unsupported type of objectPublic; or non-duplicable storage key |
| 4650 | represented by objectPublic and its parent referenced by |
| 4651 | parentHandle are of different types; or parentHandle is not a storage |
| 4652 | key; or only the public portion of parentHandle is loaded; or |
| 4653 | |
| 4654 | Family “2.0” TCG Published Page 91 |
| 4655 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 4656 | Part 3: Commands Trusted Platform Module Library |
| 4657 | |
| 4658 | objectPublic and duplicate are of different types |
| 4659 | TPM_RC_VALUE nonempty inSymSeed and its numeric value is greater than the |
| 4660 | modulus of the key referenced by parentHandle or inSymSeed is |
| 4661 | larger than the size of the digest produced by the name algorithm of |
| 4662 | the symmetric key referenced by parentHandle |
| 4663 | |
| 4664 | 5 TPM_RC |
| 4665 | 6 TPM2_Import( |
| 4666 | 7 Import_In *in, // IN: input parameter list |
| 4667 | 8 Import_Out *out // OUT: output parameter list |
| 4668 | 9 ) |
| 4669 | 10 { |
| 4670 | 11 |
| 4671 | 12 TPM_RC result = TPM_RC_SUCCESS; |
| 4672 | 13 OBJECT *parentObject; |
| 4673 | 14 TPM2B_DATA data; // symmetric key |
| 4674 | 15 TPMT_SENSITIVE sensitive; |
| 4675 | 16 TPM2B_NAME name; |
| 4676 | 17 |
| 4677 | 18 UINT16 innerKeySize = 0; // encrypt key size for inner |
| 4678 | 19 // wrapper |
| 4679 | 20 |
| 4680 | 21 // Input Validation |
| 4681 | 22 |
| 4682 | 23 // FixedTPM and fixedParent must be CLEAR |
| 4683 | 24 if( in->objectPublic.t.publicArea.objectAttributes.fixedTPM == SET |
| 4684 | 25 || in->objectPublic.t.publicArea.objectAttributes.fixedParent == SET) |
| 4685 | 26 return TPM_RC_ATTRIBUTES + RC_Import_objectPublic; |
| 4686 | 27 |
| 4687 | 28 // Get parent pointer |
| 4688 | 29 parentObject = ObjectGet(in->parentHandle); |
| 4689 | 30 |
| 4690 | 31 if(!AreAttributesForParent(parentObject)) |
| 4691 | 32 return TPM_RC_TYPE + RC_Import_parentHandle; |
| 4692 | 33 |
| 4693 | 34 if(in->symmetricAlg.algorithm != TPM_ALG_NULL) |
| 4694 | 35 { |
| 4695 | 36 // Get inner wrap key size |
| 4696 | 37 innerKeySize = in->symmetricAlg.keyBits.sym; |
| 4697 | 38 // Input symmetric key must match the size of algorithm. |
| 4698 | 39 if(in->encryptionKey.t.size != (innerKeySize + 7) / 8) |
| 4699 | 40 return TPM_RC_SIZE + RC_Import_encryptionKey; |
| 4700 | 41 } |
| 4701 | 42 else |
| 4702 | 43 { |
| 4703 | 44 // If input symmetric algorithm is NULL, input symmetric key size must |
| 4704 | 45 // be 0 as well |
| 4705 | 46 if(in->encryptionKey.t.size != 0) |
| 4706 | 47 return TPM_RCS_SIZE + RC_Import_encryptionKey; |
| 4707 | 48 // If encryptedDuplication is SET, then the object must have an inner |
| 4708 | 49 // wrapper |
| 4709 | 50 if(in->objectPublic.t.publicArea.objectAttributes.encryptedDuplication) |
| 4710 | 51 return TPM_RCS_ATTRIBUTES + RC_Import_encryptionKey; |
| 4711 | 52 } |
| 4712 | 53 |
| 4713 | 54 // See if there is an outer wrapper |
| 4714 | 55 if(in->inSymSeed.t.size != 0) |
| 4715 | 56 { |
| 4716 | 57 // Decrypt input secret data via asymmetric decryption. TPM_RC_ATTRIBUTES, |
| 4717 | 58 // TPM_RC_ECC_POINT, TPM_RC_INSUFFICIENT, TPM_RC_KEY, TPM_RC_NO_RESULT, |
| 4718 | 59 // TPM_RC_SIZE, TPM_RC_VALUE may be returned at this point |
| 4719 | 60 result = CryptSecretDecrypt(in->parentHandle, NULL, "DUPLICATE", |
| 4720 | 61 &in->inSymSeed, &data); |
| 4721 | 62 pAssert(result != TPM_RC_BINDING); |
| 4722 | |
| 4723 | |
| 4724 | Page 92 TCG Published Family “2.0” |
| 4725 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 4726 | Trusted Platform Module Library Part 3: Commands |
| 4727 | |
| 4728 | 63 if(result != TPM_RC_SUCCESS) |
| 4729 | 64 return RcSafeAddToResult(result, RC_Import_inSymSeed); |
| 4730 | 65 } |
| 4731 | 66 else |
| 4732 | 67 { |
| 4733 | 68 // If encrytpedDuplication is set, then the object must have an outer |
| 4734 | 69 // wrapper |
| 4735 | 70 if(in->objectPublic.t.publicArea.objectAttributes.encryptedDuplication) |
| 4736 | 71 return TPM_RCS_ATTRIBUTES + RC_Import_inSymSeed; |
| 4737 | 72 data.t.size = 0; |
| 4738 | 73 } |
| 4739 | 74 |
| 4740 | 75 // Compute name of object |
| 4741 | 76 ObjectComputeName(&(in->objectPublic.t.publicArea), &name); |
| 4742 | 77 |
| 4743 | 78 // Retrieve sensitive from private. |
| 4744 | 79 // TPM_RC_INSUFFICIENT, TPM_RC_INTEGRITY, TPM_RC_SIZE may be returned here. |
| 4745 | 80 result = DuplicateToSensitive(&in->duplicate, &name, in->parentHandle, |
| 4746 | 81 in->objectPublic.t.publicArea.nameAlg, |
| 4747 | 82 (TPM2B_SEED *) &data, &in->symmetricAlg, |
| 4748 | 83 &in->encryptionKey, &sensitive); |
| 4749 | 84 if(result != TPM_RC_SUCCESS) |
| 4750 | 85 return RcSafeAddToResult(result, RC_Import_duplicate); |
| 4751 | 86 |
| 4752 | 87 // If the parent of this object has fixedTPM SET, then fully validate this |
| 4753 | 88 // object so that validation can be skipped when it is loaded |
| 4754 | 89 if(parentObject->publicArea.objectAttributes.fixedTPM == SET) |
| 4755 | 90 { |
| 4756 | 91 TPM_HANDLE objectHandle; |
| 4757 | 92 |
| 4758 | 93 // Perform self check on input public area. A TPM_RC_SIZE, TPM_RC_SCHEME, |
| 4759 | 94 // TPM_RC_VALUE, TPM_RC_SYMMETRIC, TPM_RC_TYPE, TPM_RC_HASH, |
| 4760 | 95 // TPM_RC_ASYMMETRIC, TPM_RC_ATTRIBUTES or TPM_RC_KDF error may be returned |
| 4761 | 96 // at this point |
| 4762 | 97 result = PublicAttributesValidation(TRUE, in->parentHandle, |
| 4763 | 98 &in->objectPublic.t.publicArea); |
| 4764 | 99 if(result != TPM_RC_SUCCESS) |
| 4765 | 100 return RcSafeAddToResult(result, RC_Import_objectPublic); |
| 4766 | 101 |
| 4767 | 102 // Create internal object. A TPM_RC_KEY_SIZE, TPM_RC_KEY or |
| 4768 | 103 // TPM_RC_OBJECT_MEMORY error may be returned at this point |
| 4769 | 104 result = ObjectLoad(TPM_RH_NULL, &in->objectPublic.t.publicArea, |
| 4770 | 105 &sensitive, NULL, in->parentHandle, FALSE, |
| 4771 | 106 &objectHandle); |
| 4772 | 107 if(result != TPM_RC_SUCCESS) |
| 4773 | 108 return result; |
| 4774 | 109 |
| 4775 | 110 // Don't need the object, just needed the checks to be performed so |
| 4776 | 111 // flush the object |
| 4777 | 112 ObjectFlush(objectHandle); |
| 4778 | 113 } |
| 4779 | 114 |
| 4780 | 115 // Command output |
| 4781 | 116 |
| 4782 | 117 // Prepare output private data from sensitive |
| 4783 | 118 SensitiveToPrivate(&sensitive, &name, in->parentHandle, |
| 4784 | 119 in->objectPublic.t.publicArea.nameAlg, |
| 4785 | 120 &out->outPrivate); |
| 4786 | 121 |
| 4787 | 122 return TPM_RC_SUCCESS; |
| 4788 | 123 } |
| 4789 | 124 #endif // CC_Import |
| 4790 | |
| 4791 | |
| 4792 | |
| 4793 | |
| 4794 | Family “2.0” TCG Published Page 93 |
| 4795 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 4796 | Part 3: Commands Trusted Platform Module Library |
| 4797 | |
| 4798 | |
| 4799 | 14 Asymmetric Primitives |
| 4800 | |
| 4801 | 14.1 Introduction |
| 4802 | |
| 4803 | The commands in this clause provide low-level primitives for access to the asymmetric algorithms |
| 4804 | implemented in the TPM. Many of these commands are only allowed if the asymmetric key is an |
| 4805 | unrestricted key. |
| 4806 | |
| 4807 | 14.2 TPM2_RSA_Encrypt |
| 4808 | |
| 4809 | 14.2.1 General Description |
| 4810 | |
| 4811 | This command performs RSA encryption using the indicated padding scheme according to IETF RFC |
| 4812 | 3447. If the scheme of keyHandle is TPM_ALG_NULL, then the caller may use inScheme to specify the |
| 4813 | padding scheme. If scheme of keyHandle is not TPM_ALG_NULL, then inScheme shall either be |
| 4814 | TPM_ALG_NULL or be the same as scheme (TPM_RC_SCHEME). |
| 4815 | The key referenced by keyHandle is required to be an RSA key (TPM_RC_KEY) with the decrypt attribute |
| 4816 | SET (TPM_RC_ATTRIBUTES). |
| 4817 | |
| 4818 | NOTE Requiring that the decrypt attribute be set allows the TPM to ensure that the scheme selection is |
| 4819 | done with the presumption that the scheme of the key is a decryption scheme selection. It is |
| 4820 | understood that this command will operate on a key with only the public part loaded so the caller |
| 4821 | may modify any key in any desired way. So, this constraint only serves to simplify the TPM logic. |
| 4822 | |
| 4823 | The three types of allowed padding are: |
| 4824 | 1) TPM_ALG_OAEP – Data is OAEP padded as described in 7.1 of IETF RFC 3447 (PKCS#1). |
| 4825 | The only supported mask generation is MGF1. |
| 4826 | 2) TPM_ALG_RSAES – Data is padded as described in 7.2 of IETF RFC 3447 (PKCS#1). |
| 4827 | 3) TPM_ALG_NULL – Data is not padded by the TPM and the TPM will treat message as an |
| 4828 | unsigned integer and perform a modular exponentiation of message using the public |
| 4829 | exponent of the key referenced by keyHandle. This scheme is only used if both the scheme |
| 4830 | in the key referenced by keyHandle is TPM_ALG_NULL, and the inScheme parameter of the |
| 4831 | command is TPM_ALG_NULL. The input value cannot be larger than the public modulus of |
| 4832 | the key referenced by keyHandle. |
| 4833 | |
| 4834 | Table 41 — Padding Scheme Selection |
| 4835 | keyHandle→scheme inScheme padding scheme used |
| 4836 | |
| 4837 | TPM_ALG_NULL none |
| 4838 | TPM_ALG_NULL TPM_ALG_RSAES RSAES |
| 4839 | TPM_ALG_OAEP OAEP |
| 4840 | TPM_ALG_NULL RSAES |
| 4841 | TPM_ALG_RSAES TPM_ALG_RSAES RSAES |
| 4842 | TPM_ALG_OAEP error (TPM_RC_SCHEME) |
| 4843 | TPM_ALG_NULL OAEP |
| 4844 | TPM_ALG_OAEP TPM_ALG_RSAES error (TPM_RC_SCHEME) |
| 4845 | TPM_AGL_OAEP OAEP |
| 4846 | |
| 4847 | After padding, the data is RSAEP encrypted according to 5.1.1 of IETF RFC 3447 (PKCS#1). |
| 4848 | |
| 4849 | |
| 4850 | Page 94 TCG Published Family “2.0” |
| 4851 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 4852 | Trusted Platform Module Library Part 3: Commands |
| 4853 | |
| 4854 | NOTE 1 It is required that decrypt be SET so that the commands that load a key can validate that the |
| 4855 | scheme is consistent rather than have that deferred until the key is used. |
| 4856 | |
| 4857 | NOTE 2 If it is desired to use a key that had restricted SET, the caller may CLEAR restricted and load the |
| 4858 | public part of the key and use that unrestricted version of the key for encryption. |
| 4859 | |
| 4860 | If inScheme is used, and the scheme requires a hash algorithm it may not be TPM_ALG_NULL. |
| 4861 | |
| 4862 | NOTE 3 Because only the public portion of the key needs to be loaded for this command, th e caller can |
| 4863 | manipulate the attributes of the key in any way desired. As a result , the TPM shall not check the |
| 4864 | consistency of the attributes. The only property checking is that the key is an RSA key and that the |
| 4865 | padding scheme is supported. |
| 4866 | |
| 4867 | The message parameter is limited in size by the padding scheme according to the following table: |
| 4868 | |
| 4869 | Table 42 — Message Size Limits Based on Padding |
| 4870 | Maximum Message Length |
| 4871 | Scheme (mLen) in Octets Comments |
| 4872 | |
| 4873 | TPM_ALG_OAEP mLen k – 2hLen – 2 |
| 4874 | TPM_ALG_RSAES mLen k – 11 |
| 4875 | TPM_ALG_NULL mLen k The numeric value of the message must be |
| 4876 | less than the numeric value of the public |
| 4877 | modulus (n). |
| 4878 | NOTES |
| 4879 | 1) k ≔ the number of byes in the public modulus |
| 4880 | 2) hLen ≔ the number of octets in the digest produced by the hash algorithm used in the process |
| 4881 | |
| 4882 | The label parameter is optional. If provided (label.size != 0) then the TPM shall return TPM_RC_VALUE if |
| 4883 | the last octet in label is not zero. If a zero octet occurs before label.buffer[label.size-1], the TPM shall |
| 4884 | truncate the label at that point. The terminating octet of zero is included in the label used in the padding |
| 4885 | scheme. |
| 4886 | |
| 4887 | NOTE 4 If the scheme does not use a label, the TPM will still verify that label is properly formatted if label is |
| 4888 | present. |
| 4889 | |
| 4890 | The function returns padded and encrypted value outData. |
| 4891 | The message parameter in the command may be encrypted using parameter encryption. |
| 4892 | |
| 4893 | NOTE 5 Only the public area of keyHandle is required to be loaded. A public key may be loaded with any |
| 4894 | desired scheme. If the scheme is to be changed, a different public area must be loaded. |
| 4895 | |
| 4896 | |
| 4897 | |
| 4898 | |
| 4899 | Family “2.0” TCG Published Page 95 |
| 4900 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 4901 | Part 3: Commands Trusted Platform Module Library |
| 4902 | |
| 4903 | |
| 4904 | 14.2.2 Command and Response |
| 4905 | |
| 4906 | Table 43 — TPM2_RSA_Encrypt Command |
| 4907 | Type Name Description |
| 4908 | |
| 4909 | TPM_ST_SESSIONS if an audit, encrypt, or decrypt |
| 4910 | TPMI_ST_COMMAND_TAG tag session is present; otherwise, |
| 4911 | TPM_ST_NO_SESSIONS |
| 4912 | UINT32 commandSize |
| 4913 | TPM_CC commandCode TPM_CC_RSA_Encrypt |
| 4914 | |
| 4915 | reference to public portion of RSA key to use for |
| 4916 | TPMI_DH_OBJECT keyHandle encryption |
| 4917 | Auth Index: None |
| 4918 | |
| 4919 | message to be encrypted |
| 4920 | NOTE 1 The data type was chosen because it limits the |
| 4921 | TPM2B_PUBLIC_KEY_RSA message overall size of the input to no greater than the size |
| 4922 | of the largest RSA public key. This may be larger |
| 4923 | than allowed for keyHandle. |
| 4924 | |
| 4925 | the padding scheme to use if scheme associated with |
| 4926 | TPMT_RSA_DECRYPT+ inScheme |
| 4927 | keyHandle is TPM_ALG_NULL |
| 4928 | optional label L to be associated with the message |
| 4929 | TPM2B_DATA label Size of the buffer is zero if no label is present |
| 4930 | NOTE 2 See description of label above. |
| 4931 | |
| 4932 | |
| 4933 | Table 44 — TPM2_RSA_Encrypt Response |
| 4934 | Type Name Description |
| 4935 | |
| 4936 | TPM_ST tag see clause 6 |
| 4937 | UINT32 responseSize |
| 4938 | TPM_RC responseCode |
| 4939 | |
| 4940 | TPM2B_PUBLIC_KEY_RSA outData encrypted output |
| 4941 | |
| 4942 | |
| 4943 | |
| 4944 | |
| 4945 | Page 96 TCG Published Family “2.0” |
| 4946 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 4947 | Trusted Platform Module Library Part 3: Commands |
| 4948 | |
| 4949 | |
| 4950 | |
| 4951 | 14.2.3 Detailed Actions |
| 4952 | |
| 4953 | 1 #include "InternalRoutines.h" |
| 4954 | 2 #include "RSA_Encrypt_fp.h" |
| 4955 | 3 #ifdef TPM_CC_RSA_Encrypt // Conditional expansion of this file |
| 4956 | 4 #ifdef TPM_ALG_RSA |
| 4957 | |
| 4958 | |
| 4959 | Error Returns Meaning |
| 4960 | |
| 4961 | TPM_RC_ATTRIBUTES decrypt attribute is not SET in key referenced by keyHandle |
| 4962 | TPM_RC_KEY keyHandle does not reference an RSA key |
| 4963 | TPM_RC_SCHEME incorrect input scheme, or the chosen scheme is not a valid RSA |
| 4964 | decrypt scheme |
| 4965 | TPM_RC_VALUE the numeric value of message is greater than the public modulus of |
| 4966 | the key referenced by keyHandle, or label is not a null-terminated |
| 4967 | string |
| 4968 | |
| 4969 | 5 TPM_RC |
| 4970 | 6 TPM2_RSA_Encrypt( |
| 4971 | 7 RSA_Encrypt_In *in, // IN: input parameter list |
| 4972 | 8 RSA_Encrypt_Out *out // OUT: output parameter list |
| 4973 | 9 ) |
| 4974 | 10 { |
| 4975 | 11 TPM_RC result; |
| 4976 | 12 OBJECT *rsaKey; |
| 4977 | 13 TPMT_RSA_DECRYPT *scheme; |
| 4978 | 14 char *label = NULL; |
| 4979 | 15 |
| 4980 | 16 // Input Validation |
| 4981 | 17 |
| 4982 | 18 rsaKey = ObjectGet(in->keyHandle); |
| 4983 | 19 |
| 4984 | 20 // selected key must be an RSA key |
| 4985 | 21 if(rsaKey->publicArea.type != TPM_ALG_RSA) |
| 4986 | 22 return TPM_RC_KEY + RC_RSA_Encrypt_keyHandle; |
| 4987 | 23 |
| 4988 | 24 // selected key must have the decryption attribute |
| 4989 | 25 if(rsaKey->publicArea.objectAttributes.decrypt != SET) |
| 4990 | 26 return TPM_RC_ATTRIBUTES + RC_RSA_Encrypt_keyHandle; |
| 4991 | 27 |
| 4992 | 28 // Is there a label? |
| 4993 | 29 if(in->label.t.size > 0) |
| 4994 | 30 { |
| 4995 | 31 // label is present, so make sure that is it NULL-terminated |
| 4996 | 32 if(in->label.t.buffer[in->label.t.size - 1] != 0) |
| 4997 | 33 return TPM_RC_VALUE + RC_RSA_Encrypt_label; |
| 4998 | 34 label = (char *)in->label.t.buffer; |
| 4999 | 35 } |
| 5000 | 36 |
| 5001 | 37 // Command Output |
| 5002 | 38 |
| 5003 | 39 // Select a scheme for encryption |
| 5004 | 40 scheme = CryptSelectRSAScheme(in->keyHandle, &in->inScheme); |
| 5005 | 41 if(scheme == NULL) |
| 5006 | 42 return TPM_RC_SCHEME + RC_RSA_Encrypt_inScheme; |
| 5007 | 43 |
| 5008 | 44 // Encryption. TPM_RC_VALUE, or TPM_RC_SCHEME errors my be returned buy |
| 5009 | 45 // CryptEncyptRSA. Note: It can also return TPM_RC_ATTRIBUTES if the key does |
| 5010 | 46 // not have the decrypt attribute but that was checked above. |
| 5011 | 47 out->outData.t.size = sizeof(out->outData.t.buffer); |
| 5012 | 48 result = CryptEncryptRSA(&out->outData.t.size, out->outData.t.buffer, rsaKey, |
| 5013 | |
| 5014 | Family “2.0” TCG Published Page 97 |
| 5015 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 5016 | Part 3: Commands Trusted Platform Module Library |
| 5017 | |
| 5018 | 49 scheme, in->message.t.size, in->message.t.buffer, |
| 5019 | 50 label); |
| 5020 | 51 return result; |
| 5021 | 52 } |
| 5022 | 53 #endif |
| 5023 | 54 #endif // CC_RSA_Encrypt |
| 5024 | |
| 5025 | |
| 5026 | |
| 5027 | |
| 5028 | Page 98 TCG Published Family “2.0” |
| 5029 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 5030 | Trusted Platform Module Library Part 3: Commands |
| 5031 | |
| 5032 | |
| 5033 | 14.3 TPM2_RSA_Decrypt |
| 5034 | |
| 5035 | 14.3.1 General Description |
| 5036 | |
| 5037 | This command performs RSA decryption using the indicated padding scheme according to IETF RFC |
| 5038 | 3447 ((PKCS#1). |
| 5039 | The scheme selection for this command is the same as for TPM2_RSA_Encrypt() and is shown in Table |
| 5040 | 41. |
| 5041 | The key referenced by keyHandle shall be an RSA key (TPM_RC_KEY) with restricted CLEAR and |
| 5042 | decrypt SET (TPM_RC_ATTRIBUTES). |
| 5043 | This command uses the private key of keyHandle for this operation and authorization is required. |
| 5044 | The TPM will perform a modular exponentiation of ciphertext using the private exponent associated with |
| 5045 | keyHandle (this is described in IETF RFC 3447 (PKCS#1), clause 5.1.2). It will then validate the padding |
| 5046 | according to the selected scheme. If the padding checks fail, TPM_RC_VALUE is returned. Otherwise, |
| 5047 | the data is returned with the padding removed. If no padding is used, the returned value is an unsigned |
| 5048 | integer value that is the result of the modular exponentiation of cipherText using the private exponent of |
| 5049 | keyHandle. The returned value may include leading octets zeros so that it is the same size as the public |
| 5050 | modulus. For the other padding schemes, the returned value will be smaller than the public modulus but |
| 5051 | will contain all the data remaining after padding is removed and this may include leading zeros if the |
| 5052 | original encrypted value contained leading zeros. |
| 5053 | If a label is used in the padding process of the scheme during encryption, the label parameter is required |
| 5054 | to be present in the decryption process and label is required to be the same in both cases. If label is not |
| 5055 | the same, the decrypt operation is very likely to fail ((TPM_RC_VALUE). If label is present (label.size != |
| 5056 | 0), it shall be a NULL-terminated string or the TPM will return TPM_RC_VALUE. |
| 5057 | |
| 5058 | NOTE 1 The size of label includes the terminating null. |
| 5059 | |
| 5060 | The message parameter in the response may be encrypted using parameter encryption. |
| 5061 | If inScheme is used, and the scheme requires a hash algorithm it may not be TPM_ALG_NULL. |
| 5062 | If the scheme does not require a label, the value in label is not used but the size of the label field is |
| 5063 | checked for consistency with the indicated data type (TPM2B_DATA). That is, the field may not be larger |
| 5064 | than allowed for a TPM2B_DATA. |
| 5065 | |
| 5066 | |
| 5067 | |
| 5068 | |
| 5069 | Family “2.0” TCG Published Page 99 |
| 5070 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 5071 | Part 3: Commands Trusted Platform Module Library |
| 5072 | |
| 5073 | |
| 5074 | |
| 5075 | 14.3.2 Command and Response |
| 5076 | |
| 5077 | Table 45 — TPM2_RSA_Decrypt Command |
| 5078 | Type Name Description |
| 5079 | |
| 5080 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 5081 | UINT32 commandSize |
| 5082 | TPM_CC commandCode TPM_CC_RSA_Decrypt |
| 5083 | |
| 5084 | RSA key to use for decryption |
| 5085 | TPMI_DH_OBJECT @keyHandle Auth Index: 1 |
| 5086 | Auth Role: USER |
| 5087 | |
| 5088 | cipher text to be decrypted |
| 5089 | TPM2B_PUBLIC_KEY_RSA cipherText NOTE An encrypted RSA data block is the size of the |
| 5090 | public modulus. |
| 5091 | |
| 5092 | the padding scheme to use if scheme associated with |
| 5093 | TPMT_RSA_DECRYPT+ inScheme |
| 5094 | keyHandle is TPM_ALG_NULL |
| 5095 | label whose association with the message is to be |
| 5096 | TPM2B_DATA label |
| 5097 | verified |
| 5098 | |
| 5099 | |
| 5100 | Table 46 — TPM2_RSA_Decrypt Response |
| 5101 | Type Name Description |
| 5102 | |
| 5103 | TPM_ST tag see clause 6 |
| 5104 | UINT32 responseSize |
| 5105 | TPM_RC responseCode |
| 5106 | |
| 5107 | TPM2B_PUBLIC_KEY_RSA message decrypted output |
| 5108 | |
| 5109 | |
| 5110 | |
| 5111 | |
| 5112 | Page 100 TCG Published Family “2.0” |
| 5113 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 5114 | Trusted Platform Module Library Part 3: Commands |
| 5115 | |
| 5116 | |
| 5117 | |
| 5118 | 14.3.3 Detailed Actions |
| 5119 | |
| 5120 | 1 #include "InternalRoutines.h" |
| 5121 | 2 #include "RSA_Decrypt_fp.h" |
| 5122 | 3 #ifdef TPM_CC_RSA_Decrypt // Conditional expansion of this file |
| 5123 | 4 #ifdef TPM_ALG_RSA |
| 5124 | |
| 5125 | |
| 5126 | Error Returns Meaning |
| 5127 | |
| 5128 | TPM_RC_BINDING The public an private parts of the key are not properly bound |
| 5129 | TPM_RC_KEY keyHandle does not reference an unrestricted decrypt key |
| 5130 | TPM_RC_SCHEME incorrect input scheme, or the chosen scheme is not a valid RSA |
| 5131 | decrypt scheme |
| 5132 | TPM_RC_SIZE cipherText is not the size of the modulus of key referenced by |
| 5133 | keyHandle |
| 5134 | TPM_RC_VALUE label is not a null terminated string or the value of cipherText is |
| 5135 | greater that the modulus of keyHandle |
| 5136 | |
| 5137 | 5 TPM_RC |
| 5138 | 6 TPM2_RSA_Decrypt( |
| 5139 | 7 RSA_Decrypt_In *in, // IN: input parameter list |
| 5140 | 8 RSA_Decrypt_Out *out // OUT: output parameter list |
| 5141 | 9 ) |
| 5142 | 10 { |
| 5143 | 11 TPM_RC result; |
| 5144 | 12 OBJECT *rsaKey; |
| 5145 | 13 TPMT_RSA_DECRYPT *scheme; |
| 5146 | 14 char *label = NULL; |
| 5147 | 15 |
| 5148 | 16 // Input Validation |
| 5149 | 17 |
| 5150 | 18 rsaKey = ObjectGet(in->keyHandle); |
| 5151 | 19 |
| 5152 | 20 // The selected key must be an RSA key |
| 5153 | 21 if(rsaKey->publicArea.type != TPM_ALG_RSA) |
| 5154 | 22 return TPM_RC_KEY + RC_RSA_Decrypt_keyHandle; |
| 5155 | 23 |
| 5156 | 24 // The selected key must be an unrestricted decryption key |
| 5157 | 25 if( rsaKey->publicArea.objectAttributes.restricted == SET |
| 5158 | 26 || rsaKey->publicArea.objectAttributes.decrypt == CLEAR) |
| 5159 | 27 return TPM_RC_ATTRIBUTES + RC_RSA_Decrypt_keyHandle; |
| 5160 | 28 |
| 5161 | 29 // NOTE: Proper operation of this command requires that the sensitive area |
| 5162 | 30 // of the key is loaded. This is assured because authorization is required |
| 5163 | 31 // to use the sensitive area of the key. In order to check the authorization, |
| 5164 | 32 // the sensitive area has to be loaded, even if authorization is with policy. |
| 5165 | 33 |
| 5166 | 34 // If label is present, make sure that it is a NULL-terminated string |
| 5167 | 35 if(in->label.t.size > 0) |
| 5168 | 36 { |
| 5169 | 37 // Present, so make sure that it is NULL-terminated |
| 5170 | 38 if(in->label.t.buffer[in->label.t.size - 1] != 0) |
| 5171 | 39 return TPM_RC_VALUE + RC_RSA_Decrypt_label; |
| 5172 | 40 label = (char *)in->label.t.buffer; |
| 5173 | 41 } |
| 5174 | 42 |
| 5175 | 43 // Command Output |
| 5176 | 44 |
| 5177 | 45 // Select a scheme for decrypt. |
| 5178 | 46 scheme = CryptSelectRSAScheme(in->keyHandle, &in->inScheme); |
| 5179 | |
| 5180 | Family “2.0” TCG Published Page 101 |
| 5181 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 5182 | Part 3: Commands Trusted Platform Module Library |
| 5183 | |
| 5184 | 47 if(scheme == NULL) |
| 5185 | 48 return TPM_RC_SCHEME + RC_RSA_Decrypt_inScheme; |
| 5186 | 49 |
| 5187 | 50 // Decryption. TPM_RC_VALUE, TPM_RC_SIZE, and TPM_RC_KEY error may be |
| 5188 | 51 // returned by CryptDecryptRSA. |
| 5189 | 52 // NOTE: CryptDecryptRSA can also return TPM_RC_ATTRIBUTES or TPM_RC_BINDING |
| 5190 | 53 // when the key is not a decryption key but that was checked above. |
| 5191 | 54 out->message.t.size = sizeof(out->message.t.buffer); |
| 5192 | 55 result = CryptDecryptRSA(&out->message.t.size, out->message.t.buffer, rsaKey, |
| 5193 | 56 scheme, in->cipherText.t.size, |
| 5194 | 57 in->cipherText.t.buffer, |
| 5195 | 58 label); |
| 5196 | 59 |
| 5197 | 60 return result; |
| 5198 | 61 } |
| 5199 | 62 #endif |
| 5200 | 63 #endif // CC_RSA_Decrypt |
| 5201 | |
| 5202 | |
| 5203 | |
| 5204 | |
| 5205 | Page 102 TCG Published Family “2.0” |
| 5206 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 5207 | Trusted Platform Module Library Part 3: Commands |
| 5208 | |
| 5209 | |
| 5210 | 14.4 TPM2_ECDH_KeyGen |
| 5211 | |
| 5212 | 14.4.1 General Description |
| 5213 | |
| 5214 | This command uses the TPM to generate an ephemeral key pair ( de, Qe where Qe ≔ [de]G). It uses the |
| 5215 | private ephemeral key and a loaded public key (QS) to compute the shared secret value (P ≔ [hde]QS). |
| 5216 | keyHandle shall refer to a loaded ECC key. The sensitive portion of this key need not be loaded. |
| 5217 | The curve parameters of the loaded ECC key are used to generate the ephemeral key. |
| 5218 | |
| 5219 | NOTE 1 This function is the equivalent of encrypting data to another object’s public key. The seed value is |
| 5220 | used in a KDF to generate a symmetric key and that key is used to encrypt the data. Once the data |
| 5221 | is encrypted and the symmetric key discarded, only the ob ject with the private portion of the |
| 5222 | keyHandle will be able to decrypt it. |
| 5223 | |
| 5224 | The zPoint in the response may be encrypted using parameter encryption. |
| 5225 | |
| 5226 | |
| 5227 | |
| 5228 | |
| 5229 | Family “2.0” TCG Published Page 103 |
| 5230 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 5231 | Part 3: Commands Trusted Platform Module Library |
| 5232 | |
| 5233 | |
| 5234 | |
| 5235 | 14.4.2 Command and Response |
| 5236 | |
| 5237 | Table 47 — TPM2_ECDH_KeyGen Command |
| 5238 | Type Name Description |
| 5239 | |
| 5240 | TPM_ST_SESSIONS if an audit or encrypt session is |
| 5241 | TPMI_ST_COMMAND_TAG tag |
| 5242 | present; otherwise, TPM_ST_NO_SESSIONS |
| 5243 | UINT32 commandSize |
| 5244 | TPM_CC commandCode TPM_CC_ECDH_KeyGen |
| 5245 | |
| 5246 | Handle of a loaded ECC key public area. |
| 5247 | TPMI_DH_OBJECT keyHandle |
| 5248 | Auth Index: None |
| 5249 | |
| 5250 | |
| 5251 | Table 48 — TPM2_ECDH_KeyGen Response |
| 5252 | Type Name Description |
| 5253 | |
| 5254 | TPM_ST tag see clause 6 |
| 5255 | UINT32 responseSize |
| 5256 | TPM_RC responseCode |
| 5257 | |
| 5258 | TPM2B_ECC_POINT zPoint results of P ≔ h[de]Qs |
| 5259 | |
| 5260 | TPM2B_ECC_POINT pubPoint generated ephemeral public point (Qe) |
| 5261 | |
| 5262 | |
| 5263 | |
| 5264 | |
| 5265 | Page 104 TCG Published Family “2.0” |
| 5266 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 5267 | Trusted Platform Module Library Part 3: Commands |
| 5268 | |
| 5269 | |
| 5270 | |
| 5271 | 14.4.3 Detailed Actions |
| 5272 | |
| 5273 | 1 #include "InternalRoutines.h" |
| 5274 | 2 #include "ECDH_KeyGen_fp.h" |
| 5275 | 3 #ifdef TPM_CC_ECDH_KeyGen // Conditional expansion of this file |
| 5276 | 4 #ifdef TPM_ALG_ECC |
| 5277 | |
| 5278 | |
| 5279 | Error Returns Meaning |
| 5280 | |
| 5281 | TPM_RC_KEY keyHandle does not reference a non-restricted decryption ECC key |
| 5282 | |
| 5283 | 5 TPM_RC |
| 5284 | 6 TPM2_ECDH_KeyGen( |
| 5285 | 7 ECDH_KeyGen_In *in, // IN: input parameter list |
| 5286 | 8 ECDH_KeyGen_Out *out // OUT: output parameter list |
| 5287 | 9 ) |
| 5288 | 10 { |
| 5289 | 11 OBJECT *eccKey; |
| 5290 | 12 TPM2B_ECC_PARAMETER sensitive; |
| 5291 | 13 TPM_RC result; |
| 5292 | 14 |
| 5293 | 15 // Input Validation |
| 5294 | 16 |
| 5295 | 17 eccKey = ObjectGet(in->keyHandle); |
| 5296 | 18 |
| 5297 | 19 // Input key must be a non-restricted, decrypt ECC key |
| 5298 | 20 if( eccKey->publicArea.type != TPM_ALG_ECC) |
| 5299 | 21 return TPM_RCS_KEY + RC_ECDH_KeyGen_keyHandle; |
| 5300 | 22 |
| 5301 | 23 if( eccKey->publicArea.objectAttributes.restricted == SET |
| 5302 | 24 || eccKey->publicArea.objectAttributes.decrypt != SET |
| 5303 | 25 ) |
| 5304 | 26 return TPM_RC_KEY + RC_ECDH_KeyGen_keyHandle; |
| 5305 | 27 |
| 5306 | 28 // Command Output |
| 5307 | 29 do |
| 5308 | 30 { |
| 5309 | 31 // Create ephemeral ECC key |
| 5310 | 32 CryptNewEccKey(eccKey->publicArea.parameters.eccDetail.curveID, |
| 5311 | 33 &out->pubPoint.t.point, &sensitive); |
| 5312 | 34 |
| 5313 | 35 out->pubPoint.t.size = TPMS_ECC_POINT_Marshal(&out->pubPoint.t.point, |
| 5314 | 36 NULL, NULL); |
| 5315 | 37 |
| 5316 | 38 // Compute Z |
| 5317 | 39 result = CryptEccPointMultiply(&out->zPoint.t.point, |
| 5318 | 40 eccKey->publicArea.parameters.eccDetail.curveID, |
| 5319 | 41 &sensitive, &eccKey->publicArea.unique.ecc); |
| 5320 | 42 // The point in the key is not on the curve. Indicate that the key is bad. |
| 5321 | 43 if(result == TPM_RC_ECC_POINT) |
| 5322 | 44 return TPM_RC_KEY + RC_ECDH_KeyGen_keyHandle; |
| 5323 | 45 // The other possible error is TPM_RC_NO_RESULT indicating that the |
| 5324 | 46 // multiplication resulted in the point at infinity, so get a new |
| 5325 | 47 // random key and start over (hardly ever happens). |
| 5326 | 48 } |
| 5327 | 49 while(result == TPM_RC_NO_RESULT); |
| 5328 | 50 |
| 5329 | 51 if(result == TPM_RC_SUCCESS) |
| 5330 | 52 // Marshal the values to generate the point. |
| 5331 | 53 out->zPoint.t.size = TPMS_ECC_POINT_Marshal(&out->zPoint.t.point, |
| 5332 | 54 NULL, NULL); |
| 5333 | 55 |
| 5334 | 56 return result; |
| 5335 | |
| 5336 | Family “2.0” TCG Published Page 105 |
| 5337 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 5338 | Part 3: Commands Trusted Platform Module Library |
| 5339 | |
| 5340 | 57 } |
| 5341 | 58 #endif |
| 5342 | 59 #endif // CC_ECDH_KeyGen |
| 5343 | |
| 5344 | |
| 5345 | |
| 5346 | |
| 5347 | Page 106 TCG Published Family “2.0” |
| 5348 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 5349 | Trusted Platform Module Library Part 3: Commands |
| 5350 | |
| 5351 | |
| 5352 | 14.5 TPM2_ECDH_ZGen |
| 5353 | |
| 5354 | 14.5.1 General Description |
| 5355 | |
| 5356 | This command uses the TPM to recover the Z value from a public point (QB) and a private key (ds). It will |
| 5357 | perform the multiplication of the provided inPoint (QB) with the private key (ds) and return the coordinates |
| 5358 | of the resultant point (Z = (xZ , yZ) ≔ [hds]QB; where h is the cofactor of the curve). |
| 5359 | keyHandle shall refer to a loaded, ECC key (TPM_RC_KEY) with the restricted attribute CLEAR and the |
| 5360 | decrypt attribute SET (TPM_RC_ATTRIBUTES). |
| 5361 | The scheme of the key referenced by keyHandle is required to be either TPM_ALG_ECDH or |
| 5362 | TPM_ALG_NULL (TPM_RC_SCHEME). |
| 5363 | inPoint is required to be on the curve of the key referenced by keyHandle (TPM_RC_ECC_POINT). |
| 5364 | The parameters of the key referenced by keyHandle are used to perform the point multiplication. |
| 5365 | |
| 5366 | |
| 5367 | |
| 5368 | |
| 5369 | Family “2.0” TCG Published Page 107 |
| 5370 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 5371 | Part 3: Commands Trusted Platform Module Library |
| 5372 | |
| 5373 | |
| 5374 | |
| 5375 | 14.5.2 Command and Response |
| 5376 | |
| 5377 | Table 49 — TPM2_ECDH_ZGen Command |
| 5378 | Type Name Description |
| 5379 | |
| 5380 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 5381 | UINT32 commandSize |
| 5382 | TPM_CC commandCode TPM_CC_ECDH_ZGen |
| 5383 | |
| 5384 | handle of a loaded ECC key |
| 5385 | TPMI_DH_OBJECT @keyHandle Auth Index: 1 |
| 5386 | Auth Role: USER |
| 5387 | |
| 5388 | TPM2B_ECC_POINT inPoint a public key |
| 5389 | |
| 5390 | |
| 5391 | Table 50 — TPM2_ECDH_ZGen Response |
| 5392 | Type Name Description |
| 5393 | |
| 5394 | TPM_ST tag see clause 6 |
| 5395 | UINT32 responseSize |
| 5396 | TPM_RC responseCode |
| 5397 | |
| 5398 | X and Y coordinates of the product of the multiplication |
| 5399 | TPM2B_ECC_POINT outPoint |
| 5400 | Z = (xZ , yZ) ≔ [hdS]QB |
| 5401 | |
| 5402 | |
| 5403 | |
| 5404 | |
| 5405 | Page 108 TCG Published Family “2.0” |
| 5406 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 5407 | Trusted Platform Module Library Part 3: Commands |
| 5408 | |
| 5409 | |
| 5410 | |
| 5411 | 14.5.3 Detailed Actions |
| 5412 | |
| 5413 | 1 #include "InternalRoutines.h" |
| 5414 | 2 #include "ECDH_ZGen_fp.h" |
| 5415 | 3 #ifdef TPM_CC_ECDH_ZGen // Conditional expansion of this file |
| 5416 | 4 #ifdef TPM_ALG_ECC |
| 5417 | |
| 5418 | |
| 5419 | Error Returns Meaning |
| 5420 | |
| 5421 | TPM_RC_ATTRIBUTES key referenced by keyA is restricted or not a decrypt key |
| 5422 | TPM_RC_KEY key referenced by keyA is not an ECC key |
| 5423 | TPM_RC_NO_RESULT multiplying inPoint resulted in a point at infinity |
| 5424 | TPM_RC_SCHEME the scheme of the key referenced by keyA is not TPM_ALG_NULL, |
| 5425 | TPM_ALG_ECDH, |
| 5426 | |
| 5427 | 5 TPM_RC |
| 5428 | 6 TPM2_ECDH_ZGen( |
| 5429 | 7 ECDH_ZGen_In *in, // IN: input parameter list |
| 5430 | 8 ECDH_ZGen_Out *out // OUT: output parameter list |
| 5431 | 9 ) |
| 5432 | 10 { |
| 5433 | 11 TPM_RC result; |
| 5434 | 12 OBJECT *eccKey; |
| 5435 | 13 |
| 5436 | 14 // Input Validation |
| 5437 | 15 |
| 5438 | 16 eccKey = ObjectGet(in->keyHandle); |
| 5439 | 17 |
| 5440 | 18 // Input key must be a non-restricted, decrypt ECC key |
| 5441 | 19 if( eccKey->publicArea.type != TPM_ALG_ECC) |
| 5442 | 20 return TPM_RCS_KEY + RC_ECDH_ZGen_keyHandle; |
| 5443 | 21 |
| 5444 | 22 if( eccKey->publicArea.objectAttributes.restricted == SET |
| 5445 | 23 || eccKey->publicArea.objectAttributes.decrypt != SET |
| 5446 | 24 ) |
| 5447 | 25 return TPM_RC_KEY + RC_ECDH_ZGen_keyHandle; |
| 5448 | 26 |
| 5449 | 27 // Make sure the scheme allows this use |
| 5450 | 28 if( eccKey->publicArea.parameters.eccDetail.scheme.scheme != TPM_ALG_ECDH |
| 5451 | 29 && eccKey->publicArea.parameters.eccDetail.scheme.scheme != TPM_ALG_NULL) |
| 5452 | 30 return TPM_RC_SCHEME + RC_ECDH_ZGen_keyHandle; |
| 5453 | 31 |
| 5454 | 32 // Command Output |
| 5455 | 33 |
| 5456 | 34 // Compute Z. TPM_RC_ECC_POINT or TPM_RC_NO_RESULT may be returned here. |
| 5457 | 35 result = CryptEccPointMultiply(&out->outPoint.t.point, |
| 5458 | 36 eccKey->publicArea.parameters.eccDetail.curveID, |
| 5459 | 37 &eccKey->sensitive.sensitive.ecc, |
| 5460 | 38 &in->inPoint.t.point); |
| 5461 | 39 if(result != TPM_RC_SUCCESS) |
| 5462 | 40 return RcSafeAddToResult(result, RC_ECDH_ZGen_inPoint); |
| 5463 | 41 |
| 5464 | 42 out->outPoint.t.size = TPMS_ECC_POINT_Marshal(&out->outPoint.t.point, |
| 5465 | 43 NULL, NULL); |
| 5466 | 44 |
| 5467 | 45 return TPM_RC_SUCCESS; |
| 5468 | 46 } |
| 5469 | 47 #endif |
| 5470 | 48 #endif // CC_ECDH_ZGen |
| 5471 | |
| 5472 | |
| 5473 | |
| 5474 | Family “2.0” TCG Published Page 109 |
| 5475 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 5476 | Part 3: Commands Trusted Platform Module Library |
| 5477 | |
| 5478 | |
| 5479 | 14.6 TPM2_ECC_Parameters |
| 5480 | |
| 5481 | 14.6.1 General Description |
| 5482 | |
| 5483 | This command returns the parameters of an ECC curve identified by its TCG-assigned curveID. |
| 5484 | |
| 5485 | 14.6.2 Command and Response |
| 5486 | |
| 5487 | Table 51 — TPM2_ECC_Parameters Command |
| 5488 | Type Name Description |
| 5489 | |
| 5490 | TPM_ST_SESSIONS if an audit session is |
| 5491 | TPMI_ST_COMMAND_TAG tag |
| 5492 | present; otherwise, TPM_ST_NO_SESSIONS |
| 5493 | UINT32 commandSize |
| 5494 | TPM_CC commandCode TPM_CC_ECC_Parameters |
| 5495 | |
| 5496 | TPMI_ECC_CURVE curveID parameter set selector |
| 5497 | |
| 5498 | |
| 5499 | Table 52 — TPM2_ECC_Parameters Response |
| 5500 | Type Name Description |
| 5501 | |
| 5502 | TPM_ST tag see clause 6 |
| 5503 | UINT32 responseSize |
| 5504 | TPM_RC responseCode |
| 5505 | |
| 5506 | TPMS_ALGORITHM_DETAIL_ECC parameters ECC parameters for the selected curve |
| 5507 | |
| 5508 | |
| 5509 | |
| 5510 | |
| 5511 | Page 110 TCG Published Family “2.0” |
| 5512 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 5513 | Trusted Platform Module Library Part 3: Commands |
| 5514 | |
| 5515 | |
| 5516 | |
| 5517 | 14.6.3 Detailed Actions |
| 5518 | |
| 5519 | 1 #include "InternalRoutines.h" |
| 5520 | 2 #include "ECC_Parameters_fp.h" |
| 5521 | 3 #ifdef TPM_CC_ECC_Parameters // Conditional expansion of this file |
| 5522 | 4 #ifdef TPM_ALG_ECC |
| 5523 | |
| 5524 | |
| 5525 | Error Returns Meaning |
| 5526 | |
| 5527 | TPM_RC_VALUE Unsupported ECC curve ID |
| 5528 | |
| 5529 | 5 TPM_RC |
| 5530 | 6 TPM2_ECC_Parameters( |
| 5531 | 7 ECC_Parameters_In *in, // IN: input parameter list |
| 5532 | 8 ECC_Parameters_Out *out // OUT: output parameter list |
| 5533 | 9 ) |
| 5534 | 10 { |
| 5535 | 11 // Command Output |
| 5536 | 12 |
| 5537 | 13 // Get ECC curve parameters |
| 5538 | 14 if(CryptEccGetParameters(in->curveID, &out->parameters)) |
| 5539 | 15 return TPM_RC_SUCCESS; |
| 5540 | 16 else |
| 5541 | 17 return TPM_RC_VALUE + RC_ECC_Parameters_curveID; |
| 5542 | 18 } |
| 5543 | 19 #endif |
| 5544 | 20 #endif // CC_ECC_Parameters |
| 5545 | |
| 5546 | |
| 5547 | |
| 5548 | |
| 5549 | Family “2.0” TCG Published Page 111 |
| 5550 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 5551 | Part 3: Commands Trusted Platform Module Library |
| 5552 | |
| 5553 | |
| 5554 | |
| 5555 | |
| 5556 | 14.7 TPM2_ZGen_2Phase |
| 5557 | |
| 5558 | 14.7.1 General Description |
| 5559 | |
| 5560 | This command supports two-phase key exchange protocols. The command is used in combination with |
| 5561 | TPM2_EC_Ephemeral(). TPM2_EC_Ephemeral() generates an ephemeral key and returns the public |
| 5562 | point of that ephemeral key along with a numeric value that allows the TPM to regenerate the associated |
| 5563 | private key. |
| 5564 | The input parameters for this command are a static public key (inQsU), an ephemeral key (inQeU) from |
| 5565 | party B, and the commitCounter returned by TPM2_EC_Ephemeral(). The TPM uses the counter value to |
| 5566 | regenerate the ephemeral private key (de,V) and the associated public key (Qe,V). keyA provides the static |
| 5567 | ephemeral elements ds,V and Qs,V. This provides the two pairs of ephemeral and static keys that are |
| 5568 | required for the schemes supported by this command. |
| 5569 | The TPM will compute Z or Zs and Ze according to the selected scheme. If the scheme is not a two-phase |
| 5570 | key exchange scheme or if the scheme is not supported, the TPM will return TPM_RC_SCHEME. |
| 5571 | It is an error if inQsB or inQeB are not on the curve of keyA (TPM_RC_ECC_POINT). |
| 5572 | |
| 5573 | The two-phase key schemes that were assigned an algorithm ID as of the time of the publication of this |
| 5574 | specification are TPM_ALG_ECDH, TPM_ALG_ECMQV, and TPM_ALG_SM2. |
| 5575 | |
| 5576 | If this command is supported, then support for TPM_ALG_ECDH is required. Support for |
| 5577 | TPM_ALG_ECMQV or TPM_ALG_SM2 is optional. |
| 5578 | |
| 5579 | NOTE 1 If SM2 is supported and this command is supported, then the implementation is required to support |
| 5580 | the key exchange protocol of SM2, part 3. |
| 5581 | |
| 5582 | |
| 5583 | For TPM_ALG_ECDH outZ1 will be Zs and outZ2 will Ze as defined in 6.1.1.2 of SP800-56A. |
| 5584 | |
| 5585 | NOTE 2 An unrestricted decryption key using ECDH may be used in either TPM2_ECDH_ZGen() or |
| 5586 | TPM2_ZGen_2Phase as the computation done with the private part of keyA is the same in both |
| 5587 | cases. |
| 5588 | |
| 5589 | |
| 5590 | For TPM_ALG_ECMQV or TPM_ALG_SM2 outZ1 will be Z and outZ2 will be an Empty Point. |
| 5591 | |
| 5592 | NOTE 3 An Empty Point has two Empty Buffers as coordinates meaning the minimum size value for outZ2 |
| 5593 | will be four. |
| 5594 | |
| 5595 | |
| 5596 | If the input scheme is TPM_ALG_ECDH, then outZ1 will be Zs and outZ2 will be Ze. For schemes like |
| 5597 | MQV (including SM2), outZ1 will contain the computed value and outZ2 will be an Empty Point. |
| 5598 | |
| 5599 | NOTE The Z values returned by the TPM are a full point and not just an x -coordinate. |
| 5600 | |
| 5601 | If a computation of either Z produces the point at infinity, then the corresponding Z value will be an Empty |
| 5602 | Point. |
| 5603 | |
| 5604 | |
| 5605 | |
| 5606 | |
| 5607 | Page 112 TCG Published Family “2.0” |
| 5608 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 5609 | Trusted Platform Module Library Part 3: Commands |
| 5610 | |
| 5611 | |
| 5612 | |
| 5613 | 14.7.2 Command and Response |
| 5614 | |
| 5615 | Table 53 — TPM2_ZGen_2Phase Command |
| 5616 | Type Name Description |
| 5617 | |
| 5618 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 5619 | UINT32 commandSize |
| 5620 | TPM_CC commandCode TPM_CC_ ZGen_2Phase |
| 5621 | |
| 5622 | handle of an unrestricted decryption key ECC |
| 5623 | The private key referenced by this handle is used as dS,A |
| 5624 | TPMI_DH_OBJECT @keyA |
| 5625 | Auth Index: 1 |
| 5626 | Auth Role: USER |
| 5627 | |
| 5628 | TPM2B_ECC_POINT inQsB other party’s static public key (Qs,B = (Xs,B, Ys,B)) |
| 5629 | |
| 5630 | TPM2B_ECC_POINT inQeB other party's ephemeral public key (Qe,B = (Xe,B, Ye,B)) |
| 5631 | TPMI_ECC_KEY_EXCHANGE inScheme the key exchange scheme |
| 5632 | UINT16 counter value returned by TPM2_EC_Ephemeral() |
| 5633 | |
| 5634 | |
| 5635 | Table 54 — TPM2_ZGen_2Phase Response |
| 5636 | Type Name Description |
| 5637 | |
| 5638 | TPM_ST tag |
| 5639 | UINT32 responseSize |
| 5640 | TPM_RC responseCode |
| 5641 | |
| 5642 | X and Y coordinates of the computed value (scheme |
| 5643 | TPM2B_ECC_POINT outZ1 |
| 5644 | dependent) |
| 5645 | X and Y coordinates of the second computed value |
| 5646 | TPM2B_ECC_POINT outZ2 |
| 5647 | (scheme dependent) |
| 5648 | |
| 5649 | |
| 5650 | |
| 5651 | |
| 5652 | Family “2.0” TCG Published Page 113 |
| 5653 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 5654 | Part 3: Commands Trusted Platform Module Library |
| 5655 | |
| 5656 | |
| 5657 | |
| 5658 | 14.7.3 Detailed Actions |
| 5659 | |
| 5660 | 1 #include "InternalRoutines.h" |
| 5661 | 2 #include "ZGen_2Phase_fp.h" |
| 5662 | 3 #ifdef TPM_CC_ZGen_2Phase // Conditional expansion of this file |
| 5663 | |
| 5664 | This command uses the TPM to recover one or two Z values in a two phase key exchange protocol |
| 5665 | |
| 5666 | Error Returns Meaning |
| 5667 | |
| 5668 | TPM_RC_ATTRIBUTES key referenced by keyA is restricted or not a decrypt key |
| 5669 | TPM_RC_ECC_POINT inQsB or inQeB is not on the curve of the key reference by keyA |
| 5670 | TPM_RC_KEY key referenced by keyA is not an ECC key |
| 5671 | TPM_RC_SCHEME the scheme of the key referenced by keyA is not TPM_ALG_NULL, |
| 5672 | TPM_ALG_ECDH, TPM_ALG_ECMQV or TPM_ALG_SM2 |
| 5673 | |
| 5674 | 4 TPM_RC |
| 5675 | 5 TPM2_ZGen_2Phase( |
| 5676 | 6 ZGen_2Phase_In *in, // IN: input parameter list |
| 5677 | 7 ZGen_2Phase_Out *out // OUT: output parameter list |
| 5678 | 8 ) |
| 5679 | 9 { |
| 5680 | 10 TPM_RC result; |
| 5681 | 11 OBJECT *eccKey; |
| 5682 | 12 TPM2B_ECC_PARAMETER r; |
| 5683 | 13 TPM_ALG_ID scheme; |
| 5684 | 14 |
| 5685 | 15 // Input Validation |
| 5686 | 16 |
| 5687 | 17 eccKey = ObjectGet(in->keyA); |
| 5688 | 18 |
| 5689 | 19 // keyA must be an ECC key |
| 5690 | 20 if(eccKey->publicArea.type != TPM_ALG_ECC) |
| 5691 | 21 return TPM_RC_KEY + RC_ZGen_2Phase_keyA; |
| 5692 | 22 |
| 5693 | 23 // keyA must not be restricted and must be a decrypt key |
| 5694 | 24 if( eccKey->publicArea.objectAttributes.restricted == SET |
| 5695 | 25 || eccKey->publicArea.objectAttributes.decrypt != SET |
| 5696 | 26 ) |
| 5697 | 27 return TPM_RC_ATTRIBUTES + RC_ZGen_2Phase_keyA; |
| 5698 | 28 |
| 5699 | 29 // if the scheme of keyA is TPM_ALG_NULL, then use the input scheme; otherwise |
| 5700 | 30 // the input scheme must be the same as the scheme of keyA |
| 5701 | 31 scheme = eccKey->publicArea.parameters.asymDetail.scheme.scheme; |
| 5702 | 32 if(scheme != TPM_ALG_NULL) |
| 5703 | 33 { |
| 5704 | 34 if(scheme != in->inScheme) |
| 5705 | 35 return TPM_RC_SCHEME + RC_ZGen_2Phase_inScheme; |
| 5706 | 36 } |
| 5707 | 37 else |
| 5708 | 38 scheme = in->inScheme; |
| 5709 | 39 if(scheme == TPM_ALG_NULL) |
| 5710 | 40 return TPM_RC_SCHEME + RC_ZGen_2Phase_inScheme; |
| 5711 | 41 |
| 5712 | 42 // Input points must be on the curve of keyA |
| 5713 | 43 if(!CryptEccIsPointOnCurve(eccKey->publicArea.parameters.eccDetail.curveID, |
| 5714 | 44 &in->inQsB.t.point)) |
| 5715 | 45 return TPM_RC_ECC_POINT + RC_ZGen_2Phase_inQsB; |
| 5716 | 46 |
| 5717 | 47 if(!CryptEccIsPointOnCurve(eccKey->publicArea.parameters.eccDetail.curveID, |
| 5718 | 48 &in->inQeB.t.point)) |
| 5719 | |
| 5720 | |
| 5721 | Page 114 TCG Published Family “2.0” |
| 5722 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 5723 | Trusted Platform Module Library Part 3: Commands |
| 5724 | |
| 5725 | 49 return TPM_RC_ECC_POINT + RC_ZGen_2Phase_inQeB; |
| 5726 | 50 |
| 5727 | 51 if(!CryptGenerateR(&r, &in->counter, |
| 5728 | 52 eccKey->publicArea.parameters.eccDetail.curveID, |
| 5729 | 53 NULL)) |
| 5730 | 54 return TPM_RC_VALUE + RC_ZGen_2Phase_counter; |
| 5731 | 55 |
| 5732 | 56 // Command Output |
| 5733 | 57 |
| 5734 | 58 result = CryptEcc2PhaseKeyExchange(&out->outZ1.t.point, |
| 5735 | 59 &out->outZ2.t.point, |
| 5736 | 60 eccKey->publicArea.parameters.eccDetail.curveID, |
| 5737 | 61 scheme, |
| 5738 | 62 &eccKey->sensitive.sensitive.ecc, |
| 5739 | 63 &r, |
| 5740 | 64 &in->inQsB.t.point, |
| 5741 | 65 &in->inQeB.t.point); |
| 5742 | 66 if(result == TPM_RC_SCHEME) |
| 5743 | 67 return TPM_RC_SCHEME + RC_ZGen_2Phase_inScheme; |
| 5744 | 68 |
| 5745 | 69 if(result == TPM_RC_SUCCESS) |
| 5746 | 70 CryptEndCommit(in->counter); |
| 5747 | 71 |
| 5748 | 72 return result; |
| 5749 | 73 } |
| 5750 | 74 #endif |
| 5751 | |
| 5752 | |
| 5753 | |
| 5754 | |
| 5755 | Family “2.0” TCG Published Page 115 |
| 5756 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 5757 | Part 3: Commands Trusted Platform Module Library |
| 5758 | |
| 5759 | |
| 5760 | 15 Symmetric Primitives |
| 5761 | |
| 5762 | 15.1 Introduction |
| 5763 | |
| 5764 | The commands in this clause provide low-level primitives for access to the symmetric algorithms |
| 5765 | implemented in the TPM that operate on blocks of data. These include symmetric encryption and |
| 5766 | decryption as well as hash and HMAC. All of the commands in this group are stateless. That is, they have |
| 5767 | no persistent state that is retained in the TPM when the command is complete. |
| 5768 | For hashing, HMAC, and Events that require large blocks of data with retained state, the sequence |
| 5769 | commands are provided (see clause 1). |
| 5770 | Some of the symmetric encryption/decryption modes use an IV. When an IV is used, it may be an |
| 5771 | initiation value or a chained value from a previous stage. The chaining for each mode is: |
| 5772 | |
| 5773 | |
| 5774 | |
| 5775 | |
| 5776 | Page 116 TCG Published Family “2.0” |
| 5777 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 5778 | Trusted Platform Module Library Part 3: Commands |
| 5779 | |
| 5780 | Table 55 — Symmetric Chaining Process |
| 5781 | Mode Chaining process |
| 5782 | |
| 5783 | TPM_ALG_CTR The TPM will increment the entire IV provided by the caller. The next count value will be |
| 5784 | returned to the caller as ivOut. This can be the input value to the next encrypt or decrypt |
| 5785 | operation. |
| 5786 | ivIn is required to be the size of a block encrypted by the selected algorithm and key |
| 5787 | combination. If the size of ivIn is not correct, the TPM shall return TPM_RC_SIZE. |
| 5788 | EXAMPLE 1 AES requires that ivIn be 128 bits (16 octets). |
| 5789 | ivOut will be the size of a cipher block and not the size of the last encrypted block. |
| 5790 | NOTE ivOut will be the value of the counter after the last block is encrypted. |
| 5791 | 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 |
| 5792 | were encrypted, ivOut will have a value of |
| 5793 | 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0416. |
| 5794 | All the bits of the IV are incremented as if it were an unsigned integer. |
| 5795 | TPM_ALG_OFB In Output Feedback (OFB), the output of the pseudo-random function (the block encryption |
| 5796 | algorithm) is XORed with a plaintext block to produce a ciphertext block. ivOut will be the |
| 5797 | value that was XORed with the last plaintext block. That value can be used as the ivIn for a |
| 5798 | next buffer. |
| 5799 | ivIn is required to be the size of a block encrypted by the selected algorithm and key |
| 5800 | combination. If the size of ivIn is not correct, the TPM shall return TPM_RC_SIZE. |
| 5801 | ivOut will be the size of a cipher block and not the size of the last encrypted block. |
| 5802 | TPM_ALG_CBC For Cipher Block Chaining (CBC), a block of ciphertext is XORed with the next plaintext |
| 5803 | block and that block is encrypted. The encrypted block is then input to the encryption of the |
| 5804 | next block. The last ciphertext block then is used as an IV for the next buffer. |
| 5805 | Even though the last ciphertext block is evident in the encrypted data, it is also returned in |
| 5806 | ivOut. |
| 5807 | ivIn is required to be the size of a block encrypted by the selected algorithm and key |
| 5808 | combination. If the size of ivIn is not correct, the TPM shall return TPM_RC_SIZE. |
| 5809 | inData is required to be an even multiple of the block encrypted by the selected algorithm |
| 5810 | and key combination. If the size of inData is not correct, the TPM shall return |
| 5811 | TPM_RC_SIZE. |
| 5812 | TPM_ALG_CFB Similar to CBC in that the last ciphertext block is an input to the encryption of the next block. |
| 5813 | ivOut will be the value that was XORed with the last plaintext block. That value can be used |
| 5814 | as the ivIn for a next buffer. |
| 5815 | ivIn is required to be the size of a block encrypted by the selected algorithm and key |
| 5816 | combination. If the size of ivIn is not correct, the TPM shall return TPM_RC_SIZE. |
| 5817 | ivOut will be the size of a cipher block and not the size of the last encrypted block. |
| 5818 | TPM_ALG_ECB Electronic Codebook (ECB) has no chaining. Each block of plaintext is encrypted using the |
| 5819 | key. ECB does not support chaining and ivIn shall be the Empty Buffer. ivOut will be the |
| 5820 | Empty Buffer. |
| 5821 | inData is required to be an even multiple of the block encrypted by the selected algorithm |
| 5822 | and key combination. If the size of inData is not correct, the TPM shall return |
| 5823 | TPM_RC_SIZE. |
| 5824 | |
| 5825 | |
| 5826 | |
| 5827 | |
| 5828 | Family “2.0” TCG Published Page 117 |
| 5829 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 5830 | Part 3: Commands Trusted Platform Module Library |
| 5831 | |
| 5832 | |
| 5833 | |
| 5834 | 15.2 TPM2_EncryptDecrypt |
| 5835 | |
| 5836 | 15.2.1 General Description |
| 5837 | |
| 5838 | This command performs symmetric encryption or decryption. |
| 5839 | keyHandle shall reference a symmetric cipher object (TPM_RC_KEY). |
| 5840 | For a restricted key, mode shall be either the same as the mode of the key, or TPM_ALG_NULL |
| 5841 | (TPM_RC_VALUE). For an unrestricted key, mode may be the same or different from the mode of the key |
| 5842 | but both shall not be TPM_ALG_NULL (TPM_RC_VALUE). If different, mode overrides the mode of the |
| 5843 | key. |
| 5844 | If the TPM allows this command to be canceled before completion, then the TPM may produce |
| 5845 | incremental results and return TPM_RC_SUCCESS rather than TPM_RC_CANCELED. In such case, |
| 5846 | outData may be less than inData. |
| 5847 | |
| 5848 | |
| 5849 | |
| 5850 | |
| 5851 | Page 118 TCG Published Family “2.0” |
| 5852 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 5853 | Trusted Platform Module Library Part 3: Commands |
| 5854 | |
| 5855 | |
| 5856 | |
| 5857 | 15.2.2 Command and Response |
| 5858 | |
| 5859 | Table 56 — TPM2_EncryptDecrypt Command |
| 5860 | Type Name Description |
| 5861 | |
| 5862 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 5863 | UINT32 commandSize |
| 5864 | TPM_CC commandCode TPM_CC_EncryptDecrypt |
| 5865 | |
| 5866 | the symmetric key used for the operation |
| 5867 | TPMI_DH_OBJECT @keyHandle Auth Index: 1 |
| 5868 | Auth Role: USER |
| 5869 | |
| 5870 | if YES, then the operation is decryption; if NO, the |
| 5871 | TPMI_YES_NO decrypt |
| 5872 | operation is encryption |
| 5873 | symmetric mode |
| 5874 | TPMI_ALG_SYM_MODE+ mode For a restricted key, this field shall match the default |
| 5875 | mode of the key or be TPM_ALG_NULL. |
| 5876 | TPM2B_IV ivIn an initial value as required by the algorithm |
| 5877 | TPM2B_MAX_BUFFER inData the data to be encrypted/decrypted |
| 5878 | |
| 5879 | |
| 5880 | Table 57 — TPM2_EncryptDecrypt Response |
| 5881 | Type Name Description |
| 5882 | |
| 5883 | TPM_ST tag see clause 6 |
| 5884 | UINT32 responseSize |
| 5885 | TPM_RC responseCode |
| 5886 | |
| 5887 | TPM2B_MAX_BUFFER outData encrypted or decrypted output |
| 5888 | TPM2B_IV ivOut chaining value to use for IV in next round |
| 5889 | |
| 5890 | |
| 5891 | |
| 5892 | |
| 5893 | Family “2.0” TCG Published Page 119 |
| 5894 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 5895 | Part 3: Commands Trusted Platform Module Library |
| 5896 | |
| 5897 | |
| 5898 | |
| 5899 | 15.2.3 Detailed Actions |
| 5900 | |
| 5901 | 1 #include "InternalRoutines.h" |
| 5902 | 2 #include "EncryptDecrypt_fp.h" |
| 5903 | 3 #ifdef TPM_CC_EncryptDecrypt // Conditional expansion of this file |
| 5904 | |
| 5905 | |
| 5906 | Error Returns Meaning |
| 5907 | |
| 5908 | TPM_RC_KEY is not a symmetric decryption key with both public and private |
| 5909 | portions loaded |
| 5910 | TPM_RC_SIZE IvIn size is incompatible with the block cipher mode; or inData size is |
| 5911 | not an even multiple of the block size for CBC or ECB mode |
| 5912 | TPM_RC_VALUE keyHandle is restricted and the argument mode does not match the |
| 5913 | key's mode |
| 5914 | |
| 5915 | 4 TPM_RC |
| 5916 | 5 TPM2_EncryptDecrypt( |
| 5917 | 6 EncryptDecrypt_In *in, // IN: input parameter list |
| 5918 | 7 EncryptDecrypt_Out *out // OUT: output parameter list |
| 5919 | 8 ) |
| 5920 | 9 { |
| 5921 | 10 OBJECT *symKey; |
| 5922 | 11 UINT16 keySize; |
| 5923 | 12 UINT16 blockSize; |
| 5924 | 13 BYTE *key; |
| 5925 | 14 TPM_ALG_ID alg; |
| 5926 | 15 |
| 5927 | 16 // Input Validation |
| 5928 | 17 symKey = ObjectGet(in->keyHandle); |
| 5929 | 18 |
| 5930 | 19 // The input key should be a symmetric decrypt key. |
| 5931 | 20 if( symKey->publicArea.type != TPM_ALG_SYMCIPHER |
| 5932 | 21 || symKey->attributes.publicOnly == SET) |
| 5933 | 22 return TPM_RC_KEY + RC_EncryptDecrypt_keyHandle; |
| 5934 | 23 |
| 5935 | 24 // If the input mode is TPM_ALG_NULL, use the key's mode |
| 5936 | 25 if( in->mode == TPM_ALG_NULL) |
| 5937 | 26 in->mode = symKey->publicArea.parameters.symDetail.sym.mode.sym; |
| 5938 | 27 |
| 5939 | 28 // If the key is restricted, the input symmetric mode should match the key's |
| 5940 | 29 // symmetric mode |
| 5941 | 30 if( symKey->publicArea.objectAttributes.restricted == SET |
| 5942 | 31 && symKey->publicArea.parameters.symDetail.sym.mode.sym != in->mode) |
| 5943 | 32 return TPM_RC_VALUE + RC_EncryptDecrypt_mode; |
| 5944 | 33 |
| 5945 | 34 // If the mode is null, then we have a problem. |
| 5946 | 35 // Note: Construction of a TPMT_SYM_DEF does not allow the 'mode' to be |
| 5947 | 36 // TPM_ALG_NULL so setting in->mode to the mode of the key should have |
| 5948 | 37 // produced a valid mode. However, this is suspenders. |
| 5949 | 38 if(in->mode == TPM_ALG_NULL) |
| 5950 | 39 return TPM_RC_VALUE + RC_EncryptDecrypt_mode; |
| 5951 | 40 |
| 5952 | 41 // The input iv for ECB mode should be null. All the other modes should |
| 5953 | 42 // have an iv size same as encryption block size |
| 5954 | 43 |
| 5955 | 44 keySize = symKey->publicArea.parameters.symDetail.sym.keyBits.sym; |
| 5956 | 45 alg = symKey->publicArea.parameters.symDetail.sym.algorithm; |
| 5957 | 46 blockSize = CryptGetSymmetricBlockSize(alg, keySize); |
| 5958 | 47 if( (in->mode == TPM_ALG_ECB && in->ivIn.t.size != 0) |
| 5959 | 48 || (in->mode != TPM_ALG_ECB && in->ivIn.t.size != blockSize)) |
| 5960 | 49 return TPM_RC_SIZE + RC_EncryptDecrypt_ivIn; |
| 5961 | |
| 5962 | Page 120 TCG Published Family “2.0” |
| 5963 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 5964 | Trusted Platform Module Library Part 3: Commands |
| 5965 | |
| 5966 | 50 |
| 5967 | 51 // The input data size of CBC mode or ECB mode must be an even multiple of |
| 5968 | 52 // the symmetric algorithm's block size |
| 5969 | 53 if( (in->mode == TPM_ALG_CBC || in->mode == TPM_ALG_ECB) |
| 5970 | 54 && (in->inData.t.size % blockSize) != 0) |
| 5971 | 55 return TPM_RC_SIZE + RC_EncryptDecrypt_inData; |
| 5972 | 56 |
| 5973 | 57 // Copy IV |
| 5974 | 58 // Note: This is copied here so that the calls to the encrypt/decrypt functions |
| 5975 | 59 // will modify the output buffer, not the input buffer |
| 5976 | 60 out->ivOut = in->ivIn; |
| 5977 | 61 |
| 5978 | 62 // Command Output |
| 5979 | 63 |
| 5980 | 64 key = symKey->sensitive.sensitive.sym.t.buffer; |
| 5981 | 65 // For symmetric encryption, the cipher data size is the same as plain data |
| 5982 | 66 // size. |
| 5983 | 67 out->outData.t.size = in->inData.t.size; |
| 5984 | 68 if(in->decrypt == YES) |
| 5985 | 69 { |
| 5986 | 70 // Decrypt data to output |
| 5987 | 71 CryptSymmetricDecrypt(out->outData.t.buffer, |
| 5988 | 72 alg, |
| 5989 | 73 keySize, in->mode, key, |
| 5990 | 74 &(out->ivOut), |
| 5991 | 75 in->inData.t.size, |
| 5992 | 76 in->inData.t.buffer); |
| 5993 | 77 } |
| 5994 | 78 else |
| 5995 | 79 { |
| 5996 | 80 // Encrypt data to output |
| 5997 | 81 CryptSymmetricEncrypt(out->outData.t.buffer, |
| 5998 | 82 alg, |
| 5999 | 83 keySize, |
| 6000 | 84 in->mode, key, |
| 6001 | 85 &(out->ivOut), |
| 6002 | 86 in->inData.t.size, |
| 6003 | 87 in->inData.t.buffer); |
| 6004 | 88 } |
| 6005 | 89 |
| 6006 | 90 return TPM_RC_SUCCESS; |
| 6007 | 91 } |
| 6008 | 92 #endif // CC_EncryptDecrypt |
| 6009 | |
| 6010 | |
| 6011 | |
| 6012 | |
| 6013 | Family “2.0” TCG Published Page 121 |
| 6014 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 6015 | Part 3: Commands Trusted Platform Module Library |
| 6016 | |
| 6017 | |
| 6018 | 15.3 TPM2_Hash |
| 6019 | |
| 6020 | 15.3.1 General Description |
| 6021 | |
| 6022 | This command performs a hash operation on a data buffer and returns the results. |
| 6023 | |
| 6024 | NOTE If the data buffer to be hashed is larger than will fit into the TPM’s input buffer, then the sequence |
| 6025 | hash commands will need to be used. |
| 6026 | |
| 6027 | If the results of the hash will be used in a signing operation that uses a restricted signing key, then the |
| 6028 | ticket returned by this command can indicate that the hash is safe to sign. |
| 6029 | If the digest is not safe to sign, then the TPM will return a TPMT_TK_HASHCHECK with the hierarchy set |
| 6030 | to TPM_RH_NULL and digest set to the Empty Buffer. |
| 6031 | If hierarchy is TPM_RH_NULL, then digest in the ticket will be the Empty Buffer. |
| 6032 | |
| 6033 | |
| 6034 | |
| 6035 | |
| 6036 | Page 122 TCG Published Family “2.0” |
| 6037 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 6038 | Trusted Platform Module Library Part 3: Commands |
| 6039 | |
| 6040 | |
| 6041 | |
| 6042 | 15.3.2 Command and Response |
| 6043 | |
| 6044 | Table 58 — TPM2_Hash Command |
| 6045 | Type Name Description |
| 6046 | |
| 6047 | TPM_ST_SESSIONS if an audit, decrypt, or encrypt |
| 6048 | TPMI_ST_COMMAND_TAG tag session is present; otherwise, |
| 6049 | TPM_ST_NO_SESSIONS |
| 6050 | UINT32 commandSize |
| 6051 | TPM_CC commandCode TPM_CC_Hash |
| 6052 | |
| 6053 | TPM2B_MAX_BUFFER data data to be hashed |
| 6054 | algorithm for the hash being computed – shall not be |
| 6055 | TPMI_ALG_HASH hashAlg |
| 6056 | TPM_ALG_NULL |
| 6057 | TPMI_RH_HIERARCHY+ hierarchy hierarchy to use for the ticket (TPM_RH_NULL allowed) |
| 6058 | |
| 6059 | |
| 6060 | Table 59 — TPM2_Hash Response |
| 6061 | Type Name Description |
| 6062 | |
| 6063 | TPM_ST tag see clause 6 |
| 6064 | UINT32 responseSize |
| 6065 | TPM_RC responseCode |
| 6066 | |
| 6067 | TPM2B_DIGEST outHash results |
| 6068 | ticket indicating that the sequence of octets used to |
| 6069 | compute outDigest did not start with |
| 6070 | TPMT_TK_HASHCHECK validation TPM_GENERATED_VALUE |
| 6071 | will be a NULL ticket if the digest may not be signed |
| 6072 | with a restricted key |
| 6073 | |
| 6074 | |
| 6075 | |
| 6076 | |
| 6077 | Family “2.0” TCG Published Page 123 |
| 6078 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 6079 | Part 3: Commands Trusted Platform Module Library |
| 6080 | |
| 6081 | |
| 6082 | |
| 6083 | 15.3.3 Detailed Actions |
| 6084 | |
| 6085 | 1 #include "InternalRoutines.h" |
| 6086 | 2 #include "Hash_fp.h" |
| 6087 | 3 #ifdef TPM_CC_Hash // Conditional expansion of this file |
| 6088 | 4 TPM_RC |
| 6089 | 5 TPM2_Hash( |
| 6090 | 6 Hash_In *in, // IN: input parameter list |
| 6091 | 7 Hash_Out *out // OUT: output parameter list |
| 6092 | 8 ) |
| 6093 | 9 { |
| 6094 | 10 HASH_STATE hashState; |
| 6095 | 11 |
| 6096 | 12 // Command Output |
| 6097 | 13 |
| 6098 | 14 // Output hash |
| 6099 | 15 // Start hash stack |
| 6100 | 16 out->outHash.t.size = CryptStartHash(in->hashAlg, &hashState); |
| 6101 | 17 // Adding hash data |
| 6102 | 18 CryptUpdateDigest2B(&hashState, &in->data.b); |
| 6103 | 19 // Complete hash |
| 6104 | 20 CryptCompleteHash2B(&hashState, &out->outHash.b); |
| 6105 | 21 |
| 6106 | 22 // Output ticket |
| 6107 | 23 out->validation.tag = TPM_ST_HASHCHECK; |
| 6108 | 24 out->validation.hierarchy = in->hierarchy; |
| 6109 | 25 |
| 6110 | 26 if(in->hierarchy == TPM_RH_NULL) |
| 6111 | 27 { |
| 6112 | 28 // Ticket is not required |
| 6113 | 29 out->validation.hierarchy = TPM_RH_NULL; |
| 6114 | 30 out->validation.digest.t.size = 0; |
| 6115 | 31 } |
| 6116 | 32 else if( in->data.t.size >= sizeof(TPM_GENERATED) |
| 6117 | 33 && !TicketIsSafe(&in->data.b)) |
| 6118 | 34 { |
| 6119 | 35 // Ticket is not safe |
| 6120 | 36 out->validation.hierarchy = TPM_RH_NULL; |
| 6121 | 37 out->validation.digest.t.size = 0; |
| 6122 | 38 } |
| 6123 | 39 else |
| 6124 | 40 { |
| 6125 | 41 // Compute ticket |
| 6126 | 42 TicketComputeHashCheck(in->hierarchy, in->hashAlg, |
| 6127 | 43 &out->outHash, &out->validation); |
| 6128 | 44 } |
| 6129 | 45 |
| 6130 | 46 return TPM_RC_SUCCESS; |
| 6131 | 47 } |
| 6132 | 48 #endif // CC_Hash |
| 6133 | |
| 6134 | |
| 6135 | |
| 6136 | |
| 6137 | Page 124 TCG Published Family “2.0” |
| 6138 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 6139 | Trusted Platform Module Library Part 3: Commands |
| 6140 | |
| 6141 | |
| 6142 | 15.4 TPM2_HMAC |
| 6143 | |
| 6144 | 15.4.1 General Description |
| 6145 | |
| 6146 | This command performs an HMAC on the supplied data using the indicated hash algorithm. |
| 6147 | The caller shall provide proper authorization for use of handle. |
| 6148 | If the sign attribute is not SET in the key referenced by handle then the TPM shall return |
| 6149 | TPM_RC_ATTRIBUTES. If the key type is not TPM_ALG_KEYEDHASH then the TPM shall return |
| 6150 | TPM_RC_TYPE. If the key referenced by handle has the restricted attribute SET, the TPM shall return |
| 6151 | TPM_RC_ATTRIBUTES. |
| 6152 | If the default scheme of the key referenced by handle is not TPM_ALG_NULL, then the hashAlg |
| 6153 | parameter is required to be either the same as the key’s default or TPM_ALG_NULL (TPM_RC_VALUE). |
| 6154 | If the default scheme of the key is TPM_ALG_NULL, then hashAlg is required to be a valid hash and not |
| 6155 | TPM_ALG_NULL (TPM_RC_VALUE). (See hash selection matrix in Table 66.) |
| 6156 | |
| 6157 | NOTE A key may only have both sign and decrypt SET if the key is unrestricted. When both sign and |
| 6158 | decrypt are set, there is no default scheme for the ke y and the hash algorithm must be specified. |
| 6159 | |
| 6160 | |
| 6161 | |
| 6162 | |
| 6163 | Family “2.0” TCG Published Page 125 |
| 6164 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 6165 | Part 3: Commands Trusted Platform Module Library |
| 6166 | |
| 6167 | |
| 6168 | 15.4.2 Command and Response |
| 6169 | |
| 6170 | Table 60 — TPM2_HMAC Command |
| 6171 | Type Name Description |
| 6172 | |
| 6173 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 6174 | UINT32 commandSize |
| 6175 | TPM_CC commandCode TPM_CC_HMAC |
| 6176 | |
| 6177 | handle for the symmetric signing key providing the |
| 6178 | HMAC key |
| 6179 | TPMI_DH_OBJECT @handle |
| 6180 | Auth Index: 1 |
| 6181 | Auth Role: USER |
| 6182 | |
| 6183 | TPM2B_MAX_BUFFER buffer HMAC data |
| 6184 | TPMI_ALG_HASH+ hashAlg algorithm to use for HMAC |
| 6185 | |
| 6186 | |
| 6187 | Table 61 — TPM2_HMAC Response |
| 6188 | Type Name Description |
| 6189 | |
| 6190 | TPM_ST tag see clause 6 |
| 6191 | UINT32 responseSize |
| 6192 | TPM_RC responseCode |
| 6193 | |
| 6194 | TPM2B_DIGEST outHMAC the returned HMAC in a sized buffer |
| 6195 | |
| 6196 | |
| 6197 | |
| 6198 | |
| 6199 | Page 126 TCG Published Family “2.0” |
| 6200 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 6201 | Trusted Platform Module Library Part 3: Commands |
| 6202 | |
| 6203 | |
| 6204 | |
| 6205 | 15.4.3 Detailed Actions |
| 6206 | |
| 6207 | 1 #include "InternalRoutines.h" |
| 6208 | 2 #include "HMAC_fp.h" |
| 6209 | 3 #ifdef TPM_CC_HMAC // Conditional expansion of this file |
| 6210 | |
| 6211 | |
| 6212 | Error Returns Meaning |
| 6213 | |
| 6214 | TPM_RC_ATTRIBUTES key referenced by handle is not a signing key or is a restricted key |
| 6215 | TPM_RC_TYPE key referenced by handle is not an HMAC key |
| 6216 | TPM_RC_VALUE hashAlg is not compatible with the hash algorithm of the scheme of |
| 6217 | the object referenced by handle |
| 6218 | |
| 6219 | 4 TPM_RC |
| 6220 | 5 TPM2_HMAC( |
| 6221 | 6 HMAC_In *in, // IN: input parameter list |
| 6222 | 7 HMAC_Out *out // OUT: output parameter list |
| 6223 | 8 ) |
| 6224 | 9 { |
| 6225 | 10 HMAC_STATE hmacState; |
| 6226 | 11 OBJECT *hmacObject; |
| 6227 | 12 TPMI_ALG_HASH hashAlg; |
| 6228 | 13 TPMT_PUBLIC *publicArea; |
| 6229 | 14 |
| 6230 | 15 // Input Validation |
| 6231 | 16 |
| 6232 | 17 // Get HMAC key object and public area pointers |
| 6233 | 18 hmacObject = ObjectGet(in->handle); |
| 6234 | 19 publicArea = &hmacObject->publicArea; |
| 6235 | 20 |
| 6236 | 21 // Make sure that the key is an HMAC key |
| 6237 | 22 if(publicArea->type != TPM_ALG_KEYEDHASH) |
| 6238 | 23 return TPM_RCS_TYPE + RC_HMAC_handle; |
| 6239 | 24 |
| 6240 | 25 // and that it is unrestricted |
| 6241 | 26 if(publicArea->objectAttributes.restricted == SET) |
| 6242 | 27 return TPM_RCS_ATTRIBUTES + RC_HMAC_handle; |
| 6243 | 28 |
| 6244 | 29 // and that it is a signing key |
| 6245 | 30 if(publicArea->objectAttributes.sign != SET) |
| 6246 | 31 return TPM_RCS_KEY + RC_HMAC_handle; |
| 6247 | 32 |
| 6248 | 33 // See if the key has a default |
| 6249 | 34 if(publicArea->parameters.keyedHashDetail.scheme.scheme == TPM_ALG_NULL) |
| 6250 | 35 // it doesn't so use the input value |
| 6251 | 36 hashAlg = in->hashAlg; |
| 6252 | 37 else |
| 6253 | 38 { |
| 6254 | 39 // key has a default so use it |
| 6255 | 40 hashAlg |
| 6256 | 41 = publicArea->parameters.keyedHashDetail.scheme.details.hmac.hashAlg; |
| 6257 | 42 // and verify that the input was either the TPM_ALG_NULL or the default |
| 6258 | 43 if(in->hashAlg != TPM_ALG_NULL && in->hashAlg != hashAlg) |
| 6259 | 44 hashAlg = TPM_ALG_NULL; |
| 6260 | 45 } |
| 6261 | 46 // if we ended up without a hash algorith then return an error |
| 6262 | 47 if(hashAlg == TPM_ALG_NULL) |
| 6263 | 48 return TPM_RCS_VALUE + RC_HMAC_hashAlg; |
| 6264 | 49 |
| 6265 | 50 // Command Output |
| 6266 | 51 |
| 6267 | |
| 6268 | Family “2.0” TCG Published Page 127 |
| 6269 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 6270 | Part 3: Commands Trusted Platform Module Library |
| 6271 | |
| 6272 | 52 // Start HMAC stack |
| 6273 | 53 out->outHMAC.t.size = CryptStartHMAC2B(hashAlg, |
| 6274 | 54 &hmacObject->sensitive.sensitive.bits.b, |
| 6275 | 55 &hmacState); |
| 6276 | 56 // Adding HMAC data |
| 6277 | 57 CryptUpdateDigest2B(&hmacState, &in->buffer.b); |
| 6278 | 58 |
| 6279 | 59 // Complete HMAC |
| 6280 | 60 CryptCompleteHMAC2B(&hmacState, &out->outHMAC.b); |
| 6281 | 61 |
| 6282 | 62 return TPM_RC_SUCCESS; |
| 6283 | 63 } |
| 6284 | 64 #endif // CC_HMAC |
| 6285 | |
| 6286 | |
| 6287 | |
| 6288 | |
| 6289 | Page 128 TCG Published Family “2.0” |
| 6290 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 6291 | Trusted Platform Module Library Part 3: Commands |
| 6292 | |
| 6293 | |
| 6294 | 16 Random Number Generator |
| 6295 | |
| 6296 | 16.1 TPM2_GetRandom |
| 6297 | |
| 6298 | 16.1.1 General Description |
| 6299 | |
| 6300 | This command returns the next bytesRequested octets from the random number generator (RNG). |
| 6301 | |
| 6302 | NOTE 1 It is recommended that a TPM implement the RNG in a manner that would allow it to return RNG |
| 6303 | octets such that, as long as the value of bytesRequested is not greater than the maximum digest |
| 6304 | size, the frequency of bytesRequested being more than the number of octets available is an |
| 6305 | infrequent occurrence. |
| 6306 | |
| 6307 | If bytesRequested is more than will fit into a TPM2B_DIGEST on the TPM, no error is returned but the |
| 6308 | TPM will only return as much data as will fit into a TPM2B_DIGEST buffer for the TPM. |
| 6309 | |
| 6310 | NOTE 2 TPM2B_DIGEST is large enough to hold the largest dig est that may be produced by the TPM. |
| 6311 | Because that digest size changes according to the implemented hashes, the maximum amount of |
| 6312 | data returned by this command is TPM implementation-dependent. |
| 6313 | |
| 6314 | |
| 6315 | |
| 6316 | |
| 6317 | Family “2.0” TCG Published Page 129 |
| 6318 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 6319 | Part 3: Commands Trusted Platform Module Library |
| 6320 | |
| 6321 | |
| 6322 | 16.1.2 Command and Response |
| 6323 | |
| 6324 | Table 62 — TPM2_GetRandom Command |
| 6325 | Type Name Description |
| 6326 | |
| 6327 | TPM_ST_SESSIONS if an audit or encrypt session is |
| 6328 | TPMI_ST_COMMAND_TAG tag |
| 6329 | present; otherwise, TPM_ST_NO_SESSIONS |
| 6330 | UINT32 commandSize |
| 6331 | TPM_CC commandCode TPM_CC_GetRandom |
| 6332 | |
| 6333 | UINT16 bytesRequested number of octets to return |
| 6334 | |
| 6335 | |
| 6336 | Table 63 — TPM2_GetRandom Response |
| 6337 | Type Name Description |
| 6338 | |
| 6339 | TPM_ST tag see clause 6 |
| 6340 | UINT32 responseSize |
| 6341 | TPM_RC responseCode |
| 6342 | |
| 6343 | TPM2B_DIGEST randomBytes the random octets |
| 6344 | |
| 6345 | |
| 6346 | |
| 6347 | |
| 6348 | Page 130 TCG Published Family “2.0” |
| 6349 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 6350 | Trusted Platform Module Library Part 3: Commands |
| 6351 | |
| 6352 | |
| 6353 | |
| 6354 | 16.1.3 Detailed Actions |
| 6355 | |
| 6356 | 1 #include "InternalRoutines.h" |
| 6357 | 2 #include "GetRandom_fp.h" |
| 6358 | 3 #ifdef TPM_CC_GetRandom // Conditional expansion of this file |
| 6359 | 4 TPM_RC |
| 6360 | 5 TPM2_GetRandom( |
| 6361 | 6 GetRandom_In *in, // IN: input parameter list |
| 6362 | 7 GetRandom_Out *out // OUT: output parameter list |
| 6363 | 8 ) |
| 6364 | 9 { |
| 6365 | 10 // Command Output |
| 6366 | 11 |
| 6367 | 12 // if the requested bytes exceed the output buffer size, generates the |
| 6368 | 13 // maximum bytes that the output buffer allows |
| 6369 | 14 if(in->bytesRequested > sizeof(TPMU_HA)) |
| 6370 | 15 out->randomBytes.t.size = sizeof(TPMU_HA); |
| 6371 | 16 else |
| 6372 | 17 out->randomBytes.t.size = in->bytesRequested; |
| 6373 | 18 |
| 6374 | 19 CryptGenerateRandom(out->randomBytes.t.size, out->randomBytes.t.buffer); |
| 6375 | 20 |
| 6376 | 21 return TPM_RC_SUCCESS; |
| 6377 | 22 } |
| 6378 | 23 #endif // CC_GetRandom |
| 6379 | |
| 6380 | |
| 6381 | |
| 6382 | |
| 6383 | Family “2.0” TCG Published Page 131 |
| 6384 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 6385 | Part 3: Commands Trusted Platform Module Library |
| 6386 | |
| 6387 | |
| 6388 | 16.2 TPM2_StirRandom |
| 6389 | |
| 6390 | 16.2.1 General Description |
| 6391 | |
| 6392 | This command is used to add "additional information" to the RNG state. |
| 6393 | |
| 6394 | NOTE The "additional information" is as defined in SP800 -90A. |
| 6395 | |
| 6396 | The inData parameter may not be larger than 128 octets. |
| 6397 | |
| 6398 | |
| 6399 | |
| 6400 | |
| 6401 | Page 132 TCG Published Family “2.0” |
| 6402 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 6403 | Trusted Platform Module Library Part 3: Commands |
| 6404 | |
| 6405 | |
| 6406 | |
| 6407 | 16.2.2 Command and Response |
| 6408 | |
| 6409 | Table 64 — TPM2_StirRandom Command |
| 6410 | Type Name Description |
| 6411 | |
| 6412 | TPM_ST_SESSIONS if an audit or decrypt session is |
| 6413 | TPMI_ST_COMMAND_TAG tag |
| 6414 | present; otherwise, TPM_ST_NO_SESSIONS |
| 6415 | UINT32 commandSize |
| 6416 | TPM_CC commandCode TPM_CC_StirRandom {NV} |
| 6417 | |
| 6418 | TPM2B_SENSITIVE_DATA inData additional information |
| 6419 | |
| 6420 | |
| 6421 | Table 65 — TPM2_StirRandom Response |
| 6422 | Type Name Description |
| 6423 | |
| 6424 | TPM_ST tag see clause 6 |
| 6425 | UINT32 responseSize |
| 6426 | TPM_RC responseCode |
| 6427 | |
| 6428 | |
| 6429 | |
| 6430 | |
| 6431 | Family “2.0” TCG Published Page 133 |
| 6432 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 6433 | Part 3: Commands Trusted Platform Module Library |
| 6434 | |
| 6435 | |
| 6436 | |
| 6437 | 16.2.3 Detailed Actions |
| 6438 | |
| 6439 | 1 #include "InternalRoutines.h" |
| 6440 | 2 #include "StirRandom_fp.h" |
| 6441 | 3 #ifdef TPM_CC_StirRandom // Conditional expansion of this file |
| 6442 | 4 TPM_RC |
| 6443 | 5 TPM2_StirRandom( |
| 6444 | 6 StirRandom_In *in // IN: input parameter list |
| 6445 | 7 ) |
| 6446 | 8 { |
| 6447 | 9 // Internal Data Update |
| 6448 | 10 CryptStirRandom(in->inData.t.size, in->inData.t.buffer); |
| 6449 | 11 |
| 6450 | 12 return TPM_RC_SUCCESS; |
| 6451 | 13 } |
| 6452 | 14 #endif // CC_StirRandom |
| 6453 | |
| 6454 | |
| 6455 | |
| 6456 | |
| 6457 | Page 134 TCG Published Family “2.0” |
| 6458 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 6459 | Trusted Platform Module Library Part 3: Commands |
| 6460 | |
| 6461 | |
| 6462 | 17 Hash/HMAC/Event Sequences |
| 6463 | |
| 6464 | 17.1 Introduction |
| 6465 | |
| 6466 | All of the commands in this group are to support sequences for which an intermediate state must be |
| 6467 | maintained. For a description of sequences, see “Hash, HMAC, and Event Sequences” in TPM 2.0 Part 1. |
| 6468 | |
| 6469 | 17.2 TPM2_HMAC_Start |
| 6470 | |
| 6471 | 17.2.1 General Description |
| 6472 | |
| 6473 | This command starts an HMAC sequence. The TPM will create and initialize an HMAC sequence |
| 6474 | structure, assign a handle to the sequence, and set the authValue of the sequence object to the value in |
| 6475 | auth. |
| 6476 | |
| 6477 | NOTE The structure of a sequence object is vendor -dependent. |
| 6478 | |
| 6479 | The caller shall provide proper authorization for use of handle. |
| 6480 | If the sign attribute is not SET in the key referenced by handle then the TPM shall return |
| 6481 | TPM_RC_ATTRIBUTES. If the key type is not TPM_ALG_KEYEDHASH then the TPM shall return |
| 6482 | TPM_RC_TYPE. If the key referenced by handle has the restricted attribute SET, the TPM shall return |
| 6483 | TPM_RC_ATTRIBUTES. |
| 6484 | If the default scheme of the key referenced by handle is not TPM_ALG_NULL, then the hashAlg |
| 6485 | parameter is required to be either the same as the key’s default or TPM_ALG_NULL (TPM_RC_VALUE). |
| 6486 | If the default scheme of the key is TPM_ALG_NULL, then hashAlg is required to be a valid hash and not |
| 6487 | TPM_ALG_NULL (TPM_RC_VALUE). |
| 6488 | |
| 6489 | Table 66 — Hash Selection Matrix |
| 6490 | handle→restricted handle→scheme |
| 6491 | (key's restricted (hash algorithm |
| 6492 | attribute) from key's scheme) hashAlg hash used |
| 6493 | (1) (1) |
| 6494 | CLEAR (unrestricted) TPM_ALG_NULL TPM_ALG_NULL error (TPM_RC_VALUE) |
| 6495 | CLEAR TPM_ALG_NULL valid hash hashAlg |
| 6496 | CLEAR valid hash TPM_ALG_NULL or same as handle→scheme |
| 6497 | handle→scheme |
| 6498 | SET (restricted) don't care don't care TPM_RC_ATTRIBUTES |
| 6499 | NOTES: |
| 6500 | 1) A hash algorithm is required for the HMAC. |
| 6501 | |
| 6502 | |
| 6503 | |
| 6504 | |
| 6505 | Family “2.0” TCG Published Page 135 |
| 6506 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 6507 | Part 3: Commands Trusted Platform Module Library |
| 6508 | |
| 6509 | |
| 6510 | |
| 6511 | 17.2.2 Command and Response |
| 6512 | |
| 6513 | Table 67 — TPM2_HMAC_Start Command |
| 6514 | Type Name Description |
| 6515 | |
| 6516 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 6517 | UINT32 commandSize |
| 6518 | TPM_CC commandCode TPM_CC_HMAC_Start |
| 6519 | |
| 6520 | handle of an HMAC key |
| 6521 | TPMI_DH_OBJECT @handle Auth Index: 1 |
| 6522 | Auth Role: USER |
| 6523 | |
| 6524 | TPM2B_AUTH auth authorization value for subsequent use of the sequence |
| 6525 | TPMI_ALG_HASH+ hashAlg the hash algorithm to use for the HMAC |
| 6526 | |
| 6527 | |
| 6528 | Table 68 — TPM2_HMAC_Start Response |
| 6529 | Type Name Description |
| 6530 | |
| 6531 | TPM_ST tag see clause 6 |
| 6532 | UINT32 responseSize |
| 6533 | TPM_RC responseCode |
| 6534 | |
| 6535 | TPMI_DH_OBJECT sequenceHandle a handle to reference the sequence |
| 6536 | |
| 6537 | |
| 6538 | |
| 6539 | |
| 6540 | Page 136 TCG Published Family “2.0” |
| 6541 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 6542 | Trusted Platform Module Library Part 3: Commands |
| 6543 | |
| 6544 | |
| 6545 | |
| 6546 | 17.2.3 Detailed Actions |
| 6547 | |
| 6548 | 1 #include "InternalRoutines.h" |
| 6549 | 2 #include "HMAC_Start_fp.h" |
| 6550 | 3 #ifdef TPM_CC_HMAC_Start // Conditional expansion of this file |
| 6551 | |
| 6552 | |
| 6553 | Error Returns Meaning |
| 6554 | |
| 6555 | TPM_RC_ATTRIBUTES key referenced by handle is not a signing key or is restricted |
| 6556 | TPM_RC_OBJECT_MEMORY no space to create an internal object |
| 6557 | TPM_RC_KEY key referenced by handle is not an HMAC key |
| 6558 | TPM_RC_VALUE hashAlg is not compatible with the hash algorithm of the scheme of |
| 6559 | the object referenced by handle |
| 6560 | |
| 6561 | 4 TPM_RC |
| 6562 | 5 TPM2_HMAC_Start( |
| 6563 | 6 HMAC_Start_In *in, // IN: input parameter list |
| 6564 | 7 HMAC_Start_Out *out // OUT: output parameter list |
| 6565 | 8 ) |
| 6566 | 9 { |
| 6567 | 10 OBJECT *hmacObject; |
| 6568 | 11 TPMT_PUBLIC *publicArea; |
| 6569 | 12 TPM_ALG_ID hashAlg; |
| 6570 | 13 |
| 6571 | 14 // Input Validation |
| 6572 | 15 |
| 6573 | 16 // Get HMAC key object and public area pointers |
| 6574 | 17 hmacObject = ObjectGet(in->handle); |
| 6575 | 18 publicArea = &hmacObject->publicArea; |
| 6576 | 19 |
| 6577 | 20 // Make sure that the key is an HMAC key |
| 6578 | 21 if(publicArea->type != TPM_ALG_KEYEDHASH) |
| 6579 | 22 return TPM_RCS_TYPE + RC_HMAC_Start_handle; |
| 6580 | 23 |
| 6581 | 24 // and that it is unrestricted |
| 6582 | 25 if(publicArea->objectAttributes.restricted == SET) |
| 6583 | 26 return TPM_RCS_ATTRIBUTES + RC_HMAC_Start_handle; |
| 6584 | 27 |
| 6585 | 28 // and that it is a signing key |
| 6586 | 29 if(publicArea->objectAttributes.sign != SET) |
| 6587 | 30 return TPM_RCS_KEY + RC_HMAC_Start_handle; |
| 6588 | 31 |
| 6589 | 32 // See if the key has a default |
| 6590 | 33 if(publicArea->parameters.keyedHashDetail.scheme.scheme == TPM_ALG_NULL) |
| 6591 | 34 // it doesn't so use the input value |
| 6592 | 35 hashAlg = in->hashAlg; |
| 6593 | 36 else |
| 6594 | 37 { |
| 6595 | 38 // key has a default so use it |
| 6596 | 39 hashAlg |
| 6597 | 40 = publicArea->parameters.keyedHashDetail.scheme.details.hmac.hashAlg; |
| 6598 | 41 // and verify that the input was either the TPM_ALG_NULL or the default |
| 6599 | 42 if(in->hashAlg != TPM_ALG_NULL && in->hashAlg != hashAlg) |
| 6600 | 43 hashAlg = TPM_ALG_NULL; |
| 6601 | 44 } |
| 6602 | 45 // if we ended up without a hash algorith then return an error |
| 6603 | 46 if(hashAlg == TPM_ALG_NULL) |
| 6604 | 47 return TPM_RCS_VALUE + RC_HMAC_Start_hashAlg; |
| 6605 | 48 |
| 6606 | 49 // Internal Data Update |
| 6607 | 50 |
| 6608 | |
| 6609 | Family “2.0” TCG Published Page 137 |
| 6610 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 6611 | Part 3: Commands Trusted Platform Module Library |
| 6612 | |
| 6613 | 51 // Create a HMAC sequence object. A TPM_RC_OBJECT_MEMORY error may be |
| 6614 | 52 // returned at this point |
| 6615 | 53 return ObjectCreateHMACSequence(hashAlg, |
| 6616 | 54 in->handle, |
| 6617 | 55 &in->auth, |
| 6618 | 56 &out->sequenceHandle); |
| 6619 | 57 } |
| 6620 | 58 #endif // CC_HMAC_Start |
| 6621 | |
| 6622 | |
| 6623 | |
| 6624 | |
| 6625 | Page 138 TCG Published Family “2.0” |
| 6626 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 6627 | Trusted Platform Module Library Part 3: Commands |
| 6628 | |
| 6629 | |
| 6630 | 17.3 TPM2_HashSequenceStart |
| 6631 | |
| 6632 | 17.3.1 General Description |
| 6633 | |
| 6634 | This command starts a hash or an Event Sequence. If hashAlg is an implemented hash, then a hash |
| 6635 | sequence is started. If hashAlg is TPM_ALG_NULL, then an Event Sequence is started. If hashAlg is |
| 6636 | neither an implemented algorithm nor TPM_ALG_NULL, then the TPM shall return TPM_RC_HASH. |
| 6637 | Depending on hashAlg, the TPM will create and initialize a Hash Sequence context or an Event |
| 6638 | Sequence context. Additionally, it will assign a handle to the context and set the authValue of the context |
| 6639 | to the value in auth. A sequence context for an Event (hashAlg = TPM_ALG_NULL) contains a hash |
| 6640 | context for each of the PCR banks implemented on the TPM. |
| 6641 | |
| 6642 | |
| 6643 | |
| 6644 | |
| 6645 | Family “2.0” TCG Published Page 139 |
| 6646 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 6647 | Part 3: Commands Trusted Platform Module Library |
| 6648 | |
| 6649 | |
| 6650 | |
| 6651 | 17.3.2 Command and Response |
| 6652 | |
| 6653 | Table 69 — TPM2_HashSequenceStart Command |
| 6654 | Type Name Description |
| 6655 | |
| 6656 | TPM_ST_SESSIONS if an audit or decrypt session is |
| 6657 | TPMI_ST_COMMAND_TAG tag |
| 6658 | present; otherwise, TPM_ST_NO_SESSIONS |
| 6659 | UINT32 commandSize |
| 6660 | TPM_CC commandCode TPM_CC_HashSequenceStart |
| 6661 | |
| 6662 | TPM2B_AUTH auth authorization value for subsequent use of the sequence |
| 6663 | the hash algorithm to use for the hash sequence |
| 6664 | TPMI_ALG_HASH+ hashAlg |
| 6665 | An Event Sequence starts if this is TPM_ALG_NULL. |
| 6666 | |
| 6667 | |
| 6668 | Table 70 — TPM2_HashSequenceStart Response |
| 6669 | Type Name Description |
| 6670 | |
| 6671 | TPM_ST tag see clause 6 |
| 6672 | UINT32 responseSize |
| 6673 | TPM_RC responseCode |
| 6674 | |
| 6675 | TPMI_DH_OBJECT sequenceHandle a handle to reference the sequence |
| 6676 | |
| 6677 | |
| 6678 | |
| 6679 | |
| 6680 | Page 140 TCG Published Family “2.0” |
| 6681 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 6682 | Trusted Platform Module Library Part 3: Commands |
| 6683 | |
| 6684 | |
| 6685 | |
| 6686 | 17.3.3 Detailed Actions |
| 6687 | |
| 6688 | 1 #include "InternalRoutines.h" |
| 6689 | 2 #include "HashSequenceStart_fp.h" |
| 6690 | 3 #ifdef TPM_CC_HashSequenceStart // Conditional expansion of this file |
| 6691 | |
| 6692 | |
| 6693 | Error Returns Meaning |
| 6694 | |
| 6695 | TPM_RC_OBJECT_MEMORY no space to create an internal object |
| 6696 | |
| 6697 | 4 TPM_RC |
| 6698 | 5 TPM2_HashSequenceStart( |
| 6699 | 6 HashSequenceStart_In *in, // IN: input parameter list |
| 6700 | 7 HashSequenceStart_Out *out // OUT: output parameter list |
| 6701 | 8 ) |
| 6702 | 9 { |
| 6703 | 10 // Internal Data Update |
| 6704 | 11 |
| 6705 | 12 if(in->hashAlg == TPM_ALG_NULL) |
| 6706 | 13 // Start a event sequence. A TPM_RC_OBJECT_MEMORY error may be |
| 6707 | 14 // returned at this point |
| 6708 | 15 return ObjectCreateEventSequence(&in->auth, &out->sequenceHandle); |
| 6709 | 16 |
| 6710 | 17 // Start a hash sequence. A TPM_RC_OBJECT_MEMORY error may be |
| 6711 | 18 // returned at this point |
| 6712 | 19 return ObjectCreateHashSequence(in->hashAlg, &in->auth, &out->sequenceHandle); |
| 6713 | 20 } |
| 6714 | 21 #endif // CC_HashSequenceStart |
| 6715 | |
| 6716 | |
| 6717 | |
| 6718 | |
| 6719 | Family “2.0” TCG Published Page 141 |
| 6720 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 6721 | Part 3: Commands Trusted Platform Module Library |
| 6722 | |
| 6723 | |
| 6724 | 17.4 TPM2_SequenceUpdate |
| 6725 | |
| 6726 | 17.4.1 General Description |
| 6727 | |
| 6728 | This command is used to add data to a hash or HMAC sequence. The amount of data in buffer may be |
| 6729 | any size up to the limits of the TPM. |
| 6730 | |
| 6731 | NOTE 1 In all TPM, a buffer size of 1,024 octets is allowed. |
| 6732 | |
| 6733 | Proper authorization for the sequence object associated with sequenceHandle is required. If an |
| 6734 | authorization or audit of this command requires computation of a cpHash and an rpHash, the Name |
| 6735 | associated with sequenceHandle will be the Empty Buffer. |
| 6736 | If the command does not return TPM_RC_SUCCESS, the state of the sequence is unmodified. |
| 6737 | If the sequence is intended to produce a digest that will be signed by a restricted signing key, then the |
| 6738 | first block of data shall contain sizeof(TPM_GENERATED) octets and the first octets shall not be |
| 6739 | TPM_GENERATED_VALUE. |
| 6740 | |
| 6741 | NOTE 2 This requirement allows the TPM to validate that the first block is safe to sign without having to |
| 6742 | accumulate octets over multiple calls. |
| 6743 | |
| 6744 | |
| 6745 | |
| 6746 | |
| 6747 | Page 142 TCG Published Family “2.0” |
| 6748 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 6749 | Trusted Platform Module Library Part 3: Commands |
| 6750 | |
| 6751 | |
| 6752 | 17.4.2 Command and Response |
| 6753 | |
| 6754 | Table 71 — TPM2_SequenceUpdate Command |
| 6755 | Type Name Description |
| 6756 | |
| 6757 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 6758 | UINT32 commandSize |
| 6759 | TPM_CC commandCode TPM_CC_SequenceUpdate |
| 6760 | |
| 6761 | handle for the sequence object |
| 6762 | TPMI_DH_OBJECT @sequenceHandle Auth Index: 1 |
| 6763 | Auth Role: USER |
| 6764 | |
| 6765 | TPM2B_MAX_BUFFER buffer data to be added to hash |
| 6766 | |
| 6767 | |
| 6768 | Table 72 — TPM2_SequenceUpdate Response |
| 6769 | Type Name Description |
| 6770 | |
| 6771 | TPM_ST tag see clause 6 |
| 6772 | UINT32 responseSize |
| 6773 | TPM_RC responseCode |
| 6774 | |
| 6775 | |
| 6776 | |
| 6777 | |
| 6778 | Family “2.0” TCG Published Page 143 |
| 6779 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 6780 | Part 3: Commands Trusted Platform Module Library |
| 6781 | |
| 6782 | |
| 6783 | |
| 6784 | 17.4.3 Detailed Actions |
| 6785 | |
| 6786 | 1 #include "InternalRoutines.h" |
| 6787 | 2 #include "SequenceUpdate_fp.h" |
| 6788 | 3 #ifdef TPM_CC_SequenceUpdate // Conditional expansion of this file |
| 6789 | |
| 6790 | |
| 6791 | Error Returns Meaning |
| 6792 | |
| 6793 | TPM_RC_MODE sequenceHandle does not reference a hash or HMAC sequence |
| 6794 | object |
| 6795 | |
| 6796 | 4 TPM_RC |
| 6797 | 5 TPM2_SequenceUpdate( |
| 6798 | 6 SequenceUpdate_In *in // IN: input parameter list |
| 6799 | 7 ) |
| 6800 | 8 { |
| 6801 | 9 OBJECT *object; |
| 6802 | 10 |
| 6803 | 11 // Input Validation |
| 6804 | 12 |
| 6805 | 13 // Get sequence object pointer |
| 6806 | 14 object = ObjectGet(in->sequenceHandle); |
| 6807 | 15 |
| 6808 | 16 // Check that referenced object is a sequence object. |
| 6809 | 17 if(!ObjectIsSequence(object)) |
| 6810 | 18 return TPM_RC_MODE + RC_SequenceUpdate_sequenceHandle; |
| 6811 | 19 |
| 6812 | 20 // Internal Data Update |
| 6813 | 21 |
| 6814 | 22 if(object->attributes.eventSeq == SET) |
| 6815 | 23 { |
| 6816 | 24 // Update event sequence object |
| 6817 | 25 UINT32 i; |
| 6818 | 26 HASH_OBJECT *hashObject = (HASH_OBJECT *)object; |
| 6819 | 27 for(i = 0; i < HASH_COUNT; i++) |
| 6820 | 28 { |
| 6821 | 29 // Update sequence object |
| 6822 | 30 CryptUpdateDigest2B(&hashObject->state.hashState[i], &in->buffer.b); |
| 6823 | 31 } |
| 6824 | 32 } |
| 6825 | 33 else |
| 6826 | 34 { |
| 6827 | 35 HASH_OBJECT *hashObject = (HASH_OBJECT *)object; |
| 6828 | 36 |
| 6829 | 37 // Update hash/HMAC sequence object |
| 6830 | 38 if(hashObject->attributes.hashSeq == SET) |
| 6831 | 39 { |
| 6832 | 40 // Is this the first block of the sequence |
| 6833 | 41 if(hashObject->attributes.firstBlock == CLEAR) |
| 6834 | 42 { |
| 6835 | 43 // If so, indicate that first block was received |
| 6836 | 44 hashObject->attributes.firstBlock = SET; |
| 6837 | 45 |
| 6838 | 46 // Check the first block to see if the first block can contain |
| 6839 | 47 // the TPM_GENERATED_VALUE. If it does, it is not safe for |
| 6840 | 48 // a ticket. |
| 6841 | 49 if(TicketIsSafe(&in->buffer.b)) |
| 6842 | 50 hashObject->attributes.ticketSafe = SET; |
| 6843 | 51 } |
| 6844 | 52 // Update sequence object hash/HMAC stack |
| 6845 | 53 CryptUpdateDigest2B(&hashObject->state.hashState[0], &in->buffer.b); |
| 6846 | 54 |
| 6847 | 55 } |
| 6848 | |
| 6849 | Page 144 TCG Published Family “2.0” |
| 6850 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 6851 | Trusted Platform Module Library Part 3: Commands |
| 6852 | |
| 6853 | 56 else if(object->attributes.hmacSeq == SET) |
| 6854 | 57 { |
| 6855 | 58 HASH_OBJECT *hashObject = (HASH_OBJECT *)object; |
| 6856 | 59 |
| 6857 | 60 // Update sequence object hash/HMAC stack |
| 6858 | 61 CryptUpdateDigest2B(&hashObject->state.hmacState, &in->buffer.b); |
| 6859 | 62 } |
| 6860 | 63 } |
| 6861 | 64 |
| 6862 | 65 return TPM_RC_SUCCESS; |
| 6863 | 66 } |
| 6864 | 67 #endif // CC_SequenceUpdate |
| 6865 | |
| 6866 | |
| 6867 | |
| 6868 | |
| 6869 | Family “2.0” TCG Published Page 145 |
| 6870 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 6871 | Part 3: Commands Trusted Platform Module Library |
| 6872 | |
| 6873 | |
| 6874 | 17.5 TPM2_SequenceComplete |
| 6875 | |
| 6876 | 17.5.1 General Description |
| 6877 | |
| 6878 | This command adds the last part of data, if any, to a hash/HMAC sequence and returns the result. |
| 6879 | |
| 6880 | NOTE 1 This command is not used to complete an Event Sequence. TPM2_EventSequenceComplete() is |
| 6881 | used for that purpose. |
| 6882 | |
| 6883 | For a hash sequence, if the results of the hash will be used in a signing operation that uses a restricted |
| 6884 | signing key, then the ticket returned by this command can indicate that the hash is safe to sign. |
| 6885 | If the digest is not safe to sign, then validation will be a TPMT_TK_HASHCHECK with the hierarchy set to |
| 6886 | TPM_RH_NULL and digest set to the Empty Buffer. |
| 6887 | |
| 6888 | NOTE 2 Regardless of the contents of the first octets of the hashed message, if the first buffer sent to the |
| 6889 | TPM had fewer than sizeof(TPM_GENERATED) octets, then the TPM will operate as if digest is not |
| 6890 | safe to sign. |
| 6891 | |
| 6892 | NOTE 3 The ticket is only required for a signing operation that uses a restricted signing key. It is always |
| 6893 | returned, but can be ignored if not needed. |
| 6894 | |
| 6895 | If sequenceHandle references an Event Sequence, then the TPM shall return TPM_RC_MODE. |
| 6896 | Proper authorization for the sequence object associated with sequenceHandle is required. If an |
| 6897 | authorization or audit of this command requires computation of a cpHash and an rpHash, the Name |
| 6898 | associated with sequenceHandle will be the Empty Buffer. |
| 6899 | If this command completes successfully, the sequenceHandle object will be flushed. |
| 6900 | |
| 6901 | |
| 6902 | |
| 6903 | |
| 6904 | Page 146 TCG Published Family “2.0” |
| 6905 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 6906 | Trusted Platform Module Library Part 3: Commands |
| 6907 | |
| 6908 | |
| 6909 | |
| 6910 | 17.5.2 Command and Response |
| 6911 | |
| 6912 | Table 73 — TPM2_SequenceComplete Command |
| 6913 | Type Name Description |
| 6914 | |
| 6915 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 6916 | UINT32 commandSize |
| 6917 | TPM_CC commandCode TPM_CC_SequenceComplete {F} |
| 6918 | |
| 6919 | authorization for the sequence |
| 6920 | TPMI_DH_OBJECT @sequenceHandle Auth Index: 1 |
| 6921 | Auth Role: USER |
| 6922 | |
| 6923 | TPM2B_MAX_BUFFER buffer data to be added to the hash/HMAC |
| 6924 | TPMI_RH_HIERARCHY+ hierarchy hierarchy of the ticket for a hash |
| 6925 | |
| 6926 | |
| 6927 | Table 74 — TPM2_SequenceComplete Response |
| 6928 | Type Name Description |
| 6929 | |
| 6930 | TPM_ST tag see clause 6 |
| 6931 | UINT32 responseSize |
| 6932 | TPM_RC responseCode |
| 6933 | |
| 6934 | TPM2B_DIGEST result the returned HMAC or digest in a sized buffer |
| 6935 | ticket indicating that the sequence of octets used to |
| 6936 | compute outDigest did not start with |
| 6937 | TPMT_TK_HASHCHECK validation TPM_GENERATED_VALUE |
| 6938 | This is a NULL Ticket when the sequence is HMAC. |
| 6939 | |
| 6940 | |
| 6941 | |
| 6942 | |
| 6943 | Family “2.0” TCG Published Page 147 |
| 6944 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 6945 | Part 3: Commands Trusted Platform Module Library |
| 6946 | |
| 6947 | |
| 6948 | |
| 6949 | 17.5.3 Detailed Actions |
| 6950 | |
| 6951 | 1 #include "InternalRoutines.h" |
| 6952 | 2 #include "SequenceComplete_fp.h" |
| 6953 | 3 #ifdef TPM_CC_SequenceComplete // Conditional expansion of this file |
| 6954 | 4 #include <Platform.h> |
| 6955 | |
| 6956 | |
| 6957 | Error Returns Meaning |
| 6958 | |
| 6959 | TPM_RC_TYPE sequenceHandle does not reference a hash or HMAC sequence |
| 6960 | object |
| 6961 | |
| 6962 | 5 TPM_RC |
| 6963 | 6 TPM2_SequenceComplete( |
| 6964 | 7 SequenceComplete_In *in, // IN: input parameter list |
| 6965 | 8 SequenceComplete_Out *out // OUT: output parameter list |
| 6966 | 9 ) |
| 6967 | 10 { |
| 6968 | 11 OBJECT *object; |
| 6969 | 12 |
| 6970 | 13 // Input validation |
| 6971 | 14 |
| 6972 | 15 // Get hash object pointer |
| 6973 | 16 object = ObjectGet(in->sequenceHandle); |
| 6974 | 17 |
| 6975 | 18 // input handle must be a hash or HMAC sequence object. |
| 6976 | 19 if( object->attributes.hashSeq == CLEAR |
| 6977 | 20 && object->attributes.hmacSeq == CLEAR) |
| 6978 | 21 return TPM_RC_MODE + RC_SequenceComplete_sequenceHandle; |
| 6979 | 22 |
| 6980 | 23 // Command Output |
| 6981 | 24 |
| 6982 | 25 if(object->attributes.hashSeq == SET) // sequence object for hash |
| 6983 | 26 { |
| 6984 | 27 // Update last piece of data |
| 6985 | 28 HASH_OBJECT *hashObject = (HASH_OBJECT *)object; |
| 6986 | 29 |
| 6987 | 30 // Get the hash algorithm before the algorithm is lost in CryptCompleteHash |
| 6988 | 31 TPM_ALG_ID hashAlg = hashObject->state.hashState[0].state.hashAlg; |
| 6989 | 32 |
| 6990 | 33 CryptUpdateDigest2B(&hashObject->state.hashState[0], &in->buffer.b); |
| 6991 | 34 |
| 6992 | 35 // Complete hash |
| 6993 | 36 out->result.t.size |
| 6994 | 37 = CryptGetHashDigestSize( |
| 6995 | 38 CryptGetContextAlg(&hashObject->state.hashState[0])); |
| 6996 | 39 |
| 6997 | 40 CryptCompleteHash2B(&hashObject->state.hashState[0], &out->result.b); |
| 6998 | 41 |
| 6999 | 42 // Check if the first block of the sequence has been received |
| 7000 | 43 if(hashObject->attributes.firstBlock == CLEAR) |
| 7001 | 44 { |
| 7002 | 45 // If not, then this is the first block so see if it is 'safe' |
| 7003 | 46 // to sign. |
| 7004 | 47 if(TicketIsSafe(&in->buffer.b)) |
| 7005 | 48 hashObject->attributes.ticketSafe = SET; |
| 7006 | 49 } |
| 7007 | 50 |
| 7008 | 51 // Output ticket |
| 7009 | 52 out->validation.tag = TPM_ST_HASHCHECK; |
| 7010 | 53 out->validation.hierarchy = in->hierarchy; |
| 7011 | 54 |
| 7012 | 55 if(in->hierarchy == TPM_RH_NULL) |
| 7013 | |
| 7014 | Page 148 TCG Published Family “2.0” |
| 7015 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 7016 | Trusted Platform Module Library Part 3: Commands |
| 7017 | |
| 7018 | 56 { |
| 7019 | 57 // Ticket is not required |
| 7020 | 58 out->validation.digest.t.size = 0; |
| 7021 | 59 } |
| 7022 | 60 else if(object->attributes.ticketSafe == CLEAR) |
| 7023 | 61 { |
| 7024 | 62 // Ticket is not safe to generate |
| 7025 | 63 out->validation.hierarchy = TPM_RH_NULL; |
| 7026 | 64 out->validation.digest.t.size = 0; |
| 7027 | 65 } |
| 7028 | 66 else |
| 7029 | 67 { |
| 7030 | 68 // Compute ticket |
| 7031 | 69 TicketComputeHashCheck(out->validation.hierarchy, hashAlg, |
| 7032 | 70 &out->result, &out->validation); |
| 7033 | 71 } |
| 7034 | 72 } |
| 7035 | 73 else |
| 7036 | 74 { |
| 7037 | 75 HASH_OBJECT *hashObject = (HASH_OBJECT *)object; |
| 7038 | 76 |
| 7039 | 77 // Update last piece of data |
| 7040 | 78 CryptUpdateDigest2B(&hashObject->state.hmacState, &in->buffer.b); |
| 7041 | 79 // Complete hash/HMAC |
| 7042 | 80 out->result.t.size = |
| 7043 | 81 CryptGetHashDigestSize( |
| 7044 | 82 CryptGetContextAlg(&hashObject->state.hmacState.hashState)); |
| 7045 | 83 CryptCompleteHMAC2B(&(hashObject->state.hmacState), &out->result.b); |
| 7046 | 84 |
| 7047 | 85 // No ticket is generated for HMAC sequence |
| 7048 | 86 out->validation.tag = TPM_ST_HASHCHECK; |
| 7049 | 87 out->validation.hierarchy = TPM_RH_NULL; |
| 7050 | 88 out->validation.digest.t.size = 0; |
| 7051 | 89 } |
| 7052 | 90 |
| 7053 | 91 // Internal Data Update |
| 7054 | 92 |
| 7055 | 93 // mark sequence object as evict so it will be flushed on the way out |
| 7056 | 94 object->attributes.evict = SET; |
| 7057 | 95 |
| 7058 | 96 return TPM_RC_SUCCESS; |
| 7059 | 97 } |
| 7060 | 98 #endif // CC_SequenceComplete |
| 7061 | |
| 7062 | |
| 7063 | |
| 7064 | |
| 7065 | Family “2.0” TCG Published Page 149 |
| 7066 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 7067 | Part 3: Commands Trusted Platform Module Library |
| 7068 | |
| 7069 | |
| 7070 | 17.6 TPM2_EventSequenceComplete |
| 7071 | |
| 7072 | 17.6.1 General Description |
| 7073 | |
| 7074 | This command adds the last part of data, if any, to an Event Sequence and returns the result in a digest |
| 7075 | list. If pcrHandle references a PCR and not TPM_RH_NULL, then the returned digest list is processed in |
| 7076 | the same manner as the digest list input parameter to TPM2_PCR_Extend() with the pcrHandle in each |
| 7077 | bank extended with the associated digest value. |
| 7078 | If sequenceHandle references a hash or HMAC sequence, the TPM shall return TPM_RC_MODE. |
| 7079 | Proper authorization for the sequence object associated with sequenceHandle is required. If an |
| 7080 | authorization or audit of this command requires computation of a cpHash and an rpHash, the Name |
| 7081 | associated with sequenceHandle will be the Empty Buffer. |
| 7082 | If this command completes successfully, the sequenceHandle object will be flushed. |
| 7083 | |
| 7084 | |
| 7085 | |
| 7086 | |
| 7087 | Page 150 TCG Published Family “2.0” |
| 7088 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 7089 | Trusted Platform Module Library Part 3: Commands |
| 7090 | |
| 7091 | |
| 7092 | |
| 7093 | 17.6.2 Command and Response |
| 7094 | |
| 7095 | Table 75 — TPM2_EventSequenceComplete Command |
| 7096 | Type Name Description |
| 7097 | |
| 7098 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 7099 | UINT32 commandSize |
| 7100 | TPM_CC commandCode TPM_CC_EventSequenceComplete {NV F} |
| 7101 | |
| 7102 | PCR to be extended with the Event data |
| 7103 | TPMI_DH_PCR+ @ pcrHandle Auth Index: 1 |
| 7104 | Auth Role: USER |
| 7105 | authorization for the sequence |
| 7106 | TPMI_DH_OBJECT @sequenceHandle Auth Index: 2 |
| 7107 | Auth Role: USER |
| 7108 | |
| 7109 | TPM2B_MAX_BUFFER buffer data to be added to the Event |
| 7110 | |
| 7111 | |
| 7112 | Table 76 — TPM2_EventSequenceComplete Response |
| 7113 | Type Name Description |
| 7114 | |
| 7115 | TPM_ST tag see clause 6 |
| 7116 | UINT32 responseSize |
| 7117 | TPM_RC responseCode |
| 7118 | |
| 7119 | TPML_DIGEST_VALUES results list of digests computed for the PCR |
| 7120 | |
| 7121 | |
| 7122 | |
| 7123 | |
| 7124 | Family “2.0” TCG Published Page 151 |
| 7125 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 7126 | Part 3: Commands Trusted Platform Module Library |
| 7127 | |
| 7128 | |
| 7129 | |
| 7130 | 17.6.3 Detailed Actions |
| 7131 | |
| 7132 | 1 #include "InternalRoutines.h" |
| 7133 | 2 #include "EventSequenceComplete_fp.h" |
| 7134 | 3 #ifdef TPM_CC_EventSequenceComplete // Conditional expansion of this file |
| 7135 | |
| 7136 | |
| 7137 | Error Returns Meaning |
| 7138 | |
| 7139 | TPM_RC_LOCALITY PCR extension is not allowed at the current locality |
| 7140 | TPM_RC_MODE input handle is not a valid event sequence object |
| 7141 | |
| 7142 | 4 TPM_RC |
| 7143 | 5 TPM2_EventSequenceComplete( |
| 7144 | 6 EventSequenceComplete_In *in, // IN: input parameter list |
| 7145 | 7 EventSequenceComplete_Out *out // OUT: output parameter list |
| 7146 | 8 ) |
| 7147 | 9 { |
| 7148 | 10 TPM_RC result; |
| 7149 | 11 HASH_OBJECT *hashObject; |
| 7150 | 12 UINT32 i; |
| 7151 | 13 TPM_ALG_ID hashAlg; |
| 7152 | 14 |
| 7153 | 15 // Input validation |
| 7154 | 16 |
| 7155 | 17 // get the event sequence object pointer |
| 7156 | 18 hashObject = (HASH_OBJECT *)ObjectGet(in->sequenceHandle); |
| 7157 | 19 |
| 7158 | 20 // input handle must reference an event sequence object |
| 7159 | 21 if(hashObject->attributes.eventSeq != SET) |
| 7160 | 22 return TPM_RC_MODE + RC_EventSequenceComplete_sequenceHandle; |
| 7161 | 23 |
| 7162 | 24 // see if a PCR extend is requested in call |
| 7163 | 25 if(in->pcrHandle != TPM_RH_NULL) |
| 7164 | 26 { |
| 7165 | 27 // see if extend of the PCR is allowed at the locality of the command, |
| 7166 | 28 if(!PCRIsExtendAllowed(in->pcrHandle)) |
| 7167 | 29 return TPM_RC_LOCALITY; |
| 7168 | 30 // if an extend is going to take place, then check to see if there has |
| 7169 | 31 // been an orderly shutdown. If so, and the selected PCR is one of the |
| 7170 | 32 // state saved PCR, then the orderly state has to change. The orderly state |
| 7171 | 33 // does not change for PCR that are not preserved. |
| 7172 | 34 // NOTE: This doesn't just check for Shutdown(STATE) because the orderly |
| 7173 | 35 // state will have to change if this is a state-saved PCR regardless |
| 7174 | 36 // of the current state. This is because a subsequent Shutdown(STATE) will |
| 7175 | 37 // check to see if there was an orderly shutdown and not do anything if |
| 7176 | 38 // there was. So, this must indicate that a future Shutdown(STATE) has |
| 7177 | 39 // something to do. |
| 7178 | 40 if(gp.orderlyState != SHUTDOWN_NONE && PCRIsStateSaved(in->pcrHandle)) |
| 7179 | 41 { |
| 7180 | 42 result = NvIsAvailable(); |
| 7181 | 43 if(result != TPM_RC_SUCCESS) return result; |
| 7182 | 44 g_clearOrderly = TRUE; |
| 7183 | 45 } |
| 7184 | 46 } |
| 7185 | 47 |
| 7186 | 48 // Command Output |
| 7187 | 49 |
| 7188 | 50 out->results.count = 0; |
| 7189 | 51 |
| 7190 | 52 for(i = 0; i < HASH_COUNT; i++) |
| 7191 | 53 { |
| 7192 | 54 hashAlg = CryptGetHashAlgByIndex(i); |
| 7193 | |
| 7194 | Page 152 TCG Published Family “2.0” |
| 7195 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 7196 | Trusted Platform Module Library Part 3: Commands |
| 7197 | |
| 7198 | 55 // Update last piece of data |
| 7199 | 56 CryptUpdateDigest2B(&hashObject->state.hashState[i], &in->buffer.b); |
| 7200 | 57 // Complete hash |
| 7201 | 58 out->results.digests[out->results.count].hashAlg = hashAlg; |
| 7202 | 59 CryptCompleteHash(&hashObject->state.hashState[i], |
| 7203 | 60 CryptGetHashDigestSize(hashAlg), |
| 7204 | 61 (BYTE *) &out->results.digests[out->results.count].digest); |
| 7205 | 62 |
| 7206 | 63 // Extend PCR |
| 7207 | 64 if(in->pcrHandle != TPM_RH_NULL) |
| 7208 | 65 PCRExtend(in->pcrHandle, hashAlg, |
| 7209 | 66 CryptGetHashDigestSize(hashAlg), |
| 7210 | 67 (BYTE *) &out->results.digests[out->results.count].digest); |
| 7211 | 68 out->results.count++; |
| 7212 | 69 } |
| 7213 | 70 |
| 7214 | 71 // Internal Data Update |
| 7215 | 72 |
| 7216 | 73 // mark sequence object as evict so it will be flushed on the way out |
| 7217 | 74 hashObject->attributes.evict = SET; |
| 7218 | 75 |
| 7219 | 76 return TPM_RC_SUCCESS; |
| 7220 | 77 } |
| 7221 | 78 #endif // CC_EventSequenceComplete |
| 7222 | |
| 7223 | |
| 7224 | |
| 7225 | |
| 7226 | Family “2.0” TCG Published Page 153 |
| 7227 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 7228 | Part 3: Commands Trusted Platform Module Library |
| 7229 | |
| 7230 | |
| 7231 | 18 Attestation Commands |
| 7232 | |
| 7233 | 18.1 Introduction |
| 7234 | |
| 7235 | The attestation commands cause the TPM to sign an internally generated data structure. The contents of |
| 7236 | the data structure vary according to the command. |
| 7237 | All signing commands include a parameter (typically inScheme) for the caller to specify a scheme to be |
| 7238 | used for the signing operation. This scheme will be applied only if the scheme of the key is |
| 7239 | TPM_ALG_NULL or the key handle is TPM_RH_NULL. If the scheme for signHandle is not |
| 7240 | TPM_ALG_NULL, then inScheme.scheme shall be TPM_ALG_NULL or the same as scheme in the |
| 7241 | public area of the key. If the scheme for signHandle is TPM_ALG_NULL or the key handle is |
| 7242 | TPM_RH_NULL, then inScheme will be used for the signing operation and may not be TPM_ALG_NULL. |
| 7243 | The TPM shall return TPM_RC_SCHEME to indicate that the scheme is not appropriate. |
| 7244 | For a signing key that is not restricted, the caller may specify the scheme to be used as long as the |
| 7245 | scheme is compatible with the family of the key (for example, TPM_ALG_RSAPSS cannot be selected for |
| 7246 | an ECC key). If the caller sets scheme to TPM_ALG_NULL, then the default scheme of the key is used. |
| 7247 | For a restricted signing key, the key's scheme cannot be TPM_ALG_NULL and cannot be overridden. |
| 7248 | If the handle for the signing key (signHandle) is TPM_RH_NULL, then all of the actions of the command |
| 7249 | are performed and the attestation block is “signed” with the NULL Signature. |
| 7250 | |
| 7251 | NOTE 1 This mechanism is provided so that additional commands are not required to access the data that |
| 7252 | might be in an attestation structure. |
| 7253 | |
| 7254 | NOTE 2 When signHandle is TPM_RH_NULL, scheme is still required to be a valid signing scheme (may be |
| 7255 | TPM_ALG_NULL), but the scheme will have no effect on the format of the signature. It will always |
| 7256 | be the NULL Signature. |
| 7257 | |
| 7258 | TPM2_NV_Certify() is an attestation command that is documented in 1. The remaining attestation |
| 7259 | commands are collected in the remainder of this clause. |
| 7260 | Each of the attestation structures contains a TPMS_CLOCK_INFO structure and a firmware version |
| 7261 | number. These values may be considered privacy-sensitive, because they would aid in the correlation of |
| 7262 | attestations by different keys. To provide improved privacy, the resetCount, restartCount, and |
| 7263 | firmwareVersion numbers are obfuscated when the signing key is not in the Endorsement or Platform |
| 7264 | hierarchies. |
| 7265 | The obfuscation value is computed by: |
| 7266 | obfuscation ≔ KDFa(signHandle→nameAlg, shProof, “OBFUSCATE”, signHandle→QN, 0, 128) (3) |
| 7267 | Of the returned 128 bits, 64 bits are added to the versionNumber field of the attestation structure; 32 bits |
| 7268 | are added to the clockInfo.resetCount and 32 bits are added to the clockInfo.restartCount. The order in |
| 7269 | which the bits are added is implementation-dependent. |
| 7270 | |
| 7271 | NOTE 3 The obfuscation value for each signing key will be unique to that key in a specific location. That is, |
| 7272 | each version of a duplicated signing key will have a different obfuscation value. |
| 7273 | |
| 7274 | When the signing key is TPM_RH_NULL, the data structure is produced but not signed; and the values in |
| 7275 | the signed data structure are obfuscated. When computing the obfuscation value for TPM_RH_NULL, the |
| 7276 | hash used for context integrity is used. |
| 7277 | |
| 7278 | NOTE 4 The QN for TPM_RH_NULL is TPM_RH_NULL. |
| 7279 | |
| 7280 | If the signing scheme of signHandle is an anonymous scheme, then the attestation blocks will not contain |
| 7281 | the Qualified Name of the signHandle. |
| 7282 | Each of the attestation structures allows the caller to provide some qualifying data (qualifyingData). For |
| 7283 | most signing schemes, this value will be placed in the TPMS_ATTEST.extraData parameter that is then |
| 7284 | |
| 7285 | Page 154 TCG Published Family “2.0” |
| 7286 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 7287 | Trusted Platform Module Library Part 3: Commands |
| 7288 | |
| 7289 | hashed and signed. However, for some schemes such as ECDAA, the qualifyingData is used in a |
| 7290 | different manner (for details, see “ECDAA” in TPM 2.0 Part 1). |
| 7291 | |
| 7292 | |
| 7293 | |
| 7294 | |
| 7295 | Family “2.0” TCG Published Page 155 |
| 7296 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 7297 | Part 3: Commands Trusted Platform Module Library |
| 7298 | |
| 7299 | |
| 7300 | |
| 7301 | 18.2 TPM2_Certify |
| 7302 | |
| 7303 | 18.2.1 General Description |
| 7304 | |
| 7305 | The purpose of this command is to prove that an object with a specific Name is loaded in the TPM. By |
| 7306 | certifying that the object is loaded, the TPM warrants that a public area with a given Name is self- |
| 7307 | consistent and associated with a valid sensitive area. If a relying party has a public area that has the |
| 7308 | same Name as a Name certified with this command, then the values in that public area are correct. |
| 7309 | |
| 7310 | NOTE 1 See 18.1 for description of how the signing scheme is selected. |
| 7311 | |
| 7312 | Authorization for objectHandle requires ADMIN role authorization. If performed with a policy session, the |
| 7313 | session shall have a policySession→commandCode set to TPM_CC_Certify. This indicates that the |
| 7314 | policy that is being used is a policy that is for certification, and not a policy that would approve another |
| 7315 | use. That is, authority to use an object does not grant authority to certify the object. |
| 7316 | The object may be any object that is loaded with TPM2_Load() or TPM2_CreatePrimary(). An object that |
| 7317 | only has its public area loaded cannot be certified. |
| 7318 | |
| 7319 | NOTE 2 The restriction occurs because the Name is used to identify the object being certified. If the TPM |
| 7320 | has not validated that the public area is associated with a mat ched sensitive area, then the public |
| 7321 | area may not represent a valid object and cannot be certified. |
| 7322 | |
| 7323 | The certification includes the Name and Qualified Name of the certified object as well as the Name and |
| 7324 | the Qualified Name of the certifying object. |
| 7325 | |
| 7326 | NOTE 2 If signHandle is TPM_RH_NULL, the TPMS_ATTEST structure is returned and signature is a NULL |
| 7327 | Signature. |
| 7328 | |
| 7329 | |
| 7330 | |
| 7331 | |
| 7332 | Page 156 TCG Published Family “2.0” |
| 7333 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 7334 | Trusted Platform Module Library Part 3: Commands |
| 7335 | |
| 7336 | |
| 7337 | |
| 7338 | 18.2.2 Command and Response |
| 7339 | |
| 7340 | Table 77 — TPM2_Certify Command |
| 7341 | Type Name Description |
| 7342 | |
| 7343 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 7344 | UINT32 commandSize |
| 7345 | TPM_CC commandCode TPM_CC_Certify |
| 7346 | |
| 7347 | handle of the object to be certified |
| 7348 | TPMI_DH_OBJECT @objectHandle Auth Index: 1 |
| 7349 | Auth Role: ADMIN |
| 7350 | handle of the key used to sign the attestation structure |
| 7351 | TPMI_DH_OBJECT+ @signHandle Auth Index: 2 |
| 7352 | Auth Role: USER |
| 7353 | |
| 7354 | TPM2B_DATA qualifyingData user provided qualifying data |
| 7355 | signing scheme to use if the scheme for signHandle is |
| 7356 | TPMT_SIG_SCHEME+ inScheme |
| 7357 | TPM_ALG_NULL |
| 7358 | |
| 7359 | |
| 7360 | Table 78 — TPM2_Certify Response |
| 7361 | Type Name Description |
| 7362 | |
| 7363 | TPM_ST tag see clause 6 |
| 7364 | UINT32 responseSize |
| 7365 | TPM_RC responseCode . |
| 7366 | |
| 7367 | TPM2B_ATTEST certifyInfo the structure that was signed |
| 7368 | the asymmetric signature over certifyInfo using the key |
| 7369 | TPMT_SIGNATURE signature |
| 7370 | referenced by signHandle |
| 7371 | |
| 7372 | |
| 7373 | |
| 7374 | |
| 7375 | Family “2.0” TCG Published Page 157 |
| 7376 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 7377 | Part 3: Commands Trusted Platform Module Library |
| 7378 | |
| 7379 | |
| 7380 | |
| 7381 | 18.2.3 Detailed Actions |
| 7382 | |
| 7383 | 1 #include "InternalRoutines.h" |
| 7384 | 2 #include "Attest_spt_fp.h" |
| 7385 | 3 #include "Certify_fp.h" |
| 7386 | 4 #ifdef TPM_CC_Certify // Conditional expansion of this file |
| 7387 | |
| 7388 | |
| 7389 | Error Returns Meaning |
| 7390 | |
| 7391 | TPM_RC_KEY key referenced by signHandle is not a signing key |
| 7392 | TPM_RC_SCHEME inScheme is not compatible with signHandle |
| 7393 | TPM_RC_VALUE digest generated for inScheme is greater or has larger size than the |
| 7394 | modulus of signHandle, or the buffer for the result in signature is too |
| 7395 | small (for an RSA key); invalid commit status (for an ECC key with a |
| 7396 | split scheme). |
| 7397 | |
| 7398 | 5 TPM_RC |
| 7399 | 6 TPM2_Certify( |
| 7400 | 7 Certify_In *in, // IN: input parameter list |
| 7401 | 8 Certify_Out *out // OUT: output parameter list |
| 7402 | 9 ) |
| 7403 | 10 { |
| 7404 | 11 TPM_RC result; |
| 7405 | 12 TPMS_ATTEST certifyInfo; |
| 7406 | 13 |
| 7407 | 14 // Command Output |
| 7408 | 15 |
| 7409 | 16 // Filling in attest information |
| 7410 | 17 // Common fields |
| 7411 | 18 result = FillInAttestInfo(in->signHandle, |
| 7412 | 19 &in->inScheme, |
| 7413 | 20 &in->qualifyingData, |
| 7414 | 21 &certifyInfo); |
| 7415 | 22 if(result != TPM_RC_SUCCESS) |
| 7416 | 23 { |
| 7417 | 24 if(result == TPM_RC_KEY) |
| 7418 | 25 return TPM_RC_KEY + RC_Certify_signHandle; |
| 7419 | 26 else |
| 7420 | 27 return RcSafeAddToResult(result, RC_Certify_inScheme); |
| 7421 | 28 } |
| 7422 | 29 // Certify specific fields |
| 7423 | 30 // Attestation type |
| 7424 | 31 certifyInfo.type = TPM_ST_ATTEST_CERTIFY; |
| 7425 | 32 // Certified object name |
| 7426 | 33 certifyInfo.attested.certify.name.t.size = |
| 7427 | 34 ObjectGetName(in->objectHandle, |
| 7428 | 35 &certifyInfo.attested.certify.name.t.name); |
| 7429 | 36 // Certified object qualified name |
| 7430 | 37 ObjectGetQualifiedName(in->objectHandle, |
| 7431 | 38 &certifyInfo.attested.certify.qualifiedName); |
| 7432 | 39 |
| 7433 | 40 // Sign attestation structure. A NULL signature will be returned if |
| 7434 | 41 // signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE, |
| 7435 | 42 // TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned |
| 7436 | 43 // by SignAttestInfo() |
| 7437 | 44 result = SignAttestInfo(in->signHandle, |
| 7438 | 45 &in->inScheme, |
| 7439 | 46 &certifyInfo, |
| 7440 | 47 &in->qualifyingData, |
| 7441 | 48 &out->certifyInfo, |
| 7442 | 49 &out->signature); |
| 7443 | |
| 7444 | Page 158 TCG Published Family “2.0” |
| 7445 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 7446 | Trusted Platform Module Library Part 3: Commands |
| 7447 | |
| 7448 | 50 |
| 7449 | 51 // TPM_RC_ATTRIBUTES cannot be returned here as FillInAttestInfo would already |
| 7450 | 52 // have returned TPM_RC_KEY |
| 7451 | 53 pAssert(result != TPM_RC_ATTRIBUTES); |
| 7452 | 54 |
| 7453 | 55 if(result != TPM_RC_SUCCESS) |
| 7454 | 56 return result; |
| 7455 | 57 |
| 7456 | 58 // orderly state should be cleared because of the reporting of clock info |
| 7457 | 59 // if signing happens |
| 7458 | 60 if(in->signHandle != TPM_RH_NULL) |
| 7459 | 61 g_clearOrderly = TRUE; |
| 7460 | 62 |
| 7461 | 63 return TPM_RC_SUCCESS; |
| 7462 | 64 } |
| 7463 | 65 #endif // CC_Certify |
| 7464 | |
| 7465 | |
| 7466 | |
| 7467 | |
| 7468 | Family “2.0” TCG Published Page 159 |
| 7469 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 7470 | Part 3: Commands Trusted Platform Module Library |
| 7471 | |
| 7472 | |
| 7473 | 18.3 TPM2_CertifyCreation |
| 7474 | |
| 7475 | 18.3.1 General Description |
| 7476 | |
| 7477 | This command is used to prove the association between an object and its creation data. The TPM will |
| 7478 | validate that the ticket was produced by the TPM and that the ticket validates the association between a |
| 7479 | loaded public area and the provided hash of the creation data (creationHash). |
| 7480 | |
| 7481 | NOTE 1 See 18.1 for description of how the signing scheme is selected. |
| 7482 | |
| 7483 | The TPM will create a test ticket using the Name associated with objectHandle and creationHash as: |
| 7484 | HMAC(proof, (TPM_ST_CREATION || objectHandle→Name || creationHash)) (4) |
| 7485 | This ticket is then compared to creation ticket. If the tickets are not the same, the TPM shall return |
| 7486 | TPM_RC_TICKET. |
| 7487 | If the ticket is valid, then the TPM will create a TPMS_ATTEST structure and place creationHash of the |
| 7488 | command in the creationHash field of the structure. The Name associated with objectHandle will be |
| 7489 | included in the attestation data that is then signed using the key associated with signHandle. |
| 7490 | |
| 7491 | NOTE 2 If signHandle is TPM_RH_NULL, the TPMS_ATTEST structure is returned and signature is a NULL |
| 7492 | Signature. |
| 7493 | |
| 7494 | ObjectHandle may be any object that is loaded with TPM2_Load() or TPM2_CreatePrimary(). |
| 7495 | |
| 7496 | |
| 7497 | |
| 7498 | |
| 7499 | Page 160 TCG Published Family “2.0” |
| 7500 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 7501 | Trusted Platform Module Library Part 3: Commands |
| 7502 | |
| 7503 | |
| 7504 | |
| 7505 | 18.3.2 Command and Response |
| 7506 | |
| 7507 | Table 79 — TPM2_CertifyCreation Command |
| 7508 | Type Name Description |
| 7509 | |
| 7510 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 7511 | UINT32 commandSize |
| 7512 | TPM_CC commandCode TPM_CC_CertifyCreation |
| 7513 | |
| 7514 | handle of the key that will sign the attestation block |
| 7515 | TPMI_DH_OBJECT+ @signHandle Auth Index: 1 |
| 7516 | Auth Role: USER |
| 7517 | the object associated with the creation data |
| 7518 | TPMI_DH_OBJECT objectHandle |
| 7519 | Auth Index: None |
| 7520 | |
| 7521 | TPM2B_DATA qualifyingData user-provided qualifying data |
| 7522 | hash of the creation data produced by TPM2_Create() |
| 7523 | TPM2B_DIGEST creationHash |
| 7524 | or TPM2_CreatePrimary() |
| 7525 | signing scheme to use if the scheme for signHandle is |
| 7526 | TPMT_SIG_SCHEME+ inScheme |
| 7527 | TPM_ALG_NULL |
| 7528 | ticket produced by TPM2_Create() or |
| 7529 | TPMT_TK_CREATION creationTicket |
| 7530 | TPM2_CreatePrimary() |
| 7531 | |
| 7532 | |
| 7533 | Table 80 — TPM2_CertifyCreation Response |
| 7534 | Type Name Description |
| 7535 | |
| 7536 | TPM_ST tag see clause 6 |
| 7537 | UINT32 responseSize |
| 7538 | TPM_RC responseCode |
| 7539 | |
| 7540 | TPM2B_ATTEST certifyInfo the structure that was signed |
| 7541 | TPMT_SIGNATURE signature the signature over certifyInfo |
| 7542 | |
| 7543 | |
| 7544 | |
| 7545 | |
| 7546 | Family “2.0” TCG Published Page 161 |
| 7547 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 7548 | Part 3: Commands Trusted Platform Module Library |
| 7549 | |
| 7550 | |
| 7551 | |
| 7552 | 18.3.3 Detailed Actions |
| 7553 | |
| 7554 | 1 #include "InternalRoutines.h" |
| 7555 | 2 #include "Attest_spt_fp.h" |
| 7556 | 3 #include "CertifyCreation_fp.h" |
| 7557 | 4 #ifdef TPM_CC_CertifyCreation // Conditional expansion of this file |
| 7558 | |
| 7559 | |
| 7560 | Error Returns Meaning |
| 7561 | |
| 7562 | TPM_RC_KEY key referenced by signHandle is not a signing key |
| 7563 | TPM_RC_SCHEME inScheme is not compatible with signHandle |
| 7564 | TPM_RC_TICKET creationTicket does not match objectHandle |
| 7565 | TPM_RC_VALUE digest generated for inScheme is greater or has larger size than the |
| 7566 | modulus of signHandle, or the buffer for the result in signature is too |
| 7567 | small (for an RSA key); invalid commit status (for an ECC key with a |
| 7568 | split scheme). |
| 7569 | |
| 7570 | 5 TPM_RC |
| 7571 | 6 TPM2_CertifyCreation( |
| 7572 | 7 CertifyCreation_In *in, // IN: input parameter list |
| 7573 | 8 CertifyCreation_Out *out // OUT: output parameter list |
| 7574 | 9 ) |
| 7575 | 10 { |
| 7576 | 11 TPM_RC result; |
| 7577 | 12 TPM2B_NAME name; |
| 7578 | 13 TPMT_TK_CREATION ticket; |
| 7579 | 14 TPMS_ATTEST certifyInfo; |
| 7580 | 15 |
| 7581 | 16 // Input Validation |
| 7582 | 17 |
| 7583 | 18 // CertifyCreation specific input validation |
| 7584 | 19 // Get certified object name |
| 7585 | 20 name.t.size = ObjectGetName(in->objectHandle, &name.t.name); |
| 7586 | 21 // Re-compute ticket |
| 7587 | 22 TicketComputeCreation(in->creationTicket.hierarchy, &name, |
| 7588 | 23 &in->creationHash, &ticket); |
| 7589 | 24 // Compare ticket |
| 7590 | 25 if(!Memory2BEqual(&ticket.digest.b, &in->creationTicket.digest.b)) |
| 7591 | 26 return TPM_RC_TICKET + RC_CertifyCreation_creationTicket; |
| 7592 | 27 |
| 7593 | 28 // Command Output |
| 7594 | 29 // Common fields |
| 7595 | 30 result = FillInAttestInfo(in->signHandle, &in->inScheme, &in->qualifyingData, |
| 7596 | 31 &certifyInfo); |
| 7597 | 32 if(result != TPM_RC_SUCCESS) |
| 7598 | 33 { |
| 7599 | 34 if(result == TPM_RC_KEY) |
| 7600 | 35 return TPM_RC_KEY + RC_CertifyCreation_signHandle; |
| 7601 | 36 else |
| 7602 | 37 return RcSafeAddToResult(result, RC_CertifyCreation_inScheme); |
| 7603 | 38 } |
| 7604 | 39 |
| 7605 | 40 // CertifyCreation specific fields |
| 7606 | 41 // Attestation type |
| 7607 | 42 certifyInfo.type = TPM_ST_ATTEST_CREATION; |
| 7608 | 43 certifyInfo.attested.creation.objectName = name; |
| 7609 | 44 |
| 7610 | 45 // Copy the creationHash |
| 7611 | 46 certifyInfo.attested.creation.creationHash = in->creationHash; |
| 7612 | 47 |
| 7613 | 48 // Sign attestation structure. A NULL signature will be returned if |
| 7614 | |
| 7615 | Page 162 TCG Published Family “2.0” |
| 7616 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 7617 | Trusted Platform Module Library Part 3: Commands |
| 7618 | |
| 7619 | 49 // signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE, |
| 7620 | 50 // TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned at |
| 7621 | 51 // this point |
| 7622 | 52 result = SignAttestInfo(in->signHandle, |
| 7623 | 53 &in->inScheme, |
| 7624 | 54 &certifyInfo, |
| 7625 | 55 &in->qualifyingData, |
| 7626 | 56 &out->certifyInfo, |
| 7627 | 57 &out->signature); |
| 7628 | 58 |
| 7629 | 59 // TPM_RC_ATTRIBUTES cannot be returned here as FillInAttestInfo would already |
| 7630 | 60 // have returned TPM_RC_KEY |
| 7631 | 61 pAssert(result != TPM_RC_ATTRIBUTES); |
| 7632 | 62 |
| 7633 | 63 if(result != TPM_RC_SUCCESS) |
| 7634 | 64 return result; |
| 7635 | 65 |
| 7636 | 66 // orderly state should be cleared because of the reporting of clock info |
| 7637 | 67 // if signing happens |
| 7638 | 68 if(in->signHandle != TPM_RH_NULL) |
| 7639 | 69 g_clearOrderly = TRUE; |
| 7640 | 70 |
| 7641 | 71 return TPM_RC_SUCCESS; |
| 7642 | 72 } |
| 7643 | 73 #endif // CC_CertifyCreation |
| 7644 | |
| 7645 | |
| 7646 | |
| 7647 | |
| 7648 | Family “2.0” TCG Published Page 163 |
| 7649 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 7650 | Part 3: Commands Trusted Platform Module Library |
| 7651 | |
| 7652 | |
| 7653 | 18.4 TPM2_Quote |
| 7654 | |
| 7655 | 18.4.1 General Description |
| 7656 | |
| 7657 | This command is used to quote PCR values. |
| 7658 | |
| 7659 | NOTE See 18.1 for description of how the signing scheme is selected. |
| 7660 | |
| 7661 | The TPM will hash the list of PCR selected by PCRselect using the hash algorithm associated with |
| 7662 | signHandle (this is the hash algorithm of the signing scheme, not the nameAlg of signHandle). |
| 7663 | The digest is computed as the hash of the concatenation of all of the digest values of the selected PCR. |
| 7664 | The concatenation of PCR is described in TPM 2.0 Part 1, Selecting Multiple PCR. |
| 7665 | |
| 7666 | NOTE 2 If signHandle is TPM_RH_NULL, the TPMS_ATTEST structure is returned and signature is a NULL |
| 7667 | Signature. |
| 7668 | |
| 7669 | |
| 7670 | |
| 7671 | |
| 7672 | Page 164 TCG Published Family “2.0” |
| 7673 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 7674 | Trusted Platform Module Library Part 3: Commands |
| 7675 | |
| 7676 | |
| 7677 | |
| 7678 | 18.4.2 Command and Response |
| 7679 | |
| 7680 | Table 81 — TPM2_Quote Command |
| 7681 | Type Name Description |
| 7682 | |
| 7683 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 7684 | UINT32 commandSize |
| 7685 | TPM_CC commandCode TPM_CC_Quote |
| 7686 | |
| 7687 | handle of key that will perform signature |
| 7688 | TPMI_DH_OBJECT+ @signHandle Auth Index: 1 |
| 7689 | Auth Role: USER |
| 7690 | |
| 7691 | TPM2B_DATA qualifyingData data supplied by the caller |
| 7692 | signing scheme to use if the scheme for signHandle is |
| 7693 | TPMT_SIG_SCHEME+ inScheme |
| 7694 | TPM_ALG_NULL |
| 7695 | TPML_PCR_SELECTION PCRselect PCR set to quote |
| 7696 | |
| 7697 | |
| 7698 | Table 82 — TPM2_Quote Response |
| 7699 | Type Name Description |
| 7700 | |
| 7701 | TPM_ST tag see clause 6 |
| 7702 | UINT32 responseSize |
| 7703 | TPM_RC responseCode |
| 7704 | |
| 7705 | TPM2B_ATTEST quoted the quoted information |
| 7706 | TPMT_SIGNATURE signature the signature over quoted |
| 7707 | |
| 7708 | |
| 7709 | |
| 7710 | |
| 7711 | Family “2.0” TCG Published Page 165 |
| 7712 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 7713 | Part 3: Commands Trusted Platform Module Library |
| 7714 | |
| 7715 | |
| 7716 | |
| 7717 | 18.4.3 Detailed Actions |
| 7718 | |
| 7719 | 1 #include "InternalRoutines.h" |
| 7720 | 2 #include "Attest_spt_fp.h" |
| 7721 | 3 #include "Quote_fp.h" |
| 7722 | 4 #ifdef TPM_CC_Quote // Conditional expansion of this file |
| 7723 | |
| 7724 | |
| 7725 | Error Returns Meaning |
| 7726 | |
| 7727 | TPM_RC_KEY signHandle does not reference a signing key; |
| 7728 | TPM_RC_SCHEME the scheme is not compatible with sign key type, or input scheme is |
| 7729 | not compatible with default scheme, or the chosen scheme is not a |
| 7730 | valid sign scheme |
| 7731 | |
| 7732 | 5 TPM_RC |
| 7733 | 6 TPM2_Quote( |
| 7734 | 7 Quote_In *in, // IN: input parameter list |
| 7735 | 8 Quote_Out *out // OUT: output parameter list |
| 7736 | 9 ) |
| 7737 | 10 { |
| 7738 | 11 TPM_RC result; |
| 7739 | 12 TPMI_ALG_HASH hashAlg; |
| 7740 | 13 TPMS_ATTEST quoted; |
| 7741 | 14 |
| 7742 | 15 // Command Output |
| 7743 | 16 |
| 7744 | 17 // Filling in attest information |
| 7745 | 18 // Common fields |
| 7746 | 19 // FillInAttestInfo may return TPM_RC_SCHEME or TPM_RC_KEY |
| 7747 | 20 result = FillInAttestInfo(in->signHandle, |
| 7748 | 21 &in->inScheme, |
| 7749 | 22 &in->qualifyingData, |
| 7750 | 23 "ed); |
| 7751 | 24 if(result != TPM_RC_SUCCESS) |
| 7752 | 25 { |
| 7753 | 26 if(result == TPM_RC_KEY) |
| 7754 | 27 return TPM_RC_KEY + RC_Quote_signHandle; |
| 7755 | 28 else |
| 7756 | 29 return RcSafeAddToResult(result, RC_Quote_inScheme); |
| 7757 | 30 } |
| 7758 | 31 |
| 7759 | 32 // Quote specific fields |
| 7760 | 33 // Attestation type |
| 7761 | 34 quoted.type = TPM_ST_ATTEST_QUOTE; |
| 7762 | 35 |
| 7763 | 36 // Get hash algorithm in sign scheme. This hash algorithm is used to |
| 7764 | 37 // compute PCR digest. If there is no algorithm, then the PCR cannot |
| 7765 | 38 // be digested and this command returns TPM_RC_SCHEME |
| 7766 | 39 hashAlg = in->inScheme.details.any.hashAlg; |
| 7767 | 40 |
| 7768 | 41 if(hashAlg == TPM_ALG_NULL) |
| 7769 | 42 return TPM_RC_SCHEME + RC_Quote_inScheme; |
| 7770 | 43 |
| 7771 | 44 // Compute PCR digest |
| 7772 | 45 PCRComputeCurrentDigest(hashAlg, |
| 7773 | 46 &in->PCRselect, |
| 7774 | 47 "ed.attested.quote.pcrDigest); |
| 7775 | 48 |
| 7776 | 49 // Copy PCR select. "PCRselect" is modified in PCRComputeCurrentDigest |
| 7777 | 50 // function |
| 7778 | 51 quoted.attested.quote.pcrSelect = in->PCRselect; |
| 7779 | 52 |
| 7780 | |
| 7781 | Page 166 TCG Published Family “2.0” |
| 7782 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 7783 | Trusted Platform Module Library Part 3: Commands |
| 7784 | |
| 7785 | 53 // Sign attestation structure. A NULL signature will be returned if |
| 7786 | 54 // signHandle is TPM_RH_NULL. TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES |
| 7787 | 55 // error may be returned by SignAttestInfo. |
| 7788 | 56 // NOTE: TPM_RC_ATTRIBUTES means that the key is not a signing key but that |
| 7789 | 57 // was checked above and TPM_RC_KEY was returned. TPM_RC_VALUE means that the |
| 7790 | 58 // value to sign is too large but that means that the digest is too big and |
| 7791 | 59 // that can't happen. |
| 7792 | 60 result = SignAttestInfo(in->signHandle, |
| 7793 | 61 &in->inScheme, |
| 7794 | 62 "ed, |
| 7795 | 63 &in->qualifyingData, |
| 7796 | 64 &out->quoted, |
| 7797 | 65 &out->signature); |
| 7798 | 66 if(result != TPM_RC_SUCCESS) |
| 7799 | 67 return result; |
| 7800 | 68 |
| 7801 | 69 // orderly state should be cleared because of the reporting of clock info |
| 7802 | 70 // if signing happens |
| 7803 | 71 if(in->signHandle != TPM_RH_NULL) |
| 7804 | 72 g_clearOrderly = TRUE; |
| 7805 | 73 |
| 7806 | 74 return TPM_RC_SUCCESS; |
| 7807 | 75 } |
| 7808 | 76 #endif // CC_Quote |
| 7809 | |
| 7810 | |
| 7811 | |
| 7812 | |
| 7813 | Family “2.0” TCG Published Page 167 |
| 7814 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 7815 | Part 3: Commands Trusted Platform Module Library |
| 7816 | |
| 7817 | |
| 7818 | 18.5 TPM2_GetSessionAuditDigest |
| 7819 | |
| 7820 | 18.5.1 General Description |
| 7821 | |
| 7822 | This command returns a digital signature of the audit session digest. |
| 7823 | |
| 7824 | NOTE 1 See 18.1 for description of how the signing scheme is selected. |
| 7825 | |
| 7826 | If sessionHandle is not an audit session, the TPM shall return TPM_RC_TYPE. |
| 7827 | |
| 7828 | NOTE 2 A session does not become an audit session until the successful completion of the command in |
| 7829 | which the session is first used as an audit session. |
| 7830 | |
| 7831 | This command requires authorization from the privacy administrator of the TPM (expressed with |
| 7832 | Endorsement Authorization) as well as authorization to use the key associated with signHandle. |
| 7833 | If this command is audited, then the audit digest that is signed will not include the digest of this command |
| 7834 | because the audit digest is only updated when the command completes successfully. |
| 7835 | This command does not cause the audit session to be closed and does not reset the digest value. |
| 7836 | |
| 7837 | NOTE 3 If sessionHandle is used as an audit session for this command, the command is audited in the same |
| 7838 | manner as any other command. |
| 7839 | |
| 7840 | NOTE 4 If signHandle is TPM_RH_NULL, the TPMS_ATTEST structure is returned and signature is a NULL |
| 7841 | Signature. |
| 7842 | |
| 7843 | |
| 7844 | |
| 7845 | |
| 7846 | Page 168 TCG Published Family “2.0” |
| 7847 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 7848 | Trusted Platform Module Library Part 3: Commands |
| 7849 | |
| 7850 | |
| 7851 | |
| 7852 | 18.5.2 Command and Response |
| 7853 | |
| 7854 | Table 83 — TPM2_GetSessionAuditDigest Command |
| 7855 | Type Name Description |
| 7856 | |
| 7857 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 7858 | UINT32 commandSize |
| 7859 | TPM_CC commandCode TPM_CC_GetSessionAuditDigest |
| 7860 | |
| 7861 | handle of the privacy administrator |
| 7862 | (TPM_RH_ENDORSEMENT) |
| 7863 | TPMI_RH_ENDORSEMENT @privacyAdminHandle |
| 7864 | Auth Index: 1 |
| 7865 | Auth Role: USER |
| 7866 | handle of the signing key |
| 7867 | TPMI_DH_OBJECT+ @signHandle Auth Index: 2 |
| 7868 | Auth Role: USER |
| 7869 | handle of the audit session |
| 7870 | TPMI_SH_HMAC sessionHandle |
| 7871 | Auth Index: None |
| 7872 | |
| 7873 | TPM2B_DATA qualifyingData user-provided qualifying data – may be zero-length |
| 7874 | signing scheme to use if the scheme for signHandle is |
| 7875 | TPMT_SIG_SCHEME+ inScheme |
| 7876 | TPM_ALG_NULL |
| 7877 | |
| 7878 | |
| 7879 | Table 84 — TPM2_GetSessionAuditDigest Response |
| 7880 | Type Name Description |
| 7881 | |
| 7882 | TPM_ST tag see clause 6 |
| 7883 | UINT32 responseSize |
| 7884 | TPM_RC responseCode |
| 7885 | |
| 7886 | TPM2B_ATTEST auditInfo the audit information that was signed |
| 7887 | TPMT_SIGNATURE signature the signature over auditInfo |
| 7888 | |
| 7889 | |
| 7890 | |
| 7891 | |
| 7892 | Family “2.0” TCG Published Page 169 |
| 7893 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 7894 | Part 3: Commands Trusted Platform Module Library |
| 7895 | |
| 7896 | |
| 7897 | |
| 7898 | 18.5.3 Detailed Actions |
| 7899 | |
| 7900 | 1 #include "InternalRoutines.h" |
| 7901 | 2 #include "Attest_spt_fp.h" |
| 7902 | 3 #include "GetSessionAuditDigest_fp.h" |
| 7903 | 4 #ifdef TPM_CC_GetSessionAuditDigest // Conditional expansion of this file |
| 7904 | |
| 7905 | |
| 7906 | Error Returns Meaning |
| 7907 | |
| 7908 | TPM_RC_KEY key referenced by signHandle is not a signing key |
| 7909 | TPM_RC_SCHEME inScheme is incompatible with signHandle type; or both scheme and |
| 7910 | key's default scheme are empty; or scheme is empty while key's |
| 7911 | default scheme requires explicit input scheme (split signing); or non- |
| 7912 | empty default key scheme differs from scheme |
| 7913 | TPM_RC_TYPE sessionHandle does not reference an audit session |
| 7914 | TPM_RC_VALUE digest generated for the given scheme is greater than the modulus of |
| 7915 | signHandle (for an RSA key); invalid commit status or failed to |
| 7916 | generate r value (for an ECC key) |
| 7917 | |
| 7918 | 5 TPM_RC |
| 7919 | 6 TPM2_GetSessionAuditDigest( |
| 7920 | 7 GetSessionAuditDigest_In *in, // IN: input parameter list |
| 7921 | 8 GetSessionAuditDigest_Out *out // OUT: output parameter list |
| 7922 | 9 ) |
| 7923 | 10 { |
| 7924 | 11 TPM_RC result; |
| 7925 | 12 SESSION *session; |
| 7926 | 13 TPMS_ATTEST auditInfo; |
| 7927 | 14 |
| 7928 | 15 // Input Validation |
| 7929 | 16 |
| 7930 | 17 // SessionAuditDigest specific input validation |
| 7931 | 18 // Get session pointer |
| 7932 | 19 session = SessionGet(in->sessionHandle); |
| 7933 | 20 |
| 7934 | 21 // session must be an audit session |
| 7935 | 22 if(session->attributes.isAudit == CLEAR) |
| 7936 | 23 return TPM_RC_TYPE + RC_GetSessionAuditDigest_sessionHandle; |
| 7937 | 24 |
| 7938 | 25 // Command Output |
| 7939 | 26 |
| 7940 | 27 // Filling in attest information |
| 7941 | 28 // Common fields |
| 7942 | 29 result = FillInAttestInfo(in->signHandle, |
| 7943 | 30 &in->inScheme, |
| 7944 | 31 &in->qualifyingData, |
| 7945 | 32 &auditInfo); |
| 7946 | 33 if(result != TPM_RC_SUCCESS) |
| 7947 | 34 { |
| 7948 | 35 if(result == TPM_RC_KEY) |
| 7949 | 36 return TPM_RC_KEY + RC_GetSessionAuditDigest_signHandle; |
| 7950 | 37 else |
| 7951 | 38 return RcSafeAddToResult(result, RC_GetSessionAuditDigest_inScheme); |
| 7952 | 39 } |
| 7953 | 40 |
| 7954 | 41 // SessionAuditDigest specific fields |
| 7955 | 42 // Attestation type |
| 7956 | 43 auditInfo.type = TPM_ST_ATTEST_SESSION_AUDIT; |
| 7957 | 44 |
| 7958 | 45 // Copy digest |
| 7959 | 46 auditInfo.attested.sessionAudit.sessionDigest = session->u2.auditDigest; |
| 7960 | |
| 7961 | Page 170 TCG Published Family “2.0” |
| 7962 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 7963 | Trusted Platform Module Library Part 3: Commands |
| 7964 | |
| 7965 | 47 |
| 7966 | 48 // Exclusive audit session |
| 7967 | 49 if(g_exclusiveAuditSession == in->sessionHandle) |
| 7968 | 50 auditInfo.attested.sessionAudit.exclusiveSession = TRUE; |
| 7969 | 51 else |
| 7970 | 52 auditInfo.attested.sessionAudit.exclusiveSession = FALSE; |
| 7971 | 53 |
| 7972 | 54 // Sign attestation structure. A NULL signature will be returned if |
| 7973 | 55 // signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE, |
| 7974 | 56 // TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned at |
| 7975 | 57 // this point |
| 7976 | 58 result = SignAttestInfo(in->signHandle, |
| 7977 | 59 &in->inScheme, |
| 7978 | 60 &auditInfo, |
| 7979 | 61 &in->qualifyingData, |
| 7980 | 62 &out->auditInfo, |
| 7981 | 63 &out->signature); |
| 7982 | 64 if(result != TPM_RC_SUCCESS) |
| 7983 | 65 return result; |
| 7984 | 66 |
| 7985 | 67 // orderly state should be cleared because of the reporting of clock info |
| 7986 | 68 // if signing happens |
| 7987 | 69 if(in->signHandle != TPM_RH_NULL) |
| 7988 | 70 g_clearOrderly = TRUE; |
| 7989 | 71 |
| 7990 | 72 return TPM_RC_SUCCESS; |
| 7991 | 73 } |
| 7992 | 74 #endif // CC_GetSessionAuditDigest |
| 7993 | |
| 7994 | |
| 7995 | |
| 7996 | |
| 7997 | Family “2.0” TCG Published Page 171 |
| 7998 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 7999 | Part 3: Commands Trusted Platform Module Library |
| 8000 | |
| 8001 | |
| 8002 | 18.6 TPM2_GetCommandAuditDigest |
| 8003 | |
| 8004 | 18.6.1 General Description |
| 8005 | |
| 8006 | This command returns the current value of the command audit digest, a digest of the commands being |
| 8007 | audited, and the audit hash algorithm. These values are placed in an attestation structure and signed with |
| 8008 | the key referenced by signHandle. |
| 8009 | |
| 8010 | NOTE 1 See 18.1 for description of how the signing scheme is selected. |
| 8011 | |
| 8012 | When this command completes successfully, and signHandle is not TPM_RH_NULL, the audit digest is |
| 8013 | cleared. If signHandle is TPM_RH_NULL, signature is the Empty Buffer and the audit digest is not |
| 8014 | cleared. |
| 8015 | |
| 8016 | NOTE 2 The way that the TPM tracks that the digest is clear is vendor-dependent. The reference |
| 8017 | implementation resets the size of the digest to zero. |
| 8018 | |
| 8019 | If this command is being audited, then the signed digest produced by the command will not include the |
| 8020 | command. At the end of this command, the audit digest will be extended with cpHash and the rpHash of |
| 8021 | the command which would change the command audit digest signed by the next invocation of this |
| 8022 | command. |
| 8023 | This command requires authorization from the privacy administrator of the TPM (expressed with |
| 8024 | Endorsement Authorization) as well as authorization to use the key associated with signHandle. |
| 8025 | |
| 8026 | |
| 8027 | |
| 8028 | |
| 8029 | Page 172 TCG Published Family “2.0” |
| 8030 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 8031 | Trusted Platform Module Library Part 3: Commands |
| 8032 | |
| 8033 | |
| 8034 | |
| 8035 | 18.6.2 Command and Response |
| 8036 | |
| 8037 | Table 85 — TPM2_GetCommandAuditDigest Command |
| 8038 | Type Name Description |
| 8039 | |
| 8040 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 8041 | UINT32 commandSize |
| 8042 | TPM_CC commandCode TPM_CC_GetCommandAuditDigest {NV} |
| 8043 | |
| 8044 | handle of the privacy administrator |
| 8045 | (TPM_RH_ENDORSEMENT) |
| 8046 | TPMI_RH_ENDORSEMENT @privacyHandle |
| 8047 | Auth Index: 1 |
| 8048 | Auth Role: USER |
| 8049 | the handle of the signing key |
| 8050 | TPMI_DH_OBJECT+ @signHandle Auth Index: 2 |
| 8051 | Auth Role: USER |
| 8052 | |
| 8053 | TPM2B_DATA qualifyingData other data to associate with this audit digest |
| 8054 | signing scheme to use if the scheme for signHandle is |
| 8055 | TPMT_SIG_SCHEME+ inScheme |
| 8056 | TPM_ALG_NULL |
| 8057 | |
| 8058 | |
| 8059 | Table 86 — TPM2_GetCommandAuditDigest Response |
| 8060 | Type Name Description |
| 8061 | |
| 8062 | TPM_ST tag see clause 6 |
| 8063 | UINT32 responseSize |
| 8064 | TPM_RC responseCode |
| 8065 | |
| 8066 | TPM2B_ATTEST auditInfo the auditInfo that was signed |
| 8067 | TPMT_SIGNATURE signature the signature over auditInfo |
| 8068 | |
| 8069 | |
| 8070 | |
| 8071 | |
| 8072 | Family “2.0” TCG Published Page 173 |
| 8073 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 8074 | Part 3: Commands Trusted Platform Module Library |
| 8075 | |
| 8076 | |
| 8077 | |
| 8078 | 18.6.3 Detailed Actions |
| 8079 | |
| 8080 | 1 #include "InternalRoutines.h" |
| 8081 | 2 #include "Attest_spt_fp.h" |
| 8082 | 3 #include "GetCommandAuditDigest_fp.h" |
| 8083 | 4 #ifdef TPM_CC_GetCommandAuditDigest // Conditional expansion of this file |
| 8084 | |
| 8085 | |
| 8086 | Error Returns Meaning |
| 8087 | |
| 8088 | TPM_RC_KEY key referenced by signHandle is not a signing key |
| 8089 | TPM_RC_SCHEME inScheme is incompatible with signHandle type; or both scheme and |
| 8090 | key's default scheme are empty; or scheme is empty while key's |
| 8091 | default scheme requires explicit input scheme (split signing); or non- |
| 8092 | empty default key scheme differs from scheme |
| 8093 | TPM_RC_VALUE digest generated for the given scheme is greater than the modulus of |
| 8094 | signHandle (for an RSA key); invalid commit status or failed to |
| 8095 | generate r value (for an ECC key) |
| 8096 | |
| 8097 | 5 TPM_RC |
| 8098 | 6 TPM2_GetCommandAuditDigest( |
| 8099 | 7 GetCommandAuditDigest_In *in, // IN: input parameter list |
| 8100 | 8 GetCommandAuditDigest_Out *out // OUT: output parameter list |
| 8101 | 9 ) |
| 8102 | 10 { |
| 8103 | 11 TPM_RC result; |
| 8104 | 12 TPMS_ATTEST auditInfo; |
| 8105 | 13 |
| 8106 | 14 // Command Output |
| 8107 | 15 |
| 8108 | 16 // Filling in attest information |
| 8109 | 17 // Common fields |
| 8110 | 18 result = FillInAttestInfo(in->signHandle, |
| 8111 | 19 &in->inScheme, |
| 8112 | 20 &in->qualifyingData, |
| 8113 | 21 &auditInfo); |
| 8114 | 22 if(result != TPM_RC_SUCCESS) |
| 8115 | 23 { |
| 8116 | 24 if(result == TPM_RC_KEY) |
| 8117 | 25 return TPM_RC_KEY + RC_GetCommandAuditDigest_signHandle; |
| 8118 | 26 else |
| 8119 | 27 return RcSafeAddToResult(result, RC_GetCommandAuditDigest_inScheme); |
| 8120 | 28 } |
| 8121 | 29 |
| 8122 | 30 // CommandAuditDigest specific fields |
| 8123 | 31 // Attestation type |
| 8124 | 32 auditInfo.type = TPM_ST_ATTEST_COMMAND_AUDIT; |
| 8125 | 33 |
| 8126 | 34 // Copy audit hash algorithm |
| 8127 | 35 auditInfo.attested.commandAudit.digestAlg = gp.auditHashAlg; |
| 8128 | 36 |
| 8129 | 37 // Copy counter value |
| 8130 | 38 auditInfo.attested.commandAudit.auditCounter = gp.auditCounter; |
| 8131 | 39 |
| 8132 | 40 // Copy command audit log |
| 8133 | 41 auditInfo.attested.commandAudit.auditDigest = gr.commandAuditDigest; |
| 8134 | 42 CommandAuditGetDigest(&auditInfo.attested.commandAudit.commandDigest); |
| 8135 | 43 |
| 8136 | 44 // Sign attestation structure. A NULL signature will be returned if |
| 8137 | 45 // signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE, |
| 8138 | 46 // TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned at |
| 8139 | 47 // this point |
| 8140 | |
| 8141 | Page 174 TCG Published Family “2.0” |
| 8142 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 8143 | Trusted Platform Module Library Part 3: Commands |
| 8144 | |
| 8145 | 48 result = SignAttestInfo(in->signHandle, |
| 8146 | 49 &in->inScheme, |
| 8147 | 50 &auditInfo, |
| 8148 | 51 &in->qualifyingData, |
| 8149 | 52 &out->auditInfo, |
| 8150 | 53 &out->signature); |
| 8151 | 54 |
| 8152 | 55 if(result != TPM_RC_SUCCESS) |
| 8153 | 56 return result; |
| 8154 | 57 |
| 8155 | 58 // Internal Data Update |
| 8156 | 59 |
| 8157 | 60 if(in->signHandle != TPM_RH_NULL) |
| 8158 | 61 { |
| 8159 | 62 // Reset log |
| 8160 | 63 gr.commandAuditDigest.t.size = 0; |
| 8161 | 64 |
| 8162 | 65 // orderly state should be cleared because of the update in |
| 8163 | 66 // commandAuditDigest, as well as the reporting of clock info |
| 8164 | 67 g_clearOrderly = TRUE; |
| 8165 | 68 } |
| 8166 | 69 |
| 8167 | 70 return TPM_RC_SUCCESS; |
| 8168 | 71 } |
| 8169 | 72 #endif // CC_GetCommandAuditDigest |
| 8170 | |
| 8171 | |
| 8172 | |
| 8173 | |
| 8174 | Family “2.0” TCG Published Page 175 |
| 8175 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 8176 | Part 3: Commands Trusted Platform Module Library |
| 8177 | |
| 8178 | |
| 8179 | 18.7 TPM2_GetTime |
| 8180 | |
| 8181 | 18.7.1 General Description |
| 8182 | |
| 8183 | This command returns the current values of Time and Clock. |
| 8184 | |
| 8185 | NOTE 1 See 18.1 for description of how the signing scheme is selected. |
| 8186 | |
| 8187 | The values of Clock, resetCount and restartCount appear in two places in timeInfo: once in |
| 8188 | TPMS_ATTEST.clockInfo and again in TPMS_ATTEST.attested.time.clockInfo. The firmware version |
| 8189 | number also appears in two places (TPMS_ATTEST.firmwareVersion and |
| 8190 | TPMS_ATTEST.attested.time.firmwareVersion). If signHandle is in the endorsement or platform |
| 8191 | hierarchies, both copies of the data will be the same. However, if signHandle is in the storage hierarchy or |
| 8192 | is TPM_RH_NULL, the values in TPMS_ATTEST.clockInfo and TPMS_ATTEST.firmwareVersion are |
| 8193 | obfuscated but the values in TPMS_ATTEST.attested.time are not. |
| 8194 | |
| 8195 | NOTE 2 The purpose of this duplication is to allow an entity who is trusted by the privacy Administrator to |
| 8196 | correlate the obfuscated values with the clear-text values. This command requires Endorsement |
| 8197 | Authorization. |
| 8198 | |
| 8199 | NOTE 3 If signHandle is TPM_RH_NULL, the TPMS_ATTEST structure is returned and signature is a NULL |
| 8200 | Signature. |
| 8201 | |
| 8202 | |
| 8203 | |
| 8204 | |
| 8205 | Page 176 TCG Published Family “2.0” |
| 8206 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 8207 | Trusted Platform Module Library Part 3: Commands |
| 8208 | |
| 8209 | |
| 8210 | |
| 8211 | 18.7.2 Command and Response |
| 8212 | |
| 8213 | Table 87 — TPM2_GetTime Command |
| 8214 | Type Name Description |
| 8215 | |
| 8216 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 8217 | UINT32 commandSize |
| 8218 | TPM_CC commandCode TPM_CC_GetTime |
| 8219 | |
| 8220 | handle of the privacy administrator |
| 8221 | (TPM_RH_ENDORSEMENT) |
| 8222 | TPMI_RH_ENDORSEMENT @privacyAdminHandle |
| 8223 | Auth Index: 1 |
| 8224 | Auth Role: USER |
| 8225 | the keyHandle identifier of a loaded key that can |
| 8226 | perform digital signatures |
| 8227 | TPMI_DH_OBJECT+ @signHandle |
| 8228 | Auth Index: 2 |
| 8229 | Auth Role: USER |
| 8230 | |
| 8231 | TPM2B_DATA qualifyingData data to tick stamp |
| 8232 | signing scheme to use if the scheme for signHandle is |
| 8233 | TPMT_SIG_SCHEME+ inScheme |
| 8234 | TPM_ALG_NULL |
| 8235 | |
| 8236 | |
| 8237 | Table 88 — TPM2_GetTime Response |
| 8238 | Type Name Description |
| 8239 | |
| 8240 | TPM_ST tag see clause 6 |
| 8241 | UINT32 responseSize |
| 8242 | TPM_RC responseCode . |
| 8243 | |
| 8244 | TPM2B_ATTEST timeInfo standard TPM-generated attestation block |
| 8245 | TPMT_SIGNATURE signature the signature over timeInfo |
| 8246 | |
| 8247 | |
| 8248 | |
| 8249 | |
| 8250 | Family “2.0” TCG Published Page 177 |
| 8251 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 8252 | Part 3: Commands Trusted Platform Module Library |
| 8253 | |
| 8254 | |
| 8255 | |
| 8256 | 18.7.3 Detailed Actions |
| 8257 | |
| 8258 | 1 #include "InternalRoutines.h" |
| 8259 | 2 #include "Attest_spt_fp.h" |
| 8260 | 3 #include "GetTime_fp.h" |
| 8261 | 4 #ifdef TPM_CC_GetTime // Conditional expansion of this file |
| 8262 | |
| 8263 | |
| 8264 | Error Returns Meaning |
| 8265 | |
| 8266 | TPM_RC_KEY key referenced by signHandle is not a signing key |
| 8267 | TPM_RC_SCHEME inScheme is incompatible with signHandle type; or both scheme and |
| 8268 | key's default scheme are empty; or scheme is empty while key's |
| 8269 | default scheme requires explicit input scheme (split signing); or non- |
| 8270 | empty default key scheme differs from scheme |
| 8271 | TPM_RC_VALUE digest generated for the given scheme is greater than the modulus of |
| 8272 | signHandle (for an RSA key); invalid commit status or failed to |
| 8273 | generate r value (for an ECC key) |
| 8274 | |
| 8275 | 5 TPM_RC |
| 8276 | 6 TPM2_GetTime( |
| 8277 | 7 GetTime_In *in, // IN: input parameter list |
| 8278 | 8 GetTime_Out *out // OUT: output parameter list |
| 8279 | 9 ) |
| 8280 | 10 { |
| 8281 | 11 TPM_RC result; |
| 8282 | 12 TPMS_ATTEST timeInfo; |
| 8283 | 13 |
| 8284 | 14 // Command Output |
| 8285 | 15 |
| 8286 | 16 // Filling in attest information |
| 8287 | 17 // Common fields |
| 8288 | 18 result = FillInAttestInfo(in->signHandle, |
| 8289 | 19 &in->inScheme, |
| 8290 | 20 &in->qualifyingData, |
| 8291 | 21 &timeInfo); |
| 8292 | 22 if(result != TPM_RC_SUCCESS) |
| 8293 | 23 { |
| 8294 | 24 if(result == TPM_RC_KEY) |
| 8295 | 25 return TPM_RC_KEY + RC_GetTime_signHandle; |
| 8296 | 26 else |
| 8297 | 27 return RcSafeAddToResult(result, RC_GetTime_inScheme); |
| 8298 | 28 } |
| 8299 | 29 |
| 8300 | 30 // GetClock specific fields |
| 8301 | 31 // Attestation type |
| 8302 | 32 timeInfo.type = TPM_ST_ATTEST_TIME; |
| 8303 | 33 |
| 8304 | 34 // current clock in plain text |
| 8305 | 35 timeInfo.attested.time.time.time = g_time; |
| 8306 | 36 TimeFillInfo(&timeInfo.attested.time.time.clockInfo); |
| 8307 | 37 |
| 8308 | 38 // Firmware version in plain text |
| 8309 | 39 timeInfo.attested.time.firmwareVersion |
| 8310 | 40 = ((UINT64) gp.firmwareV1) << 32; |
| 8311 | 41 timeInfo.attested.time.firmwareVersion += gp.firmwareV2; |
| 8312 | 42 |
| 8313 | 43 // Sign attestation structure. A NULL signature will be returned if |
| 8314 | 44 // signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE, |
| 8315 | 45 // TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned at |
| 8316 | 46 // this point |
| 8317 | 47 result = SignAttestInfo(in->signHandle, |
| 8318 | |
| 8319 | Page 178 TCG Published Family “2.0” |
| 8320 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 8321 | Trusted Platform Module Library Part 3: Commands |
| 8322 | |
| 8323 | 48 &in->inScheme, |
| 8324 | 49 &timeInfo, |
| 8325 | 50 &in->qualifyingData, |
| 8326 | 51 &out->timeInfo, |
| 8327 | 52 &out->signature); |
| 8328 | 53 if(result != TPM_RC_SUCCESS) |
| 8329 | 54 return result; |
| 8330 | 55 |
| 8331 | 56 // orderly state should be cleared because of the reporting of clock info |
| 8332 | 57 // if signing happens |
| 8333 | 58 if(in->signHandle != TPM_RH_NULL) |
| 8334 | 59 g_clearOrderly = TRUE; |
| 8335 | 60 |
| 8336 | 61 return TPM_RC_SUCCESS; |
| 8337 | 62 } |
| 8338 | 63 #endif // CC_GetTime |
| 8339 | |
| 8340 | |
| 8341 | |
| 8342 | |
| 8343 | Family “2.0” TCG Published Page 179 |
| 8344 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 8345 | Part 3: Commands Trusted Platform Module Library |
| 8346 | |
| 8347 | |
| 8348 | 19 Ephemeral EC Keys |
| 8349 | |
| 8350 | 19.1 Introduction |
| 8351 | |
| 8352 | The TPM generates keys that have different lifetimes. TPM keys in a hierarchy can be persistent for as |
| 8353 | long as the seed of the hierarchy is unchanged and these keys may be used multiple times. Other TPM- |
| 8354 | generated keys are only useful for a single operation. Some of these single-use keys are used in the |
| 8355 | command in which they are created. Examples of this use are TPM2_Duplicate() where an ephemeral |
| 8356 | key is created for a single pass key exchange with another TPM. However, there are other cases, such |
| 8357 | as anonymous attestation, where the protocol requires two passes where the public part of the ephemeral |
| 8358 | key is used outside of the TPM before the final command "consumes" the ephemeral key. |
| 8359 | For these uses, TPM2_Commit() or TPM2_EC_Ephemeral() may be used to have the TPM create an |
| 8360 | ephemeral EC key and return the public part of the key for external use. Then in a subsequent command, |
| 8361 | the caller provides a reference to the ephemeral key so that the TPM can retrieve or recreate the |
| 8362 | associated private key. |
| 8363 | When an ephemeral EC key is created, it is assigned a number and that number is returned to the caller |
| 8364 | as the identifier for the key. This number is not a handle. A handle is assigned to a key that may be |
| 8365 | context saved but these ephemeral EC keys may not be saved and do not have a full key context. When |
| 8366 | a subsequent command uses the ephemeral key, the caller provides the number of the ephemeral key. |
| 8367 | The TPM uses that number to either look up or recompute the associated private key. After the key is |
| 8368 | used, the TPM records the fact that the key has been used so that it cannot be used again. |
| 8369 | As mentioned, the TPM can keep each assigned private ephemeral key in memory until it is used. |
| 8370 | However, this could consume a large amount of memory. To limit the memory size, the TPM is allowed to |
| 8371 | restrict the number of pending private keys – keys that have been allocated but not used. |
| 8372 | |
| 8373 | NOTE The minimum number of ephemeral keys is determined by a platform specific specification |
| 8374 | |
| 8375 | To further reduce the memory requirements for the ephemeral private keys, the TPM is allowed to use |
| 8376 | pseudo-random values for the ephemeral keys. Instead of keeping the full value of the key in memory, the |
| 8377 | TPM can use a counter as input to a KDF. Incrementing the counter will cause the TPM to generate a |
| 8378 | new pseudo-random value. |
| 8379 | Using the counter to generate pseudo-random private ephemeral keys greatly simplifies tracking of key |
| 8380 | usage. When a counter value is used to create a key, a bit in an array may be set to indicate that the key |
| 8381 | use is pending. When the ephemeral key is consumed, the bit is cleared. This prevents the key from |
| 8382 | being used more than once. |
| 8383 | Since the TPM is allowed to restrict the number of pending ephemeral keys, the array size can be limited. |
| 8384 | For example, a 128 bit array would allow 128 keys to be "pending". |
| 8385 | The management of the array is described in greater detail in the Split Operations clause in Annex C of |
| 8386 | TPM 2.0 Part 1. |
| 8387 | |
| 8388 | |
| 8389 | |
| 8390 | |
| 8391 | Page 180 TCG Published Family “2.0” |
| 8392 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 8393 | Trusted Platform Module Library Part 3: Commands |
| 8394 | |
| 8395 | |
| 8396 | |
| 8397 | 19.2 TPM2_Commit |
| 8398 | |
| 8399 | 19.2.1 General Description |
| 8400 | |
| 8401 | TPM2_Commit() performs the first part of an ECC anonymous signing operation. The TPM will perform |
| 8402 | the point multiplications on the provided points and return intermediate signing values. The signHandle |
| 8403 | parameter shall refer to an ECC key with the sign attribute (TPM_RC_ATTRIBUTES) and the signing |
| 8404 | scheme must be anonymous (TPM_RC_SCHEME). Currently, TPM_ALG_ECDAA is the only defined |
| 8405 | anonymous scheme. |
| 8406 | |
| 8407 | NOTE This command cannot be used with a sign+decrypt key because that type of key is req uired to have |
| 8408 | a scheme of TPM_ALG_NULL. |
| 8409 | |
| 8410 | For this command, p1, s2 and y2 are optional parameters. If s2 is an Empty Buffer, then the TPM shall |
| 8411 | return TPM_RC_SIZE if y2 is not an Empty Buffer. |
| 8412 | The algorithm is specified in the TPM 2.0 Part 1 Annex for ECC, TPM2_Commit(). |
| 8413 | |
| 8414 | |
| 8415 | |
| 8416 | |
| 8417 | Family “2.0” TCG Published Page 181 |
| 8418 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 8419 | Part 3: Commands Trusted Platform Module Library |
| 8420 | |
| 8421 | |
| 8422 | |
| 8423 | 19.2.2 Command and Response |
| 8424 | |
| 8425 | Table 89 — TPM2_Commit Command |
| 8426 | Type Name Description |
| 8427 | |
| 8428 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 8429 | |
| 8430 | UINT32 commandSize |
| 8431 | |
| 8432 | TPM_CC commandCode TPM_CC_Commit |
| 8433 | |
| 8434 | handle of the key that will be used in the signing |
| 8435 | operation |
| 8436 | TPMI_DH_OBJECT @signHandle |
| 8437 | Auth Index: 1 |
| 8438 | Auth Role: USER |
| 8439 | |
| 8440 | TPM2B_ECC_POINT P1 a point (M) on the curve used by signHandle |
| 8441 | |
| 8442 | TPM2B_SENSITIVE_DATA s2 octet array used to derive x-coordinate of a base point |
| 8443 | |
| 8444 | TPM2B_ECC_PARAMETER y2 y coordinate of the point associated with s2 |
| 8445 | |
| 8446 | |
| 8447 | Table 90 — TPM2_Commit Response |
| 8448 | Type Name Description |
| 8449 | |
| 8450 | TPM_ST tag see 6 |
| 8451 | |
| 8452 | UINT32 responseSize |
| 8453 | |
| 8454 | TPM_RC responseCode |
| 8455 | |
| 8456 | TPM2B_ECC_POINT K ECC point K ≔ [ds](x2, y2) |
| 8457 | |
| 8458 | TPM2B_ECC_POINT L ECC point L ≔ [r](x2, y2) |
| 8459 | |
| 8460 | TPM2B_ECC_POINT E ECC point E ≔ [r]P1 |
| 8461 | |
| 8462 | UINT16 counter least-significant 16 bits of commitCount |
| 8463 | |
| 8464 | |
| 8465 | |
| 8466 | |
| 8467 | Page 182 TCG Published Family “2.0” |
| 8468 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 8469 | Trusted Platform Module Library Part 3: Commands |
| 8470 | |
| 8471 | |
| 8472 | 19.2.3 Detailed Actions |
| 8473 | |
| 8474 | 1 #include "InternalRoutines.h" |
| 8475 | 2 #include "Commit_fp.h" |
| 8476 | 3 #ifdef TPM_CC_Commit // Conditional expansion of this file |
| 8477 | 4 #ifdef TPM_ALG_ECC |
| 8478 | |
| 8479 | |
| 8480 | Error Returns Meaning |
| 8481 | |
| 8482 | TPM_RC_ATTRIBUTES keyHandle references a restricted key that is not a signing key |
| 8483 | TPM_RC_ECC_POINT either P1 or the point derived from s2 is not on the curve of |
| 8484 | keyHandle |
| 8485 | TPM_RC_HASH invalid name algorithm in keyHandle |
| 8486 | TPM_RC_KEY keyHandle does not reference an ECC key |
| 8487 | TPM_RC_SCHEME the scheme of keyHandle is not an anonymous scheme |
| 8488 | TPM_RC_NO_RESULT K, L or E was a point at infinity; or failed to generate r value |
| 8489 | TPM_RC_SIZE s2 is empty but y2 is not or s2 provided but y2 is not |
| 8490 | |
| 8491 | 5 TPM_RC |
| 8492 | 6 TPM2_Commit( |
| 8493 | 7 Commit_In *in, // IN: input parameter list |
| 8494 | 8 Commit_Out *out // OUT: output parameter list |
| 8495 | 9 ) |
| 8496 | 10 { |
| 8497 | 11 OBJECT *eccKey; |
| 8498 | 12 TPMS_ECC_POINT P2; |
| 8499 | 13 TPMS_ECC_POINT *pP2 = NULL; |
| 8500 | 14 TPMS_ECC_POINT *pP1 = NULL; |
| 8501 | 15 TPM2B_ECC_PARAMETER r; |
| 8502 | 16 TPM2B *p; |
| 8503 | 17 TPM_RC result; |
| 8504 | 18 TPMS_ECC_PARMS *parms; |
| 8505 | 19 |
| 8506 | 20 // Input Validation |
| 8507 | 21 |
| 8508 | 22 eccKey = ObjectGet(in->signHandle); |
| 8509 | 23 parms = & eccKey->publicArea.parameters.eccDetail; |
| 8510 | 24 |
| 8511 | 25 // Input key must be an ECC key |
| 8512 | 26 if(eccKey->publicArea.type != TPM_ALG_ECC) |
| 8513 | 27 return TPM_RC_KEY + RC_Commit_signHandle; |
| 8514 | 28 |
| 8515 | 29 // This command may only be used with a sign-only key using an anonymous |
| 8516 | 30 // scheme. |
| 8517 | 31 // NOTE: a sign + decrypt key has no scheme so it will not be an anonymous one |
| 8518 | 32 // and an unrestricted sign key might no have a signing scheme but it can't |
| 8519 | 33 // be use in Commit() |
| 8520 | 34 if(!CryptIsSchemeAnonymous(parms->scheme.scheme)) |
| 8521 | 35 return TPM_RC_SCHEME + RC_Commit_signHandle; |
| 8522 | 36 |
| 8523 | 37 // Make sure that both parts of P2 are present if either is present |
| 8524 | 38 if((in->s2.t.size == 0) != (in->y2.t.size == 0)) |
| 8525 | 39 return TPM_RC_SIZE + RC_Commit_y2; |
| 8526 | 40 |
| 8527 | 41 // Get prime modulus for the curve. This is needed later but getting this now |
| 8528 | 42 // allows confirmation that the curve exists |
| 8529 | 43 p = (TPM2B *)CryptEccGetParameter('p', parms->curveID); |
| 8530 | 44 |
| 8531 | 45 // if no p, then the curve ID is bad |
| 8532 | |
| 8533 | |
| 8534 | Family “2.0” TCG Published Page 183 |
| 8535 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 8536 | Part 3: Commands Trusted Platform Module Library |
| 8537 | |
| 8538 | 46 // NOTE: This should never occur if the input unmarshaling code is working |
| 8539 | 47 // correctly |
| 8540 | 48 pAssert(p != NULL); |
| 8541 | 49 |
| 8542 | 50 // Get the random value that will be used in the point multiplications |
| 8543 | 51 // Note: this does not commit the count. |
| 8544 | 52 if(!CryptGenerateR(&r, NULL, parms->curveID, &eccKey->name)) |
| 8545 | 53 return TPM_RC_NO_RESULT; |
| 8546 | 54 |
| 8547 | 55 // Set up P2 if s2 and Y2 are provided |
| 8548 | 56 if(in->s2.t.size != 0) |
| 8549 | 57 { |
| 8550 | 58 pP2 = &P2; |
| 8551 | 59 |
| 8552 | 60 // copy y2 for P2 |
| 8553 | 61 MemoryCopy2B(&P2.y.b, &in->y2.b, sizeof(P2.y.t.buffer)); |
| 8554 | 62 // Compute x2 HnameAlg(s2) mod p |
| 8555 | 63 |
| 8556 | 64 // do the hash operation on s2 with the size of curve 'p' |
| 8557 | 65 P2.x.t.size = CryptHashBlock(eccKey->publicArea.nameAlg, |
| 8558 | 66 in->s2.t.size, |
| 8559 | 67 in->s2.t.buffer, |
| 8560 | 68 p->size, |
| 8561 | 69 P2.x.t.buffer); |
| 8562 | 70 |
| 8563 | 71 // If there were error returns in the hash routine, indicate a problem |
| 8564 | 72 // with the hash in |
| 8565 | 73 if(P2.x.t.size == 0) |
| 8566 | 74 return TPM_RC_HASH + RC_Commit_signHandle; |
| 8567 | 75 |
| 8568 | 76 // set p2.x = hash(s2) mod p |
| 8569 | 77 if(CryptDivide(&P2.x.b, p, NULL, &P2.x.b) != TPM_RC_SUCCESS) |
| 8570 | 78 return TPM_RC_NO_RESULT; |
| 8571 | 79 |
| 8572 | 80 if(!CryptEccIsPointOnCurve(parms->curveID, pP2)) |
| 8573 | 81 return TPM_RC_ECC_POINT + RC_Commit_s2; |
| 8574 | 82 |
| 8575 | 83 if(eccKey->attributes.publicOnly == SET) |
| 8576 | 84 return TPM_RC_KEY + RC_Commit_signHandle; |
| 8577 | 85 |
| 8578 | 86 } |
| 8579 | 87 // If there is a P1, make sure that it is on the curve |
| 8580 | 88 // NOTE: an "empty" point has two UINT16 values which are the size values |
| 8581 | 89 // for each of the coordinates. |
| 8582 | 90 if(in->P1.t.size > 4) |
| 8583 | 91 { |
| 8584 | 92 pP1 = &in->P1.t.point; |
| 8585 | 93 if(!CryptEccIsPointOnCurve(parms->curveID, pP1)) |
| 8586 | 94 return TPM_RC_ECC_POINT + RC_Commit_P1; |
| 8587 | 95 } |
| 8588 | 96 |
| 8589 | 97 // Pass the parameters to CryptCommit. |
| 8590 | 98 // The work is not done in-line because it does several point multiplies |
| 8591 | 99 // with the same curve. There is significant optimization by not |
| 8592 | 100 // having to reload the curve parameters multiple times. |
| 8593 | 101 result = CryptCommitCompute(&out->K.t.point, |
| 8594 | 102 &out->L.t.point, |
| 8595 | 103 &out->E.t.point, |
| 8596 | 104 parms->curveID, |
| 8597 | 105 pP1, |
| 8598 | 106 pP2, |
| 8599 | 107 &eccKey->sensitive.sensitive.ecc, |
| 8600 | 108 &r); |
| 8601 | 109 if(result != TPM_RC_SUCCESS) |
| 8602 | 110 return result; |
| 8603 | 111 |
| 8604 | |
| 8605 | Page 184 TCG Published Family “2.0” |
| 8606 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 8607 | Trusted Platform Module Library Part 3: Commands |
| 8608 | |
| 8609 | 112 out->K.t.size = TPMS_ECC_POINT_Marshal(&out->K.t.point, NULL, NULL); |
| 8610 | 113 out->L.t.size = TPMS_ECC_POINT_Marshal(&out->L.t.point, NULL, NULL); |
| 8611 | 114 out->E.t.size = TPMS_ECC_POINT_Marshal(&out->E.t.point, NULL, NULL); |
| 8612 | 115 |
| 8613 | 116 // The commit computation was successful so complete the commit by setting |
| 8614 | 117 // the bit |
| 8615 | 118 out->counter = CryptCommit(); |
| 8616 | 119 |
| 8617 | 120 return TPM_RC_SUCCESS; |
| 8618 | 121 } |
| 8619 | 122 #endif |
| 8620 | 123 #endif // CC_Commit |
| 8621 | |
| 8622 | |
| 8623 | |
| 8624 | |
| 8625 | Family “2.0” TCG Published Page 185 |
| 8626 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 8627 | Part 3: Commands Trusted Platform Module Library |
| 8628 | |
| 8629 | |
| 8630 | |
| 8631 | 19.3 TPM2_EC_Ephemeral |
| 8632 | |
| 8633 | 19.3.1 General Description |
| 8634 | |
| 8635 | TPM2_EC_Ephemeral() creates an ephemeral key for use in a two-phase key exchange protocol. |
| 8636 | The TPM will use the commit mechanism to assign an ephemeral key r and compute a public point Q ≔ |
| 8637 | [r]G where G is the generator point associated with curveID. |
| 8638 | |
| 8639 | |
| 8640 | |
| 8641 | |
| 8642 | Page 186 TCG Published Family “2.0” |
| 8643 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 8644 | Trusted Platform Module Library Part 3: Commands |
| 8645 | |
| 8646 | |
| 8647 | |
| 8648 | 19.3.2 Command and Response |
| 8649 | |
| 8650 | Table 91 — TPM2_EC_Ephemeral Command |
| 8651 | Type Name Description |
| 8652 | |
| 8653 | TPM_ST_SESSIONS if an audit or encrypt session is |
| 8654 | TPMI_ST_COMMAND_TAG tag |
| 8655 | present; otherwise, TPM_ST_NO_SESSIONS |
| 8656 | |
| 8657 | UINT32 commandSize |
| 8658 | |
| 8659 | TPM_CC commandCode TPM_CC_EC_Ephemeral |
| 8660 | |
| 8661 | TPMI_ECC_CURVE curveID The curve for the computed ephemeral point |
| 8662 | |
| 8663 | |
| 8664 | Table 92 — TPM2_EC_Ephemeral Response |
| 8665 | Type Name Description |
| 8666 | |
| 8667 | TPM_ST tag see 6 |
| 8668 | |
| 8669 | UINT32 responseSize |
| 8670 | |
| 8671 | TPM_RC responseCode |
| 8672 | |
| 8673 | TPM2B_ECC_POINT Q ephemeral public key Q ≔ [r]G |
| 8674 | |
| 8675 | UINT16 counter least-significant 16 bits of commitCount |
| 8676 | |
| 8677 | |
| 8678 | |
| 8679 | |
| 8680 | Family “2.0” TCG Published Page 187 |
| 8681 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 8682 | Part 3: Commands Trusted Platform Module Library |
| 8683 | |
| 8684 | |
| 8685 | 19.3.3 Detailed Actions |
| 8686 | |
| 8687 | 1 #include "InternalRoutines.h" |
| 8688 | 2 #include "EC_Ephemeral_fp.h" |
| 8689 | 3 #ifdef TPM_CC_EC_Ephemeral // Conditional expansion of this file |
| 8690 | 4 #ifdef TPM_ALG_ECC |
| 8691 | |
| 8692 | |
| 8693 | Error Returns Meaning |
| 8694 | |
| 8695 | none ... |
| 8696 | |
| 8697 | 5 TPM_RC |
| 8698 | 6 TPM2_EC_Ephemeral( |
| 8699 | 7 EC_Ephemeral_In *in, // IN: input parameter list |
| 8700 | 8 EC_Ephemeral_Out *out // OUT: output parameter list |
| 8701 | 9 ) |
| 8702 | 10 { |
| 8703 | 11 TPM2B_ECC_PARAMETER r; |
| 8704 | 12 |
| 8705 | 13 // Get the random value that will be used in the point multiplications |
| 8706 | 14 // Note: this does not commit the count. |
| 8707 | 15 if(!CryptGenerateR(&r, |
| 8708 | 16 NULL, |
| 8709 | 17 in->curveID, |
| 8710 | 18 NULL)) |
| 8711 | 19 return TPM_RC_NO_RESULT; |
| 8712 | 20 |
| 8713 | 21 CryptEccPointMultiply(&out->Q.t.point, in->curveID, &r, NULL); |
| 8714 | 22 |
| 8715 | 23 // commit the count value |
| 8716 | 24 out->counter = CryptCommit(); |
| 8717 | 25 |
| 8718 | 26 return TPM_RC_SUCCESS; |
| 8719 | 27 } |
| 8720 | 28 #endif |
| 8721 | 29 #endif // CC_EC_Ephemeral |
| 8722 | |
| 8723 | |
| 8724 | |
| 8725 | |
| 8726 | Page 188 TCG Published Family “2.0” |
| 8727 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 8728 | Trusted Platform Module Library Part 3: Commands |
| 8729 | |
| 8730 | |
| 8731 | 20 Signing and Signature Verification |
| 8732 | |
| 8733 | 20.1 TPM2_VerifySignature |
| 8734 | |
| 8735 | 20.1.1 General Description |
| 8736 | |
| 8737 | This command uses loaded keys to validate a signature on a message with the message digest passed |
| 8738 | to the TPM. |
| 8739 | If the signature check succeeds, then the TPM will produce a TPMT_TK_VERIFIED. Otherwise, the TPM |
| 8740 | shall return TPM_RC_SIGNATURE. |
| 8741 | |
| 8742 | NOTE 1 A valid ticket may be used in subsequent commands to provide proof to the TPM that the TPM has |
| 8743 | validated the signature over the message using the key referenced by keyHandle. |
| 8744 | |
| 8745 | If keyHandle references an asymmetric key, only the public portion of the key needs to be loaded. If |
| 8746 | keyHandle references a symmetric key, both the public and private portions need to be loaded. |
| 8747 | |
| 8748 | NOTE 2 The sensitive area of the symmetric object is required to allow verification of the symmetric |
| 8749 | signature (the HMAC). |
| 8750 | |
| 8751 | |
| 8752 | |
| 8753 | |
| 8754 | Family “2.0” TCG Published Page 189 |
| 8755 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 8756 | Part 3: Commands Trusted Platform Module Library |
| 8757 | |
| 8758 | |
| 8759 | 20.1.2 Command and Response |
| 8760 | |
| 8761 | Table 93 — TPM2_VerifySignature Command |
| 8762 | Type Name Description |
| 8763 | |
| 8764 | TPM_ST_SESSIONS if an audit or encrypt session is |
| 8765 | TPMI_ST_COMMAND_TAG tag |
| 8766 | present; otherwise, TPM_ST_NO_SESSIONS |
| 8767 | UINT32 commandSize |
| 8768 | TPM_CC commandCode TPM_CC_VerifySignature |
| 8769 | |
| 8770 | handle of public key that will be used in the validation |
| 8771 | TPMI_DH_OBJECT keyHandle |
| 8772 | Auth Index: None |
| 8773 | |
| 8774 | TPM2B_DIGEST digest digest of the signed message |
| 8775 | TPMT_SIGNATURE signature signature to be tested |
| 8776 | |
| 8777 | |
| 8778 | Table 94 — TPM2_VerifySignature Response |
| 8779 | Type Name Description |
| 8780 | |
| 8781 | TPM_ST tag see clause 6 |
| 8782 | UINT32 responseSize |
| 8783 | TPM_RC responseCode |
| 8784 | |
| 8785 | TPMT_TK_VERIFIED validation |
| 8786 | |
| 8787 | |
| 8788 | |
| 8789 | |
| 8790 | Page 190 TCG Published Family “2.0” |
| 8791 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 8792 | Trusted Platform Module Library Part 3: Commands |
| 8793 | |
| 8794 | |
| 8795 | |
| 8796 | 20.1.3 Detailed Actions |
| 8797 | |
| 8798 | 1 #include "InternalRoutines.h" |
| 8799 | 2 #include "VerifySignature_fp.h" |
| 8800 | 3 #ifdef TPM_CC_VerifySignature // Conditional expansion of this file |
| 8801 | |
| 8802 | |
| 8803 | Error Returns Meaning |
| 8804 | |
| 8805 | TPM_RC_ATTRIBUTES keyHandle does not reference a signing key |
| 8806 | TPM_RC_SIGNATURE signature is not genuine |
| 8807 | TPM_RC_SCHEME CryptVerifySignature() |
| 8808 | TPM_RC_HANDLE the input handle is references an HMAC key but the private portion is |
| 8809 | not loaded |
| 8810 | |
| 8811 | 4 TPM_RC |
| 8812 | 5 TPM2_VerifySignature( |
| 8813 | 6 VerifySignature_In *in, // IN: input parameter list |
| 8814 | 7 VerifySignature_Out *out // OUT: output parameter list |
| 8815 | 8 ) |
| 8816 | 9 { |
| 8817 | 10 TPM_RC result; |
| 8818 | 11 TPM2B_NAME name; |
| 8819 | 12 OBJECT *signObject; |
| 8820 | 13 TPMI_RH_HIERARCHY hierarchy; |
| 8821 | 14 |
| 8822 | 15 // Input Validation |
| 8823 | 16 |
| 8824 | 17 // Get sign object pointer |
| 8825 | 18 signObject = ObjectGet(in->keyHandle); |
| 8826 | 19 |
| 8827 | 20 // The object to validate the signature must be a signing key. |
| 8828 | 21 if(signObject->publicArea.objectAttributes.sign != SET) |
| 8829 | 22 return TPM_RC_ATTRIBUTES + RC_VerifySignature_keyHandle; |
| 8830 | 23 |
| 8831 | 24 // Validate Signature. TPM_RC_SCHEME, TPM_RC_HANDLE or TPM_RC_SIGNATURE |
| 8832 | 25 // error may be returned by CryptCVerifySignatrue() |
| 8833 | 26 result = CryptVerifySignature(in->keyHandle, &in->digest, &in->signature); |
| 8834 | 27 if(result != TPM_RC_SUCCESS) |
| 8835 | 28 return RcSafeAddToResult(result, RC_VerifySignature_signature); |
| 8836 | 29 |
| 8837 | 30 // Command Output |
| 8838 | 31 |
| 8839 | 32 hierarchy = ObjectGetHierarchy(in->keyHandle); |
| 8840 | 33 if( hierarchy == TPM_RH_NULL |
| 8841 | 34 || signObject->publicArea.nameAlg == TPM_ALG_NULL) |
| 8842 | 35 { |
| 8843 | 36 // produce empty ticket if hierarchy is TPM_RH_NULL or nameAlg is |
| 8844 | 37 // TPM_ALG_NULL |
| 8845 | 38 out->validation.tag = TPM_ST_VERIFIED; |
| 8846 | 39 out->validation.hierarchy = TPM_RH_NULL; |
| 8847 | 40 out->validation.digest.t.size = 0; |
| 8848 | 41 } |
| 8849 | 42 else |
| 8850 | 43 { |
| 8851 | 44 // Get object name that verifies the signature |
| 8852 | 45 name.t.size = ObjectGetName(in->keyHandle, &name.t.name); |
| 8853 | 46 // Compute ticket |
| 8854 | 47 TicketComputeVerified(hierarchy, &in->digest, &name, &out->validation); |
| 8855 | 48 } |
| 8856 | 49 |
| 8857 | 50 return TPM_RC_SUCCESS; |
| 8858 | |
| 8859 | Family “2.0” TCG Published Page 191 |
| 8860 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 8861 | Part 3: Commands Trusted Platform Module Library |
| 8862 | |
| 8863 | 51 } |
| 8864 | 52 #endif // CC_VerifySignature |
| 8865 | |
| 8866 | |
| 8867 | |
| 8868 | |
| 8869 | Page 192 TCG Published Family “2.0” |
| 8870 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 8871 | Trusted Platform Module Library Part 3: Commands |
| 8872 | |
| 8873 | |
| 8874 | 20.2 TPM2_Sign |
| 8875 | |
| 8876 | 20.2.1 General Description |
| 8877 | |
| 8878 | This command causes the TPM to sign an externally provided hash with the specified symmetric or |
| 8879 | asymmetric signing key. |
| 8880 | |
| 8881 | NOTE 1 Symmetric “signing” is done with the TPM HMAC commands. |
| 8882 | |
| 8883 | If keyHandle references a restricted signing key, then validation shall be provided, indicating that the TPM |
| 8884 | performed the hash of the data and validation shall indicate that hashed data did not start with |
| 8885 | TPM_GENERATED_VALUE. |
| 8886 | |
| 8887 | NOTE 2 If the hashed data did start with TPM_GENERATED_VALUE, then the validation will be a NULL |
| 8888 | ticket. |
| 8889 | |
| 8890 | If the scheme of keyHandle is not TPM_ALG_NULL, then inScheme shall either be the same scheme as |
| 8891 | keyHandle or TPM_ALG_NULL. |
| 8892 | If the scheme of keyHandle is TPM_ALG_NULL, the TPM will sign using inScheme; otherwise, it will sign |
| 8893 | using the scheme of keyHandle. |
| 8894 | |
| 8895 | NOTE 3 When the signing scheme uses a hash algorithm, the algorithm is defined in the qualifying data of |
| 8896 | the scheme. This is the same algorithm that is required to be used in producing digest. The size of |
| 8897 | digest must match that of the hash algorithm in the scheme. |
| 8898 | |
| 8899 | If inScheme is not a valid signing scheme for the type of keyHandle (or TPM_ALG_NULL), then the TPM |
| 8900 | shall return TPM_RC_SCHEME. |
| 8901 | If the scheme of keyHandle is an anonymous scheme, then inScheme shall have the same scheme |
| 8902 | algorithm as keyHandle and inScheme will contain a counter value that will be used in the signing |
| 8903 | process. |
| 8904 | If validation is provided, then the hash algorithm used in computing the digest is required to be the hash |
| 8905 | algorithm specified in the scheme of keyHandle (TPM_RC_TICKET). |
| 8906 | If the validation parameter is not the Empty Buffer, then it will be checked even if the key referenced by |
| 8907 | keyHandle is not a restricted signing key. |
| 8908 | |
| 8909 | NOTE 4 If keyHandle is both a sign and decrypt key, keyHandle will have an scheme of TPM_ALG_NULL. If |
| 8910 | validation is provided, then it must be a NULL validation ticket or the ticket validation will fail. |
| 8911 | |
| 8912 | |
| 8913 | |
| 8914 | |
| 8915 | Family “2.0” TCG Published Page 193 |
| 8916 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 8917 | Part 3: Commands Trusted Platform Module Library |
| 8918 | |
| 8919 | |
| 8920 | 20.2.2 Command and Response |
| 8921 | |
| 8922 | Table 95 — TPM2_Sign Command |
| 8923 | Type Name Description |
| 8924 | |
| 8925 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 8926 | UINT32 commandSize |
| 8927 | TPM_CC commandCode TPM_CC_Sign |
| 8928 | |
| 8929 | Handle of key that will perform signing |
| 8930 | TPMI_DH_OBJECT @keyHandle Auth Index: 1 |
| 8931 | Auth Role: USER |
| 8932 | |
| 8933 | TPM2B_DIGEST digest digest to be signed |
| 8934 | signing scheme to use if the scheme for keyHandle is |
| 8935 | TPMT_SIG_SCHEME+ inScheme |
| 8936 | TPM_ALG_NULL |
| 8937 | proof that digest was created by the TPM |
| 8938 | TPMT_TK_HASHCHECK validation If keyHandle is not a restricted signing key, then this |
| 8939 | may be a NULL Ticket with tag = |
| 8940 | TPM_ST_CHECKHASH. |
| 8941 | |
| 8942 | |
| 8943 | Table 96 — TPM2_Sign Response |
| 8944 | Type Name Description |
| 8945 | |
| 8946 | TPM_ST tag see clause 6 |
| 8947 | UINT32 responseSize |
| 8948 | TPM_RC responseCode |
| 8949 | |
| 8950 | TPMT_SIGNATURE signature the signature |
| 8951 | |
| 8952 | |
| 8953 | |
| 8954 | |
| 8955 | Page 194 TCG Published Family “2.0” |
| 8956 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 8957 | Trusted Platform Module Library Part 3: Commands |
| 8958 | |
| 8959 | |
| 8960 | |
| 8961 | 20.2.3 Detailed Actions |
| 8962 | |
| 8963 | 1 #include "InternalRoutines.h" |
| 8964 | 2 #include "Sign_fp.h" |
| 8965 | 3 #ifdef TPM_CC_Sign // Conditional expansion of this file |
| 8966 | 4 #include "Attest_spt_fp.h" |
| 8967 | |
| 8968 | |
| 8969 | Error Returns Meaning |
| 8970 | |
| 8971 | TPM_RC_BINDING The public and private portions of the key are not properly bound. |
| 8972 | TPM_RC_KEY signHandle does not reference a signing key; |
| 8973 | TPM_RC_SCHEME the scheme is not compatible with sign key type, or input scheme is |
| 8974 | not compatible with default scheme, or the chosen scheme is not a |
| 8975 | valid sign scheme |
| 8976 | TPM_RC_TICKET validation is not a valid ticket |
| 8977 | TPM_RC_VALUE the value to sign is larger than allowed for the type of keyHandle |
| 8978 | |
| 8979 | 5 TPM_RC |
| 8980 | 6 TPM2_Sign( |
| 8981 | 7 Sign_In *in, // IN: input parameter list |
| 8982 | 8 Sign_Out *out // OUT: output parameter list |
| 8983 | 9 ) |
| 8984 | 10 { |
| 8985 | 11 TPM_RC result; |
| 8986 | 12 TPMT_TK_HASHCHECK ticket; |
| 8987 | 13 OBJECT *signKey; |
| 8988 | 14 |
| 8989 | 15 // Input Validation |
| 8990 | 16 // Get sign key pointer |
| 8991 | 17 signKey = ObjectGet(in->keyHandle); |
| 8992 | 18 |
| 8993 | 19 // pick a scheme for sign. If the input sign scheme is not compatible with |
| 8994 | 20 // the default scheme, return an error. |
| 8995 | 21 result = CryptSelectSignScheme(in->keyHandle, &in->inScheme); |
| 8996 | 22 if(result != TPM_RC_SUCCESS) |
| 8997 | 23 { |
| 8998 | 24 if(result == TPM_RC_KEY) |
| 8999 | 25 return TPM_RC_KEY + RC_Sign_keyHandle; |
| 9000 | 26 else |
| 9001 | 27 return RcSafeAddToResult(result, RC_Sign_inScheme); |
| 9002 | 28 } |
| 9003 | 29 |
| 9004 | 30 // If validation is provided, or the key is restricted, check the ticket |
| 9005 | 31 if( in->validation.digest.t.size != 0 |
| 9006 | 32 || signKey->publicArea.objectAttributes.restricted == SET) |
| 9007 | 33 { |
| 9008 | 34 // Compute and compare ticket |
| 9009 | 35 TicketComputeHashCheck(in->validation.hierarchy, |
| 9010 | 36 in->inScheme.details.any.hashAlg, |
| 9011 | 37 &in->digest, &ticket); |
| 9012 | 38 |
| 9013 | 39 if(!Memory2BEqual(&in->validation.digest.b, &ticket.digest.b)) |
| 9014 | 40 return TPM_RC_TICKET + RC_Sign_validation; |
| 9015 | 41 } |
| 9016 | 42 else |
| 9017 | 43 // If we don't have a ticket, at least verify that the provided 'digest' |
| 9018 | 44 // is the size of the scheme hashAlg digest. |
| 9019 | 45 // NOTE: this does not guarantee that the 'digest' is actually produced using |
| 9020 | 46 // the indicated hash algorithm, but at least it might be. |
| 9021 | 47 { |
| 9022 | |
| 9023 | Family “2.0” TCG Published Page 195 |
| 9024 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 9025 | Part 3: Commands Trusted Platform Module Library |
| 9026 | |
| 9027 | 48 if( in->digest.t.size |
| 9028 | 49 != CryptGetHashDigestSize(in->inScheme.details.any.hashAlg)) |
| 9029 | 50 return TPM_RCS_SIZE + RC_Sign_digest; |
| 9030 | 51 } |
| 9031 | 52 |
| 9032 | 53 // Command Output |
| 9033 | 54 // Sign the hash. A TPM_RC_VALUE or TPM_RC_SCHEME |
| 9034 | 55 // error may be returned at this point |
| 9035 | 56 result = CryptSign(in->keyHandle, &in->inScheme, &in->digest, &out->signature); |
| 9036 | 57 |
| 9037 | 58 return result; |
| 9038 | 59 } |
| 9039 | 60 #endif // CC_Sign |
| 9040 | |
| 9041 | |
| 9042 | |
| 9043 | |
| 9044 | Page 196 TCG Published Family “2.0” |
| 9045 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 9046 | Trusted Platform Module Library Part 3: Commands |
| 9047 | |
| 9048 | |
| 9049 | 21 Command Audit |
| 9050 | |
| 9051 | 21.1 Introduction |
| 9052 | |
| 9053 | If a command has been selected for command audit, the command audit status will be updated when that |
| 9054 | command completes successfully. The digest is updated as: |
| 9055 | commandAuditDigestnew ≔ HauditAlg(commandAuditDigestold || cpHash || rpHash) (5) |
| 9056 | where |
| 9057 | HauditAlg hash function using the algorithm of the audit sequence |
| 9058 | commandAuditDigest accumulated digest |
| 9059 | cpHash the command parameter hash |
| 9060 | rpHash the response parameter hash |
| 9061 | |
| 9062 | auditAlg, the hash algorithm, is set using TPM2_SetCommandCodeAuditStatus. |
| 9063 | |
| 9064 | |
| 9065 | TPM2_Shutdown() cannot be audited but TPM2_Startup() can be audited. If the cpHash of the |
| 9066 | TPM2_Startup() is TPM_SU_STATE, that would indicate that a TPM2_Shutdown() had been successfully |
| 9067 | executed. |
| 9068 | TPM2_SetCommandCodeAuditStatus() is always audited. |
| 9069 | If the TPM is in Failure mode, command audit is not functional. |
| 9070 | |
| 9071 | |
| 9072 | |
| 9073 | |
| 9074 | Family “2.0” TCG Published Page 197 |
| 9075 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 9076 | Part 3: Commands Trusted Platform Module Library |
| 9077 | |
| 9078 | |
| 9079 | |
| 9080 | 21.2 TPM2_SetCommandCodeAuditStatus |
| 9081 | |
| 9082 | 21.2.1 General Description |
| 9083 | |
| 9084 | This command may be used by the Privacy Administrator or platform to change the audit status of a |
| 9085 | command or to set the hash algorithm used for the audit digest, but not both at the same time. |
| 9086 | If the auditAlg parameter is a supported hash algorithm and not the same as the current algorithm, then |
| 9087 | the TPM will check both setList and clearList are empty (zero length). If so, then the algorithm is changed, |
| 9088 | and the audit digest is cleared. If auditAlg is TPM_ALG_NULL or the same as the current algorithm, then |
| 9089 | the algorithm and audit digest are unchanged and the setList and clearList will be processed. |
| 9090 | |
| 9091 | NOTE 1 Because the audit digest is cleared, the audit counter will increment the next time that an audited |
| 9092 | command is executed. |
| 9093 | |
| 9094 | Use of TPM2_SetCommandCodeAuditStatus() to change the list of audited commands is an audited |
| 9095 | event. If TPM_CC_SetCommandCodeAuditStatus is in clearList, the fact that it is in clearList is ignored. |
| 9096 | |
| 9097 | NOTE 2 Use of this command to change the audit hash algorithm is not audited and the digest is reset when |
| 9098 | the command completes. The change in the audit hash algorith m is the evidence that this command |
| 9099 | was used to change the algorithm. |
| 9100 | |
| 9101 | The commands in setList indicate the commands to be added to the list of audited commands and the |
| 9102 | commands in clearList indicate the commands that will no longer be audited. It is not an error if a |
| 9103 | command in setList is already audited or is not implemented. It is not an error if a command in clearList is |
| 9104 | not currently being audited or is not implemented. |
| 9105 | If a command code is in both setList and clearList, then it will not be audited (that is, setList shall be |
| 9106 | processed first). |
| 9107 | |
| 9108 | |
| 9109 | |
| 9110 | |
| 9111 | Page 198 TCG Published Family “2.0” |
| 9112 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 9113 | Trusted Platform Module Library Part 3: Commands |
| 9114 | |
| 9115 | |
| 9116 | |
| 9117 | 21.2.2 Command and Response |
| 9118 | |
| 9119 | Table 97 — TPM2_SetCommandCodeAuditStatus Command |
| 9120 | Type Name Description |
| 9121 | |
| 9122 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 9123 | UINT32 commandSize |
| 9124 | TPM_CC commandCode TPM_CC_SetCommandCodeAuditStatus {NV} |
| 9125 | |
| 9126 | TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} |
| 9127 | TPMI_RH_PROVISION @auth Auth Index: 1 |
| 9128 | Auth Role: USER |
| 9129 | |
| 9130 | hash algorithm for the audit digest; if |
| 9131 | TPMI_ALG_HASH+ auditAlg |
| 9132 | TPM_ALG_NULL, then the hash is not changed |
| 9133 | list of commands that will be added to those that will |
| 9134 | TPML_CC setList |
| 9135 | be audited |
| 9136 | TPML_CC clearList list of commands that will no longer be audited |
| 9137 | |
| 9138 | |
| 9139 | Table 98 — TPM2_SetCommandCodeAuditStatus Response |
| 9140 | Type Name Description |
| 9141 | |
| 9142 | TPM_ST tag see clause 6 |
| 9143 | UINT32 responseSize |
| 9144 | TPM_RC responseCode |
| 9145 | |
| 9146 | |
| 9147 | |
| 9148 | |
| 9149 | Family “2.0” TCG Published Page 199 |
| 9150 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 9151 | Part 3: Commands Trusted Platform Module Library |
| 9152 | |
| 9153 | |
| 9154 | |
| 9155 | 21.2.3 Detailed Actions |
| 9156 | |
| 9157 | 1 #include "InternalRoutines.h" |
| 9158 | 2 #include "SetCommandCodeAuditStatus_fp.h" |
| 9159 | 3 #ifdef TPM_CC_SetCommandCodeAuditStatus // Conditional expansion of this file |
| 9160 | 4 TPM_RC |
| 9161 | 5 TPM2_SetCommandCodeAuditStatus( |
| 9162 | 6 SetCommandCodeAuditStatus_In *in // IN: input parameter list |
| 9163 | 7 ) |
| 9164 | 8 { |
| 9165 | 9 TPM_RC result; |
| 9166 | 10 UINT32 i; |
| 9167 | 11 BOOL changed = FALSE; |
| 9168 | 12 |
| 9169 | 13 // The command needs NV update. Check if NV is available. |
| 9170 | 14 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at |
| 9171 | 15 // this point |
| 9172 | 16 result = NvIsAvailable(); |
| 9173 | 17 if(result != TPM_RC_SUCCESS) |
| 9174 | 18 return result; |
| 9175 | 19 |
| 9176 | 20 // Internal Data Update |
| 9177 | 21 |
| 9178 | 22 // Update hash algorithm |
| 9179 | 23 if( in->auditAlg != TPM_ALG_NULL |
| 9180 | 24 && in->auditAlg != gp.auditHashAlg) |
| 9181 | 25 { |
| 9182 | 26 // Can't change the algorithm and command list at the same time |
| 9183 | 27 if(in->setList.count != 0 || in->clearList.count != 0) |
| 9184 | 28 return TPM_RC_VALUE + RC_SetCommandCodeAuditStatus_auditAlg; |
| 9185 | 29 |
| 9186 | 30 // Change the hash algorithm for audit |
| 9187 | 31 gp.auditHashAlg = in->auditAlg; |
| 9188 | 32 |
| 9189 | 33 // Set the digest size to a unique value that indicates that the digest |
| 9190 | 34 // algorithm has been changed. The size will be cleared to zero in the |
| 9191 | 35 // command audit processing on exit. |
| 9192 | 36 gr.commandAuditDigest.t.size = 1; |
| 9193 | 37 |
| 9194 | 38 // Save the change of command audit data (this sets g_updateNV so that NV |
| 9195 | 39 // will be updated on exit.) |
| 9196 | 40 NvWriteReserved(NV_AUDIT_HASH_ALG, &gp.auditHashAlg); |
| 9197 | 41 |
| 9198 | 42 } else { |
| 9199 | 43 |
| 9200 | 44 // Process set list |
| 9201 | 45 for(i = 0; i < in->setList.count; i++) |
| 9202 | 46 |
| 9203 | 47 // If change is made in CommandAuditSet, set changed flag |
| 9204 | 48 if(CommandAuditSet(in->setList.commandCodes[i])) |
| 9205 | 49 changed = TRUE; |
| 9206 | 50 |
| 9207 | 51 // Process clear list |
| 9208 | 52 for(i = 0; i < in->clearList.count; i++) |
| 9209 | 53 // If change is made in CommandAuditClear, set changed flag |
| 9210 | 54 if(CommandAuditClear(in->clearList.commandCodes[i])) |
| 9211 | 55 changed = TRUE; |
| 9212 | 56 |
| 9213 | 57 // if change was made to command list, update NV |
| 9214 | 58 if(changed) |
| 9215 | 59 // this sets g_updateNV so that NV will be updated on exit. |
| 9216 | 60 NvWriteReserved(NV_AUDIT_COMMANDS, &gp.auditComands); |
| 9217 | 61 } |
| 9218 | 62 |
| 9219 | |
| 9220 | Page 200 TCG Published Family “2.0” |
| 9221 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 9222 | Trusted Platform Module Library Part 3: Commands |
| 9223 | |
| 9224 | 63 return TPM_RC_SUCCESS; |
| 9225 | 64 } |
| 9226 | 65 #endif // CC_SetCommandCodeAuditStatus |
| 9227 | |
| 9228 | |
| 9229 | |
| 9230 | |
| 9231 | Family “2.0” TCG Published Page 201 |
| 9232 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 9233 | Part 3: Commands Trusted Platform Module Library |
| 9234 | |
| 9235 | |
| 9236 | 22 Integrity Collection (PCR) |
| 9237 | |
| 9238 | 22.1 Introduction |
| 9239 | |
| 9240 | In TPM 1.2, an Event was hashed using SHA-1 and then the 20-octet digest was extended to a PCR |
| 9241 | using TPM_Extend(). This specification allows the use of multiple PCR at a given Index, each using a |
| 9242 | different hash algorithm. Rather than require that the external software generate multiple hashes of the |
| 9243 | Event with each being extended to a different PCR, the Event data may be sent to the TPM for hashing. |
| 9244 | This ensures that the resulting digests will properly reflect the algorithms chosen for the PCR even if the |
| 9245 | calling software is unable to implement the hash algorithm. |
| 9246 | |
| 9247 | NOTE 1 There is continued support for software hashing of events with TPM2_PCR_Extend(). |
| 9248 | |
| 9249 | To support recording of an Event that is larger than the TPM input buffer, the caller may use the |
| 9250 | command sequence described in clause 1. |
| 9251 | Change to a PCR requires authorization. The authorization may be with either an authorization value or |
| 9252 | an authorization policy. The platform-specific specifications determine which PCR may be controlled by |
| 9253 | policy. All other PCR are controlled by authorization. |
| 9254 | If a PCR may be associated with a policy, then the algorithm ID of that policy determines whether the |
| 9255 | policy is to be applied. If the algorithm ID is not TPM_ALG_NULL, then the policy digest associated with |
| 9256 | the PCR must match the policySession→policyDigest in a policy session. If the algorithm ID is |
| 9257 | TPM_ALG_NULL, then no policy is present and the authorization requires an EmptyAuth. |
| 9258 | If a platform-specific specification indicates that PCR are grouped, then all the PCR in the group use the |
| 9259 | same authorization policy or authorization value. |
| 9260 | PcrUpdateCounter counter will be incremented on the successful completion of any command that |
| 9261 | modifies (Extends or resets) a PCR unless the platform-specific specification explicitly excludes the PCR |
| 9262 | from being counted. |
| 9263 | |
| 9264 | NOTE 2 If a command causes PCR in multiple banks to change, the PCR Update Counter may be |
| 9265 | incremented either once or once for each bank. |
| 9266 | |
| 9267 | A platform-specific specification may designate a set of PCR that are under control of the TCB. These |
| 9268 | PCR may not be modified without the proper authorization. Updates of these PCR shall not cause the |
| 9269 | PCR Update Counter to increment. |
| 9270 | |
| 9271 | EXAMPLE Updates of the TCB PCR will not cause the PCR update counter to increment because these PCR |
| 9272 | are changed at the whim of the TCB and may not represent the trust state of the platform. |
| 9273 | |
| 9274 | |
| 9275 | |
| 9276 | |
| 9277 | Page 202 TCG Published Family “2.0” |
| 9278 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 9279 | Trusted Platform Module Library Part 3: Commands |
| 9280 | |
| 9281 | |
| 9282 | 22.2 TPM2_PCR_Extend |
| 9283 | |
| 9284 | 22.2.1 General Description |
| 9285 | |
| 9286 | This command is used to cause an update to the indicated PCR. The digests parameter contains one or |
| 9287 | more tagged digest values identified by an algorithm ID. For each digest, the PCR associated with |
| 9288 | pcrHandle is Extended into the bank identified by the tag (hashAlg). |
| 9289 | |
| 9290 | EXAMPLE A SHA1 digest would be Extended i nto the SHA1 bank and a SHA256 digest would be Extended into |
| 9291 | the SHA256 bank. |
| 9292 | |
| 9293 | For each list entry, the TPM will check to see if pcrNum is implemented for that algorithm. If so, the TPM |
| 9294 | shall perform the following operation: |
| 9295 | PCR.digestnew [pcrNum][alg] ≔ Halg(PCR.digestold [pcrNum][alg] || data[alg].buffer)) (6) |
| 9296 | where |
| 9297 | Halg() hash function using the hash algorithm associated with the PCR |
| 9298 | instance |
| 9299 | PCR.digest the digest value in a PCR |
| 9300 | pcrNum the PCR numeric selector (pcrHandle) |
| 9301 | alg the PCR algorithm selector for the digest |
| 9302 | data[alg].buffer the bank-specific data to be extended |
| 9303 | |
| 9304 | |
| 9305 | If no digest value is specified for a bank, then the PCR in that bank is not modified. |
| 9306 | |
| 9307 | NOTE 1 This allows consistent operation of the digests list for all of the Event recording commands. |
| 9308 | |
| 9309 | If a digest is present and the PCR in that bank is not implemented, the digest value is not used. |
| 9310 | |
| 9311 | NOTE 2 If the caller includes digests for algorithms that are not implemented, then the TPM will fail the call |
| 9312 | because the unmarshalling of digests will fail. Each of the entries in the list is a TPMT_HA, which is |
| 9313 | a hash algorithm followed by a digest. If the algorithm is not implemented, unmarshalling of the |
| 9314 | hashAlg will fail and the TPM will return TPM_RC_HASH. |
| 9315 | |
| 9316 | If the TPM unmarshals the hashAlg of a list entry and the unmarshaled value is not a hash algorithm |
| 9317 | implemented on the TPM, the TPM shall return TPM_RC_HASH. |
| 9318 | The pcrHandle parameter is allowed to reference TPM_RH_NULL. If so, the input parameters are |
| 9319 | processed but no action is taken by the TPM. This permits the caller to probe for implemented hash |
| 9320 | algorithms as an alternative to TPM2_GetCapability. |
| 9321 | |
| 9322 | NOTE 3 This command allows a list of digests so that PCR in all banks may be updated in a single |
| 9323 | command. While the semantics of this command allow multiple extends to a single PCR bank, this is |
| 9324 | not the preferred use and the limit on the number of entries in the list make this use somewhat |
| 9325 | impractical. |
| 9326 | |
| 9327 | |
| 9328 | |
| 9329 | |
| 9330 | Family “2.0” TCG Published Page 203 |
| 9331 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 9332 | Part 3: Commands Trusted Platform Module Library |
| 9333 | |
| 9334 | |
| 9335 | 22.2.2 Command and Response |
| 9336 | |
| 9337 | Table 99 — TPM2_PCR_Extend Command |
| 9338 | Type Name Description |
| 9339 | |
| 9340 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 9341 | UINT32 commandSize |
| 9342 | TPM_CC commandCode TPM_CC_PCR_Extend {NV} |
| 9343 | |
| 9344 | handle of the PCR |
| 9345 | TPMI_DH_PCR+ @pcrHandle Auth Handle: 1 |
| 9346 | Auth Role: USER |
| 9347 | |
| 9348 | TPML_DIGEST_VALUES digests list of tagged digest values to be extended |
| 9349 | |
| 9350 | |
| 9351 | Table 100 — TPM2_PCR_Extend Response |
| 9352 | Type Name Description |
| 9353 | |
| 9354 | TPM_ST tag see clause 6 |
| 9355 | UINT32 responseSize |
| 9356 | TPM_RC responseCode . |
| 9357 | |
| 9358 | |
| 9359 | |
| 9360 | |
| 9361 | Page 204 TCG Published Family “2.0” |
| 9362 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 9363 | Trusted Platform Module Library Part 3: Commands |
| 9364 | |
| 9365 | |
| 9366 | |
| 9367 | 22.2.3 Detailed Actions |
| 9368 | |
| 9369 | 1 #include "InternalRoutines.h" |
| 9370 | 2 #include "PCR_Extend_fp.h" |
| 9371 | 3 #ifdef TPM_CC_PCR_Extend // Conditional expansion of this file |
| 9372 | |
| 9373 | |
| 9374 | Error Returns Meaning |
| 9375 | |
| 9376 | TPM_RC_LOCALITY current command locality is not allowed to extend the PCR |
| 9377 | referenced by pcrHandle |
| 9378 | |
| 9379 | 4 TPM_RC |
| 9380 | 5 TPM2_PCR_Extend( |
| 9381 | 6 PCR_Extend_In *in // IN: input parameter list |
| 9382 | 7 ) |
| 9383 | 8 { |
| 9384 | 9 TPM_RC result; |
| 9385 | 10 UINT32 i; |
| 9386 | 11 |
| 9387 | 12 // Input Validation |
| 9388 | 13 |
| 9389 | 14 // NOTE: This function assumes that the unmarshaling function for 'digests' will |
| 9390 | 15 // have validated that all of the indicated hash algorithms are valid. If the |
| 9391 | 16 // hash algorithms are correct, the unmarshaling code will unmarshal a digest |
| 9392 | 17 // of the size indicated by the hash algorithm. If the overall size is not |
| 9393 | 18 // consistent, the unmarshaling code will run out of input data or have input |
| 9394 | 19 // data left over. In either case, it will cause an unmarshaling error and this |
| 9395 | 20 // function will not be called. |
| 9396 | 21 |
| 9397 | 22 // For NULL handle, do nothing and return success |
| 9398 | 23 if(in->pcrHandle == TPM_RH_NULL) |
| 9399 | 24 return TPM_RC_SUCCESS; |
| 9400 | 25 |
| 9401 | 26 // Check if the extend operation is allowed by the current command locality |
| 9402 | 27 if(!PCRIsExtendAllowed(in->pcrHandle)) |
| 9403 | 28 return TPM_RC_LOCALITY; |
| 9404 | 29 |
| 9405 | 30 // If PCR is state saved and we need to update orderlyState, check NV |
| 9406 | 31 // availability |
| 9407 | 32 if(PCRIsStateSaved(in->pcrHandle) && gp.orderlyState != SHUTDOWN_NONE) |
| 9408 | 33 { |
| 9409 | 34 result = NvIsAvailable(); |
| 9410 | 35 if(result != TPM_RC_SUCCESS) return result; |
| 9411 | 36 g_clearOrderly = TRUE; |
| 9412 | 37 } |
| 9413 | 38 |
| 9414 | 39 // Internal Data Update |
| 9415 | 40 |
| 9416 | 41 // Iterate input digest list to extend |
| 9417 | 42 for(i = 0; i < in->digests.count; i++) |
| 9418 | 43 { |
| 9419 | 44 PCRExtend(in->pcrHandle, in->digests.digests[i].hashAlg, |
| 9420 | 45 CryptGetHashDigestSize(in->digests.digests[i].hashAlg), |
| 9421 | 46 (BYTE *) &in->digests.digests[i].digest); |
| 9422 | 47 } |
| 9423 | 48 |
| 9424 | 49 return TPM_RC_SUCCESS; |
| 9425 | 50 } |
| 9426 | 51 #endif // CC_PCR_Extend |
| 9427 | |
| 9428 | |
| 9429 | |
| 9430 | |
| 9431 | Family “2.0” TCG Published Page 205 |
| 9432 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 9433 | Part 3: Commands Trusted Platform Module Library |
| 9434 | |
| 9435 | |
| 9436 | 22.3 TPM2_PCR_Event |
| 9437 | |
| 9438 | 22.3.1 General Description |
| 9439 | |
| 9440 | This command is used to cause an update to the indicated PCR. |
| 9441 | The data in eventData is hashed using the hash algorithm associated with each bank in which the |
| 9442 | indicated PCR has been allocated. After the data is hashed, the digests list is returned. If the pcrHandle |
| 9443 | references an implemented PCR and not TPM_ALG_NULL, the digests list is processed as in |
| 9444 | TPM2_PCR_Extend(). |
| 9445 | A TPM shall support an Event.size of zero through 1,024 inclusive (Event.size is an octet count). An |
| 9446 | Event.size of zero indicates that there is no data but the indicated operations will still occur, |
| 9447 | |
| 9448 | EXAMPLE 1 If the command implements PCR[2] in a SHA1 bank and a SHA256 bank, then an extend to PCR[2] |
| 9449 | will cause eventData to be hashed twice, once with SHA1 and once with SHA256. The SHA1 hash of |
| 9450 | eventData will be Extended to PCR[2] in the SHA1 bank and the SHA256 hash of eventData will be |
| 9451 | Extended to PCR[2] of the SHA256 bank. |
| 9452 | |
| 9453 | On successful command completion, digests will contain the list of tagged digests of eventData that was |
| 9454 | computed in preparation for extending the data into the PCR. At the option of the TPM, the list may |
| 9455 | contain a digest for each bank, or it may only contain a digest for each bank in which pcrHandle is extant. |
| 9456 | If pcrHandle is TPM_RH_NULL, the TPM may return either an empty list or a digest for each bank. |
| 9457 | |
| 9458 | EXAMPLE 2 Assume a TPM that implements a SHA1 bank and a SHA256 bank and that PCR[22] is only |
| 9459 | implemented in the SHA1 bank. If pcrHandle references PCR[22], then digests may contain either a |
| 9460 | SHA1 and a SHA256 digest or just a SHA1 digest. |
| 9461 | |
| 9462 | |
| 9463 | |
| 9464 | |
| 9465 | Page 206 TCG Published Family “2.0” |
| 9466 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 9467 | Trusted Platform Module Library Part 3: Commands |
| 9468 | |
| 9469 | |
| 9470 | 22.3.2 Command and Response |
| 9471 | |
| 9472 | Table 101 — TPM2_PCR_Event Command |
| 9473 | Type Name Description |
| 9474 | |
| 9475 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 9476 | UINT32 commandSize |
| 9477 | TPM_CC commandCode TPM_CC_PCR_Event {NV} |
| 9478 | |
| 9479 | Handle of the PCR |
| 9480 | TPMI_DH_PCR+ @pcrHandle Auth Handle: 1 |
| 9481 | Auth Role: USER |
| 9482 | |
| 9483 | TPM2B_EVENT eventData Event data in sized buffer |
| 9484 | |
| 9485 | |
| 9486 | Table 102 — TPM2_PCR_Event Response |
| 9487 | Type Name Description |
| 9488 | |
| 9489 | TPM_ST tag see clause 6 |
| 9490 | UINT32 responseSize |
| 9491 | TPM_RC responseCode . |
| 9492 | |
| 9493 | TPML_DIGEST_VALUES digests |
| 9494 | |
| 9495 | |
| 9496 | |
| 9497 | |
| 9498 | Family “2.0” TCG Published Page 207 |
| 9499 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 9500 | Part 3: Commands Trusted Platform Module Library |
| 9501 | |
| 9502 | |
| 9503 | |
| 9504 | 22.3.3 Detailed Actions |
| 9505 | |
| 9506 | 1 #include "InternalRoutines.h" |
| 9507 | 2 #include "PCR_Event_fp.h" |
| 9508 | 3 #ifdef TPM_CC_PCR_Event // Conditional expansion of this file |
| 9509 | |
| 9510 | |
| 9511 | Error Returns Meaning |
| 9512 | |
| 9513 | TPM_RC_LOCALITY current command locality is not allowed to extend the PCR |
| 9514 | referenced by pcrHandle |
| 9515 | |
| 9516 | 4 TPM_RC |
| 9517 | 5 TPM2_PCR_Event( |
| 9518 | 6 PCR_Event_In *in, // IN: input parameter list |
| 9519 | 7 PCR_Event_Out *out // OUT: output parameter list |
| 9520 | 8 ) |
| 9521 | 9 { |
| 9522 | 10 TPM_RC result; |
| 9523 | 11 HASH_STATE hashState; |
| 9524 | 12 UINT32 i; |
| 9525 | 13 UINT16 size; |
| 9526 | 14 |
| 9527 | 15 // Input Validation |
| 9528 | 16 |
| 9529 | 17 // If a PCR extend is required |
| 9530 | 18 if(in->pcrHandle != TPM_RH_NULL) |
| 9531 | 19 { |
| 9532 | 20 // If the PCR is not allow to extend, return error |
| 9533 | 21 if(!PCRIsExtendAllowed(in->pcrHandle)) |
| 9534 | 22 return TPM_RC_LOCALITY; |
| 9535 | 23 |
| 9536 | 24 // If PCR is state saved and we need to update orderlyState, check NV |
| 9537 | 25 // availability |
| 9538 | 26 if(PCRIsStateSaved(in->pcrHandle) && gp.orderlyState != SHUTDOWN_NONE) |
| 9539 | 27 { |
| 9540 | 28 result = NvIsAvailable(); |
| 9541 | 29 if(result != TPM_RC_SUCCESS) return result; |
| 9542 | 30 g_clearOrderly = TRUE; |
| 9543 | 31 } |
| 9544 | 32 } |
| 9545 | 33 |
| 9546 | 34 // Internal Data Update |
| 9547 | 35 |
| 9548 | 36 out->digests.count = HASH_COUNT; |
| 9549 | 37 |
| 9550 | 38 // Iterate supported PCR bank algorithms to extend |
| 9551 | 39 for(i = 0; i < HASH_COUNT; i++) |
| 9552 | 40 { |
| 9553 | 41 TPM_ALG_ID hash = CryptGetHashAlgByIndex(i); |
| 9554 | 42 out->digests.digests[i].hashAlg = hash; |
| 9555 | 43 size = CryptStartHash(hash, &hashState); |
| 9556 | 44 CryptUpdateDigest2B(&hashState, &in->eventData.b); |
| 9557 | 45 CryptCompleteHash(&hashState, size, |
| 9558 | 46 (BYTE *) &out->digests.digests[i].digest); |
| 9559 | 47 if(in->pcrHandle != TPM_RH_NULL) |
| 9560 | 48 PCRExtend(in->pcrHandle, hash, size, |
| 9561 | 49 (BYTE *) &out->digests.digests[i].digest); |
| 9562 | 50 } |
| 9563 | 51 |
| 9564 | 52 return TPM_RC_SUCCESS; |
| 9565 | 53 } |
| 9566 | 54 #endif // CC_PCR_Event |
| 9567 | |
| 9568 | |
| 9569 | Page 208 TCG Published Family “2.0” |
| 9570 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 9571 | Trusted Platform Module Library Part 3: Commands |
| 9572 | |
| 9573 | |
| 9574 | 22.4 TPM2_PCR_Read |
| 9575 | |
| 9576 | 22.4.1 General Description |
| 9577 | |
| 9578 | This command returns the values of all PCR specified in pcrSelectionIn. |
| 9579 | The TPM will process the list of TPMS_PCR_SELECTION in pcrSelectionIn in order. Within each |
| 9580 | TPMS_PCR_SELECTION, the TPM will process the bits in the pcrSelect array in ascending PCR order |
| 9581 | (see TPM 2.0 Part 2 for definition of the PCR order). If a bit is SET, and the indicated PCR is present, |
| 9582 | then the TPM will add the digest of the PCR to the list of values to be returned in pcrValues. |
| 9583 | The TPM will continue processing bits until all have been processed or until pcrValues would be too large |
| 9584 | to fit into the output buffer if additional values were added. |
| 9585 | The returned pcrSelectionOut will have a bit SET in its pcrSelect structures for each value present in |
| 9586 | pcrValues. |
| 9587 | The current value of the PCR Update Counter is returned in pcrUpdateCounter. |
| 9588 | The returned list may be empty if none of the selected PCR are implemented. |
| 9589 | |
| 9590 | NOTE If no PCR are returned from a bank, the selector for the bank will be present in pcrSelectionOut. |
| 9591 | |
| 9592 | No authorization is required to read a PCR and any implemented PCR may be read from any locality. |
| 9593 | |
| 9594 | |
| 9595 | |
| 9596 | |
| 9597 | Family “2.0” TCG Published Page 209 |
| 9598 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 9599 | Part 3: Commands Trusted Platform Module Library |
| 9600 | |
| 9601 | |
| 9602 | |
| 9603 | 22.4.2 Command and Response |
| 9604 | |
| 9605 | Table 103 — TPM2_PCR_Read Command |
| 9606 | Type Name Description |
| 9607 | |
| 9608 | TPM_ST_SESSIONS if an audit session is present; |
| 9609 | TPMI_ST_COMMAND_TAG tag |
| 9610 | otherwise, TPM_ST_NO_SESSIONS |
| 9611 | UINT32 commandSize |
| 9612 | TPM_CC commandCode TPM_CC_PCR_Read |
| 9613 | |
| 9614 | TPML_PCR_SELECTION pcrSelectionIn The selection of PCR to read |
| 9615 | |
| 9616 | |
| 9617 | Table 104 — TPM2_PCR_Read Response |
| 9618 | Type Name Description |
| 9619 | |
| 9620 | TPM_ST tag see clause 6 |
| 9621 | UINT32 responseSize |
| 9622 | TPM_RC responseCode |
| 9623 | |
| 9624 | UINT32 pcrUpdateCounter the current value of the PCR update counter |
| 9625 | TPML_PCR_SELECTION pcrSelectionOut the PCR in the returned list |
| 9626 | the contents of the PCR indicated in pcrSelect as |
| 9627 | TPML_DIGEST pcrValues |
| 9628 | tagged digests |
| 9629 | |
| 9630 | |
| 9631 | |
| 9632 | |
| 9633 | Page 210 TCG Published Family “2.0” |
| 9634 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 9635 | Trusted Platform Module Library Part 3: Commands |
| 9636 | |
| 9637 | |
| 9638 | |
| 9639 | 22.4.3 Detailed Actions |
| 9640 | |
| 9641 | 1 #include "InternalRoutines.h" |
| 9642 | 2 #include "PCR_Read_fp.h" |
| 9643 | 3 #ifdef TPM_CC_PCR_Read // Conditional expansion of this file |
| 9644 | 4 TPM_RC |
| 9645 | 5 TPM2_PCR_Read( |
| 9646 | 6 PCR_Read_In *in, // IN: input parameter list |
| 9647 | 7 PCR_Read_Out *out // OUT: output parameter list |
| 9648 | 8 ) |
| 9649 | 9 { |
| 9650 | 10 // Command Output |
| 9651 | 11 |
| 9652 | 12 // Call PCR read function. input pcrSelectionIn parameter could be changed |
| 9653 | 13 // to reflect the actual PCR being returned |
| 9654 | 14 PCRRead(&in->pcrSelectionIn, &out->pcrValues, &out->pcrUpdateCounter); |
| 9655 | 15 |
| 9656 | 16 out->pcrSelectionOut = in->pcrSelectionIn; |
| 9657 | 17 |
| 9658 | 18 return TPM_RC_SUCCESS; |
| 9659 | 19 } |
| 9660 | 20 #endif // CC_PCR_Read |
| 9661 | |
| 9662 | |
| 9663 | |
| 9664 | |
| 9665 | Family “2.0” TCG Published Page 211 |
| 9666 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 9667 | Part 3: Commands Trusted Platform Module Library |
| 9668 | |
| 9669 | |
| 9670 | 22.5 TPM2_PCR_Allocate |
| 9671 | |
| 9672 | 22.5.1 General Description |
| 9673 | |
| 9674 | This command is used to set the desired PCR allocation of PCR and algorithms. This command requires |
| 9675 | Platform Authorization. |
| 9676 | The TPM will evaluate the request and, if sufficient memory is available for the requested allocation, the |
| 9677 | TPM will store the allocation request for use during the next TPM2_Startup(TPM_SU_CLEAR) operation. |
| 9678 | The PCR allocation in place when this command is executed will be retained until the next |
| 9679 | TPM2_Startup(TPM_SU_CLEAR). If this command is received multiple times before a |
| 9680 | TPM2_Startup(TPM_SU_CLEAR), each one overwrites the previous stored allocation. |
| 9681 | This command will only change the allocations of banks that are listed in pcrAllocation. |
| 9682 | EXAMPLE If a TPM supports SHA1 and SHA256, then it maintains an allocation for two banks (one of which could |
| 9683 | be empty). If a TPM_PCR_ALLOCATE() only has a selector for the SHA1 bank, then only the allocation |
| 9684 | of the SHA1 bank will be changed and the SHA256 bank will re main unchanged. To change the |
| 9685 | allocation of a TPM from 24 SHA1 PCR and no SHA256 PCR to 24 SHA256 PCR and no SHA1 PCR, the |
| 9686 | pcrAllocation would have to have two selections: one for the empty SHA1 bank and one for the SHA256 |
| 9687 | bank with 24 PCR. |
| 9688 | |
| 9689 | |
| 9690 | If a bank is listed more than once, then the last selection in the pcrAllocation list is the one that the TPM |
| 9691 | will attempt to allocate. |
| 9692 | This command shall not allocate more PCR in any bank than there are PCR attribute definitions. The |
| 9693 | PCR attribute definitions indicate how a PCR is to be managed – if it is resettable, the locality for update, |
| 9694 | etc. In the response to this command, the TPM returns the maximum number of PCR allowed for any |
| 9695 | bank. |
| 9696 | When PCR are allocated, if DRTM_PCR is defined, the resulting allocation must have at least one bank |
| 9697 | with the D-RTM PCR allocated. If HCRTM_PCR is defined, the resulting allocation must have at least |
| 9698 | one bank with the HCRTM_PCR allocated. If not, the TPM returns TPM_RC_PCR. |
| 9699 | The TPM may return TPM_RC_SUCCESS even though the request fails. This is to allow the TPM to |
| 9700 | return information about the size needed for the requested allocation and the size available. If the |
| 9701 | sizeNeeded parameter in the return is less than or equal to the sizeAvailable parameter, then the |
| 9702 | allocationSuccess parameter will be YES. Alternatively, if the request fails, The TPM may return |
| 9703 | TPM_RC_NO_RESULT. |
| 9704 | |
| 9705 | NOTE 1 An example for this type of failure is a TPM that can only support one bank at a time and cannot |
| 9706 | support arbitrary distribution of PCR among banks. |
| 9707 | |
| 9708 | After this command, TPM2_Shutdown() is only allowed to have a startupType equal to TPM_SU_CLEAR. |
| 9709 | |
| 9710 | NOTE 2 Even if this command does not cause the PCR allocation to change, the TPM cannot have its state |
| 9711 | saved. This is done in order to simplify the implementat ion. There is no need to optimize this |
| 9712 | command as it is not expected to be used more than once in the lifetime of the TPM (it can be used |
| 9713 | any number of times but there is no justification for optimization). |
| 9714 | |
| 9715 | |
| 9716 | |
| 9717 | |
| 9718 | Page 212 TCG Published Family “2.0” |
| 9719 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 9720 | Trusted Platform Module Library Part 3: Commands |
| 9721 | |
| 9722 | |
| 9723 | 22.5.2 Command and Response |
| 9724 | |
| 9725 | Table 105 — TPM2_PCR_Allocate Command |
| 9726 | Type Name Description |
| 9727 | |
| 9728 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 9729 | UINT32 commandSize |
| 9730 | TPM_CC commandCode TPM_CC_PCR_Allocate {NV} |
| 9731 | |
| 9732 | TPM_RH_PLATFORM+{PP} |
| 9733 | TPMI_RH_PLATFORM @authHandle Auth Index: 1 |
| 9734 | Auth Role: USER |
| 9735 | |
| 9736 | TPML_PCR_SELECTION pcrAllocation the requested allocation |
| 9737 | |
| 9738 | |
| 9739 | Table 106 — TPM2_PCR_Allocate Response |
| 9740 | Type Name Description |
| 9741 | |
| 9742 | TPM_ST tag see clause 6 |
| 9743 | UINT32 responseSize |
| 9744 | TPM_RC responseCode |
| 9745 | |
| 9746 | TPMI_YES_NO allocationSuccess YES if the allocation succeeded |
| 9747 | UINT32 maxPCR maximum number of PCR that may be in a bank |
| 9748 | UINT32 sizeNeeded number of octets required to satisfy the request |
| 9749 | Number of octets available. Computed before the |
| 9750 | UINT32 sizeAvailable |
| 9751 | allocation. |
| 9752 | |
| 9753 | |
| 9754 | |
| 9755 | |
| 9756 | Family “2.0” TCG Published Page 213 |
| 9757 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 9758 | Part 3: Commands Trusted Platform Module Library |
| 9759 | |
| 9760 | |
| 9761 | |
| 9762 | 22.5.3 Detailed Actions |
| 9763 | |
| 9764 | 1 #include "InternalRoutines.h" |
| 9765 | 2 #include "PCR_Allocate_fp.h" |
| 9766 | 3 #ifdef TPM_CC_PCR_Allocate // Conditional expansion of this file |
| 9767 | |
| 9768 | |
| 9769 | Error Returns Meaning |
| 9770 | |
| 9771 | TPM_RC_PCR the allocation did not have required PCR |
| 9772 | TPM_RC_NV_UNAVAILABLE NV is not accessible |
| 9773 | TPM_RC_NV_RATE NV is in a rate-limiting mode |
| 9774 | |
| 9775 | 4 TPM_RC |
| 9776 | 5 TPM2_PCR_Allocate( |
| 9777 | 6 PCR_Allocate_In *in, // IN: input parameter list |
| 9778 | 7 PCR_Allocate_Out *out // OUT: output parameter list |
| 9779 | 8 ) |
| 9780 | 9 { |
| 9781 | 10 TPM_RC result; |
| 9782 | 11 |
| 9783 | 12 // The command needs NV update. Check if NV is available. |
| 9784 | 13 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at |
| 9785 | 14 // this point. |
| 9786 | 15 // Note: These codes are not listed in the return values above because it is |
| 9787 | 16 // an implementation choice to check in this routine rather than in a common |
| 9788 | 17 // function that is called before these actions are called. These return values |
| 9789 | 18 // are described in the Response Code section of Part 3. |
| 9790 | 19 result = NvIsAvailable(); |
| 9791 | 20 if(result != TPM_RC_SUCCESS) |
| 9792 | 21 return result; |
| 9793 | 22 |
| 9794 | 23 // Command Output |
| 9795 | 24 |
| 9796 | 25 // Call PCR Allocation function. |
| 9797 | 26 result = PCRAllocate(&in->pcrAllocation, &out->maxPCR, |
| 9798 | 27 &out->sizeNeeded, &out->sizeAvailable); |
| 9799 | 28 if(result == TPM_RC_PCR) |
| 9800 | 29 return result; |
| 9801 | 30 |
| 9802 | 31 // |
| 9803 | 32 out->allocationSuccess = (result == TPM_RC_SUCCESS); |
| 9804 | 33 |
| 9805 | 34 // if re-configuration succeeds, set the flag to indicate PCR configuration is |
| 9806 | 35 // going to be changed in next boot |
| 9807 | 36 if(out->allocationSuccess == YES) |
| 9808 | 37 g_pcrReConfig = TRUE; |
| 9809 | 38 |
| 9810 | 39 return TPM_RC_SUCCESS; |
| 9811 | 40 } |
| 9812 | 41 #endif // CC_PCR_Allocate |
| 9813 | |
| 9814 | |
| 9815 | |
| 9816 | |
| 9817 | Page 214 TCG Published Family “2.0” |
| 9818 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 9819 | Trusted Platform Module Library Part 3: Commands |
| 9820 | |
| 9821 | |
| 9822 | 22.6 TPM2_PCR_SetAuthPolicy |
| 9823 | |
| 9824 | 22.6.1 General Description |
| 9825 | |
| 9826 | This command is used to associate a policy with a PCR or group of PCR. The policy determines the |
| 9827 | conditions under which a PCR may be extended or reset. |
| 9828 | A policy may only be associated with a PCR that has been defined by a platform-specific specification as |
| 9829 | allowing a policy. If the TPM implementation does not allow a policy for pcrNum, the TPM shall return |
| 9830 | TPM_RC_VALUE. |
| 9831 | A platform-specific specification may group PCR so that they share a common policy. In such case, a |
| 9832 | pcrNum that selects any of the PCR in the group will change the policy for all PCR in the group. |
| 9833 | The policy setting is persistent and may only be changed by TPM2_PCR_SetAuthPolicy() or by |
| 9834 | TPM2_ChangePPS(). |
| 9835 | Before this command is first executed on a TPM or after TPM2_ChangePPS(), the access control on the |
| 9836 | PCR will be set to the default value defined in the platform-specific specification. |
| 9837 | |
| 9838 | NOTE 1 It is expected that the typical default will be with the policy hash set to TPM_ALG_NULL and an |
| 9839 | Empty Buffer for the authPolicy value. This will allow an EmptyAuth to be used as the authorization |
| 9840 | value. |
| 9841 | |
| 9842 | If the size of the data buffer in authPolicy is not the size of a digest produced by hashAlg, the TPM shall |
| 9843 | return TPM_RC_SIZE. |
| 9844 | |
| 9845 | NOTE 2 If hashAlg is TPM_ALG_NULL, then the size is required to be zero. |
| 9846 | |
| 9847 | This command requires platformAuth/platformPolicy. |
| 9848 | |
| 9849 | NOTE 3 If the PCR is in multiple policy sets, the policy will be changed in only one set. The set that is |
| 9850 | changed will be implementation dependent. |
| 9851 | |
| 9852 | |
| 9853 | |
| 9854 | |
| 9855 | Family “2.0” TCG Published Page 215 |
| 9856 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 9857 | Part 3: Commands Trusted Platform Module Library |
| 9858 | |
| 9859 | |
| 9860 | 22.6.2 Command and Response |
| 9861 | |
| 9862 | Table 107 — TPM2_PCR_SetAuthPolicy Command |
| 9863 | Type Name Description |
| 9864 | |
| 9865 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 9866 | UINT32 commandSize |
| 9867 | TPM_CC commandCode TPM_CC_PCR_SetAuthPolicy {NV} |
| 9868 | |
| 9869 | TPM_RH_PLATFORM+{PP} |
| 9870 | TPMI_RH_PLATFORM @authHandle Auth Index: 1 |
| 9871 | Auth Role: USER |
| 9872 | |
| 9873 | TPM2B_DIGEST authPolicy the desired authPolicy |
| 9874 | TPMI_ALG_HASH+ hashAlg the hash algorithm of the policy |
| 9875 | TPMI_DH_PCR pcrNum the PCR for which the policy is to be set |
| 9876 | |
| 9877 | |
| 9878 | Table 108 — TPM2_PCR_SetAuthPolicy Response |
| 9879 | Type Name Description |
| 9880 | |
| 9881 | TPM_ST tag see clause 6 |
| 9882 | UINT32 responseSize |
| 9883 | TPM_RC responseCode |
| 9884 | |
| 9885 | |
| 9886 | |
| 9887 | |
| 9888 | Page 216 TCG Published Family “2.0” |
| 9889 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 9890 | Trusted Platform Module Library Part 3: Commands |
| 9891 | |
| 9892 | |
| 9893 | |
| 9894 | 22.6.3 Detailed Actions |
| 9895 | |
| 9896 | 1 #include "InternalRoutines.h" |
| 9897 | 2 #include "PCR_SetAuthPolicy_fp.h" |
| 9898 | 3 #ifdef TPM_CC_PCR_SetAuthPolicy // Conditional expansion of this file |
| 9899 | |
| 9900 | |
| 9901 | Error Returns Meaning |
| 9902 | |
| 9903 | TPM_RC_SIZE size of authPolicy is not the size of a digest produced by policyDigest |
| 9904 | TPM_RC_VALUE PCR referenced by pcrNum is not a member of a PCR policy group |
| 9905 | |
| 9906 | 4 TPM_RC |
| 9907 | 5 TPM2_PCR_SetAuthPolicy( |
| 9908 | 6 PCR_SetAuthPolicy_In *in // IN: input parameter list |
| 9909 | 7 ) |
| 9910 | 8 { |
| 9911 | 9 UINT32 groupIndex; |
| 9912 | 10 |
| 9913 | 11 TPM_RC result; |
| 9914 | 12 |
| 9915 | 13 // The command needs NV update. Check if NV is available. |
| 9916 | 14 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at |
| 9917 | 15 // this point |
| 9918 | 16 result = NvIsAvailable(); |
| 9919 | 17 if(result != TPM_RC_SUCCESS) return result; |
| 9920 | 18 |
| 9921 | 19 // Input Validation: |
| 9922 | 20 |
| 9923 | 21 // Check the authPolicy consistent with hash algorithm |
| 9924 | 22 if(in->authPolicy.t.size != CryptGetHashDigestSize(in->hashAlg)) |
| 9925 | 23 return TPM_RC_SIZE + RC_PCR_SetAuthPolicy_authPolicy; |
| 9926 | 24 |
| 9927 | 25 // If PCR does not belong to a policy group, return TPM_RC_VALUE |
| 9928 | 26 if(!PCRBelongsPolicyGroup(in->pcrNum, &groupIndex)) |
| 9929 | 27 return TPM_RC_VALUE + RC_PCR_SetAuthPolicy_pcrNum; |
| 9930 | 28 |
| 9931 | 29 // Internal Data Update |
| 9932 | 30 |
| 9933 | 31 // Set PCR policy |
| 9934 | 32 gp.pcrPolicies.hashAlg[groupIndex] = in->hashAlg; |
| 9935 | 33 gp.pcrPolicies.policy[groupIndex] = in->authPolicy; |
| 9936 | 34 |
| 9937 | 35 // Save new policy to NV |
| 9938 | 36 NvWriteReserved(NV_PCR_POLICIES, &gp.pcrPolicies); |
| 9939 | 37 |
| 9940 | 38 return TPM_RC_SUCCESS; |
| 9941 | 39 } |
| 9942 | 40 #endif // CC_PCR_SetAuthPolicy |
| 9943 | |
| 9944 | |
| 9945 | |
| 9946 | |
| 9947 | Family “2.0” TCG Published Page 217 |
| 9948 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 9949 | Part 3: Commands Trusted Platform Module Library |
| 9950 | |
| 9951 | |
| 9952 | 22.7 TPM2_PCR_SetAuthValue |
| 9953 | |
| 9954 | 22.7.1 General Description |
| 9955 | |
| 9956 | This command changes the authValue of a PCR or group of PCR. |
| 9957 | An authValue may only be associated with a PCR that has been defined by a platform-specific |
| 9958 | specification as allowing an authorization value. If the TPM implementation does not allow an |
| 9959 | authorization for pcrNum, the TPM shall return TPM_RC_VALUE. A platform-specific specification may |
| 9960 | group PCR so that they share a common authorization value. In such case, a pcrNum that selects any of |
| 9961 | the PCR in the group will change the authValue value for all PCR in the group. |
| 9962 | The authorization setting is set to EmptyAuth on each STARTUP(CLEAR) or by TPM2_Clear(). The |
| 9963 | authorization setting is preserved by SHUTDOWN(STATE). |
| 9964 | |
| 9965 | |
| 9966 | |
| 9967 | |
| 9968 | Page 218 TCG Published Family “2.0” |
| 9969 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 9970 | Trusted Platform Module Library Part 3: Commands |
| 9971 | |
| 9972 | |
| 9973 | |
| 9974 | 22.7.2 Command and Response |
| 9975 | |
| 9976 | Table 109 — TPM2_PCR_SetAuthValue Command |
| 9977 | Type Name Description |
| 9978 | |
| 9979 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 9980 | UINT32 commandSize |
| 9981 | TPM_CC commandCode TPM_CC_PCR_SetAuthValue |
| 9982 | |
| 9983 | handle for a PCR that may have an authorization value |
| 9984 | set |
| 9985 | TPMI_DH_PCR @pcrHandle |
| 9986 | Auth Index: 1 |
| 9987 | Auth Role: USER |
| 9988 | |
| 9989 | TPM2B_DIGEST auth the desired authorization value |
| 9990 | |
| 9991 | |
| 9992 | Table 110 — TPM2_PCR_SetAuthValue Response |
| 9993 | Type Name Description |
| 9994 | |
| 9995 | TPM_ST tag see clause 6 |
| 9996 | UINT32 responseSize |
| 9997 | TPM_RC responseCode |
| 9998 | |
| 9999 | |
| 10000 | |
| 10001 | |
| 10002 | Family “2.0” TCG Published Page 219 |
| 10003 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 10004 | Part 3: Commands Trusted Platform Module Library |
| 10005 | |
| 10006 | |
| 10007 | |
| 10008 | 22.7.3 Detailed Actions |
| 10009 | |
| 10010 | 1 #include "InternalRoutines.h" |
| 10011 | 2 #include "PCR_SetAuthValue_fp.h" |
| 10012 | 3 #ifdef TPM_CC_PCR_SetAuthValue // Conditional expansion of this file |
| 10013 | |
| 10014 | |
| 10015 | Error Returns Meaning |
| 10016 | |
| 10017 | TPM_RC_VALUE PCR referenced by pcrHandle is not a member of a PCR |
| 10018 | authorization group |
| 10019 | |
| 10020 | 4 TPM_RC |
| 10021 | 5 TPM2_PCR_SetAuthValue( |
| 10022 | 6 PCR_SetAuthValue_In *in // IN: input parameter list |
| 10023 | 7 ) |
| 10024 | 8 { |
| 10025 | 9 UINT32 groupIndex; |
| 10026 | 10 TPM_RC result; |
| 10027 | 11 |
| 10028 | 12 // Input Validation: |
| 10029 | 13 |
| 10030 | 14 // If PCR does not belong to an auth group, return TPM_RC_VALUE |
| 10031 | 15 if(!PCRBelongsAuthGroup(in->pcrHandle, &groupIndex)) |
| 10032 | 16 return TPM_RC_VALUE; |
| 10033 | 17 |
| 10034 | 18 // The command may cause the orderlyState to be cleared due to the update of |
| 10035 | 19 // state clear data. If this is the case, Check if NV is available. |
| 10036 | 20 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at |
| 10037 | 21 // this point |
| 10038 | 22 if(gp.orderlyState != SHUTDOWN_NONE) |
| 10039 | 23 { |
| 10040 | 24 result = NvIsAvailable(); |
| 10041 | 25 if(result != TPM_RC_SUCCESS) return result; |
| 10042 | 26 g_clearOrderly = TRUE; |
| 10043 | 27 } |
| 10044 | 28 |
| 10045 | 29 // Internal Data Update |
| 10046 | 30 |
| 10047 | 31 // Set PCR authValue |
| 10048 | 32 gc.pcrAuthValues.auth[groupIndex] = in->auth; |
| 10049 | 33 |
| 10050 | 34 return TPM_RC_SUCCESS; |
| 10051 | 35 } |
| 10052 | 36 #endif // CC_PCR_SetAuthValue |
| 10053 | |
| 10054 | |
| 10055 | |
| 10056 | |
| 10057 | Page 220 TCG Published Family “2.0” |
| 10058 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 10059 | Trusted Platform Module Library Part 3: Commands |
| 10060 | |
| 10061 | |
| 10062 | 22.8 TPM2_PCR_Reset |
| 10063 | |
| 10064 | 22.8.1 General Description |
| 10065 | |
| 10066 | If the attribute of a PCR allows the PCR to be reset and proper authorization is provided, then this |
| 10067 | command may be used to set the PCR to zero. The attributes of the PCR may restrict the locality that can |
| 10068 | perform the reset operation. |
| 10069 | |
| 10070 | NOTE 1 The definition of TPMI_DH_PCR in TPM 2.0 Part 2 indicates that if pcrHandle is out of the allowed |
| 10071 | range for PCR, then the appropriate return value is TPM_RC_VALUE. |
| 10072 | |
| 10073 | If pcrHandle references a PCR that cannot be reset, the TPM shall return TPM_RC_LOCALITY. |
| 10074 | |
| 10075 | NOTE 2 TPM_RC_LOCALITY is returned because the reset attributes are defined on a per -locality basis. |
| 10076 | |
| 10077 | |
| 10078 | |
| 10079 | |
| 10080 | Family “2.0” TCG Published Page 221 |
| 10081 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 10082 | Part 3: Commands Trusted Platform Module Library |
| 10083 | |
| 10084 | |
| 10085 | 22.8.2 Command and Response |
| 10086 | |
| 10087 | Table 111 — TPM2_PCR_Reset Command |
| 10088 | Type Name Description |
| 10089 | |
| 10090 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 10091 | UINT32 commandSize |
| 10092 | TPM_CC commandCode TPM_CC_PCR_Reset {NV} |
| 10093 | |
| 10094 | the PCR to reset |
| 10095 | TPMI_DH_PCR @pcrHandle Auth Index: 1 |
| 10096 | Auth Role: USER |
| 10097 | |
| 10098 | |
| 10099 | Table 112 — TPM2_PCR_Reset Response |
| 10100 | Type Name Description |
| 10101 | |
| 10102 | TPM_ST tag see clause 6 |
| 10103 | UINT32 responseSize |
| 10104 | TPM_RC responseCode |
| 10105 | |
| 10106 | |
| 10107 | |
| 10108 | |
| 10109 | Page 222 TCG Published Family “2.0” |
| 10110 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 10111 | Trusted Platform Module Library Part 3: Commands |
| 10112 | |
| 10113 | |
| 10114 | |
| 10115 | 22.8.3 Detailed Actions |
| 10116 | |
| 10117 | 1 #include "InternalRoutines.h" |
| 10118 | 2 #include "PCR_Reset_fp.h" |
| 10119 | 3 #ifdef TPM_CC_PCR_Reset // Conditional expansion of this file |
| 10120 | |
| 10121 | |
| 10122 | Error Returns Meaning |
| 10123 | |
| 10124 | TPM_RC_LOCALITY current command locality is not allowed to reset the PCR referenced |
| 10125 | by pcrHandle |
| 10126 | |
| 10127 | 4 TPM_RC |
| 10128 | 5 TPM2_PCR_Reset( |
| 10129 | 6 PCR_Reset_In *in // IN: input parameter list |
| 10130 | 7 ) |
| 10131 | 8 { |
| 10132 | 9 TPM_RC result; |
| 10133 | 10 |
| 10134 | 11 // Input Validation |
| 10135 | 12 |
| 10136 | 13 // Check if the reset operation is allowed by the current command locality |
| 10137 | 14 if(!PCRIsResetAllowed(in->pcrHandle)) |
| 10138 | 15 return TPM_RC_LOCALITY; |
| 10139 | 16 |
| 10140 | 17 // If PCR is state saved and we need to update orderlyState, check NV |
| 10141 | 18 // availability |
| 10142 | 19 if(PCRIsStateSaved(in->pcrHandle) && gp.orderlyState != SHUTDOWN_NONE) |
| 10143 | 20 { |
| 10144 | 21 result = NvIsAvailable(); |
| 10145 | 22 if(result != TPM_RC_SUCCESS) |
| 10146 | 23 return result; |
| 10147 | 24 g_clearOrderly = TRUE; |
| 10148 | 25 } |
| 10149 | 26 |
| 10150 | 27 // Internal Data Update |
| 10151 | 28 |
| 10152 | 29 // Reset selected PCR in all banks to 0 |
| 10153 | 30 PCRSetValue(in->pcrHandle, 0); |
| 10154 | 31 |
| 10155 | 32 // Indicate that the PCR changed so that pcrCounter will be incremented if |
| 10156 | 33 // necessary. |
| 10157 | 34 PCRChanged(in->pcrHandle); |
| 10158 | 35 |
| 10159 | 36 return TPM_RC_SUCCESS; |
| 10160 | 37 } |
| 10161 | 38 #endif // CC_PCR_Reset |
| 10162 | |
| 10163 | |
| 10164 | |
| 10165 | |
| 10166 | Family “2.0” TCG Published Page 223 |
| 10167 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 10168 | Part 3: Commands Trusted Platform Module Library |
| 10169 | |
| 10170 | |
| 10171 | 22.9 _TPM_Hash_Start |
| 10172 | |
| 10173 | 22.9.1 Description |
| 10174 | |
| 10175 | This indication from the TPM interface indicates the start of an H-CRTM measurement sequence. On |
| 10176 | receipt of this indication, the TPM will initialize an H-CRTM Event Sequence context. |
| 10177 | If no object memory is available for creation of the sequence context, the TPM will flush the context of an |
| 10178 | object so that creation of the sequence context will always succeed. |
| 10179 | A platform-specific specification may allow this indication before TPM2_Startup(). |
| 10180 | |
| 10181 | NOTE If this indication occurs after TPM2_Startup(), i t is the responsibility of software to ensure that an |
| 10182 | object context slot is available or to deal with the consequences of having the TPM select an |
| 10183 | arbitrary object to be flushed. If this indication occurs before TPM2_Startup() then all context slots |
| 10184 | are available. |
| 10185 | |
| 10186 | |
| 10187 | |
| 10188 | |
| 10189 | Page 224 TCG Published Family “2.0” |
| 10190 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 10191 | Trusted Platform Module Library Part 3: Commands |
| 10192 | |
| 10193 | |
| 10194 | 22.9.2 Detailed Actions |
| 10195 | |
| 10196 | 1 #include "InternalRoutines.h" |
| 10197 | |
| 10198 | This function is called to process a _TPM_Hash_Start() indication. |
| 10199 | |
| 10200 | 2 void |
| 10201 | 3 _TPM_Hash_Start( |
| 10202 | 4 void |
| 10203 | 5 ) |
| 10204 | 6 { |
| 10205 | 7 TPM_RC result; |
| 10206 | 8 TPMI_DH_OBJECT handle; |
| 10207 | 9 |
| 10208 | 10 // If a DRTM sequence object exists, free it up |
| 10209 | 11 if(g_DRTMHandle != TPM_RH_UNASSIGNED) |
| 10210 | 12 { |
| 10211 | 13 ObjectFlush(g_DRTMHandle); |
| 10212 | 14 g_DRTMHandle = TPM_RH_UNASSIGNED; |
| 10213 | 15 } |
| 10214 | 16 |
| 10215 | 17 // Create an event sequence object and store the handle in global |
| 10216 | 18 // g_DRTMHandle. A TPM_RC_OBJECT_MEMORY error may be returned at this point |
| 10217 | 19 // The null value for the 'auth' parameter will cause the sequence structure to |
| 10218 | 20 // be allocated without being set as present. This keeps the sequence from |
| 10219 | 21 // being left behind if the sequence is terminated early. |
| 10220 | 22 result = ObjectCreateEventSequence(NULL, &g_DRTMHandle); |
| 10221 | 23 |
| 10222 | 24 // If a free slot was not available, then free up a slot. |
| 10223 | 25 if(result != TPM_RC_SUCCESS) |
| 10224 | 26 { |
| 10225 | 27 // An implementation does not need to have a fixed relationship between |
| 10226 | 28 // slot numbers and handle numbers. To handle the general case, scan for |
| 10227 | 29 // a handle that is assigned and free it for the DRTM sequence. |
| 10228 | 30 // In the reference implementation, the relationship between handles and |
| 10229 | 31 // slots is fixed. So, if the call to ObjectCreateEvenSequence() |
| 10230 | 32 // failed indicating that all slots are occupied, then the first handle we |
| 10231 | 33 // are going to check (TRANSIENT_FIRST) will be occupied. It will be freed |
| 10232 | 34 // so that it can be assigned for use as the DRTM sequence object. |
| 10233 | 35 for(handle = TRANSIENT_FIRST; handle < TRANSIENT_LAST; handle++) |
| 10234 | 36 { |
| 10235 | 37 // try to flush the first object |
| 10236 | 38 if(ObjectIsPresent(handle)) |
| 10237 | 39 break; |
| 10238 | 40 } |
| 10239 | 41 // If the first call to find a slot fails but none of the slots is occupied |
| 10240 | 42 // then there's a big problem |
| 10241 | 43 pAssert(handle < TRANSIENT_LAST); |
| 10242 | 44 |
| 10243 | 45 // Free the slot |
| 10244 | 46 ObjectFlush(handle); |
| 10245 | 47 |
| 10246 | 48 // Try to create an event sequence object again. This time, we must |
| 10247 | 49 // succeed. |
| 10248 | 50 result = ObjectCreateEventSequence(NULL, &g_DRTMHandle); |
| 10249 | 51 pAssert(result == TPM_RC_SUCCESS); |
| 10250 | 52 } |
| 10251 | 53 |
| 10252 | 54 return; |
| 10253 | 55 } |
| 10254 | |
| 10255 | |
| 10256 | |
| 10257 | |
| 10258 | Family “2.0” TCG Published Page 225 |
| 10259 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 10260 | Part 3: Commands Trusted Platform Module Library |
| 10261 | |
| 10262 | |
| 10263 | 22.10 _TPM_Hash_Data |
| 10264 | |
| 10265 | 22.10.1 Description |
| 10266 | |
| 10267 | This indication from the TPM interface indicates arrival of one or more octets of data that are to be |
| 10268 | included in the H-CRTM Event Sequence sequence context created by the _TPM_Hash_Start indication. |
| 10269 | The context holds data for each hash algorithm for each PCR bank implemented on the TPM. |
| 10270 | If no H-CRTM Event Sequence context exists, this indication is discarded and no other action is |
| 10271 | performed. |
| 10272 | |
| 10273 | |
| 10274 | |
| 10275 | |
| 10276 | Page 226 TCG Published Family “2.0” |
| 10277 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 10278 | Trusted Platform Module Library Part 3: Commands |
| 10279 | |
| 10280 | |
| 10281 | |
| 10282 | 22.10.2 Detailed Actions |
| 10283 | |
| 10284 | 1 #include "InternalRoutines.h" |
| 10285 | 2 #include "Platform.h" |
| 10286 | 3 #include "PCR_fp.h" |
| 10287 | |
| 10288 | This function is called to process a _TPM_Hash_Data() indication. |
| 10289 | |
| 10290 | 4 void |
| 10291 | 5 _TPM_Hash_Data( |
| 10292 | 6 UINT32 dataSize, // IN: size of data to be extend |
| 10293 | 7 BYTE *data // IN: data buffer |
| 10294 | 8 ) |
| 10295 | 9 { |
| 10296 | 10 UINT32 i; |
| 10297 | 11 HASH_OBJECT *hashObject; |
| 10298 | 12 TPMI_DH_PCR pcrHandle = TPMIsStarted() |
| 10299 | 13 ? PCR_FIRST + DRTM_PCR : PCR_FIRST + HCRTM_PCR; |
| 10300 | 14 |
| 10301 | 15 // If there is no DRTM sequence object, then _TPM_Hash_Start |
| 10302 | 16 // was not called so this function returns without doing |
| 10303 | 17 // anything. |
| 10304 | 18 if(g_DRTMHandle == TPM_RH_UNASSIGNED) |
| 10305 | 19 return; |
| 10306 | 20 |
| 10307 | 21 hashObject = (HASH_OBJECT *)ObjectGet(g_DRTMHandle); |
| 10308 | 22 pAssert(hashObject->attributes.eventSeq); |
| 10309 | 23 |
| 10310 | 24 // For each of the implemented hash algorithms, update the digest with the |
| 10311 | 25 // data provided. |
| 10312 | 26 for(i = 0; i < HASH_COUNT; i++) |
| 10313 | 27 { |
| 10314 | 28 // make sure that the PCR is implemented for this algorithm |
| 10315 | 29 if(PcrIsAllocated(pcrHandle, |
| 10316 | 30 hashObject->state.hashState[i].state.hashAlg)) |
| 10317 | 31 // Update sequence object |
| 10318 | 32 CryptUpdateDigest(&hashObject->state.hashState[i], dataSize, data); |
| 10319 | 33 } |
| 10320 | 34 |
| 10321 | 35 return; |
| 10322 | 36 } |
| 10323 | |
| 10324 | |
| 10325 | |
| 10326 | |
| 10327 | Family “2.0” TCG Published Page 227 |
| 10328 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 10329 | Part 3: Commands Trusted Platform Module Library |
| 10330 | |
| 10331 | |
| 10332 | 22.11 _TPM_Hash_End |
| 10333 | |
| 10334 | 22.11.1 Description |
| 10335 | |
| 10336 | This indication from the TPM interface indicates the end of the H-CRTM measurement. This indication is |
| 10337 | discarded and no other action performed if the TPM does not contain an H-CRTM Event Sequence |
| 10338 | context. |
| 10339 | |
| 10340 | NOTE 1 An H-CRTM Event Sequence context is created by _TPM_Hash_Start(). |
| 10341 | |
| 10342 | If the H-CRTM Event Sequence occurs after TPM2_Startup(), the TPM will set all of the PCR designated |
| 10343 | in the platform-specific specifications as resettable by this event to the value indicated in the platform |
| 10344 | specific specification, and increment restartCount. The TPM will then Extend the Event Sequence |
| 10345 | digest/digests into the designated D-RTM PCR (PCR[17]). |
| 10346 | PCR[17][hashAlg] ≔ HhashAlg (initial_value || HhashAlg (hash_data)) (7) |
| 10347 | where |
| 10348 | hashAlg hash algorithm associated with a bank of PCR |
| 10349 | initial_value initialization value specified in the platform-specific specification |
| 10350 | (should be 0…0) |
| 10351 | hash_data all the octets of data received in _TPM_Hash_Data indications |
| 10352 | A _TPM_Hash_End indication that occurs after TPM2_Startup() will increment pcrUpdateCounter unless |
| 10353 | a platform-specific specification excludes modifications of PCR[DRTM] from causing an increment. |
| 10354 | A platform-specific specification may allow an H-CRTM Event Sequence before TPM2_Startup(). If so, |
| 10355 | _TPM_Hash_End will complete the digest, initialize PCR[0] with a digest-size value of 4, and then extend |
| 10356 | the H-CRTM Event Sequence data into PCR[0]. |
| 10357 | PCR[0][hashAlg] ≔ HhashAlg (0…04 || HhashAlg (hash_data)) (8) |
| 10358 | |
| 10359 | NOTE 2 The entire sequence of _TPM_Hash_Start, _TPM_Hash_Data, and _TPM_Hash_End are required to |
| 10360 | complete before TPM2_Startup() or the sequence will have no effect on the TPM. |
| 10361 | |
| 10362 | NOTE 3 PCR[0] does not need to be updated according to (8) until the end of TPM2_Startup(). |
| 10363 | |
| 10364 | |
| 10365 | |
| 10366 | |
| 10367 | Page 228 TCG Published Family “2.0” |
| 10368 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 10369 | Trusted Platform Module Library Part 3: Commands |
| 10370 | |
| 10371 | |
| 10372 | 22.11.2 Detailed Actions |
| 10373 | |
| 10374 | 1 #include "InternalRoutines.h" |
| 10375 | |
| 10376 | This function is called to process a _TPM_Hash_End() indication. |
| 10377 | |
| 10378 | 2 void |
| 10379 | 3 _TPM_Hash_End( |
| 10380 | 4 void |
| 10381 | 5 ) |
| 10382 | 6 { |
| 10383 | 7 |
| 10384 | 8 UINT32 i; |
| 10385 | 9 TPM2B_DIGEST digest; |
| 10386 | 10 HASH_OBJECT *hashObject; |
| 10387 | 11 TPMI_DH_PCR pcrHandle; |
| 10388 | 12 |
| 10389 | 13 // If the DRTM handle is not being used, then either _TPM_Hash_Start has not |
| 10390 | 14 // been called, _TPM_Hash_End was previously called, or some other command |
| 10391 | 15 // was executed and the sequence was aborted. |
| 10392 | 16 if(g_DRTMHandle == TPM_RH_UNASSIGNED) |
| 10393 | 17 return; |
| 10394 | 18 |
| 10395 | 19 // Get DRTM sequence object |
| 10396 | 20 hashObject = (HASH_OBJECT *)ObjectGet(g_DRTMHandle); |
| 10397 | 21 |
| 10398 | 22 // Is this _TPM_Hash_End after Startup or before |
| 10399 | 23 if(TPMIsStarted()) |
| 10400 | 24 { |
| 10401 | 25 // After |
| 10402 | 26 |
| 10403 | 27 // Reset the DRTM PCR |
| 10404 | 28 PCRResetDynamics(); |
| 10405 | 29 |
| 10406 | 30 // Extend the DRTM_PCR. |
| 10407 | 31 pcrHandle = PCR_FIRST + DRTM_PCR; |
| 10408 | 32 |
| 10409 | 33 // DRTM sequence increments restartCount |
| 10410 | 34 gr.restartCount++; |
| 10411 | 35 } |
| 10412 | 36 else |
| 10413 | 37 { |
| 10414 | 38 pcrHandle = PCR_FIRST + HCRTM_PCR; |
| 10415 | 39 } |
| 10416 | 40 |
| 10417 | 41 // Complete hash and extend PCR, or if this is an HCRTM, complete |
| 10418 | 42 // the hash, reset the H-CRTM register (PCR[0]) to 0...04, and then |
| 10419 | 43 // extend the H-CRTM data |
| 10420 | 44 for(i = 0; i < HASH_COUNT; i++) |
| 10421 | 45 { |
| 10422 | 46 TPMI_ALG_HASH hash = CryptGetHashAlgByIndex(i); |
| 10423 | 47 // make sure that the PCR is implemented for this algorithm |
| 10424 | 48 if(PcrIsAllocated(pcrHandle, |
| 10425 | 49 hashObject->state.hashState[i].state.hashAlg)) |
| 10426 | 50 { |
| 10427 | 51 // Complete hash |
| 10428 | 52 digest.t.size = CryptGetHashDigestSize(hash); |
| 10429 | 53 CryptCompleteHash2B(&hashObject->state.hashState[i], &digest.b); |
| 10430 | 54 |
| 10431 | 55 PcrDrtm(pcrHandle, hash, &digest); |
| 10432 | 56 } |
| 10433 | 57 } |
| 10434 | 58 |
| 10435 | 59 // Flush sequence object. |
| 10436 | |
| 10437 | |
| 10438 | Family “2.0” TCG Published Page 229 |
| 10439 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 10440 | Part 3: Commands Trusted Platform Module Library |
| 10441 | |
| 10442 | 60 ObjectFlush(g_DRTMHandle); |
| 10443 | 61 |
| 10444 | 62 g_DRTMHandle = TPM_RH_UNASSIGNED; |
| 10445 | 63 |
| 10446 | 64 g_DrtmPreStartup = TRUE; |
| 10447 | 65 |
| 10448 | 66 return; |
| 10449 | 67 } |
| 10450 | |
| 10451 | |
| 10452 | |
| 10453 | |
| 10454 | Page 230 TCG Published Family “2.0” |
| 10455 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 10456 | Trusted Platform Module Library Part 3: Commands |
| 10457 | |
| 10458 | |
| 10459 | 23 Enhanced Authorization (EA) Commands |
| 10460 | |
| 10461 | 23.1 Introduction |
| 10462 | |
| 10463 | The commands in this clause 1 are used for policy evaluation. When successful, each command will |
| 10464 | update the policySession→policyDigest in a policy session context in order to establish that the |
| 10465 | authorizations required to use an object have been provided. Many of the commands will also modify |
| 10466 | other parts of a policy context so that the caller may constrain the scope of the authorization that is |
| 10467 | provided. |
| 10468 | |
| 10469 | NOTE 1 Many of the terms used in this clause are described in detail in TPM 2.0 Part 1 and are not redefined |
| 10470 | in this clause. |
| 10471 | |
| 10472 | The policySession parameter of the command is the handle of the policy session context to be modified |
| 10473 | by the command. |
| 10474 | If the policySession parameter indicates a trial policy session, then the policySession→policyDigest will |
| 10475 | be updated and the indicated validations are not performed. |
| 10476 | |
| 10477 | NOTE 2 A policy session is set to a trial policy by TPM2_StartAuthSession(sessionType = TPM_SE_TRIAL). |
| 10478 | |
| 10479 | NOTE 3 Unless there is an unmarshaling error in the parameters of the command, these commands will |
| 10480 | return TPM_RC_SUCCESS when policySession references a trial session. |
| 10481 | |
| 10482 | NOTE 4 Policy context other than the policySession→policyDigest may be updated for a trial policy but it is |
| 10483 | not required. |
| 10484 | |
| 10485 | |
| 10486 | |
| 10487 | |
| 10488 | Family “2.0” TCG Published Page 231 |
| 10489 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 10490 | Part 3: Commands Trusted Platform Module Library |
| 10491 | |
| 10492 | |
| 10493 | 23.2 Signed Authorization Actions |
| 10494 | |
| 10495 | 23.2.1 Introduction |
| 10496 | |
| 10497 | The TPM2_PolicySigned, TPM_PolicySecret, and TPM2_PolicyTicket commands use many of the same |
| 10498 | functions. This clause consolidates those functions to simplify the document and to ensure uniformity of |
| 10499 | the operations. |
| 10500 | |
| 10501 | 23.2.2 Policy Parameter Checks |
| 10502 | |
| 10503 | These parameter checks will be performed when indicated in the description of each of the commands: |
| 10504 | a) nonceTPM – If this parameter is not the Empty Buffer, and it does not match |
| 10505 | policySession→nonceTPM, then the TPM shall return TPM_RC_VALUE. This parameter is required |
| 10506 | to be present if expiration is non-zero (TPM_RC_EXPIRED). |
| 10507 | b) expiration – If this parameter is not zero, then its absolute value is compared to the time in seconds |
| 10508 | since the policySession→nonceTPM was generated. If more time has passed than indicated in |
| 10509 | expiration, the TPM shall return TPM_RC_EXPIRED. If nonceTPM is the Empty buffer, and expiration |
| 10510 | is non-zero, then the TPM shall return TPM_RC_EXPIRED. |
| 10511 | If policySession→timeout is greater than policySession→startTime plus the absolute value of |
| 10512 | expiration, then policySession→timeout is set to policySession→startTime plus the absolute value of |
| 10513 | expiration. That is, policySession→timeout can only be changed to a smaller value. |
| 10514 | c) timeout – This parameter is compared to the current TPM time. If policySession→timeout is in the |
| 10515 | past, then the TPM shall return TPM_RC_EXPIRED. |
| 10516 | |
| 10517 | NOTE 1 The expiration parameter is present in the TPM2_PolicySigned and TPM2_PolicySecret |
| 10518 | command and timeout is the analogous parameter in the TPM2_PolicyTicket command. |
| 10519 | |
| 10520 | d) cpHashA – If this parameter is not an Empty Buffer |
| 10521 | |
| 10522 | NOTE 2 CpHashA is the hash of the command to be executed using this policy session in the |
| 10523 | authorization. The algorithm used to compute this hash is required to be the algorithm of the |
| 10524 | policy session. |
| 10525 | |
| 10526 | 1) the TPM shall return TPM_RC_CPHASH if policySession→cpHash is set and the contents of |
| 10527 | policySession→cpHash are not the same as cpHashA; or |
| 10528 | |
| 10529 | NOTE 3 cpHash is the expected cpHash value held in the policy session context. |
| 10530 | |
| 10531 | 2) the TPM shall return TPM_RC_SIZE if cpHashA is not the same size as |
| 10532 | policySession→policyDigest. |
| 10533 | |
| 10534 | NOTE 4 policySession→policyDigest is the size of the digest produced by the hash algorithm used |
| 10535 | to compute policyDigest. |
| 10536 | |
| 10537 | |
| 10538 | |
| 10539 | |
| 10540 | Page 232 TCG Published Family “2.0” |
| 10541 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 10542 | Trusted Platform Module Library Part 3: Commands |
| 10543 | |
| 10544 | |
| 10545 | 23.2.3 Policy Digest Update Function (PolicyUpdate()) |
| 10546 | |
| 10547 | This is the update process for policySession→policyDigest used by TPM2_PolicySigned(), |
| 10548 | TPM2_PolicySecret(), TPM2_PolicyTicket(), and TPM2_PolicyAuthorize(). The function prototype for the |
| 10549 | update function is: |
| 10550 | PolicyUpdate(commandCode, arg2, arg3) (9) |
| 10551 | where |
| 10552 | arg2 a TPM2B_NAME |
| 10553 | arg3 a TPM2B |
| 10554 | These parameters are used to update policySession→policyDigest by |
| 10555 | policyDigestnew ≔ HpolicyAlg(policyDigestold || commandCode || arg2.name) (10) |
| 10556 | followed by |
| 10557 | policyDigestnew+1 ≔ HpolicyAlg(policyDigestnew || arg3.buffer) (11) |
| 10558 | where |
| 10559 | HpolicyAlg() the hash algorithm chosen when the policy session was started |
| 10560 | |
| 10561 | NOTE 1 If arg3 is a TPM2B_NAME, then arg3.buffer will actually be an arg3.name. |
| 10562 | |
| 10563 | NOTE 2 The arg2.size and arg3.size fields are not included in the hashes. |
| 10564 | |
| 10565 | NOTE 3 PolicyUpdate() uses two hash operations because arg2 and arg3 are variable-sized and the |
| 10566 | concatenation of arg2 and arg3 in a single hash could produce the same digest even though arg2 |
| 10567 | and arg3 are different. For example, arg2 = 1 2 3 and arg3 = 4 5 6 would produce the same digest |
| 10568 | as arg2 = 1 2 and arg3 = 3 4 5 6. Processing of the arguments separately in different Extend |
| 10569 | operation insures that the digest produced by PolicyUpdate() will be different if arg2 and arg3 are |
| 10570 | different. |
| 10571 | |
| 10572 | |
| 10573 | |
| 10574 | |
| 10575 | Family “2.0” TCG Published Page 233 |
| 10576 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 10577 | Part 3: Commands Trusted Platform Module Library |
| 10578 | |
| 10579 | |
| 10580 | |
| 10581 | 23.2.4 Policy Context Updates |
| 10582 | |
| 10583 | When a policy command modifies some part of the policy session context other than the |
| 10584 | policySession→policyDigest, the following rules apply. |
| 10585 | cpHash – this parameter may only be changed if it contains its initialization value (an Empty |
| 10586 | String). If cpHash is not the Empty String when a policy command attempts to update it, the TPM |
| 10587 | will return an error (TPM_RC_CPHASH) if the current and update values are not the same. |
| 10588 | timeOut – this parameter may only be changed to a smaller value. If a command attempts to |
| 10589 | update this value with a larger value (longer into the future), the TPM will discard the update |
| 10590 | value. This is not an error condition. |
| 10591 | commandCode – once set by a policy command, this value may not be changed except by |
| 10592 | TPM2_PolicyRestart(). If a policy command tries to change this to a different value, an error is |
| 10593 | returned (TPM_RC_POLICY_CC). |
| 10594 | pcrUpdateCounter – this parameter is updated by TPM2_PolicyPCR(). This value may only be |
| 10595 | set once during a policy. Each time TPM2_PolicyPCR() executes, it checks to see if |
| 10596 | policySession→pcrUpdateCounter has its default state, indicating that this is the first |
| 10597 | TPM2_PolicyPCR(). If it has its default value, then policySession→pcrUpdateCounter is set to the |
| 10598 | current value of pcrUpdateCounter. If policySession→pcrUpdateCounter does not have its default |
| 10599 | value and its value is not the same as pcrUpdateCounter, the TPM shall return |
| 10600 | TPM_RC_PCR_CHANGED. |
| 10601 | |
| 10602 | NOTE 1 If this parameter and pcrUpdateCounter are not the same, it indicates that PCR have changed |
| 10603 | since checked by the previous TPM2_PolicyPCR(). Since they have changed, the previous PCR |
| 10604 | validation is no longer valid. |
| 10605 | |
| 10606 | commandLocality – this parameter is the logical AND of all enabled localities. All localities are |
| 10607 | enabled for a policy when the policy session is created. TPM2_PolicyLocalities() selectively |
| 10608 | disables localities. Once use of a policy for a locality has been disabled, it cannot be enabled |
| 10609 | except by TPM2_PolicyRestart(). |
| 10610 | isPPRequired – once SET, this parameter may only be CLEARed by TPM2_PolicyRestart(). |
| 10611 | isAuthValueNeeded – once SET, this parameter may only be CLEARed by |
| 10612 | TPM2_PolicyPassword() or TPM2_PolicyRestart(). |
| 10613 | isPasswordNeeded – once SET, this parameter may only be CLEARed by |
| 10614 | TPM2_PolicyAuthValue() or TPM2_PolicyRestart(), |
| 10615 | |
| 10616 | NOTE 2 Both TPM2_PolicyAuthValue() and TPM2_PolicyPassword() change policySession→policyDigest in |
| 10617 | the same way. The different commands simply indicate to the TPM the format used for the authValue |
| 10618 | (HMAC or clear text). Both commands could be in the same policy. The final instance of these |
| 10619 | commands determines the format. |
| 10620 | |
| 10621 | |
| 10622 | |
| 10623 | |
| 10624 | Page 234 TCG Published Family “2.0” |
| 10625 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 10626 | Trusted Platform Module Library Part 3: Commands |
| 10627 | |
| 10628 | |
| 10629 | 23.2.5 Policy Ticket Creation |
| 10630 | |
| 10631 | If, for TPM2_PolicySigned() or TPM2_PolicySecret(), the caller specified a negative value for expiration, |
| 10632 | and the nonceTPM matches policySession->nonceTPM, then the TPM will return a ticket that includes a |
| 10633 | value indicating when the authorization expires. If expiration is non-negative, then the TPM will return a |
| 10634 | NULL ticket. |
| 10635 | The required computation for the digest in the authorization ticket is: |
| 10636 | HMAC(proof, HpolicyAlg(ticketType || timeout || cpHashA || policyRef || authObject→Name)) (12) |
| 10637 | where |
| 10638 | proof secret associated with the storage primary seed (SPS) of the |
| 10639 | TPM |
| 10640 | HpolicyAlg hash function using the hash algorithm associated with the policy |
| 10641 | session |
| 10642 | ticketType either TPM_ST_AUTH_SECRET or TPM_ST_AUTH_SIGNED, |
| 10643 | used to indicate type of the ticket |
| 10644 | |
| 10645 | NOTE 1 If the ticket is produced by TPM2_PolicySecret () then ticketType is |
| 10646 | TPM_ST_AUTH_SECRET and if produced by TPM2_PolicySigned() then ticketType is |
| 10647 | TPM_ST_AUTH_SIGNED. |
| 10648 | |
| 10649 | |
| 10650 | timeout implementation-specific representation of the expiration time of |
| 10651 | the ticket; required to be the implementation equivalent of |
| 10652 | policySession→startTime plus the absolute value of expiration |
| 10653 | |
| 10654 | NOTE 2 timeout is not the same as expiration. The expiration value in the aHash is a relative time, |
| 10655 | using the creation time of the authorization session (TPM2_StartAuthSession()) as its |
| 10656 | reference. The timeout parameter is an absolute time, using TPM Clock as the reference. |
| 10657 | |
| 10658 | |
| 10659 | cpHashA the command parameter digest for the command being |
| 10660 | authorized; computed using the hash algorithm of the policy |
| 10661 | session |
| 10662 | policyRef the commands that use this function have a policyRef parameter |
| 10663 | and the value of that parameter is used here |
| 10664 | authObject→Name Name associated with the authObject parameter |
| 10665 | |
| 10666 | |
| 10667 | |
| 10668 | |
| 10669 | Family “2.0” TCG Published Page 235 |
| 10670 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 10671 | Part 3: Commands Trusted Platform Module Library |
| 10672 | |
| 10673 | 23.3 TPM2_PolicySigned |
| 10674 | |
| 10675 | 23.3.1 General Description |
| 10676 | |
| 10677 | This command includes a signed authorization in a policy. The command ties the policy to a signing key |
| 10678 | by including the Name of the signing key in the policyDigest |
| 10679 | If policySession is a trial session, the TPM will not check the signature and will update |
| 10680 | policySession→policyDigest as described in 23.2.3 as if a properly signed authorization was received, but |
| 10681 | no ticket will be produced. |
| 10682 | If policySession is not a trial session, the TPM will validate auth and only perform the update if it is a valid |
| 10683 | signature over the fields of the command. |
| 10684 | The authorizing entity will sign a digest of the authorization qualifiers: nonceTPM, expiration, cpHashA, |
| 10685 | and policyRef. The digest is computed as: |
| 10686 | aHash ≔ HauthAlg(nonceTPM || expiration || cpHashA || policyRef) (13) |
| 10687 | where |
| 10688 | HauthAlg() the hash associated with the auth parameter of this command |
| 10689 | |
| 10690 | NOTE 1 Each signature and key combination indicates the scheme and each scheme has an |
| 10691 | associated hash. |
| 10692 | |
| 10693 | |
| 10694 | nonceTPM the nonceTPM parameter from the TPM2_StartAuthSession() |
| 10695 | response. If the authorization is not limited to this session, the |
| 10696 | size of this value is zero. |
| 10697 | |
| 10698 | NOTE 2 This parameter must be present if expiration is non-zero. |
| 10699 | |
| 10700 | |
| 10701 | expiration time limit on authorization set by authorizing object. This 32-bit |
| 10702 | value is set to zero if the expiration time is not being set. |
| 10703 | cpHashA digest of the command parameters for the command being |
| 10704 | approved using the hash algorithm of the policy session. Set to |
| 10705 | an EmptyAuth if the authorization is not limited to a specific |
| 10706 | command. |
| 10707 | |
| 10708 | NOTE 3 This is not the cpHash of this TPM2_PolicySigned() command. |
| 10709 | |
| 10710 | |
| 10711 | policyRef an opaque value determined by the authorizing entity. Set to the |
| 10712 | Empty Buffer if no value is present. |
| 10713 | |
| 10714 | EXAMPLE The computation for an aHash if there are no restrictions is: |
| 10715 | |
| 10716 | |
| 10717 | aHash ≔ HauthAlg(00 00 00 0016) |
| 10718 | which is the hash of an expiration time of zero. |
| 10719 | |
| 10720 | The aHash is signed by the key associated with a key whose handle is authObject. The signature and |
| 10721 | signing parameters are combined to create the auth parameter. |
| 10722 | The TPM will perform the parameter checks listed in 23.2.2 |
| 10723 | If the parameter checks succeed, the TPM will construct a test digest (tHash) over the provided |
| 10724 | parameters using the same formulation as shown in equation (13) above. |
| 10725 | If tHash does not match the digest of the signed aHash, then the authorization fails and the TPM shall |
| 10726 | return TPM_RC_POLICY_FAIL and make no change to policySession→policyDigest. |
| 10727 | |
| 10728 | |
| 10729 | Page 236 TCG Published Family “2.0” |
| 10730 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 10731 | Trusted Platform Module Library Part 3: Commands |
| 10732 | |
| 10733 | When all validations have succeeded, policySession→policyDigest is updated by PolicyUpdate() (see |
| 10734 | 23.2.3). |
| 10735 | PolicyUpdate(TPM_CC_PolicySigned, authObject→Name, policyRef) (14) |
| 10736 | policySession is updated as described in 23.2.4. The TPM will optionally produce a ticket as described in |
| 10737 | 23.2.5. |
| 10738 | Authorization to use authObject is not required. |
| 10739 | |
| 10740 | |
| 10741 | |
| 10742 | |
| 10743 | Family “2.0” TCG Published Page 237 |
| 10744 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 10745 | Part 3: Commands Trusted Platform Module Library |
| 10746 | |
| 10747 | |
| 10748 | |
| 10749 | 23.3.2 Command and Response |
| 10750 | |
| 10751 | Table 113 — TPM2_PolicySigned Command |
| 10752 | Type Name Description |
| 10753 | |
| 10754 | TPM_ST_SESSIONS if an audit, encrypt, or decrypt |
| 10755 | TPMI_ST_COMMAND_TAG tag session is present; otherwise, |
| 10756 | TPM_ST_NO_SESSIONS |
| 10757 | UINT32 commandSize |
| 10758 | TPM_CC commandCode TPM_CC_PolicySigned |
| 10759 | |
| 10760 | handle for a key that will validate the signature |
| 10761 | TPMI_DH_OBJECT authObject |
| 10762 | Auth Index: None |
| 10763 | handle for the policy session being extended |
| 10764 | TPMI_SH_POLICY policySession |
| 10765 | Auth Index: None |
| 10766 | |
| 10767 | the policy nonce for the session |
| 10768 | TPM2B_NONCE nonceTPM |
| 10769 | This can be the Empty Buffer. |
| 10770 | digest of the command parameters to which this |
| 10771 | authorization is limited |
| 10772 | TPM2B_DIGEST cpHashA This is not the cpHash for this command but the cpHash |
| 10773 | for the command to which this policy session will be |
| 10774 | applied. If it is not limited, the parameter will be the |
| 10775 | Empty Buffer. |
| 10776 | a reference to a policy relating to the authorization – |
| 10777 | may be the Empty Buffer |
| 10778 | TPM2B_NONCE policyRef |
| 10779 | Size is limited to be no larger than the nonce size |
| 10780 | supported on the TPM. |
| 10781 | time when authorization will expire, measured in |
| 10782 | seconds from the time that nonceTPM was generated |
| 10783 | INT32 expiration |
| 10784 | If expiration is non-negative, a NULL Ticket is returned. |
| 10785 | See 23.2.5. |
| 10786 | TPMT_SIGNATURE auth signed authorization (not optional) |
| 10787 | |
| 10788 | |
| 10789 | Table 114 — TPM2_PolicySigned Response |
| 10790 | Type Name Description |
| 10791 | |
| 10792 | TPM_ST tag see clause 6 |
| 10793 | UINT32 responseSize |
| 10794 | TPM_RC responseCode |
| 10795 | |
| 10796 | implementation-specific time value, used to indicate to |
| 10797 | the TPM when the ticket expires |
| 10798 | TPM2B_TIMEOUT timeout |
| 10799 | NOTE If policyTicket is a NULL Ticket, then this shall be |
| 10800 | the Empty Buffer. |
| 10801 | |
| 10802 | produced if the command succeeds and expiration in |
| 10803 | TPMT_TK_AUTH policyTicket the command was non-zero; this ticket will use the |
| 10804 | TPMT_ST_AUTH_SIGNED structure tag. See 23.2.5 |
| 10805 | |
| 10806 | |
| 10807 | |
| 10808 | |
| 10809 | Page 238 TCG Published Family “2.0” |
| 10810 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 10811 | Trusted Platform Module Library Part 3: Commands |
| 10812 | |
| 10813 | |
| 10814 | |
| 10815 | 23.3.3 Detailed Actions |
| 10816 | |
| 10817 | 1 #include "InternalRoutines.h" |
| 10818 | 2 #include "Policy_spt_fp.h" |
| 10819 | 3 #include "PolicySigned_fp.h" |
| 10820 | 4 #ifdef TPM_CC_PolicySigned // Conditional expansion of this file |
| 10821 | |
| 10822 | |
| 10823 | Error Returns Meaning |
| 10824 | |
| 10825 | TPM_RC_CPHASH cpHash was previously set to a different value |
| 10826 | TPM_RC_EXPIRED expiration indicates a time in the past or expiration is non-zero but no |
| 10827 | nonceTPM is present |
| 10828 | TPM_RC_HANDLE authObject need to have sensitive portion loaded |
| 10829 | TPM_RC_KEY authObject is not a signing scheme |
| 10830 | TPM_RC_NONCE nonceTPM is not the nonce associated with the policySession |
| 10831 | TPM_RC_SCHEME the signing scheme of auth is not supported by the TPM |
| 10832 | TPM_RC_SIGNATURE the signature is not genuine |
| 10833 | TPM_RC_SIZE input cpHash has wrong size |
| 10834 | TPM_RC_VALUE input policyID or expiration does not match the internal data in policy |
| 10835 | session |
| 10836 | |
| 10837 | 5 TPM_RC |
| 10838 | 6 TPM2_PolicySigned( |
| 10839 | 7 PolicySigned_In *in, // IN: input parameter list |
| 10840 | 8 PolicySigned_Out *out // OUT: output parameter list |
| 10841 | 9 ) |
| 10842 | 10 { |
| 10843 | 11 TPM_RC result = TPM_RC_SUCCESS; |
| 10844 | 12 SESSION *session; |
| 10845 | 13 TPM2B_NAME entityName; |
| 10846 | 14 TPM2B_DIGEST authHash; |
| 10847 | 15 HASH_STATE hashState; |
| 10848 | 16 UINT32 expiration = (in->expiration < 0) |
| 10849 | 17 ? -(in->expiration) : in->expiration; |
| 10850 | 18 UINT64 authTimeout = 0; |
| 10851 | 19 |
| 10852 | 20 // Input Validation |
| 10853 | 21 |
| 10854 | 22 // Set up local pointers |
| 10855 | 23 session = SessionGet(in->policySession); // the session structure |
| 10856 | 24 |
| 10857 | 25 // Only do input validation if this is not a trial policy session |
| 10858 | 26 if(session->attributes.isTrialPolicy == CLEAR) |
| 10859 | 27 { |
| 10860 | 28 if(expiration != 0) |
| 10861 | 29 authTimeout = expiration * 1000 + session->startTime; |
| 10862 | 30 |
| 10863 | 31 result = PolicyParameterChecks(session, authTimeout, |
| 10864 | 32 &in->cpHashA, &in->nonceTPM, |
| 10865 | 33 RC_PolicySigned_nonceTPM, |
| 10866 | 34 RC_PolicySigned_cpHashA, |
| 10867 | 35 RC_PolicySigned_expiration); |
| 10868 | 36 if(result != TPM_RC_SUCCESS) |
| 10869 | 37 return result; |
| 10870 | 38 |
| 10871 | 39 // Re-compute the digest being signed |
| 10872 | 40 /*(See part 3 specification) |
| 10873 | |
| 10874 | Family “2.0” TCG Published Page 239 |
| 10875 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 10876 | Part 3: Commands Trusted Platform Module Library |
| 10877 | |
| 10878 | 41 // The digest is computed as: |
| 10879 | 42 // aHash := hash ( nonceTPM | expiration | cpHashA | policyRef) |
| 10880 | 43 // where: |
| 10881 | 44 // hash() the hash associated with the signed auth |
| 10882 | 45 // nonceTPM the nonceTPM value from the TPM2_StartAuthSession . |
| 10883 | 46 // response If the authorization is not limited to this |
| 10884 | 47 // session, the size of this value is zero. |
| 10885 | 48 // expiration time limit on authorization set by authorizing object. |
| 10886 | 49 // This 32-bit value is set to zero if the expiration |
| 10887 | 50 // time is not being set. |
| 10888 | 51 // cpHashA hash of the command parameters for the command being |
| 10889 | 52 // approved using the hash algorithm of the PSAP session. |
| 10890 | 53 // Set to NULLauth if the authorization is not limited |
| 10891 | 54 // to a specific command. |
| 10892 | 55 // policyRef hash of an opaque value determined by the authorizing |
| 10893 | 56 // object. Set to the NULLdigest if no hash is present. |
| 10894 | 57 */ |
| 10895 | 58 // Start hash |
| 10896 | 59 authHash.t.size = CryptStartHash(CryptGetSignHashAlg(&in->auth), |
| 10897 | 60 &hashState); |
| 10898 | 61 |
| 10899 | 62 // add nonceTPM |
| 10900 | 63 CryptUpdateDigest2B(&hashState, &in->nonceTPM.b); |
| 10901 | 64 |
| 10902 | 65 // add expiration |
| 10903 | 66 CryptUpdateDigestInt(&hashState, sizeof(UINT32), (BYTE*) &in->expiration); |
| 10904 | 67 |
| 10905 | 68 // add cpHashA |
| 10906 | 69 CryptUpdateDigest2B(&hashState, &in->cpHashA.b); |
| 10907 | 70 |
| 10908 | 71 // add policyRef |
| 10909 | 72 CryptUpdateDigest2B(&hashState, &in->policyRef.b); |
| 10910 | 73 |
| 10911 | 74 // Complete digest |
| 10912 | 75 CryptCompleteHash2B(&hashState, &authHash.b); |
| 10913 | 76 |
| 10914 | 77 // Validate Signature. A TPM_RC_SCHEME, TPM_RC_HANDLE or TPM_RC_SIGNATURE |
| 10915 | 78 // error may be returned at this point |
| 10916 | 79 result = CryptVerifySignature(in->authObject, &authHash, &in->auth); |
| 10917 | 80 if(result != TPM_RC_SUCCESS) |
| 10918 | 81 return RcSafeAddToResult(result, RC_PolicySigned_auth); |
| 10919 | 82 } |
| 10920 | 83 // Internal Data Update |
| 10921 | 84 // Need the Name of the signing entity |
| 10922 | 85 entityName.t.size = EntityGetName(in->authObject, &entityName.t.name); |
| 10923 | 86 |
| 10924 | 87 // Update policy with input policyRef and name of auth key |
| 10925 | 88 // These values are updated even if the session is a trial session |
| 10926 | 89 PolicyContextUpdate(TPM_CC_PolicySigned, &entityName, &in->policyRef, |
| 10927 | 90 &in->cpHashA, authTimeout, session); |
| 10928 | 91 |
| 10929 | 92 // Command Output |
| 10930 | 93 |
| 10931 | 94 // Create ticket and timeout buffer if in->expiration < 0 and this is not |
| 10932 | 95 // a trial session. |
| 10933 | 96 // NOTE: PolicyParameterChecks() makes sure that nonceTPM is present |
| 10934 | 97 // when expiration is non-zero. |
| 10935 | 98 if( in->expiration < 0 |
| 10936 | 99 && session->attributes.isTrialPolicy == CLEAR |
| 10937 | 100 ) |
| 10938 | 101 { |
| 10939 | 102 // Generate timeout buffer. The format of output timeout buffer is |
| 10940 | 103 // TPM-specific. |
| 10941 | 104 // Note: can't do a direct copy because the output buffer is a byte |
| 10942 | 105 // array and it may not be aligned to accept a 64-bit value. The method |
| 10943 | 106 // used has the side-effect of making the returned value a big-endian, |
| 10944 | |
| 10945 | Page 240 TCG Published Family “2.0” |
| 10946 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 10947 | Trusted Platform Module Library Part 3: Commands |
| 10948 | |
| 10949 | 107 // 64-bit value that is byte aligned. |
| 10950 | 108 out->timeout.t.size = sizeof(UINT64); |
| 10951 | 109 UINT64_TO_BYTE_ARRAY(authTimeout, out->timeout.t.buffer); |
| 10952 | 110 |
| 10953 | 111 // Compute policy ticket |
| 10954 | 112 TicketComputeAuth(TPM_ST_AUTH_SIGNED, EntityGetHierarchy(in->authObject), |
| 10955 | 113 authTimeout, &in->cpHashA, &in->policyRef, &entityName, |
| 10956 | 114 &out->policyTicket); |
| 10957 | 115 } |
| 10958 | 116 else |
| 10959 | 117 { |
| 10960 | 118 // Generate a null ticket. |
| 10961 | 119 // timeout buffer is null |
| 10962 | 120 out->timeout.t.size = 0; |
| 10963 | 121 |
| 10964 | 122 // auth ticket is null |
| 10965 | 123 out->policyTicket.tag = TPM_ST_AUTH_SIGNED; |
| 10966 | 124 out->policyTicket.hierarchy = TPM_RH_NULL; |
| 10967 | 125 out->policyTicket.digest.t.size = 0; |
| 10968 | 126 } |
| 10969 | 127 |
| 10970 | 128 return TPM_RC_SUCCESS; |
| 10971 | 129 } |
| 10972 | 130 #endif // CC_PolicySigned |
| 10973 | |
| 10974 | |
| 10975 | |
| 10976 | |
| 10977 | Family “2.0” TCG Published Page 241 |
| 10978 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 10979 | Part 3: Commands Trusted Platform Module Library |
| 10980 | |
| 10981 | |
| 10982 | 23.4 TPM2_PolicySecret |
| 10983 | |
| 10984 | 23.4.1 General Description |
| 10985 | |
| 10986 | This command includes a secret-based authorization to a policy. The caller proves knowledge of the |
| 10987 | secret value using an authorization session using the authValue associated with authHandle. A password |
| 10988 | session, an HMAC session, or a policy session containing TPM2_PolicyAuthValue() or |
| 10989 | TPM2_PolicyPassword() will satisfy this requirement. |
| 10990 | If a policy session is used and use of the authValue of authHandle is not required, the TPM will return |
| 10991 | TPM_RC_MODE. |
| 10992 | The secret is the authValue of the entity whose handle is authHandle, which may be any TPM entity with |
| 10993 | a handle and an associated authValue. This includes the reserved handles (for example, Platform, |
| 10994 | Storage, and Endorsement), NV Indexes, and loaded objects. |
| 10995 | |
| 10996 | NOTE 1 The authorization value for a hierarchy cannot be used in this command if the hierarchy is disabled. |
| 10997 | |
| 10998 | If the authorization check fails, then the normal dictionary attack logic is invoked. |
| 10999 | If the authorization provided by the authorization session is valid, the command parameters are checked |
| 11000 | as described in 23.2.2. |
| 11001 | nonceTPM must be present if expiration is non-zero. |
| 11002 | When all validations have succeeded, policySession→policyDigest is updated by PolicyUpdate() (see |
| 11003 | 23.2.3). |
| 11004 | PolicyUpdate(TPM_CC_PolicySecret, authObject→Name, policyRef) (15) |
| 11005 | policySession is updated as described in 23.2.4. The TPM will optionally produce a ticket as described in |
| 11006 | 23.2.5. |
| 11007 | If the session is a trial session, policySession→policyDigest is updated as if the authorization is valid but |
| 11008 | no check is performed. |
| 11009 | |
| 11010 | NOTE 2 If an HMAC is used to convey the authorization, a separate session is needed for the authorization. |
| 11011 | Because the HMAC in that authorization will include a nonce that prevents replay of the |
| 11012 | authorization, the value of the nonceTPM parameter in this command is limited. It is retained mostly |
| 11013 | to provide processing consistency with TPM2_PolicySigned(). |
| 11014 | |
| 11015 | |
| 11016 | |
| 11017 | |
| 11018 | Page 242 TCG Published Family “2.0” |
| 11019 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 11020 | Trusted Platform Module Library Part 3: Commands |
| 11021 | |
| 11022 | |
| 11023 | 23.4.2 Command and Response |
| 11024 | |
| 11025 | Table 115 — TPM2_PolicySecret Command |
| 11026 | Type Name Description |
| 11027 | |
| 11028 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 11029 | UINT32 commandSize |
| 11030 | TPM_CC commandCode TPM_CC_PolicySecret |
| 11031 | |
| 11032 | handle for an entity providing the authorization |
| 11033 | TPMI_DH_ENTITY @authHandle Auth Index: 1 |
| 11034 | Auth Role: USER |
| 11035 | handle for the policy session being extended |
| 11036 | TPMI_SH_POLICY policySession |
| 11037 | Auth Index: None |
| 11038 | |
| 11039 | the policy nonce for the session |
| 11040 | TPM2B_NONCE nonceTPM |
| 11041 | This can be the Empty Buffer. |
| 11042 | digest of the command parameters to which this |
| 11043 | authorization is limited |
| 11044 | TPM2B_DIGEST cpHashA This not the cpHash for this command but the cpHash |
| 11045 | for the command to which this policy session will be |
| 11046 | applied. If it is not limited, the parameter will be the |
| 11047 | Empty Buffer. |
| 11048 | a reference to a policy relating to the authorization – |
| 11049 | may be the Empty Buffer |
| 11050 | TPM2B_NONCE policyRef |
| 11051 | Size is limited to be no larger than the nonce size |
| 11052 | supported on the TPM. |
| 11053 | time when authorization will expire, measured in |
| 11054 | seconds from the time that nonceTPM was generated |
| 11055 | INT32 expiration |
| 11056 | If expiration is non-negative, a NULL Ticket is returned. |
| 11057 | See 23.2.5. |
| 11058 | |
| 11059 | |
| 11060 | Table 116 — TPM2_PolicySecret Response |
| 11061 | Type Name Description |
| 11062 | |
| 11063 | TPM_ST tag see clause 6 |
| 11064 | UINT32 responseSize |
| 11065 | TPM_RC responseCode |
| 11066 | |
| 11067 | implementation-specific time value used to indicate to |
| 11068 | TPM2B_TIMEOUT timeout the TPM when the ticket expires; this ticket will use the |
| 11069 | TPMT_ST_AUTH_SECRET structure tag |
| 11070 | produced if the command succeeds and expiration in |
| 11071 | TPMT_TK_AUTH policyTicket |
| 11072 | the command was non-zero. See 23.2.5 |
| 11073 | |
| 11074 | |
| 11075 | |
| 11076 | |
| 11077 | Family “2.0” TCG Published Page 243 |
| 11078 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 11079 | Part 3: Commands Trusted Platform Module Library |
| 11080 | |
| 11081 | |
| 11082 | |
| 11083 | 23.4.3 Detailed Actions |
| 11084 | |
| 11085 | 1 #include "InternalRoutines.h" |
| 11086 | 2 #include "PolicySecret_fp.h" |
| 11087 | 3 #ifdef TPM_CC_PolicySecret // Conditional expansion of this file |
| 11088 | 4 #include "Policy_spt_fp.h" |
| 11089 | |
| 11090 | |
| 11091 | Error Returns Meaning |
| 11092 | |
| 11093 | TPM_RC_CPHASH cpHash for policy was previously set to a value that is not the same |
| 11094 | as cpHashA |
| 11095 | TPM_RC_EXPIRED expiration indicates a time in the past |
| 11096 | TPM_RC_NONCE nonceTPM does not match the nonce associated with policySession |
| 11097 | TPM_RC_SIZE cpHashA is not the size of a digest for the hash associated with |
| 11098 | policySession |
| 11099 | TPM_RC_VALUE input policyID or expiration does not match the internal data in policy |
| 11100 | session |
| 11101 | |
| 11102 | 5 TPM_RC |
| 11103 | 6 TPM2_PolicySecret( |
| 11104 | 7 PolicySecret_In *in, // IN: input parameter list |
| 11105 | 8 PolicySecret_Out *out // OUT: output parameter list |
| 11106 | 9 ) |
| 11107 | 10 { |
| 11108 | 11 TPM_RC result; |
| 11109 | 12 SESSION *session; |
| 11110 | 13 TPM2B_NAME entityName; |
| 11111 | 14 UINT32 expiration = (in->expiration < 0) |
| 11112 | 15 ? -(in->expiration) : in->expiration; |
| 11113 | 16 UINT64 authTimeout = 0; |
| 11114 | 17 |
| 11115 | 18 // Input Validation |
| 11116 | 19 |
| 11117 | 20 // Get pointer to the session structure |
| 11118 | 21 session = SessionGet(in->policySession); |
| 11119 | 22 |
| 11120 | 23 //Only do input validation if this is not a trial policy session |
| 11121 | 24 if(session->attributes.isTrialPolicy == CLEAR) |
| 11122 | 25 { |
| 11123 | 26 |
| 11124 | 27 if(expiration != 0) |
| 11125 | 28 authTimeout = expiration * 1000 + session->startTime; |
| 11126 | 29 |
| 11127 | 30 result = PolicyParameterChecks(session, authTimeout, |
| 11128 | 31 &in->cpHashA, &in->nonceTPM, |
| 11129 | 32 RC_PolicySecret_nonceTPM, |
| 11130 | 33 RC_PolicySecret_cpHashA, |
| 11131 | 34 RC_PolicySecret_expiration); |
| 11132 | 35 if(result != TPM_RC_SUCCESS) |
| 11133 | 36 return result; |
| 11134 | 37 } |
| 11135 | 38 |
| 11136 | 39 // Internal Data Update |
| 11137 | 40 // Need the name of the authorizing entity |
| 11138 | 41 entityName.t.size = EntityGetName(in->authHandle, &entityName.t.name); |
| 11139 | 42 |
| 11140 | 43 // Update policy context with input policyRef and name of auth key |
| 11141 | 44 // This value is computed even for trial sessions. Possibly update the cpHash |
| 11142 | 45 PolicyContextUpdate(TPM_CC_PolicySecret, &entityName, &in->policyRef, |
| 11143 | 46 &in->cpHashA, authTimeout, session); |
| 11144 | |
| 11145 | Page 244 TCG Published Family “2.0” |
| 11146 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 11147 | Trusted Platform Module Library Part 3: Commands |
| 11148 | |
| 11149 | 47 |
| 11150 | 48 // Command Output |
| 11151 | 49 |
| 11152 | 50 // Create ticket and timeout buffer if in->expiration < 0 and this is not |
| 11153 | 51 // a trial session. |
| 11154 | 52 // NOTE: PolicyParameterChecks() makes sure that nonceTPM is present |
| 11155 | 53 // when expiration is non-zero. |
| 11156 | 54 if( in->expiration < 0 |
| 11157 | 55 && session->attributes.isTrialPolicy == CLEAR |
| 11158 | 56 ) |
| 11159 | 57 { |
| 11160 | 58 // Generate timeout buffer. The format of output timeout buffer is |
| 11161 | 59 // TPM-specific. |
| 11162 | 60 // Note: can't do a direct copy because the output buffer is a byte |
| 11163 | 61 // array and it may not be aligned to accept a 64-bit value. The method |
| 11164 | 62 // used has the side-effect of making the returned value a big-endian, |
| 11165 | 63 // 64-bit value that is byte aligned. |
| 11166 | 64 out->timeout.t.size = sizeof(UINT64); |
| 11167 | 65 UINT64_TO_BYTE_ARRAY(authTimeout, out->timeout.t.buffer); |
| 11168 | 66 |
| 11169 | 67 // Compute policy ticket |
| 11170 | 68 TicketComputeAuth(TPM_ST_AUTH_SECRET, EntityGetHierarchy(in->authHandle), |
| 11171 | 69 authTimeout, &in->cpHashA, &in->policyRef, |
| 11172 | 70 &entityName, &out->policyTicket); |
| 11173 | 71 } |
| 11174 | 72 else |
| 11175 | 73 { |
| 11176 | 74 // timeout buffer is null |
| 11177 | 75 out->timeout.t.size = 0; |
| 11178 | 76 |
| 11179 | 77 // auth ticket is null |
| 11180 | 78 out->policyTicket.tag = TPM_ST_AUTH_SECRET; |
| 11181 | 79 out->policyTicket.hierarchy = TPM_RH_NULL; |
| 11182 | 80 out->policyTicket.digest.t.size = 0; |
| 11183 | 81 } |
| 11184 | 82 |
| 11185 | 83 return TPM_RC_SUCCESS; |
| 11186 | 84 } |
| 11187 | 85 #endif // CC_PolicySecret |
| 11188 | |
| 11189 | |
| 11190 | |
| 11191 | |
| 11192 | Family “2.0” TCG Published Page 245 |
| 11193 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 11194 | Part 3: Commands Trusted Platform Module Library |
| 11195 | |
| 11196 | |
| 11197 | 23.5 TPM2_PolicyTicket |
| 11198 | |
| 11199 | 23.5.1 General Description |
| 11200 | |
| 11201 | This command is similar to TPM2_PolicySigned() except that it takes a ticket instead of a signed |
| 11202 | authorization. The ticket represents a validated authorization that had an expiration time associated with |
| 11203 | it. |
| 11204 | The parameters of this command are checked as described in 23.2.2. |
| 11205 | If the checks succeed, the TPM uses the timeout, cpHashA, policyRef, and authName to construct a |
| 11206 | ticket to compare with the value in ticket. If these tickets match, then the TPM will create a TPM2B_NAME |
| 11207 | (objectName) using authName and update the context of policySession by PolicyUpdate() (see 23.2.3). |
| 11208 | PolicyUpdate(commandCode, authName, policyRef) (16) |
| 11209 | If the structure tag of ticket is TPM_ST_AUTH_SECRET, then commandCode will be |
| 11210 | TPM_CC_PolicySecret. If the structure tag of ticket is TPM_ST_AUTH_SIGNED, then commandCode will |
| 11211 | be TPM_CC_PolicySIgned. |
| 11212 | policySession is updated as described in 23.2.4. |
| 11213 | |
| 11214 | |
| 11215 | |
| 11216 | |
| 11217 | Page 246 TCG Published Family “2.0” |
| 11218 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 11219 | Trusted Platform Module Library Part 3: Commands |
| 11220 | |
| 11221 | |
| 11222 | |
| 11223 | 23.5.2 Command and Response |
| 11224 | |
| 11225 | Table 117 — TPM2_PolicyTicket Command |
| 11226 | Type Name Description |
| 11227 | |
| 11228 | TPM_ST_SESSIONS if an audit or decrypt session is |
| 11229 | TPMI_ST_COMMAND_TAG tag |
| 11230 | present; otherwise, TPM_ST_NO_SESSIONS |
| 11231 | UINT32 commandSize |
| 11232 | TPM_CC commandCode TPM_CC_PolicyTicket |
| 11233 | |
| 11234 | handle for the policy session being extended |
| 11235 | TPMI_SH_POLICY policySession |
| 11236 | Auth Index: None |
| 11237 | |
| 11238 | time when authorization will expire |
| 11239 | TPM2B_TIMEOUT timeout The contents are TPM specific. This shall be the value |
| 11240 | returned when ticket was produced. |
| 11241 | digest of the command parameters to which this |
| 11242 | authorization is limited |
| 11243 | TPM2B_DIGEST cpHashA |
| 11244 | If it is not limited, the parameter will be the Empty |
| 11245 | Buffer. |
| 11246 | reference to a qualifier for the policy – may be the |
| 11247 | TPM2B_NONCE policyRef |
| 11248 | Empty Buffer |
| 11249 | TPM2B_NAME authName name of the object that provided the authorization |
| 11250 | an authorization ticket returned by the TPM in response |
| 11251 | TPMT_TK_AUTH ticket |
| 11252 | to a TPM2_PolicySigned() or TPM2_PolicySecret() |
| 11253 | |
| 11254 | |
| 11255 | Table 118 — TPM2_PolicyTicket Response |
| 11256 | Type Name Description |
| 11257 | |
| 11258 | TPM_ST tag see clause 6 |
| 11259 | UINT32 responseSize |
| 11260 | TPM_RC responseCode |
| 11261 | |
| 11262 | |
| 11263 | |
| 11264 | |
| 11265 | Family “2.0” TCG Published Page 247 |
| 11266 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 11267 | Part 3: Commands Trusted Platform Module Library |
| 11268 | |
| 11269 | |
| 11270 | |
| 11271 | 23.5.3 Detailed Actions |
| 11272 | |
| 11273 | 1 #include "InternalRoutines.h" |
| 11274 | 2 #include "PolicyTicket_fp.h" |
| 11275 | 3 #ifdef TPM_CC_PolicyTicket // Conditional expansion of this file |
| 11276 | 4 #include "Policy_spt_fp.h" |
| 11277 | |
| 11278 | |
| 11279 | Error Returns Meaning |
| 11280 | |
| 11281 | TPM_RC_CPHASH policy's cpHash was previously set to a different value |
| 11282 | TPM_RC_EXPIRED timeout value in the ticket is in the past and the ticket has expired |
| 11283 | TPM_RC_SIZE timeout or cpHash has invalid size for the |
| 11284 | TPM_RC_TICKET ticket is not valid |
| 11285 | |
| 11286 | 5 TPM_RC |
| 11287 | 6 TPM2_PolicyTicket( |
| 11288 | 7 PolicyTicket_In *in // IN: input parameter list |
| 11289 | 8 ) |
| 11290 | 9 { |
| 11291 | 10 TPM_RC result; |
| 11292 | 11 SESSION *session; |
| 11293 | 12 UINT64 timeout; |
| 11294 | 13 TPMT_TK_AUTH ticketToCompare; |
| 11295 | 14 TPM_CC commandCode = TPM_CC_PolicySecret; |
| 11296 | 15 |
| 11297 | 16 // Input Validation |
| 11298 | 17 |
| 11299 | 18 // Get pointer to the session structure |
| 11300 | 19 session = SessionGet(in->policySession); |
| 11301 | 20 |
| 11302 | 21 // NOTE: A trial policy session is not allowed to use this command. |
| 11303 | 22 // A ticket is used in place of a previously given authorization. Since |
| 11304 | 23 // a trial policy doesn't actually authenticate, the validated |
| 11305 | 24 // ticket is not necessary and, in place of using a ticket, one |
| 11306 | 25 // should use the intended authorization for which the ticket |
| 11307 | 26 // would be a substitute. |
| 11308 | 27 if(session->attributes.isTrialPolicy) |
| 11309 | 28 return TPM_RCS_ATTRIBUTES + RC_PolicyTicket_policySession; |
| 11310 | 29 |
| 11311 | 30 // Restore timeout data. The format of timeout buffer is TPM-specific. |
| 11312 | 31 // In this implementation, we simply copy the value of timeout to the |
| 11313 | 32 // buffer. |
| 11314 | 33 if(in->timeout.t.size != sizeof(UINT64)) |
| 11315 | 34 return TPM_RC_SIZE + RC_PolicyTicket_timeout; |
| 11316 | 35 timeout = BYTE_ARRAY_TO_UINT64(in->timeout.t.buffer); |
| 11317 | 36 |
| 11318 | 37 // Do the normal checks on the cpHashA and timeout values |
| 11319 | 38 result = PolicyParameterChecks(session, timeout, |
| 11320 | 39 &in->cpHashA, NULL, |
| 11321 | 40 0, // no bad nonce return |
| 11322 | 41 RC_PolicyTicket_cpHashA, |
| 11323 | 42 RC_PolicyTicket_timeout); |
| 11324 | 43 if(result != TPM_RC_SUCCESS) |
| 11325 | 44 return result; |
| 11326 | 45 |
| 11327 | 46 // Validate Ticket |
| 11328 | 47 // Re-generate policy ticket by input parameters |
| 11329 | 48 TicketComputeAuth(in->ticket.tag, in->ticket.hierarchy, timeout, &in->cpHashA, |
| 11330 | 49 &in->policyRef, &in->authName, &ticketToCompare); |
| 11331 | 50 |
| 11332 | 51 // Compare generated digest with input ticket digest |
| 11333 | |
| 11334 | Page 248 TCG Published Family “2.0” |
| 11335 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 11336 | Trusted Platform Module Library Part 3: Commands |
| 11337 | |
| 11338 | 52 if(!Memory2BEqual(&in->ticket.digest.b, &ticketToCompare.digest.b)) |
| 11339 | 53 return TPM_RC_TICKET + RC_PolicyTicket_ticket; |
| 11340 | 54 |
| 11341 | 55 // Internal Data Update |
| 11342 | 56 |
| 11343 | 57 // Is this ticket to take the place of a TPM2_PolicySigned() or |
| 11344 | 58 // a TPM2_PolicySecret()? |
| 11345 | 59 if(in->ticket.tag == TPM_ST_AUTH_SIGNED) |
| 11346 | 60 commandCode = TPM_CC_PolicySigned; |
| 11347 | 61 else if(in->ticket.tag == TPM_ST_AUTH_SECRET) |
| 11348 | 62 commandCode = TPM_CC_PolicySecret; |
| 11349 | 63 else |
| 11350 | 64 // There could only be two possible tag values. Any other value should |
| 11351 | 65 // be caught by the ticket validation process. |
| 11352 | 66 pAssert(FALSE); |
| 11353 | 67 |
| 11354 | 68 // Update policy context |
| 11355 | 69 PolicyContextUpdate(commandCode, &in->authName, &in->policyRef, |
| 11356 | 70 &in->cpHashA, timeout, session); |
| 11357 | 71 |
| 11358 | 72 return TPM_RC_SUCCESS; |
| 11359 | 73 } |
| 11360 | 74 #endif // CC_PolicyTicket |
| 11361 | |
| 11362 | |
| 11363 | |
| 11364 | |
| 11365 | Family “2.0” TCG Published Page 249 |
| 11366 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 11367 | Part 3: Commands Trusted Platform Module Library |
| 11368 | |
| 11369 | |
| 11370 | 23.6 TPM2_PolicyOR |
| 11371 | |
| 11372 | 23.6.1 General Description |
| 11373 | |
| 11374 | This command allows options in authorizations without requiring that the TPM evaluate all of the options. |
| 11375 | If a policy may be satisfied by different sets of conditions, the TPM need only evaluate one set that |
| 11376 | satisfies the policy. This command will indicate that one of the required sets of conditions has been |
| 11377 | satisfied. |
| 11378 | PolicySession→policyDigest is compared against the list of provided values. If the current |
| 11379 | policySession→policyDigest does not match any value in the list, the TPM shall return TPM_RC_VALUE. |
| 11380 | Otherwise, it will replace policySession→policyDigest with the digest of the concatenation of all of the |
| 11381 | digests and return TPM_RC_SUCCESS. |
| 11382 | If policySession is a trial session, the TPM will assume that policySession→policyDigest matches one of |
| 11383 | the list entries and compute the new value of policyDigest. |
| 11384 | The algorithm for computing the new value for policyDigest of policySession is: |
| 11385 | a) Concatenate all the digest values in pHashList: |
| 11386 | digests ≔ pHashList.digests[1].buffer || … || pHashList.digests[n].buffer (17) |
| 11387 | |
| 11388 | NOTE 1 The TPM will not return an error if the size of an entry is not the same as the size of the digest |
| 11389 | of the policy. However, that entry cannot match policyDigest. |
| 11390 | |
| 11391 | b) Reset policyDigest to a Zero Digest. |
| 11392 | c) Extend the command code and the hashes computed in step a) above: |
| 11393 | policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyOR || digests) (18) |
| 11394 | |
| 11395 | NOTE 2 The computation in b) and c) above is equivalent to: |
| 11396 | policyDigestnew ≔ HpolicyAlg(0…0 || TPM_CC_PolicyOR || digests) |
| 11397 | |
| 11398 | A TPM shall support a list with at least eight tagged digest values. |
| 11399 | |
| 11400 | NOTE 3 If policies are to be portable between TPMs, then they should not use more than eight values. |
| 11401 | |
| 11402 | |
| 11403 | |
| 11404 | |
| 11405 | Page 250 TCG Published Family “2.0” |
| 11406 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 11407 | Trusted Platform Module Library Part 3: Commands |
| 11408 | |
| 11409 | |
| 11410 | 23.6.2 Command and Response |
| 11411 | |
| 11412 | Table 119 — TPM2_PolicyOR Command |
| 11413 | Type Name Description |
| 11414 | |
| 11415 | TPM_ST_SESSIONS if an audit session is present; |
| 11416 | TPMI_ST_COMMAND_TAG tag |
| 11417 | otherwise, TPM_ST_NO_SESSIONS |
| 11418 | UINT32 commandSize |
| 11419 | TPM_CC commandCode TPM_CC_PolicyOR. |
| 11420 | |
| 11421 | handle for the policy session being extended |
| 11422 | TPMI_SH_POLICY policySession |
| 11423 | Auth Index: None |
| 11424 | |
| 11425 | TPML_DIGEST pHashList the list of hashes to check for a match |
| 11426 | |
| 11427 | |
| 11428 | Table 120 — TPM2_PolicyOR Response |
| 11429 | Type Name Description |
| 11430 | |
| 11431 | TPM_ST tag see clause 6 |
| 11432 | UINT32 responseSize |
| 11433 | TPM_RC responseCode |
| 11434 | |
| 11435 | |
| 11436 | |
| 11437 | |
| 11438 | Family “2.0” TCG Published Page 251 |
| 11439 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 11440 | Part 3: Commands Trusted Platform Module Library |
| 11441 | |
| 11442 | |
| 11443 | |
| 11444 | 23.6.3 Detailed Actions |
| 11445 | |
| 11446 | 1 #include "InternalRoutines.h" |
| 11447 | 2 #include "PolicyOR_fp.h" |
| 11448 | 3 #ifdef TPM_CC_PolicyOR // Conditional expansion of this file |
| 11449 | 4 #include "Policy_spt_fp.h" |
| 11450 | |
| 11451 | |
| 11452 | Error Returns Meaning |
| 11453 | |
| 11454 | TPM_RC_VALUE no digest in pHashList matched the current value of policyDigest for |
| 11455 | policySession |
| 11456 | |
| 11457 | 5 TPM_RC |
| 11458 | 6 TPM2_PolicyOR( |
| 11459 | 7 PolicyOR_In *in // IN: input parameter list |
| 11460 | 8 ) |
| 11461 | 9 { |
| 11462 | 10 SESSION *session; |
| 11463 | 11 UINT32 i; |
| 11464 | 12 |
| 11465 | 13 // Input Validation and Update |
| 11466 | 14 |
| 11467 | 15 // Get pointer to the session structure |
| 11468 | 16 session = SessionGet(in->policySession); |
| 11469 | 17 |
| 11470 | 18 // Compare and Update Internal Session policy if match |
| 11471 | 19 for(i = 0; i < in->pHashList.count; i++) |
| 11472 | 20 { |
| 11473 | 21 if( session->attributes.isTrialPolicy == SET |
| 11474 | 22 || (Memory2BEqual(&session->u2.policyDigest.b, |
| 11475 | 23 &in->pHashList.digests[i].b)) |
| 11476 | 24 ) |
| 11477 | 25 { |
| 11478 | 26 // Found a match |
| 11479 | 27 HASH_STATE hashState; |
| 11480 | 28 TPM_CC commandCode = TPM_CC_PolicyOR; |
| 11481 | 29 |
| 11482 | 30 // Start hash |
| 11483 | 31 session->u2.policyDigest.t.size = CryptStartHash(session->authHashAlg, |
| 11484 | 32 &hashState); |
| 11485 | 33 // Set policyDigest to 0 string and add it to hash |
| 11486 | 34 MemorySet(session->u2.policyDigest.t.buffer, 0, |
| 11487 | 35 session->u2.policyDigest.t.size); |
| 11488 | 36 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); |
| 11489 | 37 |
| 11490 | 38 // add command code |
| 11491 | 39 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); |
| 11492 | 40 |
| 11493 | 41 // Add each of the hashes in the list |
| 11494 | 42 for(i = 0; i < in->pHashList.count; i++) |
| 11495 | 43 { |
| 11496 | 44 // Extend policyDigest |
| 11497 | 45 CryptUpdateDigest2B(&hashState, &in->pHashList.digests[i].b); |
| 11498 | 46 } |
| 11499 | 47 // Complete digest |
| 11500 | 48 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); |
| 11501 | 49 |
| 11502 | 50 return TPM_RC_SUCCESS; |
| 11503 | 51 } |
| 11504 | 52 } |
| 11505 | 53 // None of the values in the list matched the current policyDigest |
| 11506 | 54 return TPM_RC_VALUE + RC_PolicyOR_pHashList; |
| 11507 | 55 } |
| 11508 | |
| 11509 | Page 252 TCG Published Family “2.0” |
| 11510 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 11511 | Trusted Platform Module Library Part 3: Commands |
| 11512 | |
| 11513 | 56 #endif // CC_PolicyOR |
| 11514 | |
| 11515 | |
| 11516 | |
| 11517 | |
| 11518 | Family “2.0” TCG Published Page 253 |
| 11519 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 11520 | Part 3: Commands Trusted Platform Module Library |
| 11521 | |
| 11522 | |
| 11523 | 23.7 TPM2_PolicyPCR |
| 11524 | |
| 11525 | 23.7.1 General Description |
| 11526 | |
| 11527 | This command is used to cause conditional gating of a policy based on PCR. This command together |
| 11528 | with TPM2_PolicyOR() allows one group of authorizations to occur when PCR are in one state and a |
| 11529 | different set of authorizations when the PCR are in a different state. If this command is used for a trial |
| 11530 | policySession, policySession→policyDigest will be updated using the values from the command rather |
| 11531 | than the values from digest of the TPM PCR. |
| 11532 | The TPM will modify the pcrs parameter so that bits that correspond to unimplemented PCR are CLEAR. |
| 11533 | If policySession is not a trial policy session, the TPM will use the modified value of pcrs to select PCR |
| 11534 | values to hash according to TPM 2.0 Part 1, Selecting Multiple PCR. The hash algorithm of the policy |
| 11535 | session is used to compute a digest (digestTPM) of the selected PCR. If pcrDigest does not have a length |
| 11536 | of zero, then it is compared to digestTPM; and if the values do not match, the TPM shall return |
| 11537 | TPM_RC_VALUE and make no change to policySession→policyDigest. If the values match, or if the |
| 11538 | length of pcrDigest is zero, then policySession→policyDigest is extended by: |
| 11539 | policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyPCR || pcrs || digestTPM) (19) |
| 11540 | where |
| 11541 | pcrs the pcrs parameter with bits corresponding to unimplemented |
| 11542 | PCR set to 0 |
| 11543 | digestTPM the digest of the selected PCR using the hash algorithm of the |
| 11544 | policy session |
| 11545 | |
| 11546 | NOTE 1 If the caller provides the expected PCR value, the intention is that the policy evaluation stop at that |
| 11547 | point if the PCR do not match. If the caller does not provide the expected PCR value, then the |
| 11548 | validity of the settings will not be determined until an attempt is made to use the policy for |
| 11549 | authorization. If the policy is constructed such that the PCR check comes before user authorization |
| 11550 | checks, this early termination would allow software to avoid unnecessary prompts for user input to |
| 11551 | satisfy a policy that would fail later due to incorrect PCR values. |
| 11552 | |
| 11553 | After this command completes successfully, the TPM shall return TPM_RC_PCR_CHANGED if the policy |
| 11554 | session is used for authorization and the PCR are not known to be correct. |
| 11555 | The TPM uses a “generation” number (pcrUpdateCounter) that is incremented each time PCR are |
| 11556 | updated (unless the PCR being changed is specified not to cause a change to this counter). The value of |
| 11557 | this counter is stored in the policy session context (policySession→pcrUpdateCounter) when this |
| 11558 | command is executed. When the policy is used for authorization, the current value of the counter is |
| 11559 | compared to the value in the policy session context and the authorization will fail if the values are not the |
| 11560 | same. |
| 11561 | When this command is executed, policySession→pcrUpdateCounter is checked to see if it has been |
| 11562 | previously set (in the reference implementation, it has a value of zero if not previously set). If it has been |
| 11563 | set, it will be compared with the current value of pcrUpdateCounter to determine if any PCR changes |
| 11564 | have occurred. If the values are different, the TPM shall return TPM_RC_PCR_CHANGED. |
| 11565 | |
| 11566 | NOTE 2 Since the pcrUpdateCounter is updated if any PCR is extended (except those specified not to do |
| 11567 | so), this means that the command will fail even if a PCR not specified in the policy is updated. This |
| 11568 | is an optimization for the purposes of conserving internal TPM memory. This would be a rare |
| 11569 | occurrence. and, if this should occur, the policy could be reset using the TPM2_PolicyRestart |
| 11570 | command and rerun. |
| 11571 | |
| 11572 | If policySession→pcrUpdateCounter has not been set, then it is set to the current value of |
| 11573 | pcrUpdateCounter. |
| 11574 | |
| 11575 | |
| 11576 | |
| 11577 | |
| 11578 | Page 254 TCG Published Family “2.0” |
| 11579 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 11580 | Trusted Platform Module Library Part 3: Commands |
| 11581 | |
| 11582 | If policySession is a trial policy session, the TPM will not check any PCR and will compute: |
| 11583 | policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyPCR || pcrs || pcrDigest) (20) |
| 11584 | In this computation, pcrs is the input parameter without modification. |
| 11585 | |
| 11586 | NOTE 3 The pcrs parameter is expected to match the configuration of the TPM for which the policy is being |
| 11587 | computed which may not be the same as the TPM on which the trial policy is being computed. |
| 11588 | |
| 11589 | NOTE 4 Although no PCR are checked in a trial policy session, pcrDigest is expected to correspond to some |
| 11590 | useful PCR values. It is legal, but pointless, to have the TP M aid in calculating a policyDigest |
| 11591 | corresponding to PCR values that are not useful in practice. |
| 11592 | |
| 11593 | |
| 11594 | |
| 11595 | |
| 11596 | Family “2.0” TCG Published Page 255 |
| 11597 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 11598 | Part 3: Commands Trusted Platform Module Library |
| 11599 | |
| 11600 | |
| 11601 | 23.7.2 Command and Response |
| 11602 | |
| 11603 | Table 121 — TPM2_PolicyPCR Command |
| 11604 | Type Name Description |
| 11605 | |
| 11606 | TPM_ST_SESSIONS if an audit or decrypt session is |
| 11607 | TPMI_ST_COMMAND_TAG tag |
| 11608 | present; otherwise, TPM_ST_NO_SESSIONS |
| 11609 | UINT32 commandSize |
| 11610 | TPM_CC commandCode TPM_CC_PolicyPCR |
| 11611 | |
| 11612 | handle for the policy session being extended |
| 11613 | TPMI_SH_POLICY policySession |
| 11614 | Auth Index: None |
| 11615 | |
| 11616 | expected digest value of the selected PCR using the |
| 11617 | TPM2B_DIGEST pcrDigest |
| 11618 | hash algorithm of the session; may be zero length |
| 11619 | TPML_PCR_SELECTION pcrs the PCR to include in the check digest |
| 11620 | |
| 11621 | |
| 11622 | Table 122 — TPM2_PolicyPCR Response |
| 11623 | Type Name Description |
| 11624 | |
| 11625 | TPM_ST tag see clause 6 |
| 11626 | UINT32 responseSize |
| 11627 | TPM_RC responseCode |
| 11628 | |
| 11629 | |
| 11630 | |
| 11631 | |
| 11632 | Page 256 TCG Published Family “2.0” |
| 11633 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 11634 | Trusted Platform Module Library Part 3: Commands |
| 11635 | |
| 11636 | |
| 11637 | |
| 11638 | 23.7.3 Detailed Actions |
| 11639 | |
| 11640 | 1 #include "InternalRoutines.h" |
| 11641 | 2 #include "PolicyPCR_fp.h" |
| 11642 | 3 #ifdef TPM_CC_PolicyPCR // Conditional expansion of this file |
| 11643 | |
| 11644 | |
| 11645 | Error Returns Meaning |
| 11646 | |
| 11647 | TPM_RC_VALUE if provided, pcrDigest does not match the current PCR settings |
| 11648 | TPM_RC_PCR_CHANGED a previous TPM2_PolicyPCR() set pcrCounter and it has changed |
| 11649 | |
| 11650 | 4 TPM_RC |
| 11651 | 5 TPM2_PolicyPCR( |
| 11652 | 6 PolicyPCR_In *in // IN: input parameter list |
| 11653 | 7 ) |
| 11654 | 8 { |
| 11655 | 9 SESSION *session; |
| 11656 | 10 TPM2B_DIGEST pcrDigest; |
| 11657 | 11 BYTE pcrs[sizeof(TPML_PCR_SELECTION)]; |
| 11658 | 12 UINT32 pcrSize; |
| 11659 | 13 BYTE *buffer; |
| 11660 | 14 TPM_CC commandCode = TPM_CC_PolicyPCR; |
| 11661 | 15 HASH_STATE hashState; |
| 11662 | 16 |
| 11663 | 17 // Input Validation |
| 11664 | 18 |
| 11665 | 19 // Get pointer to the session structure |
| 11666 | 20 session = SessionGet(in->policySession); |
| 11667 | 21 |
| 11668 | 22 // Do validation for non trial session |
| 11669 | 23 if(session->attributes.isTrialPolicy == CLEAR) |
| 11670 | 24 { |
| 11671 | 25 // Make sure that this is not going to invalidate a previous PCR check |
| 11672 | 26 if(session->pcrCounter != 0 && session->pcrCounter != gr.pcrCounter) |
| 11673 | 27 return TPM_RC_PCR_CHANGED; |
| 11674 | 28 |
| 11675 | 29 // Compute current PCR digest |
| 11676 | 30 PCRComputeCurrentDigest(session->authHashAlg, &in->pcrs, &pcrDigest); |
| 11677 | 31 |
| 11678 | 32 // If the caller specified the PCR digest and it does not |
| 11679 | 33 // match the current PCR settings, return an error.. |
| 11680 | 34 if(in->pcrDigest.t.size != 0) |
| 11681 | 35 { |
| 11682 | 36 if(!Memory2BEqual(&in->pcrDigest.b, &pcrDigest.b)) |
| 11683 | 37 return TPM_RC_VALUE + RC_PolicyPCR_pcrDigest; |
| 11684 | 38 } |
| 11685 | 39 } |
| 11686 | 40 else |
| 11687 | 41 { |
| 11688 | 42 // For trial session, just use the input PCR digest |
| 11689 | 43 pcrDigest = in->pcrDigest; |
| 11690 | 44 } |
| 11691 | 45 // Internal Data Update |
| 11692 | 46 |
| 11693 | 47 // Update policy hash |
| 11694 | 48 // policyDigestnew = hash( policyDigestold || TPM_CC_PolicyPCR |
| 11695 | 49 // || pcrs || pcrDigest) |
| 11696 | 50 // Start hash |
| 11697 | 51 CryptStartHash(session->authHashAlg, &hashState); |
| 11698 | 52 |
| 11699 | 53 // add old digest |
| 11700 | 54 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); |
| 11701 | |
| 11702 | Family “2.0” TCG Published Page 257 |
| 11703 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 11704 | Part 3: Commands Trusted Platform Module Library |
| 11705 | |
| 11706 | 55 |
| 11707 | 56 // add commandCode |
| 11708 | 57 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); |
| 11709 | 58 |
| 11710 | 59 // add PCRS |
| 11711 | 60 buffer = pcrs; |
| 11712 | 61 pcrSize = TPML_PCR_SELECTION_Marshal(&in->pcrs, &buffer, NULL); |
| 11713 | 62 CryptUpdateDigest(&hashState, pcrSize, pcrs); |
| 11714 | 63 |
| 11715 | 64 // add PCR digest |
| 11716 | 65 CryptUpdateDigest2B(&hashState, &pcrDigest.b); |
| 11717 | 66 |
| 11718 | 67 // complete the hash and get the results |
| 11719 | 68 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); |
| 11720 | 69 |
| 11721 | 70 // update pcrCounter in session context for non trial session |
| 11722 | 71 if(session->attributes.isTrialPolicy == CLEAR) |
| 11723 | 72 { |
| 11724 | 73 session->pcrCounter = gr.pcrCounter; |
| 11725 | 74 } |
| 11726 | 75 |
| 11727 | 76 return TPM_RC_SUCCESS; |
| 11728 | 77 } |
| 11729 | 78 #endif // CC_PolicyPCR |
| 11730 | |
| 11731 | |
| 11732 | |
| 11733 | |
| 11734 | Page 258 TCG Published Family “2.0” |
| 11735 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 11736 | Trusted Platform Module Library Part 3: Commands |
| 11737 | |
| 11738 | |
| 11739 | 23.8 TPM2_PolicyLocality |
| 11740 | |
| 11741 | 23.8.1 General Description |
| 11742 | |
| 11743 | This command indicates that the authorization will be limited to a specific locality. |
| 11744 | policySession→commandLocality is a parameter kept in the session context. When the policy session is |
| 11745 | started, this parameter is initialized to a value that allows the policy to apply to any locality. |
| 11746 | If locality has a value greater than 31, then an extended locality is indicated. For an extended locality, the |
| 11747 | TPM will validate that policySession→commandLocality has not previously been set or that the current |
| 11748 | value of policySession→commandLocality is the same as locality (TPM_RC_RANGE). |
| 11749 | When locality is not an extended locality, the TPM will validate that the policySession→commandLocality |
| 11750 | is not set to an extended locality value (TPM_RC_RANGE). If not the TPM will disable any locality not |
| 11751 | SET in the locality parameter. If the result of disabling localities results in no locality being enabled, the |
| 11752 | TPM will return TPM_RC_RANGE. |
| 11753 | If no error occurred in the validation of locality, policySession→policyDigest is extended with |
| 11754 | policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyLocality || locality) (21) |
| 11755 | Then policySession→commandLocality is updated to indicate which localities are still allowed after |
| 11756 | execution of TPM2_PolicyLocality(). |
| 11757 | When the policy session is used to authorize a command, the authorization will fail if the locality used for |
| 11758 | the command is not one of the enabled localities in policySession→commandLocality. |
| 11759 | |
| 11760 | |
| 11761 | |
| 11762 | |
| 11763 | Family “2.0” TCG Published Page 259 |
| 11764 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 11765 | Part 3: Commands Trusted Platform Module Library |
| 11766 | |
| 11767 | |
| 11768 | |
| 11769 | 23.8.2 Command and Response |
| 11770 | |
| 11771 | Table 123 — TPM2_PolicyLocality Command |
| 11772 | Type Name Description |
| 11773 | |
| 11774 | TPM_ST_SESSIONS if an audit session is present; |
| 11775 | TPMI_ST_COMMAND_TAG tag |
| 11776 | otherwise, TPM_ST_NO_SESSIONS |
| 11777 | UINT32 commandSize |
| 11778 | TPM_CC commandCode TPM_CC_PolicyLocality |
| 11779 | |
| 11780 | handle for the policy session being extended |
| 11781 | TPMI_SH_POLICY policySession |
| 11782 | Auth Index: None |
| 11783 | |
| 11784 | TPMA_LOCALITY locality the allowed localities for the policy |
| 11785 | |
| 11786 | |
| 11787 | Table 124 — TPM2_PolicyLocality Response |
| 11788 | Type Name Description |
| 11789 | |
| 11790 | TPM_ST tag see clause 6 |
| 11791 | UINT32 responseSize |
| 11792 | TPM_RC responseCode |
| 11793 | |
| 11794 | |
| 11795 | |
| 11796 | |
| 11797 | Page 260 TCG Published Family “2.0” |
| 11798 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 11799 | Trusted Platform Module Library Part 3: Commands |
| 11800 | |
| 11801 | |
| 11802 | |
| 11803 | 23.8.3 Detailed Actions |
| 11804 | |
| 11805 | 1 #include "InternalRoutines.h" |
| 11806 | 2 #include "PolicyLocality_fp.h" |
| 11807 | 3 #ifdef TPM_CC_PolicyLocality // Conditional expansion of this file |
| 11808 | |
| 11809 | Limit a policy to a specific locality |
| 11810 | |
| 11811 | Error Returns Meaning |
| 11812 | |
| 11813 | TPM_RC_RANGE all the locality values selected by locality have been disabled by |
| 11814 | previous TPM2_PolicyLocality() calls. |
| 11815 | |
| 11816 | 4 TPM_RC |
| 11817 | 5 TPM2_PolicyLocality( |
| 11818 | 6 PolicyLocality_In *in // IN: input parameter list |
| 11819 | 7 ) |
| 11820 | 8 { |
| 11821 | 9 SESSION *session; |
| 11822 | 10 BYTE marshalBuffer[sizeof(TPMA_LOCALITY)]; |
| 11823 | 11 BYTE prevSetting[sizeof(TPMA_LOCALITY)]; |
| 11824 | 12 UINT32 marshalSize; |
| 11825 | 13 BYTE *buffer; |
| 11826 | 14 TPM_CC commandCode = TPM_CC_PolicyLocality; |
| 11827 | 15 HASH_STATE hashState; |
| 11828 | 16 |
| 11829 | 17 // Input Validation |
| 11830 | 18 |
| 11831 | 19 // Get pointer to the session structure |
| 11832 | 20 session = SessionGet(in->policySession); |
| 11833 | 21 |
| 11834 | 22 // Get new locality setting in canonical form |
| 11835 | 23 buffer = marshalBuffer; |
| 11836 | 24 marshalSize = TPMA_LOCALITY_Marshal(&in->locality, &buffer, NULL); |
| 11837 | 25 |
| 11838 | 26 // Its an error if the locality parameter is zero |
| 11839 | 27 if(marshalBuffer[0] == 0) |
| 11840 | 28 return TPM_RC_RANGE + RC_PolicyLocality_locality; |
| 11841 | 29 |
| 11842 | 30 // Get existing locality setting in canonical form |
| 11843 | 31 buffer = prevSetting; |
| 11844 | 32 TPMA_LOCALITY_Marshal(&session->commandLocality, &buffer, NULL); |
| 11845 | 33 |
| 11846 | 34 // If the locality has previously been set |
| 11847 | 35 if( prevSetting[0] != 0 |
| 11848 | 36 // then the current locality setting and the requested have to be the same |
| 11849 | 37 // type (that is, either both normal or both extended |
| 11850 | 38 && ((prevSetting[0] < 32) != (marshalBuffer[0] < 32))) |
| 11851 | 39 return TPM_RC_RANGE + RC_PolicyLocality_locality; |
| 11852 | 40 |
| 11853 | 41 // See if the input is a regular or extended locality |
| 11854 | 42 if(marshalBuffer[0] < 32) |
| 11855 | 43 { |
| 11856 | 44 // if there was no previous setting, start with all normal localities |
| 11857 | 45 // enabled |
| 11858 | 46 if(prevSetting[0] == 0) |
| 11859 | 47 prevSetting[0] = 0x1F; |
| 11860 | 48 |
| 11861 | 49 // AND the new setting with the previous setting and store it in prevSetting |
| 11862 | 50 prevSetting[0] &= marshalBuffer[0]; |
| 11863 | 51 |
| 11864 | 52 // The result setting can not be 0 |
| 11865 | 53 if(prevSetting[0] == 0) |
| 11866 | |
| 11867 | Family “2.0” TCG Published Page 261 |
| 11868 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 11869 | Part 3: Commands Trusted Platform Module Library |
| 11870 | |
| 11871 | 54 return TPM_RC_RANGE + RC_PolicyLocality_locality; |
| 11872 | 55 } |
| 11873 | 56 else |
| 11874 | 57 { |
| 11875 | 58 // for extended locality |
| 11876 | 59 // if the locality has already been set, then it must match the |
| 11877 | 60 if(prevSetting[0] != 0 && prevSetting[0] != marshalBuffer[0]) |
| 11878 | 61 return TPM_RC_RANGE + RC_PolicyLocality_locality; |
| 11879 | 62 |
| 11880 | 63 // Setting is OK |
| 11881 | 64 prevSetting[0] = marshalBuffer[0]; |
| 11882 | 65 |
| 11883 | 66 } |
| 11884 | 67 |
| 11885 | 68 // Internal Data Update |
| 11886 | 69 |
| 11887 | 70 // Update policy hash |
| 11888 | 71 // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyLocality || locality) |
| 11889 | 72 // Start hash |
| 11890 | 73 CryptStartHash(session->authHashAlg, &hashState); |
| 11891 | 74 |
| 11892 | 75 // add old digest |
| 11893 | 76 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); |
| 11894 | 77 |
| 11895 | 78 // add commandCode |
| 11896 | 79 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); |
| 11897 | 80 |
| 11898 | 81 // add input locality |
| 11899 | 82 CryptUpdateDigest(&hashState, marshalSize, marshalBuffer); |
| 11900 | 83 |
| 11901 | 84 // complete the digest |
| 11902 | 85 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); |
| 11903 | 86 |
| 11904 | 87 // update session locality by unmarshal function. The function must succeed |
| 11905 | 88 // because both input and existing locality setting have been validated. |
| 11906 | 89 buffer = prevSetting; |
| 11907 | 90 TPMA_LOCALITY_Unmarshal(&session->commandLocality, &buffer, |
| 11908 | 91 (INT32 *) &marshalSize); |
| 11909 | 92 |
| 11910 | 93 return TPM_RC_SUCCESS; |
| 11911 | 94 } |
| 11912 | 95 #endif // CC_PolicyLocality |
| 11913 | |
| 11914 | |
| 11915 | |
| 11916 | |
| 11917 | Page 262 TCG Published Family “2.0” |
| 11918 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 11919 | Trusted Platform Module Library Part 3: Commands |
| 11920 | |
| 11921 | |
| 11922 | 23.9 TPM2_PolicyNV |
| 11923 | |
| 11924 | 23.9.1 General Description |
| 11925 | |
| 11926 | This command is used to cause conditional gating of a policy based on the contents of an NV Index. |
| 11927 | If policySession is a trial policy session, the TPM will update policySession→policyDigest as shown in |
| 11928 | equations (22) and (23) below and return TPM_RC_SUCCESS. It will not perform any validation. The |
| 11929 | remainder of this general description would apply only if policySession is not a trial policy session. |
| 11930 | An authorization session providing authorization to read the NV Index shall be provided. |
| 11931 | |
| 11932 | NOTE If read access is controlled by policy, the policy should include a branch that authorizes a |
| 11933 | TPM2_PolicyNV(). |
| 11934 | |
| 11935 | If TPMA_NV_WRITTEN is not SET in the NV Index, the TPM shall return TPM_RC_NV_UNINITIALIZED. |
| 11936 | The TPM will validate that the size of operandB plus offset is not greater than the size of the NV Index. If |
| 11937 | it is, the TPM shall return TPM_RC_SIZE. |
| 11938 | operandA begins at offest into the NV index contents and has a size equal to the size of operandB. The |
| 11939 | TPM will perform the indicated arithmetic check using operandA and operandB. . If the check fails, the |
| 11940 | TPM shall return TPM_RC_POLICY and not change policySession→policyDigest. If the check succeeds, |
| 11941 | the TPM will hash the arguments: |
| 11942 | args ≔ HpolicyAlg(operandB.buffer || offset || operation) (22) |
| 11943 | where |
| 11944 | HpolicyAlg() hash function using the algorithm of the policy session |
| 11945 | operandB the value used for the comparison |
| 11946 | offset offset from the start of the NV Index data to start the comparison |
| 11947 | operation the operation parameter indicating the comparison being |
| 11948 | performed |
| 11949 | |
| 11950 | |
| 11951 | The value of args and the Name of the NV Index are extended to policySession→policyDigest by |
| 11952 | policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyNV || args || nvIndex→Name) (23) |
| 11953 | where |
| 11954 | HpolicyAlg() hash function using the algorithm of the policy session |
| 11955 | args value computed in equation (22) |
| 11956 | nvIndex→Name the Name of the NV Index |
| 11957 | |
| 11958 | |
| 11959 | The signed arithmetic operations are performed using twos-compliment. |
| 11960 | Magnitude comparisons assume that the octet at offset zero in the referenced NV location and in |
| 11961 | operandB contain the most significant octet of the data. |
| 11962 | |
| 11963 | |
| 11964 | |
| 11965 | |
| 11966 | Family “2.0” TCG Published Page 263 |
| 11967 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 11968 | Part 3: Commands Trusted Platform Module Library |
| 11969 | |
| 11970 | |
| 11971 | |
| 11972 | 23.9.2 Command and Response |
| 11973 | |
| 11974 | Table 125 — TPM2_PolicyNV Command |
| 11975 | Type Name Description |
| 11976 | |
| 11977 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 11978 | UINT32 commandSize |
| 11979 | TPM_CC commandCode TPM_CC_PolicyNV |
| 11980 | |
| 11981 | handle indicating the source of the authorization value |
| 11982 | TPMI_RH_NV_AUTH @authHandle Auth Index: 1 |
| 11983 | Auth Role: USER |
| 11984 | the NV Index of the area to read |
| 11985 | TPMI_RH_NV_INDEX nvIndex |
| 11986 | Auth Index: None |
| 11987 | handle for the policy session being extended |
| 11988 | TPMI_SH_POLICY policySession |
| 11989 | Auth Index: None |
| 11990 | |
| 11991 | TPM2B_OPERAND operandB the second operand |
| 11992 | UINT16 offset the offset in the NV Index for the start of operand A |
| 11993 | TPM_EO operation the comparison to make |
| 11994 | |
| 11995 | |
| 11996 | Table 126 — TPM2_PolicyNV Response |
| 11997 | Type Name Description |
| 11998 | |
| 11999 | TPM_ST tag see clause 6 |
| 12000 | UINT32 responseSize |
| 12001 | TPM_RC responseCode |
| 12002 | |
| 12003 | |
| 12004 | |
| 12005 | |
| 12006 | Page 264 TCG Published Family “2.0” |
| 12007 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 12008 | Trusted Platform Module Library Part 3: Commands |
| 12009 | |
| 12010 | |
| 12011 | |
| 12012 | 23.9.3 Detailed Actions |
| 12013 | |
| 12014 | 1 #include "InternalRoutines.h" |
| 12015 | 2 #include "PolicyNV_fp.h" |
| 12016 | 3 #ifdef TPM_CC_PolicyNV // Conditional expansion of this file |
| 12017 | 4 #include "Policy_spt_fp.h" |
| 12018 | 5 #include "NV_spt_fp.h" // Include NV support routine for read access check |
| 12019 | |
| 12020 | |
| 12021 | Error Returns Meaning |
| 12022 | |
| 12023 | TPM_RC_AUTH_TYPE NV index authorization type is not correct |
| 12024 | TPM_RC_NV_LOCKED NV index read locked |
| 12025 | TPM_RC_NV_UNINITIALIZED the NV index has not been initialized |
| 12026 | TPM_RC_POLICY the comparison to the NV contents failed |
| 12027 | TPM_RC_SIZE the size of nvIndex data starting at offset is less than the size of |
| 12028 | operandB |
| 12029 | |
| 12030 | 6 TPM_RC |
| 12031 | 7 TPM2_PolicyNV( |
| 12032 | 8 PolicyNV_In *in // IN: input parameter list |
| 12033 | 9 ) |
| 12034 | 10 { |
| 12035 | 11 TPM_RC result; |
| 12036 | 12 SESSION *session; |
| 12037 | 13 NV_INDEX nvIndex; |
| 12038 | 14 BYTE nvBuffer[sizeof(in->operandB.t.buffer)]; |
| 12039 | 15 TPM2B_NAME nvName; |
| 12040 | 16 TPM_CC commandCode = TPM_CC_PolicyNV; |
| 12041 | 17 HASH_STATE hashState; |
| 12042 | 18 TPM2B_DIGEST argHash; |
| 12043 | 19 |
| 12044 | 20 // Input Validation |
| 12045 | 21 |
| 12046 | 22 // Get NV index information |
| 12047 | 23 NvGetIndexInfo(in->nvIndex, &nvIndex); |
| 12048 | 24 |
| 12049 | 25 // Get pointer to the session structure |
| 12050 | 26 session = SessionGet(in->policySession); |
| 12051 | 27 |
| 12052 | 28 //If this is a trial policy, skip all validations and the operation |
| 12053 | 29 if(session->attributes.isTrialPolicy == CLEAR) |
| 12054 | 30 { |
| 12055 | 31 // NV Read access check. NV index should be allowed for read. A |
| 12056 | 32 // TPM_RC_AUTH_TYPE or TPM_RC_NV_LOCKED error may be return at this |
| 12057 | 33 // point |
| 12058 | 34 result = NvReadAccessChecks(in->authHandle, in->nvIndex); |
| 12059 | 35 if(result != TPM_RC_SUCCESS) return result; |
| 12060 | 36 |
| 12061 | 37 // Valid NV data size should not be smaller than input operandB size |
| 12062 | 38 if((nvIndex.publicArea.dataSize - in->offset) < in->operandB.t.size) |
| 12063 | 39 return TPM_RC_SIZE + RC_PolicyNV_operandB; |
| 12064 | 40 |
| 12065 | 41 // Arithmetic Comparison |
| 12066 | 42 |
| 12067 | 43 // Get NV data. The size of NV data equals the input operand B size |
| 12068 | 44 NvGetIndexData(in->nvIndex, &nvIndex, in->offset, |
| 12069 | 45 in->operandB.t.size, nvBuffer); |
| 12070 | 46 |
| 12071 | 47 switch(in->operation) |
| 12072 | 48 { |
| 12073 | |
| 12074 | Family “2.0” TCG Published Page 265 |
| 12075 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 12076 | Part 3: Commands Trusted Platform Module Library |
| 12077 | |
| 12078 | 49 case TPM_EO_EQ: |
| 12079 | 50 // compare A = B |
| 12080 | 51 if(CryptCompare(in->operandB.t.size, nvBuffer, |
| 12081 | 52 in->operandB.t.size, in->operandB.t.buffer) != 0) |
| 12082 | 53 return TPM_RC_POLICY; |
| 12083 | 54 break; |
| 12084 | 55 case TPM_EO_NEQ: |
| 12085 | 56 // compare A != B |
| 12086 | 57 if(CryptCompare(in->operandB.t.size, nvBuffer, |
| 12087 | 58 in->operandB.t.size, in->operandB.t.buffer) == 0) |
| 12088 | 59 return TPM_RC_POLICY; |
| 12089 | 60 break; |
| 12090 | 61 case TPM_EO_SIGNED_GT: |
| 12091 | 62 // compare A > B signed |
| 12092 | 63 if(CryptCompareSigned(in->operandB.t.size, nvBuffer, |
| 12093 | 64 in->operandB.t.size, in->operandB.t.buffer) <= 0) |
| 12094 | 65 return TPM_RC_POLICY; |
| 12095 | 66 break; |
| 12096 | 67 case TPM_EO_UNSIGNED_GT: |
| 12097 | 68 // compare A > B unsigned |
| 12098 | 69 if(CryptCompare(in->operandB.t.size, nvBuffer, |
| 12099 | 70 in->operandB.t.size, in->operandB.t.buffer) <= 0) |
| 12100 | 71 return TPM_RC_POLICY; |
| 12101 | 72 break; |
| 12102 | 73 case TPM_EO_SIGNED_LT: |
| 12103 | 74 // compare A < B signed |
| 12104 | 75 if(CryptCompareSigned(in->operandB.t.size, nvBuffer, |
| 12105 | 76 in->operandB.t.size, in->operandB.t.buffer) >= 0) |
| 12106 | 77 return TPM_RC_POLICY; |
| 12107 | 78 break; |
| 12108 | 79 case TPM_EO_UNSIGNED_LT: |
| 12109 | 80 // compare A < B unsigned |
| 12110 | 81 if(CryptCompare(in->operandB.t.size, nvBuffer, |
| 12111 | 82 in->operandB.t.size, in->operandB.t.buffer) >= 0) |
| 12112 | 83 return TPM_RC_POLICY; |
| 12113 | 84 break; |
| 12114 | 85 case TPM_EO_SIGNED_GE: |
| 12115 | 86 // compare A >= B signed |
| 12116 | 87 if(CryptCompareSigned(in->operandB.t.size, nvBuffer, |
| 12117 | 88 in->operandB.t.size, in->operandB.t.buffer) < 0) |
| 12118 | 89 return TPM_RC_POLICY; |
| 12119 | 90 break; |
| 12120 | 91 case TPM_EO_UNSIGNED_GE: |
| 12121 | 92 // compare A >= B unsigned |
| 12122 | 93 if(CryptCompare(in->operandB.t.size, nvBuffer, |
| 12123 | 94 in->operandB.t.size, in->operandB.t.buffer) < 0) |
| 12124 | 95 return TPM_RC_POLICY; |
| 12125 | 96 break; |
| 12126 | 97 case TPM_EO_SIGNED_LE: |
| 12127 | 98 // compare A <= B signed |
| 12128 | 99 if(CryptCompareSigned(in->operandB.t.size, nvBuffer, |
| 12129 | 100 in->operandB.t.size, in->operandB.t.buffer) > 0) |
| 12130 | 101 return TPM_RC_POLICY; |
| 12131 | 102 break; |
| 12132 | 103 case TPM_EO_UNSIGNED_LE: |
| 12133 | 104 // compare A <= B unsigned |
| 12134 | 105 if(CryptCompare(in->operandB.t.size, nvBuffer, |
| 12135 | 106 in->operandB.t.size, in->operandB.t.buffer) > 0) |
| 12136 | 107 return TPM_RC_POLICY; |
| 12137 | 108 break; |
| 12138 | 109 case TPM_EO_BITSET: |
| 12139 | 110 // All bits SET in B are SET in A. ((A&B)=B) |
| 12140 | 111 { |
| 12141 | 112 UINT32 i; |
| 12142 | 113 for (i = 0; i < in->operandB.t.size; i++) |
| 12143 | 114 if((nvBuffer[i] & in->operandB.t.buffer[i]) |
| 12144 | |
| 12145 | Page 266 TCG Published Family “2.0” |
| 12146 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 12147 | Trusted Platform Module Library Part 3: Commands |
| 12148 | |
| 12149 | 115 != in->operandB.t.buffer[i]) |
| 12150 | 116 return TPM_RC_POLICY; |
| 12151 | 117 } |
| 12152 | 118 break; |
| 12153 | 119 case TPM_EO_BITCLEAR: |
| 12154 | 120 // All bits SET in B are CLEAR in A. ((A&B)=0) |
| 12155 | 121 { |
| 12156 | 122 UINT32 i; |
| 12157 | 123 for (i = 0; i < in->operandB.t.size; i++) |
| 12158 | 124 if((nvBuffer[i] & in->operandB.t.buffer[i]) != 0) |
| 12159 | 125 return TPM_RC_POLICY; |
| 12160 | 126 } |
| 12161 | 127 break; |
| 12162 | 128 default: |
| 12163 | 129 pAssert(FALSE); |
| 12164 | 130 break; |
| 12165 | 131 } |
| 12166 | 132 } |
| 12167 | 133 |
| 12168 | 134 // Internal Data Update |
| 12169 | 135 |
| 12170 | 136 // Start argument hash |
| 12171 | 137 argHash.t.size = CryptStartHash(session->authHashAlg, &hashState); |
| 12172 | 138 |
| 12173 | 139 // add operandB |
| 12174 | 140 CryptUpdateDigest2B(&hashState, &in->operandB.b); |
| 12175 | 141 |
| 12176 | 142 // add offset |
| 12177 | 143 CryptUpdateDigestInt(&hashState, sizeof(UINT16), &in->offset); |
| 12178 | 144 |
| 12179 | 145 // add operation |
| 12180 | 146 CryptUpdateDigestInt(&hashState, sizeof(TPM_EO), &in->operation); |
| 12181 | 147 |
| 12182 | 148 // complete argument digest |
| 12183 | 149 CryptCompleteHash2B(&hashState, &argHash.b); |
| 12184 | 150 |
| 12185 | 151 // Update policyDigest |
| 12186 | 152 // Start digest |
| 12187 | 153 CryptStartHash(session->authHashAlg, &hashState); |
| 12188 | 154 |
| 12189 | 155 // add old digest |
| 12190 | 156 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); |
| 12191 | 157 |
| 12192 | 158 // add commandCode |
| 12193 | 159 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); |
| 12194 | 160 |
| 12195 | 161 // add argument digest |
| 12196 | 162 CryptUpdateDigest2B(&hashState, &argHash.b); |
| 12197 | 163 |
| 12198 | 164 // Adding nvName |
| 12199 | 165 nvName.t.size = EntityGetName(in->nvIndex, &nvName.t.name); |
| 12200 | 166 CryptUpdateDigest2B(&hashState, &nvName.b); |
| 12201 | 167 |
| 12202 | 168 // complete the digest |
| 12203 | 169 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); |
| 12204 | 170 |
| 12205 | 171 return TPM_RC_SUCCESS; |
| 12206 | 172 } |
| 12207 | 173 #endif // CC_PolicyNV |
| 12208 | |
| 12209 | |
| 12210 | |
| 12211 | |
| 12212 | Family “2.0” TCG Published Page 267 |
| 12213 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 12214 | Part 3: Commands Trusted Platform Module Library |
| 12215 | |
| 12216 | |
| 12217 | 23.10 TPM2_PolicyCounterTimer |
| 12218 | |
| 12219 | 23.10.1 General Description |
| 12220 | |
| 12221 | This command is used to cause conditional gating of a policy based on the contents of the |
| 12222 | TPMS_TIME_INFO structure. |
| 12223 | If policySession is a trial policy session, the TPM will update policySession→policyDigest as shown in |
| 12224 | equations (24) and (25) below and return TPM_RC_SUCCESS. It will not perform any validation. The |
| 12225 | remainder of this general description would apply only if policySession is not a trial policy session. |
| 12226 | The TPM will perform the indicated arithmetic check on the indicated portion of the TPMS_TIME_INFO |
| 12227 | structure. If the check fails, the TPM shall return TPM_RC_POLICY and not change |
| 12228 | policySession→policyDigest. If the check succeeds, the TPM will hash the arguments: |
| 12229 | args ≔ HpolicyAlg(operandB.buffer || offset || operation) (24) |
| 12230 | where |
| 12231 | HpolicyAlg() hash function using the algorithm of the policy session |
| 12232 | operandB.buffer the value used for the comparison |
| 12233 | offset offset from the start of the TPMS_TIME_INFO structure at which |
| 12234 | the comparison starts |
| 12235 | operation the operation parameter indicating the comparison being |
| 12236 | performed |
| 12237 | |
| 12238 | |
| 12239 | The value of args is extended to policySession→policyDigest by |
| 12240 | policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyCounterTimer || args) (25) |
| 12241 | where |
| 12242 | HpolicyAlg() hash function using the algorithm of the policy session |
| 12243 | args value computed in equation (24) |
| 12244 | |
| 12245 | |
| 12246 | The signed arithmetic operations are performed using twos-compliment. The indicated portion of the |
| 12247 | TPMS_TIME_INFO structure begins at offset and has a length of operandB.size. If the octets to be |
| 12248 | compared overflows the TPMS_TIME_INFO structure, the TPM returns TPM_RC_RANGE. The structure |
| 12249 | is marshaled into its canonical form with no padding. The TPM does not check for alignment of the offset |
| 12250 | with a TPMS_TIME_INFO structure member. |
| 12251 | Magnitude comparisons assume that the octet at offset zero in the referenced location and in operandB |
| 12252 | contain the most significant octet of the data. |
| 12253 | |
| 12254 | |
| 12255 | |
| 12256 | |
| 12257 | Page 268 TCG Published Family “2.0” |
| 12258 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 12259 | Trusted Platform Module Library Part 3: Commands |
| 12260 | |
| 12261 | |
| 12262 | |
| 12263 | 23.10.2 Command and Response |
| 12264 | |
| 12265 | Table 127 — TPM2_PolicyCounterTimer Command |
| 12266 | Type Name Description |
| 12267 | |
| 12268 | TPM_ST_SESSIONS if an audit or decrypt session is |
| 12269 | TPMI_ST_COMMAND_TAG tag |
| 12270 | present; otherwise, TPM_ST_NO_SESSIONS |
| 12271 | UINT32 commandSize |
| 12272 | TPM_CC commandCode TPM_CC_PolicyCounterTimer |
| 12273 | |
| 12274 | handle for the policy session being extended |
| 12275 | TPMI_SH_POLICY policySession |
| 12276 | Auth Index: None |
| 12277 | |
| 12278 | TPM2B_OPERAND operandB the second operand |
| 12279 | the offset in TPMS_TIME_INFO structure for the start of |
| 12280 | UINT16 offset |
| 12281 | operand A |
| 12282 | TPM_EO operation the comparison to make |
| 12283 | |
| 12284 | |
| 12285 | Table 128 — TPM2_PolicyCounterTimer Response |
| 12286 | Type Name Description |
| 12287 | |
| 12288 | TPM_ST tag see clause 6 |
| 12289 | UINT32 responseSize |
| 12290 | TPM_RC responseCode |
| 12291 | |
| 12292 | |
| 12293 | |
| 12294 | |
| 12295 | Family “2.0” TCG Published Page 269 |
| 12296 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 12297 | Part 3: Commands Trusted Platform Module Library |
| 12298 | |
| 12299 | |
| 12300 | |
| 12301 | 23.10.3 Detailed Actions |
| 12302 | |
| 12303 | 1 #include "InternalRoutines.h" |
| 12304 | 2 #include "PolicyCounterTimer_fp.h" |
| 12305 | 3 #ifdef TPM_CC_PolicyCounterTimer // Conditional expansion of this file |
| 12306 | 4 #include "Policy_spt_fp.h" |
| 12307 | |
| 12308 | |
| 12309 | Error Returns Meaning |
| 12310 | |
| 12311 | TPM_RC_POLICY the comparison of the selected portion of the TPMS_TIME_INFO with |
| 12312 | operandB failed |
| 12313 | TPM_RC_RANGE offset + size exceed size of TPMS_TIME_INFO structure |
| 12314 | |
| 12315 | 5 TPM_RC |
| 12316 | 6 TPM2_PolicyCounterTimer( |
| 12317 | 7 PolicyCounterTimer_In *in // IN: input parameter list |
| 12318 | 8 ) |
| 12319 | 9 { |
| 12320 | 10 TPM_RC result; |
| 12321 | 11 SESSION *session; |
| 12322 | 12 TIME_INFO infoData; // data buffer of TPMS_TIME_INFO |
| 12323 | 13 TPM_CC commandCode = TPM_CC_PolicyCounterTimer; |
| 12324 | 14 HASH_STATE hashState; |
| 12325 | 15 TPM2B_DIGEST argHash; |
| 12326 | 16 |
| 12327 | 17 // Input Validation |
| 12328 | 18 |
| 12329 | 19 // If the command is going to use any part of the counter or timer, need |
| 12330 | 20 // to verify that time is advancing. |
| 12331 | 21 // The time and clock vales are the first two 64-bit values in the clock |
| 12332 | 22 if(in->offset < sizeof(UINT64) + sizeof(UINT64)) |
| 12333 | 23 { |
| 12334 | 24 // Using Clock or Time so see if clock is running. Clock doesn't run while |
| 12335 | 25 // NV is unavailable. |
| 12336 | 26 // TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned here. |
| 12337 | 27 result = NvIsAvailable(); |
| 12338 | 28 if(result != TPM_RC_SUCCESS) |
| 12339 | 29 return result; |
| 12340 | 30 } |
| 12341 | 31 // Get pointer to the session structure |
| 12342 | 32 session = SessionGet(in->policySession); |
| 12343 | 33 |
| 12344 | 34 //If this is a trial policy, skip all validations and the operation |
| 12345 | 35 if(session->attributes.isTrialPolicy == CLEAR) |
| 12346 | 36 { |
| 12347 | 37 // Get time data info. The size of time info data equals the input |
| 12348 | 38 // operand B size. A TPM_RC_RANGE error may be returned at this point |
| 12349 | 39 result = TimeGetRange(in->offset, in->operandB.t.size, &infoData); |
| 12350 | 40 if(result != TPM_RC_SUCCESS) return result; |
| 12351 | 41 |
| 12352 | 42 // Arithmetic Comparison |
| 12353 | 43 switch(in->operation) |
| 12354 | 44 { |
| 12355 | 45 case TPM_EO_EQ: |
| 12356 | 46 // compare A = B |
| 12357 | 47 if(CryptCompare(in->operandB.t.size, infoData, |
| 12358 | 48 in->operandB.t.size, in->operandB.t.buffer) != 0) |
| 12359 | 49 return TPM_RC_POLICY; |
| 12360 | 50 break; |
| 12361 | 51 case TPM_EO_NEQ: |
| 12362 | 52 // compare A != B |
| 12363 | 53 if(CryptCompare(in->operandB.t.size, infoData, |
| 12364 | |
| 12365 | Page 270 TCG Published Family “2.0” |
| 12366 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 12367 | Trusted Platform Module Library Part 3: Commands |
| 12368 | |
| 12369 | 54 in->operandB.t.size, in->operandB.t.buffer) == 0) |
| 12370 | 55 return TPM_RC_POLICY; |
| 12371 | 56 break; |
| 12372 | 57 case TPM_EO_SIGNED_GT: |
| 12373 | 58 // compare A > B signed |
| 12374 | 59 if(CryptCompareSigned(in->operandB.t.size, infoData, |
| 12375 | 60 in->operandB.t.size, in->operandB.t.buffer) <= 0) |
| 12376 | 61 return TPM_RC_POLICY; |
| 12377 | 62 break; |
| 12378 | 63 case TPM_EO_UNSIGNED_GT: |
| 12379 | 64 // compare A > B unsigned |
| 12380 | 65 if(CryptCompare(in->operandB.t.size, infoData, |
| 12381 | 66 in->operandB.t.size, in->operandB.t.buffer) <= 0) |
| 12382 | 67 return TPM_RC_POLICY; |
| 12383 | 68 break; |
| 12384 | 69 case TPM_EO_SIGNED_LT: |
| 12385 | 70 // compare A < B signed |
| 12386 | 71 if(CryptCompareSigned(in->operandB.t.size, infoData, |
| 12387 | 72 in->operandB.t.size, in->operandB.t.buffer) >= 0) |
| 12388 | 73 return TPM_RC_POLICY; |
| 12389 | 74 break; |
| 12390 | 75 case TPM_EO_UNSIGNED_LT: |
| 12391 | 76 // compare A < B unsigned |
| 12392 | 77 if(CryptCompare(in->operandB.t.size, infoData, |
| 12393 | 78 in->operandB.t.size, in->operandB.t.buffer) >= 0) |
| 12394 | 79 return TPM_RC_POLICY; |
| 12395 | 80 break; |
| 12396 | 81 case TPM_EO_SIGNED_GE: |
| 12397 | 82 // compare A >= B signed |
| 12398 | 83 if(CryptCompareSigned(in->operandB.t.size, infoData, |
| 12399 | 84 in->operandB.t.size, in->operandB.t.buffer) < 0) |
| 12400 | 85 return TPM_RC_POLICY; |
| 12401 | 86 break; |
| 12402 | 87 case TPM_EO_UNSIGNED_GE: |
| 12403 | 88 // compare A >= B unsigned |
| 12404 | 89 if(CryptCompare(in->operandB.t.size, infoData, |
| 12405 | 90 in->operandB.t.size, in->operandB.t.buffer) < 0) |
| 12406 | 91 return TPM_RC_POLICY; |
| 12407 | 92 break; |
| 12408 | 93 case TPM_EO_SIGNED_LE: |
| 12409 | 94 // compare A <= B signed |
| 12410 | 95 if(CryptCompareSigned(in->operandB.t.size, infoData, |
| 12411 | 96 in->operandB.t.size, in->operandB.t.buffer) > 0) |
| 12412 | 97 return TPM_RC_POLICY; |
| 12413 | 98 break; |
| 12414 | 99 case TPM_EO_UNSIGNED_LE: |
| 12415 | 100 // compare A <= B unsigned |
| 12416 | 101 if(CryptCompare(in->operandB.t.size, infoData, |
| 12417 | 102 in->operandB.t.size, in->operandB.t.buffer) > 0) |
| 12418 | 103 return TPM_RC_POLICY; |
| 12419 | 104 break; |
| 12420 | 105 case TPM_EO_BITSET: |
| 12421 | 106 // All bits SET in B are SET in A. ((A&B)=B) |
| 12422 | 107 { |
| 12423 | 108 UINT32 i; |
| 12424 | 109 for (i = 0; i < in->operandB.t.size; i++) |
| 12425 | 110 if( (infoData[i] & in->operandB.t.buffer[i]) |
| 12426 | 111 != in->operandB.t.buffer[i]) |
| 12427 | 112 return TPM_RC_POLICY; |
| 12428 | 113 } |
| 12429 | 114 break; |
| 12430 | 115 case TPM_EO_BITCLEAR: |
| 12431 | 116 // All bits SET in B are CLEAR in A. ((A&B)=0) |
| 12432 | 117 { |
| 12433 | 118 UINT32 i; |
| 12434 | 119 for (i = 0; i < in->operandB.t.size; i++) |
| 12435 | |
| 12436 | Family “2.0” TCG Published Page 271 |
| 12437 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 12438 | Part 3: Commands Trusted Platform Module Library |
| 12439 | |
| 12440 | 120 if((infoData[i] & in->operandB.t.buffer[i]) != 0) |
| 12441 | 121 return TPM_RC_POLICY; |
| 12442 | 122 } |
| 12443 | 123 break; |
| 12444 | 124 default: |
| 12445 | 125 pAssert(FALSE); |
| 12446 | 126 break; |
| 12447 | 127 } |
| 12448 | 128 } |
| 12449 | 129 |
| 12450 | 130 // Internal Data Update |
| 12451 | 131 |
| 12452 | 132 // Start argument list hash |
| 12453 | 133 argHash.t.size = CryptStartHash(session->authHashAlg, &hashState); |
| 12454 | 134 // add operandB |
| 12455 | 135 CryptUpdateDigest2B(&hashState, &in->operandB.b); |
| 12456 | 136 // add offset |
| 12457 | 137 CryptUpdateDigestInt(&hashState, sizeof(UINT16), &in->offset); |
| 12458 | 138 // add operation |
| 12459 | 139 CryptUpdateDigestInt(&hashState, sizeof(TPM_EO), &in->operation); |
| 12460 | 140 // complete argument hash |
| 12461 | 141 CryptCompleteHash2B(&hashState, &argHash.b); |
| 12462 | 142 |
| 12463 | 143 // update policyDigest |
| 12464 | 144 // start hash |
| 12465 | 145 CryptStartHash(session->authHashAlg, &hashState); |
| 12466 | 146 |
| 12467 | 147 // add old digest |
| 12468 | 148 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); |
| 12469 | 149 |
| 12470 | 150 // add commandCode |
| 12471 | 151 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); |
| 12472 | 152 |
| 12473 | 153 // add argument digest |
| 12474 | 154 CryptUpdateDigest2B(&hashState, &argHash.b); |
| 12475 | 155 |
| 12476 | 156 // complete the digest |
| 12477 | 157 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); |
| 12478 | 158 |
| 12479 | 159 return TPM_RC_SUCCESS; |
| 12480 | 160 } |
| 12481 | 161 #endif // CC_PolicyCounterTimer |
| 12482 | |
| 12483 | |
| 12484 | |
| 12485 | |
| 12486 | Page 272 TCG Published Family “2.0” |
| 12487 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 12488 | Trusted Platform Module Library Part 3: Commands |
| 12489 | |
| 12490 | |
| 12491 | 23.11 TPM2_PolicyCommandCode |
| 12492 | |
| 12493 | 23.11.1 General Description |
| 12494 | |
| 12495 | This command indicates that the authorization will be limited to a specific command code. |
| 12496 | If policySession→commandCode has its default value, then it will be set to code. If |
| 12497 | policySession→commandCode does not have its default value, then the TPM will return |
| 12498 | TPM_RC_VALUE if the two values are not the same. |
| 12499 | If code is not implemented, the TPM will return TPM_RC_POLICY_CC. |
| 12500 | If the TPM does not return an error, it will update policySession→policyDigest by |
| 12501 | policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyCommandCode || code) (26) |
| 12502 | |
| 12503 | NOTE 1 If a previous TPM2_PolicyCommandCode() had been executed, then it is probable that the policy |
| 12504 | expression is improperly formed but the TPM does not return an error. |
| 12505 | |
| 12506 | NOTE 2 A TPM2_PolicyOR() would be used to allow an authorization to be used for multiple commands. |
| 12507 | |
| 12508 | When the policy session is used to authorize a command, the TPM will fail the command if the |
| 12509 | commandCode of that command does not match policySession→commandCode. |
| 12510 | This command, or TPM2_PolicyDuplicationSelect(), is required to enable the policy to be used for ADMIN |
| 12511 | role authorization. |
| 12512 | |
| 12513 | EXAMPLE Before TPM2_Certify() can be executed, TPM2_PolicyCommandCode() with code set to |
| 12514 | TPM_CC_Certify is required. |
| 12515 | |
| 12516 | |
| 12517 | |
| 12518 | |
| 12519 | Family “2.0” TCG Published Page 273 |
| 12520 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 12521 | Part 3: Commands Trusted Platform Module Library |
| 12522 | |
| 12523 | |
| 12524 | 23.11.2 Command and Response |
| 12525 | |
| 12526 | Table 129 — TPM2_PolicyCommandCode Command |
| 12527 | Type Name Description |
| 12528 | |
| 12529 | TPM_ST_SESSIONS if an audit session is present; |
| 12530 | TPMI_ST_COMMAND_TAG tag |
| 12531 | otherwise, TPM_ST_NO_SESSIONS |
| 12532 | UINT32 commandSize |
| 12533 | TPM_CC commandCode TPM_CC_PolicyCommandCode |
| 12534 | |
| 12535 | handle for the policy session being extended |
| 12536 | TPMI_SH_POLICY policySession |
| 12537 | Auth Index: None |
| 12538 | |
| 12539 | TPM_CC code the allowed commandCode |
| 12540 | |
| 12541 | |
| 12542 | Table 130 — TPM2_PolicyCommandCode Response |
| 12543 | Type Name Description |
| 12544 | |
| 12545 | TPM_ST tag see clause 6 |
| 12546 | UINT32 responseSize |
| 12547 | TPM_RC responseCode |
| 12548 | |
| 12549 | |
| 12550 | |
| 12551 | |
| 12552 | Page 274 TCG Published Family “2.0” |
| 12553 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 12554 | Trusted Platform Module Library Part 3: Commands |
| 12555 | |
| 12556 | |
| 12557 | |
| 12558 | 23.11.3 Detailed Actions |
| 12559 | |
| 12560 | 1 #include "InternalRoutines.h" |
| 12561 | 2 #include "PolicyCommandCode_fp.h" |
| 12562 | 3 #ifdef TPM_CC_PolicyCommandCode // Conditional expansion of this file |
| 12563 | |
| 12564 | |
| 12565 | Error Returns Meaning |
| 12566 | |
| 12567 | TPM_RC_VALUE commandCode of policySession previously set to a different value |
| 12568 | |
| 12569 | 4 TPM_RC |
| 12570 | 5 TPM2_PolicyCommandCode( |
| 12571 | 6 PolicyCommandCode_In *in // IN: input parameter list |
| 12572 | 7 ) |
| 12573 | 8 { |
| 12574 | 9 SESSION *session; |
| 12575 | 10 TPM_CC commandCode = TPM_CC_PolicyCommandCode; |
| 12576 | 11 HASH_STATE hashState; |
| 12577 | 12 |
| 12578 | 13 // Input validation |
| 12579 | 14 |
| 12580 | 15 // Get pointer to the session structure |
| 12581 | 16 session = SessionGet(in->policySession); |
| 12582 | 17 |
| 12583 | 18 if(session->commandCode != 0 && session->commandCode != in->code) |
| 12584 | 19 return TPM_RC_VALUE + RC_PolicyCommandCode_code; |
| 12585 | 20 if(!CommandIsImplemented(in->code)) |
| 12586 | 21 return TPM_RC_POLICY_CC + RC_PolicyCommandCode_code; |
| 12587 | 22 |
| 12588 | 23 // Internal Data Update |
| 12589 | 24 // Update policy hash |
| 12590 | 25 // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyCommandCode || code) |
| 12591 | 26 // Start hash |
| 12592 | 27 CryptStartHash(session->authHashAlg, &hashState); |
| 12593 | 28 |
| 12594 | 29 // add old digest |
| 12595 | 30 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); |
| 12596 | 31 |
| 12597 | 32 // add commandCode |
| 12598 | 33 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); |
| 12599 | 34 |
| 12600 | 35 // add input commandCode |
| 12601 | 36 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &in->code); |
| 12602 | 37 |
| 12603 | 38 // complete the hash and get the results |
| 12604 | 39 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); |
| 12605 | 40 |
| 12606 | 41 // update commandCode value in session context |
| 12607 | 42 session->commandCode = in->code; |
| 12608 | 43 |
| 12609 | 44 return TPM_RC_SUCCESS; |
| 12610 | 45 } |
| 12611 | 46 #endif // CC_PolicyCommandCode |
| 12612 | |
| 12613 | |
| 12614 | |
| 12615 | |
| 12616 | Family “2.0” TCG Published Page 275 |
| 12617 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 12618 | Part 3: Commands Trusted Platform Module Library |
| 12619 | |
| 12620 | |
| 12621 | 23.12 TPM2_PolicyPhysicalPresence |
| 12622 | |
| 12623 | 23.12.1 General Description |
| 12624 | |
| 12625 | This command indicates that physical presence will need to be asserted at the time the authorization is |
| 12626 | performed. |
| 12627 | If this command is successful, policySession→isPPRequired will be SET to indicate that this check is |
| 12628 | required when the policy is used for authorization. Additionally, policySession→policyDigest is extended |
| 12629 | with |
| 12630 | policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyPhysicalPresence) (27) |
| 12631 | |
| 12632 | |
| 12633 | |
| 12634 | |
| 12635 | Page 276 TCG Published Family “2.0” |
| 12636 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 12637 | Trusted Platform Module Library Part 3: Commands |
| 12638 | |
| 12639 | |
| 12640 | |
| 12641 | 23.12.2 Command and Response |
| 12642 | |
| 12643 | Table 131 — TPM2_PolicyPhysicalPresence Command |
| 12644 | Type Name Description |
| 12645 | |
| 12646 | TPM_ST_SESSIONS if an audit session is present; |
| 12647 | TPMI_ST_COMMAND_TAG tag |
| 12648 | otherwise, TPM_ST_NO_SESSIONS |
| 12649 | UINT32 commandSize |
| 12650 | TPM_CC commandCode TPM_CC_PolicyPhysicalPresence |
| 12651 | |
| 12652 | handle for the policy session being extended |
| 12653 | TPMI_SH_POLICY policySession |
| 12654 | Auth Index: None |
| 12655 | |
| 12656 | |
| 12657 | Table 132 — TPM2_PolicyPhysicalPresence Response |
| 12658 | Type Name Description |
| 12659 | |
| 12660 | TPM_ST tag see clause 6 |
| 12661 | UINT32 responseSize |
| 12662 | TPM_RC responseCode |
| 12663 | |
| 12664 | |
| 12665 | |
| 12666 | |
| 12667 | Family “2.0” TCG Published Page 277 |
| 12668 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 12669 | Part 3: Commands Trusted Platform Module Library |
| 12670 | |
| 12671 | |
| 12672 | |
| 12673 | 23.12.3 Detailed Actions |
| 12674 | |
| 12675 | 1 #include "InternalRoutines.h" |
| 12676 | 2 #include "PolicyPhysicalPresence_fp.h" |
| 12677 | 3 #ifdef TPM_CC_PolicyPhysicalPresence // Conditional expansion of this file |
| 12678 | 4 TPM_RC |
| 12679 | 5 TPM2_PolicyPhysicalPresence( |
| 12680 | 6 PolicyPhysicalPresence_In *in // IN: input parameter list |
| 12681 | 7 ) |
| 12682 | 8 { |
| 12683 | 9 SESSION *session; |
| 12684 | 10 TPM_CC commandCode = TPM_CC_PolicyPhysicalPresence; |
| 12685 | 11 HASH_STATE hashState; |
| 12686 | 12 |
| 12687 | 13 // Internal Data Update |
| 12688 | 14 |
| 12689 | 15 // Get pointer to the session structure |
| 12690 | 16 session = SessionGet(in->policySession); |
| 12691 | 17 |
| 12692 | 18 // Update policy hash |
| 12693 | 19 // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyPhysicalPresence) |
| 12694 | 20 // Start hash |
| 12695 | 21 CryptStartHash(session->authHashAlg, &hashState); |
| 12696 | 22 |
| 12697 | 23 // add old digest |
| 12698 | 24 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); |
| 12699 | 25 |
| 12700 | 26 // add commandCode |
| 12701 | 27 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); |
| 12702 | 28 |
| 12703 | 29 // complete the digest |
| 12704 | 30 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); |
| 12705 | 31 |
| 12706 | 32 // update session attribute |
| 12707 | 33 session->attributes.isPPRequired = SET; |
| 12708 | 34 |
| 12709 | 35 return TPM_RC_SUCCESS; |
| 12710 | 36 } |
| 12711 | 37 #endif // CC_PolicyPhysicalPresence |
| 12712 | |
| 12713 | |
| 12714 | |
| 12715 | |
| 12716 | Page 278 TCG Published Family “2.0” |
| 12717 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 12718 | Trusted Platform Module Library Part 3: Commands |
| 12719 | |
| 12720 | |
| 12721 | 23.13 TPM2_PolicyCpHash |
| 12722 | |
| 12723 | 23.13.1 General Description |
| 12724 | |
| 12725 | This command is used to allow a policy to be bound to a specific command and command parameters. |
| 12726 | TPM2_PolicySigned(), TPM2_PolicySecret(), and TPM2_PolicyTIcket() are designed to allow an |
| 12727 | authorizing entity to execute an arbitrary command as the cpHashA parameter of those commands is not |
| 12728 | included in policySession→policyDigest. TPM2_PolicyCommandCode() allows the policy to be bound to a |
| 12729 | specific Command Code so that only certain entities may authorize specific command codes. This |
| 12730 | command allows the policy to be restricted such that an entity may only authorize a command with a |
| 12731 | specific set of parameters. |
| 12732 | If policySession→cpHash is already set and not the same as cpHashA, then the TPM shall return |
| 12733 | TPM_RC_VALUE. If cpHashA does not have the size of the policySession→policyDigest, the TPM shall |
| 12734 | return TPM_RC_SIZE. |
| 12735 | If the cpHashA checks succeed, policySession→cpHash is set to cpHashA and |
| 12736 | policySession→policyDigest is updated with |
| 12737 | policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyCpHash || cpHashA) (28) |
| 12738 | |
| 12739 | |
| 12740 | |
| 12741 | |
| 12742 | Family “2.0” TCG Published Page 279 |
| 12743 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 12744 | Part 3: Commands Trusted Platform Module Library |
| 12745 | |
| 12746 | |
| 12747 | |
| 12748 | 23.13.2 Command and Response |
| 12749 | |
| 12750 | Table 133 — TPM2_PolicyCpHash Command |
| 12751 | Type Name Description |
| 12752 | |
| 12753 | TPM_ST_SESSIONS if an audit or decrypt session is |
| 12754 | TPMI_ST_COMMAND_TAG tag |
| 12755 | present; otherwise, TPM_ST_NO_SESSIONS |
| 12756 | UINT32 commandSize |
| 12757 | TPM_CC commandCode TPM_CC_PolicyCpHash |
| 12758 | |
| 12759 | handle for the policy session being extended |
| 12760 | TPMI_SH_POLICY policySession |
| 12761 | Auth Index: None |
| 12762 | |
| 12763 | TPM2B_DIGEST cpHashA the cpHash added to the policy |
| 12764 | |
| 12765 | |
| 12766 | Table 134 — TPM2_PolicyCpHash Response |
| 12767 | Type Name Description |
| 12768 | |
| 12769 | TPM_ST tag see clause 6 |
| 12770 | UINT32 responseSize |
| 12771 | TPM_RC responseCode |
| 12772 | |
| 12773 | |
| 12774 | |
| 12775 | |
| 12776 | Page 280 TCG Published Family “2.0” |
| 12777 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 12778 | Trusted Platform Module Library Part 3: Commands |
| 12779 | |
| 12780 | |
| 12781 | |
| 12782 | 23.13.3 Detailed Actions |
| 12783 | |
| 12784 | 1 #include "InternalRoutines.h" |
| 12785 | 2 #include "PolicyCpHash_fp.h" |
| 12786 | 3 #ifdef TPM_CC_PolicyCpHash // Conditional expansion of this file |
| 12787 | |
| 12788 | |
| 12789 | Error Returns Meaning |
| 12790 | |
| 12791 | TPM_RC_CPHASH cpHash of policySession has previously been set to a different value |
| 12792 | TPM_RC_SIZE cpHashA is not the size of a digest produced by the hash algorithm |
| 12793 | associated with policySession |
| 12794 | |
| 12795 | 4 TPM_RC |
| 12796 | 5 TPM2_PolicyCpHash( |
| 12797 | 6 PolicyCpHash_In *in // IN: input parameter list |
| 12798 | 7 ) |
| 12799 | 8 { |
| 12800 | 9 SESSION *session; |
| 12801 | 10 TPM_CC commandCode = TPM_CC_PolicyCpHash; |
| 12802 | 11 HASH_STATE hashState; |
| 12803 | 12 |
| 12804 | 13 // Input Validation |
| 12805 | 14 |
| 12806 | 15 // Get pointer to the session structure |
| 12807 | 16 session = SessionGet(in->policySession); |
| 12808 | 17 |
| 12809 | 18 // A new cpHash is given in input parameter, but cpHash in session context |
| 12810 | 19 // is not empty, or is not the same as the new cpHash |
| 12811 | 20 if( in->cpHashA.t.size != 0 |
| 12812 | 21 && session->u1.cpHash.t.size != 0 |
| 12813 | 22 && !Memory2BEqual(&in->cpHashA.b, &session->u1.cpHash.b) |
| 12814 | 23 ) |
| 12815 | 24 return TPM_RC_CPHASH; |
| 12816 | 25 |
| 12817 | 26 // A valid cpHash must have the same size as session hash digest |
| 12818 | 27 if(in->cpHashA.t.size != CryptGetHashDigestSize(session->authHashAlg)) |
| 12819 | 28 return TPM_RC_SIZE + RC_PolicyCpHash_cpHashA; |
| 12820 | 29 |
| 12821 | 30 // Internal Data Update |
| 12822 | 31 |
| 12823 | 32 // Update policy hash |
| 12824 | 33 // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyCpHash || cpHashA) |
| 12825 | 34 // Start hash |
| 12826 | 35 CryptStartHash(session->authHashAlg, &hashState); |
| 12827 | 36 |
| 12828 | 37 // add old digest |
| 12829 | 38 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); |
| 12830 | 39 |
| 12831 | 40 // add commandCode |
| 12832 | 41 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); |
| 12833 | 42 |
| 12834 | 43 // add cpHashA |
| 12835 | 44 CryptUpdateDigest2B(&hashState, &in->cpHashA.b); |
| 12836 | 45 |
| 12837 | 46 // complete the digest and get the results |
| 12838 | 47 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); |
| 12839 | 48 |
| 12840 | 49 // update cpHash in session context |
| 12841 | 50 session->u1.cpHash = in->cpHashA; |
| 12842 | 51 session->attributes.iscpHashDefined = SET; |
| 12843 | 52 |
| 12844 | 53 return TPM_RC_SUCCESS; |
| 12845 | |
| 12846 | Family “2.0” TCG Published Page 281 |
| 12847 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 12848 | Part 3: Commands Trusted Platform Module Library |
| 12849 | |
| 12850 | 54 } |
| 12851 | 55 #endif // CC_PolicyCpHash |
| 12852 | |
| 12853 | |
| 12854 | |
| 12855 | |
| 12856 | Page 282 TCG Published Family “2.0” |
| 12857 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 12858 | Trusted Platform Module Library Part 3: Commands |
| 12859 | |
| 12860 | |
| 12861 | 23.14 TPM2_PolicyNameHash |
| 12862 | |
| 12863 | 23.14.1 General Description |
| 12864 | |
| 12865 | This command allows a policy to be bound to a specific set of TPM entities without being bound to the |
| 12866 | parameters of the command. This is most useful for commands such as TPM2_Duplicate() and for |
| 12867 | TPM2_PCR_Event() when the referenced PCR requires a policy. |
| 12868 | The nameHash parameter should contain the digest of the Names associated with the handles to be used |
| 12869 | in the authorized command. |
| 12870 | |
| 12871 | EXAMPLE For the TPM2_Duplicate() command, two han dles are provided. One is the handle of the object |
| 12872 | being duplicated and the other is the handle of the new parent. For that command, nameHash would |
| 12873 | contain: |
| 12874 | nameHash ≔ H policyAlg (objectHandle→Name || newParentHandle→Name) |
| 12875 | |
| 12876 | If policySession→cpHash is already set, the TPM shall return TPM_RC_VALUE. If the size of nameHash |
| 12877 | is not the size of policySession→policyDigest, the TPM shall return TPM_RC_SIZE. Otherwise, |
| 12878 | policySession→cpHash is set to nameHash. |
| 12879 | If this command completes successfully, the cpHash of the authorized command will not be used for |
| 12880 | validation. Only the digest of the Names associated with the handles in the command will be used. |
| 12881 | |
| 12882 | NOTE 1 This allows the space normally used to hold policySession→cpHash to be used for |
| 12883 | policySession→nameHash instead. |
| 12884 | |
| 12885 | The policySession→policyDigest will be updated with |
| 12886 | policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyNameHash || nameHash) (29) |
| 12887 | |
| 12888 | NOTE 2 This command will often be used with TPM2_PolicyAuthorize() where the owner of the object being |
| 12889 | duplicated provides approval for their object to be migrated to a specific new parent. |
| 12890 | |
| 12891 | |
| 12892 | |
| 12893 | |
| 12894 | Family “2.0” TCG Published Page 283 |
| 12895 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 12896 | Part 3: Commands Trusted Platform Module Library |
| 12897 | |
| 12898 | |
| 12899 | 23.14.2 Command and Response |
| 12900 | |
| 12901 | Table 135 — TPM2_PolicyNameHash Command |
| 12902 | Type Name Description |
| 12903 | |
| 12904 | TPM_ST_SESSIONS if an audit or decrypt session is |
| 12905 | TPMI_ST_COMMAND_TAG tag |
| 12906 | present; otherwise, TPM_ST_NO_SESSIONS |
| 12907 | UINT32 commandSize |
| 12908 | TPM_CC commandCode TPM_CC_PolicyNameHash |
| 12909 | |
| 12910 | handle for the policy session being extended |
| 12911 | TPMI_SH_POLICY policySession |
| 12912 | Auth Index: None |
| 12913 | |
| 12914 | TPM2B_DIGEST nameHash the digest to be added to the policy |
| 12915 | |
| 12916 | |
| 12917 | Table 136 — TPM2_PolicyNameHash Response |
| 12918 | Type Name Description |
| 12919 | |
| 12920 | TPM_ST tag see clause 6 |
| 12921 | UINT32 responseSize |
| 12922 | TPM_RC responseCode |
| 12923 | |
| 12924 | |
| 12925 | |
| 12926 | |
| 12927 | Page 284 TCG Published Family “2.0” |
| 12928 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 12929 | Trusted Platform Module Library Part 3: Commands |
| 12930 | |
| 12931 | |
| 12932 | |
| 12933 | 23.14.3 Detailed Actions |
| 12934 | |
| 12935 | 1 #include "InternalRoutines.h" |
| 12936 | 2 #include "PolicyNameHash_fp.h" |
| 12937 | 3 #ifdef TPM_CC_PolicyNameHash // Conditional expansion of this file |
| 12938 | |
| 12939 | |
| 12940 | Error Returns Meaning |
| 12941 | |
| 12942 | TPM_RC_CPHASH nameHash has been previously set to a different value |
| 12943 | TPM_RC_SIZE nameHash is not the size of the digest produced by the hash |
| 12944 | algorithm associated with policySession |
| 12945 | |
| 12946 | 4 TPM_RC |
| 12947 | 5 TPM2_PolicyNameHash( |
| 12948 | 6 PolicyNameHash_In *in // IN: input parameter list |
| 12949 | 7 ) |
| 12950 | 8 { |
| 12951 | 9 SESSION *session; |
| 12952 | 10 TPM_CC commandCode = TPM_CC_PolicyNameHash; |
| 12953 | 11 HASH_STATE hashState; |
| 12954 | 12 |
| 12955 | 13 // Input Validation |
| 12956 | 14 |
| 12957 | 15 // Get pointer to the session structure |
| 12958 | 16 session = SessionGet(in->policySession); |
| 12959 | 17 |
| 12960 | 18 // A new nameHash is given in input parameter, but cpHash in session context |
| 12961 | 19 // is not empty |
| 12962 | 20 if(in->nameHash.t.size != 0 && session->u1.cpHash.t.size != 0) |
| 12963 | 21 return TPM_RC_CPHASH; |
| 12964 | 22 |
| 12965 | 23 // A valid nameHash must have the same size as session hash digest |
| 12966 | 24 if(in->nameHash.t.size != CryptGetHashDigestSize(session->authHashAlg)) |
| 12967 | 25 return TPM_RC_SIZE + RC_PolicyNameHash_nameHash; |
| 12968 | 26 |
| 12969 | 27 // Internal Data Update |
| 12970 | 28 |
| 12971 | 29 // Update policy hash |
| 12972 | 30 // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyNameHash || nameHash) |
| 12973 | 31 // Start hash |
| 12974 | 32 CryptStartHash(session->authHashAlg, &hashState); |
| 12975 | 33 |
| 12976 | 34 // add old digest |
| 12977 | 35 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); |
| 12978 | 36 |
| 12979 | 37 // add commandCode |
| 12980 | 38 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); |
| 12981 | 39 |
| 12982 | 40 // add nameHash |
| 12983 | 41 CryptUpdateDigest2B(&hashState, &in->nameHash.b); |
| 12984 | 42 |
| 12985 | 43 // complete the digest |
| 12986 | 44 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); |
| 12987 | 45 |
| 12988 | 46 // clear iscpHashDefined bit to indicate now this field contains a nameHash |
| 12989 | 47 session->attributes.iscpHashDefined = CLEAR; |
| 12990 | 48 |
| 12991 | 49 // update nameHash in session context |
| 12992 | 50 session->u1.cpHash = in->nameHash; |
| 12993 | 51 |
| 12994 | 52 return TPM_RC_SUCCESS; |
| 12995 | 53 } |
| 12996 | |
| 12997 | Family “2.0” TCG Published Page 285 |
| 12998 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 12999 | Part 3: Commands Trusted Platform Module Library |
| 13000 | |
| 13001 | 54 #endif // CC_PolicyNameHash |
| 13002 | |
| 13003 | |
| 13004 | |
| 13005 | |
| 13006 | Page 286 TCG Published Family “2.0” |
| 13007 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 13008 | Trusted Platform Module Library Part 3: Commands |
| 13009 | |
| 13010 | |
| 13011 | 23.15 TPM2_PolicyDuplicationSelect |
| 13012 | |
| 13013 | 23.15.1 General Description |
| 13014 | |
| 13015 | This command allows qualification of duplication to allow duplication to a selected new parent. |
| 13016 | If this command not used in conjunction with TPM2_PolicyAuthorize(), then only the new parent is |
| 13017 | selected. |
| 13018 | |
| 13019 | EXAMPLE When an object is created when the list of allowed duplication targets is known, the policy would be |
| 13020 | created with includeObject CLEAR. |
| 13021 | |
| 13022 | NOTE 1 Only the new parent may be selected because, without TPM2_PolicyAuthorize(), the Name of the |
| 13023 | Object to be duplicated would need to be known at the time that Object's policy is created. However, |
| 13024 | since the Name of the Object includes its policy, the Name is not known. |
| 13025 | |
| 13026 | If used in conjunction with TPM2_PolicyAuthorize(), then the authorizer of the new policy has the option |
| 13027 | of selecting just the new parent or of selecting both the new parent and the duplication Object.. |
| 13028 | |
| 13029 | NOTE 2 If the authorizing entity for an TPM2_PolicyAuthorize() only specifies the new parent, t hen that |
| 13030 | authorization may be applied to the duplication of any number of other Objects. If the authorizing |
| 13031 | entity specifies both a new parent and the duplicated Object, then the authorization only applies to |
| 13032 | that pairing of Object and new parent. |
| 13033 | |
| 13034 | If either policySession→cpHash or policySession→nameHash has been previously set, the TPM shall |
| 13035 | return TPM_RC_CPHASH. Otherwise, policySession→nameHash will be set to: |
| 13036 | nameHash ≔ HpolicyAlg(objectName || newParentName) (30) |
| 13037 | |
| 13038 | NOTE 3 It is allowed that policySesion→nameHash and policySession→cpHash share the same memory |
| 13039 | space. |
| 13040 | |
| 13041 | The policySession→policyDigest will be updated according to the setting of includeObject. If equal to |
| 13042 | YES, policySession→policyDigest is updated by: |
| 13043 | policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyDuplicationSelect || |
| 13044 | objectName || newParentName || includeObject) (31) |
| 13045 | If includeObject is NO, policySession→policyDigest is updated by: |
| 13046 | policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyDuplicationSelect || |
| 13047 | newParentName || includeObject) (32) |
| 13048 | |
| 13049 | NOTE 4 policySession→cpHash receives the digest of both Names so that the check performed in |
| 13050 | TPM2_Duplicate() may be the same regardless of which Names are included in |
| 13051 | policySession→policyDigest. This means that, when TPM2_PolicyDuplicationSelect() is executed, it |
| 13052 | is only valid for a specific pair of duplication object and new parent. |
| 13053 | |
| 13054 | If the command succeeds, policySession→commandCode is set to TPM_CC_Duplicate. |
| 13055 | |
| 13056 | NOTE 5 The normal use of this command is before a TPM2_PolicyAuthorize(). An authorized entity would |
| 13057 | approve a policyDigest that allowed duplication to a specific new parent. The authorizing entity may |
| 13058 | want to limit the authorization so that the approval allows on ly a specific object to be duplicated to |
| 13059 | the new parent. In that case, the authorizing entity would approve the policyDigest of equation (31). |
| 13060 | |
| 13061 | |
| 13062 | |
| 13063 | |
| 13064 | Family “2.0” TCG Published Page 287 |
| 13065 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 13066 | Part 3: Commands Trusted Platform Module Library |
| 13067 | |
| 13068 | |
| 13069 | 23.15.2 Command and Response |
| 13070 | |
| 13071 | Table 137 — TPM2_PolicyDuplicationSelect Command |
| 13072 | Type Name Description |
| 13073 | |
| 13074 | TPM_ST_SESSIONS if an audit or decrypt session is |
| 13075 | TPMI_ST_COMMAND_TAG tag |
| 13076 | present; otherwise, TPM_ST_NO_SESSIONS |
| 13077 | UINT32 commandSize |
| 13078 | TPM_CC commandCode TPM_CC_PolicyDuplicationSelect |
| 13079 | |
| 13080 | handle for the policy session being extended |
| 13081 | TPMI_SH_POLICY policySession |
| 13082 | Auth Index: None |
| 13083 | |
| 13084 | TPM2B_NAME objectName the Name of the object to be duplicated |
| 13085 | TPM2B_NAME newParentName the Name of the new parent |
| 13086 | if YES, the objectName will be included in the value in |
| 13087 | TPMI_YES_NO includeObject |
| 13088 | policySession→policyDigest |
| 13089 | |
| 13090 | |
| 13091 | Table 138 — TPM2_PolicyDuplicationSelect Response |
| 13092 | Type Name Description |
| 13093 | |
| 13094 | TPM_ST tag see clause 6 |
| 13095 | UINT32 responseSize |
| 13096 | TPM_RC responseCode |
| 13097 | |
| 13098 | |
| 13099 | |
| 13100 | |
| 13101 | Page 288 TCG Published Family “2.0” |
| 13102 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 13103 | Trusted Platform Module Library Part 3: Commands |
| 13104 | |
| 13105 | |
| 13106 | |
| 13107 | 23.15.3 Detailed Actions |
| 13108 | |
| 13109 | 1 #include "InternalRoutines.h" |
| 13110 | 2 #include "PolicyDuplicationSelect_fp.h" |
| 13111 | 3 #ifdef TPM_CC_PolicyDuplicationSelect // Conditional expansion of this file |
| 13112 | |
| 13113 | |
| 13114 | Error Returns Meaning |
| 13115 | |
| 13116 | TPM_RC_COMMAND_CODE commandCode of 'policySession; is not empty |
| 13117 | TPM_RC_CPHASH cpHash of policySession is not empty |
| 13118 | |
| 13119 | 4 TPM_RC |
| 13120 | 5 TPM2_PolicyDuplicationSelect( |
| 13121 | 6 PolicyDuplicationSelect_In *in // IN: input parameter list |
| 13122 | 7 ) |
| 13123 | 8 { |
| 13124 | 9 SESSION *session; |
| 13125 | 10 HASH_STATE hashState; |
| 13126 | 11 TPM_CC commandCode = TPM_CC_PolicyDuplicationSelect; |
| 13127 | 12 |
| 13128 | 13 // Input Validation |
| 13129 | 14 |
| 13130 | 15 // Get pointer to the session structure |
| 13131 | 16 session = SessionGet(in->policySession); |
| 13132 | 17 |
| 13133 | 18 // cpHash in session context must be empty |
| 13134 | 19 if(session->u1.cpHash.t.size != 0) |
| 13135 | 20 return TPM_RC_CPHASH; |
| 13136 | 21 |
| 13137 | 22 // commandCode in session context must be empty |
| 13138 | 23 if(session->commandCode != 0) |
| 13139 | 24 return TPM_RC_COMMAND_CODE; |
| 13140 | 25 |
| 13141 | 26 // Internal Data Update |
| 13142 | 27 |
| 13143 | 28 // Update name hash |
| 13144 | 29 session->u1.cpHash.t.size = CryptStartHash(session->authHashAlg, &hashState); |
| 13145 | 30 |
| 13146 | 31 // add objectName |
| 13147 | 32 CryptUpdateDigest2B(&hashState, &in->objectName.b); |
| 13148 | 33 |
| 13149 | 34 // add new parent name |
| 13150 | 35 CryptUpdateDigest2B(&hashState, &in->newParentName.b); |
| 13151 | 36 |
| 13152 | 37 // complete hash |
| 13153 | 38 CryptCompleteHash2B(&hashState, &session->u1.cpHash.b); |
| 13154 | 39 |
| 13155 | 40 // update policy hash |
| 13156 | 41 // Old policyDigest size should be the same as the new policyDigest size since |
| 13157 | 42 // they are using the same hash algorithm |
| 13158 | 43 session->u2.policyDigest.t.size |
| 13159 | 44 = CryptStartHash(session->authHashAlg, &hashState); |
| 13160 | 45 |
| 13161 | 46 // add old policy |
| 13162 | 47 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); |
| 13163 | 48 |
| 13164 | 49 // add command code |
| 13165 | 50 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); |
| 13166 | 51 |
| 13167 | 52 // add objectName |
| 13168 | 53 if(in->includeObject == YES) |
| 13169 | 54 CryptUpdateDigest2B(&hashState, &in->objectName.b); |
| 13170 | |
| 13171 | Family “2.0” TCG Published Page 289 |
| 13172 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 13173 | Part 3: Commands Trusted Platform Module Library |
| 13174 | |
| 13175 | 55 |
| 13176 | 56 // add new parent name |
| 13177 | 57 CryptUpdateDigest2B(&hashState, &in->newParentName.b); |
| 13178 | 58 |
| 13179 | 59 // add includeObject |
| 13180 | 60 CryptUpdateDigestInt(&hashState, sizeof(TPMI_YES_NO), &in->includeObject); |
| 13181 | 61 |
| 13182 | 62 // complete digest |
| 13183 | 63 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); |
| 13184 | 64 |
| 13185 | 65 // clear iscpHashDefined bit to indicate now this field contains a nameHash |
| 13186 | 66 session->attributes.iscpHashDefined = CLEAR; |
| 13187 | 67 |
| 13188 | 68 // set commandCode in session context |
| 13189 | 69 session->commandCode = TPM_CC_Duplicate; |
| 13190 | 70 |
| 13191 | 71 return TPM_RC_SUCCESS; |
| 13192 | 72 } |
| 13193 | 73 #endif // CC_PolicyDuplicationSelect |
| 13194 | |
| 13195 | |
| 13196 | |
| 13197 | |
| 13198 | Page 290 TCG Published Family “2.0” |
| 13199 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 13200 | Trusted Platform Module Library Part 3: Commands |
| 13201 | |
| 13202 | |
| 13203 | 23.16 TPM2_PolicyAuthorize |
| 13204 | |
| 13205 | 23.16.1 General Description |
| 13206 | |
| 13207 | This command allows policies to change. If a policy were static, then it would be difficult to add users to a |
| 13208 | policy. This command lets a policy authority sign a new policy so that it may be used in an existing policy. |
| 13209 | The authorizing entity signs a structure that contains |
| 13210 | aHash ≔ HaHashAlg(approvedPolicy || policyRef) (33) |
| 13211 | The aHashAlg is required to be the nameAlg of the key used to sign the aHash. The aHash value is then |
| 13212 | signed (symmetric or asymmetric) by keySign. That signature is then checked by the TPM in |
| 13213 | TPM2_VerifySignature() which produces a ticket by |
| 13214 | HMAC(proof, (TPM_ST_VERIFIED || aHash || keySign→Name)) (34) |
| 13215 | |
| 13216 | NOTE 1 The reason for the validation is because of the expectation that the policy will be used multiple times |
| 13217 | and it is more efficient to check a ticket than to load an object each time to check a signature. |
| 13218 | |
| 13219 | The ticket is then used in TPM2_PolicyAuthorize() to validate the parameters. |
| 13220 | The keySign parameter is required to be a valid object name using nameAlg other than TPM_ALG_NULL. |
| 13221 | If the first two octets of keySign are not a valid hash algorithm, the TPM shall return TPM_RC_HASH. If |
| 13222 | the remainder of the Name is not the size of the indicated digest, the TPM shall return TPM_RC_SIZE. |
| 13223 | The TPM validates that the approvedPolicy matches the current value of policySession→policyDigest and |
| 13224 | if not, shall return TPM_RC_VALUE. |
| 13225 | The TPM then validates that the parameters to TPM2_PolicyAuthorize() match the values used to |
| 13226 | generate the ticket. If so, the TPM will reset policySession→policyDigest to a Zero Digest. Then it will |
| 13227 | update policySession→policyDigest with PolicyUpdate() (see 23.2.3). |
| 13228 | PolicyUpdate(TPM_CC_PolicyAuthorize, keySign, policyRef) (35) |
| 13229 | If the ticket is not valid, the TPM shall return TPM_RC_POLICY. |
| 13230 | If policySession is a trial session, policySession→policyDigest is extended as if the ticket is valid without |
| 13231 | actual verification. |
| 13232 | |
| 13233 | NOTE 2 The unmarshaling process requires that a proper TPMT_TK_VERIFIED be provided for checkTicket |
| 13234 | but it may be a NULL Ticket. A NULL ticket is useful in a trial policy, where the caller uses the TPM |
| 13235 | to perform policy calculations but does not have a valid authorization ticket. |
| 13236 | |
| 13237 | |
| 13238 | |
| 13239 | |
| 13240 | Family “2.0” TCG Published Page 291 |
| 13241 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 13242 | Part 3: Commands Trusted Platform Module Library |
| 13243 | |
| 13244 | |
| 13245 | 23.16.2 Command and Response |
| 13246 | |
| 13247 | Table 139 — TPM2_PolicyAuthorize Command |
| 13248 | Type Name Description |
| 13249 | |
| 13250 | TPM_ST_SESSIONS if an audit or decrypt session is |
| 13251 | TPMI_ST_COMMAND_TAG tag |
| 13252 | present; otherwise, TPM_ST_NO_SESSIONS |
| 13253 | UINT32 commandSize |
| 13254 | TPM_CC commandCode TPM_CC_PolicyAuthorize |
| 13255 | |
| 13256 | handle for the policy session being extended |
| 13257 | TPMI_SH_POLICY policySession |
| 13258 | Auth Index: None |
| 13259 | |
| 13260 | TPM2B_DIGEST approvedPolicy digest of the policy being approved |
| 13261 | TPM2B_NONCE policyRef a policy qualifier |
| 13262 | TPM2B_NAME keySign Name of a key that can sign a policy addition |
| 13263 | ticket validating that approvedPolicy and policyRef were |
| 13264 | TPMT_TK_VERIFIED checkTicket |
| 13265 | signed by keySign |
| 13266 | |
| 13267 | |
| 13268 | Table 140 — TPM2_PolicyAuthorize Response |
| 13269 | Type Name Description |
| 13270 | |
| 13271 | TPM_ST tag see clause 6 |
| 13272 | UINT32 responseSize |
| 13273 | TPM_RC responseCode |
| 13274 | |
| 13275 | |
| 13276 | |
| 13277 | |
| 13278 | Page 292 TCG Published Family “2.0” |
| 13279 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 13280 | Trusted Platform Module Library Part 3: Commands |
| 13281 | |
| 13282 | |
| 13283 | |
| 13284 | 23.16.3 Detailed Actions |
| 13285 | |
| 13286 | 1 #include "InternalRoutines.h" |
| 13287 | 2 #include "PolicyAuthorize_fp.h" |
| 13288 | 3 #ifdef TPM_CC_PolicyAuthorize // Conditional expansion of this file |
| 13289 | 4 #include "Policy_spt_fp.h" |
| 13290 | |
| 13291 | |
| 13292 | Error Returns Meaning |
| 13293 | |
| 13294 | TPM_RC_HASH hash algorithm in keyName is not supported |
| 13295 | TPM_RC_SIZE keyName is not the correct size for its hash algorithm |
| 13296 | TPM_RC_VALUE the current policyDigest of policySession does not match |
| 13297 | approvedPolicy; or checkTicket doesn't match the provided values |
| 13298 | |
| 13299 | 5 TPM_RC |
| 13300 | 6 TPM2_PolicyAuthorize( |
| 13301 | 7 PolicyAuthorize_In *in // IN: input parameter list |
| 13302 | 8 ) |
| 13303 | 9 { |
| 13304 | 10 SESSION *session; |
| 13305 | 11 TPM2B_DIGEST authHash; |
| 13306 | 12 HASH_STATE hashState; |
| 13307 | 13 TPMT_TK_VERIFIED ticket; |
| 13308 | 14 TPM_ALG_ID hashAlg; |
| 13309 | 15 UINT16 digestSize; |
| 13310 | 16 |
| 13311 | 17 // Input Validation |
| 13312 | 18 |
| 13313 | 19 // Get pointer to the session structure |
| 13314 | 20 session = SessionGet(in->policySession); |
| 13315 | 21 |
| 13316 | 22 // Extract from the Name of the key, the algorithm used to compute it's Name |
| 13317 | 23 hashAlg = BYTE_ARRAY_TO_UINT16(in->keySign.t.name); |
| 13318 | 24 |
| 13319 | 25 // 'keySign' parameter needs to use a supported hash algorithm, otherwise |
| 13320 | 26 // can't tell how large the digest should be |
| 13321 | 27 digestSize = CryptGetHashDigestSize(hashAlg); |
| 13322 | 28 if(digestSize == 0) |
| 13323 | 29 return TPM_RC_HASH + RC_PolicyAuthorize_keySign; |
| 13324 | 30 |
| 13325 | 31 if(digestSize != (in->keySign.t.size - 2)) |
| 13326 | 32 return TPM_RC_SIZE + RC_PolicyAuthorize_keySign; |
| 13327 | 33 |
| 13328 | 34 //If this is a trial policy, skip all validations |
| 13329 | 35 if(session->attributes.isTrialPolicy == CLEAR) |
| 13330 | 36 { |
| 13331 | 37 // Check that "approvedPolicy" matches the current value of the |
| 13332 | 38 // policyDigest in policy session |
| 13333 | 39 if(!Memory2BEqual(&session->u2.policyDigest.b, |
| 13334 | 40 &in->approvedPolicy.b)) |
| 13335 | 41 return TPM_RC_VALUE + RC_PolicyAuthorize_approvedPolicy; |
| 13336 | 42 |
| 13337 | 43 // Validate ticket TPMT_TK_VERIFIED |
| 13338 | 44 // Compute aHash. The authorizing object sign a digest |
| 13339 | 45 // aHash := hash(approvedPolicy || policyRef). |
| 13340 | 46 // Start hash |
| 13341 | 47 authHash.t.size = CryptStartHash(hashAlg, &hashState); |
| 13342 | 48 |
| 13343 | 49 // add approvedPolicy |
| 13344 | 50 CryptUpdateDigest2B(&hashState, &in->approvedPolicy.b); |
| 13345 | 51 |
| 13346 | |
| 13347 | Family “2.0” TCG Published Page 293 |
| 13348 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 13349 | Part 3: Commands Trusted Platform Module Library |
| 13350 | |
| 13351 | 52 // add policyRef |
| 13352 | 53 CryptUpdateDigest2B(&hashState, &in->policyRef.b); |
| 13353 | 54 |
| 13354 | 55 // complete hash |
| 13355 | 56 CryptCompleteHash2B(&hashState, &authHash.b); |
| 13356 | 57 |
| 13357 | 58 // re-compute TPMT_TK_VERIFIED |
| 13358 | 59 TicketComputeVerified(in->checkTicket.hierarchy, &authHash, |
| 13359 | 60 &in->keySign, &ticket); |
| 13360 | 61 |
| 13361 | 62 // Compare ticket digest. If not match, return error |
| 13362 | 63 if(!Memory2BEqual(&in->checkTicket.digest.b, &ticket.digest.b)) |
| 13363 | 64 return TPM_RC_VALUE+ RC_PolicyAuthorize_checkTicket; |
| 13364 | 65 } |
| 13365 | 66 |
| 13366 | 67 // Internal Data Update |
| 13367 | 68 |
| 13368 | 69 // Set policyDigest to zero digest |
| 13369 | 70 MemorySet(session->u2.policyDigest.t.buffer, 0, |
| 13370 | 71 session->u2.policyDigest.t.size); |
| 13371 | 72 |
| 13372 | 73 // Update policyDigest |
| 13373 | 74 PolicyContextUpdate(TPM_CC_PolicyAuthorize, &in->keySign, &in->policyRef, |
| 13374 | 75 NULL, 0, session); |
| 13375 | 76 |
| 13376 | 77 return TPM_RC_SUCCESS; |
| 13377 | 78 |
| 13378 | 79 } |
| 13379 | 80 #endif // CC_PolicyAuthorize |
| 13380 | |
| 13381 | |
| 13382 | |
| 13383 | |
| 13384 | Page 294 TCG Published Family “2.0” |
| 13385 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 13386 | Trusted Platform Module Library Part 3: Commands |
| 13387 | |
| 13388 | |
| 13389 | 23.17 TPM2_PolicyAuthValue |
| 13390 | |
| 13391 | 23.17.1 General Description |
| 13392 | |
| 13393 | This command allows a policy to be bound to the authorization value of the authorized object. |
| 13394 | When this command completes successfully, policySession→isAuthValueNeeded is SET to indicate that |
| 13395 | the authValue will be included in hmacKey when the authorization HMAC is computed for the command |
| 13396 | being authorized using this session. Additionally, policySession→isPasswordNeeded will be CLEAR. |
| 13397 | |
| 13398 | NOTE If a policy does not use this command, then the hmacKey for the authorized command would only |
| 13399 | use sessionKey. If sessionKey is not present, then the hmacKey is an Empty Buffer and no HMAC |
| 13400 | would be computed. |
| 13401 | |
| 13402 | If successful, policySession→policyDigest will be updated with |
| 13403 | policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyAuthValue) (36) |
| 13404 | |
| 13405 | |
| 13406 | |
| 13407 | |
| 13408 | Family “2.0” TCG Published Page 295 |
| 13409 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 13410 | Part 3: Commands Trusted Platform Module Library |
| 13411 | |
| 13412 | |
| 13413 | |
| 13414 | 23.17.2 Command and Response |
| 13415 | |
| 13416 | Table 141 — TPM2_PolicyAuthValue Command |
| 13417 | Type Name Description |
| 13418 | |
| 13419 | TPM_ST_SESSIONS if an audit session is present; |
| 13420 | TPMI_ST_COMMAND_TAG tag |
| 13421 | otherwise, TPM_ST_NO_SESSIONS |
| 13422 | UINT32 commandSize |
| 13423 | TPM_CC commandCode TPM_CC_PolicyAuthValue |
| 13424 | |
| 13425 | handle for the policy session being extended |
| 13426 | TPMI_SH_POLICY policySession |
| 13427 | Auth Index: None |
| 13428 | |
| 13429 | |
| 13430 | Table 142 — TPM2_PolicyAuthValue Response |
| 13431 | Type Name Description |
| 13432 | |
| 13433 | TPM_ST tag see clause 6 |
| 13434 | UINT32 responseSize |
| 13435 | TPM_RC responseCode |
| 13436 | |
| 13437 | |
| 13438 | |
| 13439 | |
| 13440 | Page 296 TCG Published Family “2.0” |
| 13441 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 13442 | Trusted Platform Module Library Part 3: Commands |
| 13443 | |
| 13444 | |
| 13445 | |
| 13446 | 23.17.3 Detailed Actions |
| 13447 | |
| 13448 | 1 #include "InternalRoutines.h" |
| 13449 | 2 #include "PolicyAuthValue_fp.h" |
| 13450 | 3 #ifdef TPM_CC_PolicyAuthValue // Conditional expansion of this file |
| 13451 | 4 #include "Policy_spt_fp.h" |
| 13452 | 5 TPM_RC |
| 13453 | 6 TPM2_PolicyAuthValue( |
| 13454 | 7 PolicyAuthValue_In *in // IN: input parameter list |
| 13455 | 8 ) |
| 13456 | 9 { |
| 13457 | 10 SESSION *session; |
| 13458 | 11 TPM_CC commandCode = TPM_CC_PolicyAuthValue; |
| 13459 | 12 HASH_STATE hashState; |
| 13460 | 13 |
| 13461 | 14 // Internal Data Update |
| 13462 | 15 |
| 13463 | 16 // Get pointer to the session structure |
| 13464 | 17 session = SessionGet(in->policySession); |
| 13465 | 18 |
| 13466 | 19 // Update policy hash |
| 13467 | 20 // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyAuthValue) |
| 13468 | 21 // Start hash |
| 13469 | 22 CryptStartHash(session->authHashAlg, &hashState); |
| 13470 | 23 |
| 13471 | 24 // add old digest |
| 13472 | 25 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); |
| 13473 | 26 |
| 13474 | 27 // add commandCode |
| 13475 | 28 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); |
| 13476 | 29 |
| 13477 | 30 // complete the hash and get the results |
| 13478 | 31 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); |
| 13479 | 32 |
| 13480 | 33 // update isAuthValueNeeded bit in the session context |
| 13481 | 34 session->attributes.isAuthValueNeeded = SET; |
| 13482 | 35 session->attributes.isPasswordNeeded = CLEAR; |
| 13483 | 36 |
| 13484 | 37 return TPM_RC_SUCCESS; |
| 13485 | 38 } |
| 13486 | 39 #endif // CC_PolicyAuthValue |
| 13487 | |
| 13488 | |
| 13489 | |
| 13490 | |
| 13491 | Family “2.0” TCG Published Page 297 |
| 13492 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 13493 | Part 3: Commands Trusted Platform Module Library |
| 13494 | |
| 13495 | |
| 13496 | 23.18 TPM2_PolicyPassword |
| 13497 | |
| 13498 | 23.18.1 General Description |
| 13499 | |
| 13500 | This command allows a policy to be bound to the authorization value of the authorized object. |
| 13501 | When this command completes successfully, policySession→isPasswordNeeded is SET to indicate that |
| 13502 | authValue of the authorized object will be checked when the session is used for authorization. The caller |
| 13503 | will provide the authValue in clear text in the hmac parameter of the authorization. The comparison of |
| 13504 | hmac to authValue is performed as if the authorization is a password. |
| 13505 | |
| 13506 | NOTE 1 The parameter field in the policy session where the authorization value is provided is called hmac. If |
| 13507 | TPM2_PolicyPassword() is part of the sequence, then the field will c ontain a password and not an |
| 13508 | HMAC. |
| 13509 | |
| 13510 | If successful, policySession→policyDigest will be updated with |
| 13511 | policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyAuthValue) (37) |
| 13512 | |
| 13513 | NOTE 2 This is the same extend value as used with TPM2_PolicyAuthValue so that the evaluation may be |
| 13514 | done using either an HMAC or a password with no change to the authPolicy of the object. The |
| 13515 | reason that two commands are present is to indicate to the TPM if the hmac field in the authorization |
| 13516 | will contain an HMAC or a password value. |
| 13517 | |
| 13518 | When this command is successful, policySession→isAuthValueNeeded will be CLEAR. |
| 13519 | |
| 13520 | |
| 13521 | |
| 13522 | |
| 13523 | Page 298 TCG Published Family “2.0” |
| 13524 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 13525 | Trusted Platform Module Library Part 3: Commands |
| 13526 | |
| 13527 | |
| 13528 | |
| 13529 | 23.18.2 Command and Response |
| 13530 | |
| 13531 | Table 143 — TPM2_PolicyPassword Command |
| 13532 | Type Name Description |
| 13533 | |
| 13534 | TPM_ST_SESSIONS if an audit session is present; |
| 13535 | TPMI_ST_COMMAND_TAG tag |
| 13536 | otherwise, TPM_ST_NO_SESSIONS |
| 13537 | UINT32 commandSize |
| 13538 | TPM_CC commandCode TPM_CC_PolicyPassword |
| 13539 | |
| 13540 | handle for the policy session being extended |
| 13541 | TPMI_SH_POLICY policySession |
| 13542 | Auth Index: None |
| 13543 | |
| 13544 | |
| 13545 | Table 144 — TPM2_PolicyPassword Response |
| 13546 | Type Name Description |
| 13547 | |
| 13548 | TPM_ST tag see clause 6 |
| 13549 | UINT32 responseSize |
| 13550 | TPM_RC responseCode |
| 13551 | |
| 13552 | |
| 13553 | |
| 13554 | |
| 13555 | Family “2.0” TCG Published Page 299 |
| 13556 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 13557 | Part 3: Commands Trusted Platform Module Library |
| 13558 | |
| 13559 | |
| 13560 | |
| 13561 | 23.18.3 Detailed Actions |
| 13562 | |
| 13563 | 1 #include "InternalRoutines.h" |
| 13564 | 2 #include "PolicyPassword_fp.h" |
| 13565 | 3 #ifdef TPM_CC_PolicyPassword // Conditional expansion of this file |
| 13566 | 4 #include "Policy_spt_fp.h" |
| 13567 | 5 TPM_RC |
| 13568 | 6 TPM2_PolicyPassword( |
| 13569 | 7 PolicyPassword_In *in // IN: input parameter list |
| 13570 | 8 ) |
| 13571 | 9 { |
| 13572 | 10 SESSION *session; |
| 13573 | 11 TPM_CC commandCode = TPM_CC_PolicyAuthValue; |
| 13574 | 12 HASH_STATE hashState; |
| 13575 | 13 |
| 13576 | 14 // Internal Data Update |
| 13577 | 15 |
| 13578 | 16 // Get pointer to the session structure |
| 13579 | 17 session = SessionGet(in->policySession); |
| 13580 | 18 |
| 13581 | 19 // Update policy hash |
| 13582 | 20 // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyAuthValue) |
| 13583 | 21 // Start hash |
| 13584 | 22 CryptStartHash(session->authHashAlg, &hashState); |
| 13585 | 23 |
| 13586 | 24 // add old digest |
| 13587 | 25 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); |
| 13588 | 26 |
| 13589 | 27 // add commandCode |
| 13590 | 28 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); |
| 13591 | 29 |
| 13592 | 30 // complete the digest |
| 13593 | 31 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); |
| 13594 | 32 |
| 13595 | 33 // Update isPasswordNeeded bit |
| 13596 | 34 session->attributes.isPasswordNeeded = SET; |
| 13597 | 35 session->attributes.isAuthValueNeeded = CLEAR; |
| 13598 | 36 |
| 13599 | 37 return TPM_RC_SUCCESS; |
| 13600 | 38 } |
| 13601 | 39 #endif // CC_PolicyPassword |
| 13602 | |
| 13603 | |
| 13604 | |
| 13605 | |
| 13606 | Page 300 TCG Published Family “2.0” |
| 13607 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 13608 | Trusted Platform Module Library Part 3: Commands |
| 13609 | |
| 13610 | |
| 13611 | 23.19 TPM2_PolicyGetDigest |
| 13612 | |
| 13613 | 23.19.1 General Description |
| 13614 | |
| 13615 | This command returns the current policyDigest of the session. This command allows the TPM to be used |
| 13616 | to perform the actions required to pre-compute the authPolicy for an object. |
| 13617 | |
| 13618 | |
| 13619 | |
| 13620 | |
| 13621 | Family “2.0” TCG Published Page 301 |
| 13622 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 13623 | Part 3: Commands Trusted Platform Module Library |
| 13624 | |
| 13625 | |
| 13626 | |
| 13627 | 23.19.2 Command and Response |
| 13628 | |
| 13629 | Table 145 — TPM2_PolicyGetDigest Command |
| 13630 | Type Name Description |
| 13631 | |
| 13632 | TPM_ST_SESSIONS if an audit or encrypt session is |
| 13633 | TPMI_ST_COMMAND_TAG tag |
| 13634 | present; otherwise, TPM_ST_NO_SESSIONS |
| 13635 | UINT32 commandSize |
| 13636 | TPM_CC commandCode TPM_CC_PolicyGetDigest |
| 13637 | |
| 13638 | handle for the policy session |
| 13639 | TPMI_SH_POLICY policySession |
| 13640 | Auth Index: None |
| 13641 | |
| 13642 | |
| 13643 | Table 146 — TPM2_PolicyGetDigest Response |
| 13644 | Type Name Description |
| 13645 | |
| 13646 | TPM_ST tag see clause 6 |
| 13647 | UINT32 responseSize |
| 13648 | TPM_RC responseCode |
| 13649 | |
| 13650 | TPM2B_DIGEST policyDigest the current value of the policySession→policyDigest |
| 13651 | |
| 13652 | |
| 13653 | |
| 13654 | |
| 13655 | Page 302 TCG Published Family “2.0” |
| 13656 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 13657 | Trusted Platform Module Library Part 3: Commands |
| 13658 | |
| 13659 | |
| 13660 | |
| 13661 | 23.19.3 Detailed Actions |
| 13662 | |
| 13663 | 1 #include "InternalRoutines.h" |
| 13664 | 2 #include "PolicyGetDigest_fp.h" |
| 13665 | 3 #ifdef TPM_CC_PolicyGetDigest // Conditional expansion of this file |
| 13666 | 4 TPM_RC |
| 13667 | 5 TPM2_PolicyGetDigest( |
| 13668 | 6 PolicyGetDigest_In *in, // IN: input parameter list |
| 13669 | 7 PolicyGetDigest_Out *out // OUT: output parameter list |
| 13670 | 8 ) |
| 13671 | 9 { |
| 13672 | 10 SESSION *session; |
| 13673 | 11 |
| 13674 | 12 // Command Output |
| 13675 | 13 |
| 13676 | 14 // Get pointer to the session structure |
| 13677 | 15 session = SessionGet(in->policySession); |
| 13678 | 16 |
| 13679 | 17 out->policyDigest = session->u2.policyDigest; |
| 13680 | 18 |
| 13681 | 19 return TPM_RC_SUCCESS; |
| 13682 | 20 } |
| 13683 | 21 #endif // CC_PolicyGetDigest |
| 13684 | |
| 13685 | |
| 13686 | |
| 13687 | |
| 13688 | Family “2.0” TCG Published Page 303 |
| 13689 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 13690 | Part 3: Commands Trusted Platform Module Library |
| 13691 | |
| 13692 | |
| 13693 | 23.20 TPM2_PolicyNvWritten |
| 13694 | |
| 13695 | 23.20.1 General Description |
| 13696 | |
| 13697 | This command allows a policy to be bound to the TPMA_NV_WRITTEN attributes. This is a deferred |
| 13698 | assertion. Values are stored in the policy session context and checked when the policy is used for |
| 13699 | authorization. |
| 13700 | If policySession→checkNVWritten is CLEAR, it is SET and policySession→nvWrittenState is set to |
| 13701 | writtenSet. If policySession→checkNVWritten is SET, the TPM will return TPM_RC_VALUE if |
| 13702 | policySession→nvWrittenState and writtenSet are not the same. |
| 13703 | If the TPM does not return an error, it will update policySession→policyDigest by |
| 13704 | policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyNvWritten || writtenSet) (38) |
| 13705 | When the policy session is used to authorize a command, the TPM will fail the command if |
| 13706 | policySession→checkNVWritten is SET and nvIndex→attributes→TPMA_NV_WRITTEN does not match |
| 13707 | policySession→nvWrittenState. |
| 13708 | |
| 13709 | NOTE 1 A typical use case is a simple policy for the first write during manufacturing provisioning that would |
| 13710 | require TPMA_NV_WRITTEN CLEAR and a more complex policy for later use that would require |
| 13711 | TPMA_NV_WRITTEN SET. |
| 13712 | |
| 13713 | NOTE 2 When an Index is written, it has a different authorization name than an Index that has not been |
| 13714 | written. It is possible to use this change in the NV Index to create a write-once Index. |
| 13715 | |
| 13716 | |
| 13717 | |
| 13718 | |
| 13719 | Page 304 TCG Published Family “2.0” |
| 13720 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 13721 | Trusted Platform Module Library Part 3: Commands |
| 13722 | |
| 13723 | |
| 13724 | 23.20.2 Command and Response |
| 13725 | |
| 13726 | Table 147 — TPM2_PolicyNvWritten Command |
| 13727 | Type Name Description |
| 13728 | |
| 13729 | TPM_ST_SESSIONS if an audit session is present; |
| 13730 | TPMI_ST_COMMAND_TAG tag |
| 13731 | otherwise, TPM_ST_NO_SESSIONS |
| 13732 | UINT32 commandSize |
| 13733 | TPM_CC commandCode TPM_CC_PolicyNVWritten |
| 13734 | |
| 13735 | handle for the policy session being extended |
| 13736 | TPMI_SH_POLICY policySession |
| 13737 | Auth Index: None |
| 13738 | |
| 13739 | YES if NV Index is required to have been written |
| 13740 | TPMI_YES_NO writtenSet |
| 13741 | NO if NV Index is required not to have been written |
| 13742 | |
| 13743 | |
| 13744 | Table 148 — TPM2_PolicyNvWritten Response |
| 13745 | Type Name Description |
| 13746 | |
| 13747 | TPM_ST tag see clause 6 |
| 13748 | UINT32 responseSize |
| 13749 | TPM_RC responseCode |
| 13750 | |
| 13751 | |
| 13752 | |
| 13753 | |
| 13754 | Family “2.0” TCG Published Page 305 |
| 13755 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 13756 | Part 3: Commands Trusted Platform Module Library |
| 13757 | |
| 13758 | |
| 13759 | |
| 13760 | 23.20.3 Detailed Actions |
| 13761 | |
| 13762 | 1 #include "InternalRoutines.h" |
| 13763 | 2 #include "PolicyNvWritten_fp.h" |
| 13764 | 3 #ifdef TPM_CC_PolicyNvWritten // Conditional expansion of this file |
| 13765 | |
| 13766 | Make an NV Index policy dependent on the state of the TPMA_NV_WRITTEN attribute of the index. |
| 13767 | |
| 13768 | Error Returns Meaning |
| 13769 | |
| 13770 | TPM_RC_VALUE a conflicting request for the attribute has already been processed |
| 13771 | |
| 13772 | 4 TPM_RC |
| 13773 | 5 TPM2_PolicyNvWritten( |
| 13774 | 6 PolicyNvWritten_In *in // IN: input parameter list |
| 13775 | 7 ) |
| 13776 | 8 { |
| 13777 | 9 SESSION *session; |
| 13778 | 10 TPM_CC commandCode = TPM_CC_PolicyNvWritten; |
| 13779 | 11 HASH_STATE hashState; |
| 13780 | 12 |
| 13781 | 13 // Input Validation |
| 13782 | 14 |
| 13783 | 15 // Get pointer to the session structure |
| 13784 | 16 session = SessionGet(in->policySession); |
| 13785 | 17 |
| 13786 | 18 // If already set is this a duplicate (the same setting)? If it |
| 13787 | 19 // is a conflicting setting, it is an error |
| 13788 | 20 if(session->attributes.checkNvWritten == SET) |
| 13789 | 21 { |
| 13790 | 22 if(( (session->attributes.nvWrittenState == SET) |
| 13791 | 23 != (in->writtenSet == YES))) |
| 13792 | 24 return TPM_RC_VALUE + RC_PolicyNvWritten_writtenSet; |
| 13793 | 25 } |
| 13794 | 26 |
| 13795 | 27 // Internal Data Update |
| 13796 | 28 |
| 13797 | 29 // Set session attributes so that the NV Index needs to be checked |
| 13798 | 30 session->attributes.checkNvWritten = SET; |
| 13799 | 31 session->attributes.nvWrittenState = (in->writtenSet == YES); |
| 13800 | 32 |
| 13801 | 33 // Update policy hash |
| 13802 | 34 // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyNvWritten |
| 13803 | 35 // || writtenSet) |
| 13804 | 36 // Start hash |
| 13805 | 37 CryptStartHash(session->authHashAlg, &hashState); |
| 13806 | 38 |
| 13807 | 39 // add old digest |
| 13808 | 40 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b); |
| 13809 | 41 |
| 13810 | 42 // add commandCode |
| 13811 | 43 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode); |
| 13812 | 44 |
| 13813 | 45 // add the byte of writtenState |
| 13814 | 46 CryptUpdateDigestInt(&hashState, sizeof(TPMI_YES_NO), &in->writtenSet); |
| 13815 | 47 |
| 13816 | 48 // complete the digest |
| 13817 | 49 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b); |
| 13818 | 50 |
| 13819 | 51 return TPM_RC_SUCCESS; |
| 13820 | 52 } |
| 13821 | 53 #endif // CC_PolicyNvWritten |
| 13822 | |
| 13823 | |
| 13824 | Page 306 TCG Published Family “2.0” |
| 13825 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 13826 | Trusted Platform Module Library Part 3: Commands |
| 13827 | |
| 13828 | |
| 13829 | |
| 13830 | |
| 13831 | Family “2.0” TCG Published Page 307 |
| 13832 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 13833 | Part 3: Commands Trusted Platform Module Library |
| 13834 | |
| 13835 | |
| 13836 | |
| 13837 | 24 Hierarchy Commands |
| 13838 | |
| 13839 | 24.1 TPM2_CreatePrimary |
| 13840 | |
| 13841 | 24.1.1 General Description |
| 13842 | |
| 13843 | This command is used to create a Primary Object under one of the Primary Seeds or a Temporary Object |
| 13844 | under TPM_RH_NULL. The command uses a TPM2B_PUBLIC as a template for the object to be created. |
| 13845 | The command will create and load a Primary Object. The sensitive area is not returned. |
| 13846 | |
| 13847 | NOTE 1: Since the sensitive data is not returned, the key cannot be reloaded. It can either be made |
| 13848 | persistent or it can be recreated. |
| 13849 | |
| 13850 | Any type of object and attributes combination that is allowed by TPM2_Create() may be created by this |
| 13851 | command. The constraints on templates and parameters are the same as TPM2_Create() except that a |
| 13852 | Primary Storage Key and a Temporary Storage Key are not constrained to use the algorithms of their |
| 13853 | parents. |
| 13854 | For setting of the attributes of the created object, fixedParent, fixedTPM, decrypt, and restricted are |
| 13855 | implied to be SET in the parent (a Permanent Handle). The remaining attributes are implied to be CLEAR. |
| 13856 | The TPM will derive the object from the Primary Seed indicated in primaryHandle using an approved |
| 13857 | KDF. All of the bits of the template are used in the creation of the Primary Key. Methods for creating a |
| 13858 | Primary Object from a Primary Seed are described in TPM 2.0 Part 1 and implemented in TPM 2.0 Part 4. |
| 13859 | If this command is called multiple times with the same inPublic parameter, inSensitive.data, and Primary |
| 13860 | Seed, the TPM shall produce the same Primary Object. |
| 13861 | |
| 13862 | NOTE 2 If the Primary Seed is changed, the Primary Objects generated with the new seed shall be |
| 13863 | statistically unique even if the parameters of the call are the same. |
| 13864 | |
| 13865 | This command requires authorization. Authorization for a Primary Object attached to the Platform Primary |
| 13866 | Seed (PPS) shall be provided by platformAuth or platformPolicy. Authorization for a Primary Object |
| 13867 | attached to the Storage Primary Seed (SPS) shall be provided by ownerAuth or ownerPolicy. |
| 13868 | Authorization for a Primary Key attached to the Endorsement Primary Seed (EPS) shall be provided by |
| 13869 | endorsementAuth or endorsementPolicy. |
| 13870 | |
| 13871 | |
| 13872 | |
| 13873 | |
| 13874 | Page 308 TCG Published Family “2.0” |
| 13875 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 13876 | Trusted Platform Module Library Part 3: Commands |
| 13877 | |
| 13878 | |
| 13879 | |
| 13880 | 24.1.2 Command and Response |
| 13881 | |
| 13882 | Table 149 — TPM2_CreatePrimary Command |
| 13883 | Type Name Description |
| 13884 | |
| 13885 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 13886 | UINT32 commandSize |
| 13887 | TPM_CC commandCode TPM_CC_CreatePrimary |
| 13888 | |
| 13889 | TPM_RH_ENDORSEMENT, TPM_RH_OWNER, |
| 13890 | TPM_RH_PLATFORM+{PP}, or TPM_RH_NULL |
| 13891 | TPMI_RH_HIERARCHY+ @primaryHandle |
| 13892 | Auth Index: 1 |
| 13893 | Auth Role: USER |
| 13894 | |
| 13895 | TPM2B_SENSITIVE_CREATE inSensitive the sensitive data, see TPM 2.0 Part 1 Sensitive Values |
| 13896 | TPM2B_PUBLIC inPublic the public template |
| 13897 | data that will be included in the creation data for this |
| 13898 | TPM2B_DATA outsideInfo object to provide permanent, verifiable linkage between |
| 13899 | this object and some object owner data |
| 13900 | TPML_PCR_SELECTION creationPCR PCR that will be used in creation data |
| 13901 | |
| 13902 | |
| 13903 | Table 150 — TPM2_CreatePrimary Response |
| 13904 | Type Name Description |
| 13905 | |
| 13906 | TPM_ST tag see clause 6 |
| 13907 | UINT32 responseSize |
| 13908 | TPM_RC responseCode |
| 13909 | |
| 13910 | handle of type TPM_HT_TRANSIENT for created |
| 13911 | TPM_HANDLE objectHandle |
| 13912 | Primary Object |
| 13913 | |
| 13914 | TPM2B_PUBLIC outPublic the public portion of the created object |
| 13915 | TPM2B_CREATION_DATA creationData contains a TPMT_CREATION_DATA |
| 13916 | TPM2B_DIGEST creationHash digest of creationData using nameAlg of outPublic |
| 13917 | ticket used by TPM2_CertifyCreation() to validate that |
| 13918 | TPMT_TK_CREATION creationTicket |
| 13919 | the creation data was produced by the TPM |
| 13920 | TPM2B_NAME name the name of the created object |
| 13921 | |
| 13922 | |
| 13923 | |
| 13924 | |
| 13925 | Family “2.0” TCG Published Page 309 |
| 13926 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 13927 | Part 3: Commands Trusted Platform Module Library |
| 13928 | |
| 13929 | |
| 13930 | |
| 13931 | 24.1.3 Detailed Actions |
| 13932 | |
| 13933 | 1 #include "InternalRoutines.h" |
| 13934 | 2 #include "CreatePrimary_fp.h" |
| 13935 | 3 #ifdef TPM_CC_CreatePrimary // Conditional expansion of this file |
| 13936 | 4 #include "Object_spt_fp.h" |
| 13937 | 5 #include <Platform.h> |
| 13938 | |
| 13939 | |
| 13940 | Error Returns Meaning |
| 13941 | |
| 13942 | TPM_RC_ATTRIBUTES sensitiveDataOrigin is CLEAR when 'sensitive.data' is an Empty |
| 13943 | Buffer, or is SET when 'sensitive.data' is not empty; fixedTPM, |
| 13944 | fixedParent, or encryptedDuplication attributes are inconsistent |
| 13945 | between themselves or with those of the parent object; inconsistent |
| 13946 | restricted, decrypt and sign attributes; attempt to inject sensitive data |
| 13947 | for an asymmetric key; attempt to create a symmetric cipher key that |
| 13948 | is not a decryption key |
| 13949 | TPM_RC_KDF incorrect KDF specified for decrypting keyed hash object |
| 13950 | TPM_RC_OBJECT_MEMORY there is no free slot for the object |
| 13951 | TPM_RC_SCHEME inconsistent attributes decrypt, sign, restricted and key's scheme ID; |
| 13952 | or hash algorithm is inconsistent with the scheme ID for keyed hash |
| 13953 | object |
| 13954 | TPM_RC_SIZE size of public auth policy or sensitive auth value does not match |
| 13955 | digest size of the name algorithm sensitive data size for the keyed |
| 13956 | hash object is larger than is allowed for the scheme |
| 13957 | TPM_RC_SYMMETRIC a storage key with no symmetric algorithm specified; or non-storage |
| 13958 | key with symmetric algorithm different from TPM_ALG_NULL |
| 13959 | TPM_RC_TYPE unknown object type; |
| 13960 | |
| 13961 | 6 TPM_RC |
| 13962 | 7 TPM2_CreatePrimary( |
| 13963 | 8 CreatePrimary_In *in, // IN: input parameter list |
| 13964 | 9 CreatePrimary_Out *out // OUT: output parameter list |
| 13965 | 10 ) |
| 13966 | 11 { |
| 13967 | 12 // Local variables |
| 13968 | 13 TPM_RC result = TPM_RC_SUCCESS; |
| 13969 | 14 TPMT_SENSITIVE sensitive; |
| 13970 | 15 |
| 13971 | 16 // Input Validation |
| 13972 | 17 // The sensitiveDataOrigin attribute must be consistent with the setting of |
| 13973 | 18 // the size of the data object in inSensitive. |
| 13974 | 19 if( (in->inPublic.t.publicArea.objectAttributes.sensitiveDataOrigin == SET) |
| 13975 | 20 != (in->inSensitive.t.sensitive.data.t.size == 0 )) |
| 13976 | 21 // Mismatch between the object attributes and the parameter. |
| 13977 | 22 return TPM_RC_ATTRIBUTES + RC_CreatePrimary_inSensitive; |
| 13978 | 23 |
| 13979 | 24 // Check attributes in input public area. TPM_RC_ATTRIBUTES, TPM_RC_KDF, |
| 13980 | 25 // TPM_RC_SCHEME, TPM_RC_SIZE, TPM_RC_SYMMETRIC, or TPM_RC_TYPE error may |
| 13981 | 26 // be returned at this point. |
| 13982 | 27 result = PublicAttributesValidation(FALSE, in->primaryHandle, |
| 13983 | 28 &in->inPublic.t.publicArea); |
| 13984 | 29 if(result != TPM_RC_SUCCESS) |
| 13985 | 30 return RcSafeAddToResult(result, RC_CreatePrimary_inPublic); |
| 13986 | 31 |
| 13987 | 32 // Validate the sensitive area values |
| 13988 | 33 if( MemoryRemoveTrailingZeros(&in->inSensitive.t.sensitive.userAuth) |
| 13989 | 34 > CryptGetHashDigestSize(in->inPublic.t.publicArea.nameAlg)) |
| 13990 | |
| 13991 | |
| 13992 | Page 310 TCG Published Family “2.0” |
| 13993 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 13994 | Trusted Platform Module Library Part 3: Commands |
| 13995 | |
| 13996 | 35 return TPM_RC_SIZE + RC_CreatePrimary_inSensitive; |
| 13997 | 36 |
| 13998 | 37 // Command output |
| 13999 | 38 |
| 14000 | 39 // Generate Primary Object |
| 14001 | 40 // The primary key generation process uses the Name of the input public |
| 14002 | 41 // template to compute the key. The keys are generated from the template |
| 14003 | 42 // before anything in the template is allowed to be changed. |
| 14004 | 43 // A TPM_RC_KDF, TPM_RC_SIZE error may be returned at this point |
| 14005 | 44 result = CryptCreateObject(in->primaryHandle, &in->inPublic.t.publicArea, |
| 14006 | 45 &in->inSensitive.t.sensitive,&sensitive); |
| 14007 | 46 if(result != TPM_RC_SUCCESS) |
| 14008 | 47 return result; |
| 14009 | 48 |
| 14010 | 49 // Fill in creation data |
| 14011 | 50 FillInCreationData(in->primaryHandle, in->inPublic.t.publicArea.nameAlg, |
| 14012 | 51 &in->creationPCR, &in->outsideInfo, &out->creationData, |
| 14013 | 52 &out->creationHash); |
| 14014 | 53 |
| 14015 | 54 // Copy public area |
| 14016 | 55 out->outPublic = in->inPublic; |
| 14017 | 56 |
| 14018 | 57 // Fill in private area for output |
| 14019 | 58 ObjectComputeName(&(out->outPublic.t.publicArea), &out->name); |
| 14020 | 59 |
| 14021 | 60 // Compute creation ticket |
| 14022 | 61 TicketComputeCreation(EntityGetHierarchy(in->primaryHandle), &out->name, |
| 14023 | 62 &out->creationHash, &out->creationTicket); |
| 14024 | 63 |
| 14025 | 64 // Create a internal object. A TPM_RC_OBJECT_MEMORY error may be returned |
| 14026 | 65 // at this point. |
| 14027 | 66 result = ObjectLoad(in->primaryHandle, &in->inPublic.t.publicArea, &sensitive, |
| 14028 | 67 &out->name, in->primaryHandle, TRUE, &out->objectHandle); |
| 14029 | 68 |
| 14030 | 69 return result; |
| 14031 | 70 } |
| 14032 | 71 #endif // CC_CreatePrimary |
| 14033 | |
| 14034 | |
| 14035 | |
| 14036 | |
| 14037 | Family “2.0” TCG Published Page 311 |
| 14038 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 14039 | Part 3: Commands Trusted Platform Module Library |
| 14040 | |
| 14041 | |
| 14042 | 24.2 TPM2_HierarchyControl |
| 14043 | |
| 14044 | 24.2.1 General Description |
| 14045 | |
| 14046 | This command enables and disables use of a hierarchy and its associated NV storage. The command |
| 14047 | allows phEnable, phEnableNV, shEnable, and ehEnable to be changed when the proper authorization is |
| 14048 | provided. |
| 14049 | This command may be used to CLEAR phEnable and phEnableNV if platformAuth/platformPolicy is |
| 14050 | provided. phEnable may not be SET using this command. |
| 14051 | This command may be used to CLEAR shEnable if either platformAuth/platformPolicy or |
| 14052 | ownerAuth/ownerPolicy is provided. shEnable may be SET if platformAuth/platformPolicy is provided. |
| 14053 | This command may be used to CLEAR ehEnable if either platformAuth/platformPolicy or |
| 14054 | endorsementAuth/endorsementPolicy is provided. ehEnable may be SET if platformAuth/platformPolicy is |
| 14055 | provided. |
| 14056 | When this command is used to CLEAR phEnable, shEnable, or ehEnable, the TPM will disable use of |
| 14057 | any persistent entity associated with the disabled hierarchy and will flush any transient objects associated |
| 14058 | with the disabled hierarchy. |
| 14059 | When this command is used to CLEAR shEnable, the TPM will disable access to any NV index that has |
| 14060 | TPMA_NV_PLATFORMCREATE CLEAR (indicating that the NV Index was defined using Owner |
| 14061 | Authorization). As long as shEnable is CLEAR, the TPM will return an error in response to any command |
| 14062 | that attempts to operate upon an NV index that has TPMA_NV_PLATFORMCREATE CLEAR. |
| 14063 | When this command is used to CLEAR phEnableNV, the TPM will disable access to any NV index that |
| 14064 | has TPMA_NV_PLATFORMCREATE SET (indicating that the NV Index was defined using Platform |
| 14065 | Authorization). As long as phEnableNV is CLEAR, the TPM will return an error in response to any |
| 14066 | command that attempts to operate upon an NV index that has TPMA_NV_PLATFORMCREATE SET. |
| 14067 | |
| 14068 | |
| 14069 | |
| 14070 | |
| 14071 | Page 312 TCG Published Family “2.0” |
| 14072 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 14073 | Trusted Platform Module Library Part 3: Commands |
| 14074 | |
| 14075 | |
| 14076 | |
| 14077 | 24.2.2 Command and Response |
| 14078 | |
| 14079 | Table 151 — TPM2_HierarchyControl Command |
| 14080 | Type Name Description |
| 14081 | |
| 14082 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 14083 | |
| 14084 | UINT32 commandSize |
| 14085 | |
| 14086 | TPM_CC commandCode TPM_CC_HierarchyControl {NV E} |
| 14087 | |
| 14088 | TPM_RH_ENDORSEMENT, TPM_RH_OWNER or |
| 14089 | TPM_RH_PLATFORM+{PP} |
| 14090 | TPMI_RH_HIERARCHY @authHandle |
| 14091 | Auth Index: 1 |
| 14092 | Auth Role: USER |
| 14093 | |
| 14094 | the enable being modified |
| 14095 | TPMI_RH_ENABLES enable TPM_RH_ENDORSEMENT, TPM_RH_OWNER, |
| 14096 | TPM_RH_PLATFORM, or TPM_RH_PLATFORM_NV |
| 14097 | YES if the enable should be SET, NO if the enable |
| 14098 | TPMI_YES_NO state |
| 14099 | should be CLEAR |
| 14100 | |
| 14101 | |
| 14102 | Table 152 — TPM2_HierarchyControl Response |
| 14103 | Type Name Description |
| 14104 | |
| 14105 | TPM_ST tag see clause 6 |
| 14106 | |
| 14107 | UINT32 responseSize |
| 14108 | |
| 14109 | TPM_RC responseCode |
| 14110 | |
| 14111 | |
| 14112 | |
| 14113 | |
| 14114 | Family “2.0” TCG Published Page 313 |
| 14115 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 14116 | Part 3: Commands Trusted Platform Module Library |
| 14117 | |
| 14118 | |
| 14119 | |
| 14120 | 24.2.3 Detailed Actions |
| 14121 | |
| 14122 | 1 #include "InternalRoutines.h" |
| 14123 | 2 #include "HierarchyControl_fp.h" |
| 14124 | 3 #ifdef TPM_CC_HierarchyControl // Conditional expansion of this file |
| 14125 | |
| 14126 | |
| 14127 | Error Returns Meaning |
| 14128 | |
| 14129 | TPM_RC_AUTH_TYPE authHandle is not applicable to hierarchy in its current state |
| 14130 | |
| 14131 | 4 TPM_RC |
| 14132 | 5 TPM2_HierarchyControl( |
| 14133 | 6 HierarchyControl_In *in // IN: input parameter list |
| 14134 | 7 ) |
| 14135 | 8 { |
| 14136 | 9 TPM_RC result; |
| 14137 | 10 BOOL select = (in->state == YES); |
| 14138 | 11 BOOL *selected = NULL; |
| 14139 | 12 |
| 14140 | 13 // Input Validation |
| 14141 | 14 switch(in->enable) |
| 14142 | 15 { |
| 14143 | 16 // Platform hierarchy has to be disabled by platform auth |
| 14144 | 17 // If the platform hierarchy has already been disabled, only a reboot |
| 14145 | 18 // can enable it again |
| 14146 | 19 case TPM_RH_PLATFORM: |
| 14147 | 20 case TPM_RH_PLATFORM_NV: |
| 14148 | 21 if(in->authHandle != TPM_RH_PLATFORM) |
| 14149 | 22 return TPM_RC_AUTH_TYPE; |
| 14150 | 23 break; |
| 14151 | 24 |
| 14152 | 25 // ShEnable may be disabled if PlatformAuth/PlatformPolicy or |
| 14153 | 26 // OwnerAuth/OwnerPolicy is provided. If ShEnable is disabled, then it |
| 14154 | 27 // may only be enabled if PlatformAuth/PlatformPolicy is provided. |
| 14155 | 28 case TPM_RH_OWNER: |
| 14156 | 29 if( in->authHandle != TPM_RH_PLATFORM |
| 14157 | 30 && in->authHandle != TPM_RH_OWNER) |
| 14158 | 31 return TPM_RC_AUTH_TYPE; |
| 14159 | 32 if( gc.shEnable == FALSE && in->state == YES |
| 14160 | 33 && in->authHandle != TPM_RH_PLATFORM) |
| 14161 | 34 return TPM_RC_AUTH_TYPE; |
| 14162 | 35 break; |
| 14163 | 36 |
| 14164 | 37 // EhEnable may be disabled if either PlatformAuth/PlatformPolicy or |
| 14165 | 38 // EndosementAuth/EndorsementPolicy is provided. If EhEnable is disabled, |
| 14166 | 39 // then it may only be enabled if PlatformAuth/PlatformPolicy is |
| 14167 | 40 // provided. |
| 14168 | 41 case TPM_RH_ENDORSEMENT: |
| 14169 | 42 if( in->authHandle != TPM_RH_PLATFORM |
| 14170 | 43 && in->authHandle != TPM_RH_ENDORSEMENT) |
| 14171 | 44 return TPM_RC_AUTH_TYPE; |
| 14172 | 45 if( gc.ehEnable == FALSE && in->state == YES |
| 14173 | 46 && in->authHandle != TPM_RH_PLATFORM) |
| 14174 | 47 return TPM_RC_AUTH_TYPE; |
| 14175 | 48 break; |
| 14176 | 49 default: |
| 14177 | 50 pAssert(FALSE); |
| 14178 | 51 break; |
| 14179 | 52 } |
| 14180 | 53 |
| 14181 | 54 // Internal Data Update |
| 14182 | 55 |
| 14183 | 56 // Enable or disable the selected hierarchy |
| 14184 | |
| 14185 | Page 314 TCG Published Family “2.0” |
| 14186 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 14187 | Trusted Platform Module Library Part 3: Commands |
| 14188 | |
| 14189 | 57 // Note: the authorization processing for this command may keep these |
| 14190 | 58 // command actions from being executed. For example, if phEnable is |
| 14191 | 59 // CLEAR, then platformAuth cannot be used for authorization. This |
| 14192 | 60 // means that would not be possible to use platformAuth to change the |
| 14193 | 61 // state of phEnable from CLEAR to SET. |
| 14194 | 62 // If it is decided that platformPolicy can still be used when phEnable |
| 14195 | 63 // is CLEAR, then this code could SET phEnable when proper platform |
| 14196 | 64 // policy is provided. |
| 14197 | 65 switch(in->enable) |
| 14198 | 66 { |
| 14199 | 67 case TPM_RH_OWNER: |
| 14200 | 68 selected = &gc.shEnable; |
| 14201 | 69 break; |
| 14202 | 70 case TPM_RH_ENDORSEMENT: |
| 14203 | 71 selected = &gc.ehEnable; |
| 14204 | 72 break; |
| 14205 | 73 case TPM_RH_PLATFORM: |
| 14206 | 74 selected = &g_phEnable; |
| 14207 | 75 break; |
| 14208 | 76 case TPM_RH_PLATFORM_NV: |
| 14209 | 77 selected = &gc.phEnableNV; |
| 14210 | 78 break; |
| 14211 | 79 default: |
| 14212 | 80 pAssert(FALSE); |
| 14213 | 81 break; |
| 14214 | 82 } |
| 14215 | 83 if(selected != NULL && *selected != select) |
| 14216 | 84 { |
| 14217 | 85 // Before changing the internal state, make sure that NV is available. |
| 14218 | 86 // Only need to update NV if changing the orderly state |
| 14219 | 87 if(gp.orderlyState != SHUTDOWN_NONE) |
| 14220 | 88 { |
| 14221 | 89 // The command needs NV update. Check if NV is available. |
| 14222 | 90 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at |
| 14223 | 91 // this point |
| 14224 | 92 result = NvIsAvailable(); |
| 14225 | 93 if(result != TPM_RC_SUCCESS) |
| 14226 | 94 return result; |
| 14227 | 95 } |
| 14228 | 96 // state is changing and NV is available so modify |
| 14229 | 97 *selected = select; |
| 14230 | 98 // If a hierarchy was just disabled, flush it |
| 14231 | 99 if(select == CLEAR && in->enable != TPM_RH_PLATFORM_NV) |
| 14232 | 100 // Flush hierarchy |
| 14233 | 101 ObjectFlushHierarchy(in->enable); |
| 14234 | 102 |
| 14235 | 103 // orderly state should be cleared because of the update to state clear data |
| 14236 | 104 // This gets processed in ExecuteCommand() on the way out. |
| 14237 | 105 g_clearOrderly = TRUE; |
| 14238 | 106 } |
| 14239 | 107 return TPM_RC_SUCCESS; |
| 14240 | 108 } |
| 14241 | 109 #endif // CC_HierarchyControl |
| 14242 | |
| 14243 | |
| 14244 | |
| 14245 | |
| 14246 | Family “2.0” TCG Published Page 315 |
| 14247 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 14248 | Part 3: Commands Trusted Platform Module Library |
| 14249 | |
| 14250 | |
| 14251 | 24.3 TPM2_SetPrimaryPolicy |
| 14252 | |
| 14253 | 24.3.1 General Description |
| 14254 | |
| 14255 | This command allows setting of the authorization policy for the lockout (lockoutPolicy), the platform |
| 14256 | hierarchy (platformPolicy), the storage hierarchy (ownerPolicy), and the endorsement hierarchy |
| 14257 | (endorsementPolicy). |
| 14258 | The command requires an authorization session. The session shall use the current authValue or satisfy |
| 14259 | the current authPolicy for the referenced hierarchy. |
| 14260 | The policy that is changed is the policy associated with authHandle. |
| 14261 | If the enable associated with authHandle is not SET, then the associated authorization values (authValue |
| 14262 | or authPolicy) may not be used. |
| 14263 | |
| 14264 | |
| 14265 | |
| 14266 | |
| 14267 | Page 316 TCG Published Family “2.0” |
| 14268 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 14269 | Trusted Platform Module Library Part 3: Commands |
| 14270 | |
| 14271 | |
| 14272 | |
| 14273 | 24.3.2 Command and Response |
| 14274 | |
| 14275 | Table 153 — TPM2_SetPrimaryPolicy Command |
| 14276 | Type Name Description |
| 14277 | |
| 14278 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 14279 | |
| 14280 | UINT32 commandSize |
| 14281 | |
| 14282 | TPM_CC commandCode TPM_CC_SetPrimaryPolicy {NV} |
| 14283 | |
| 14284 | TPM_RH_LOCKOUT, TPM_RH_ENDORSEMENT, |
| 14285 | TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} |
| 14286 | TPMI_RH_HIERARCHY_AUTH @authHandle |
| 14287 | Auth Index: 1 |
| 14288 | Auth Role: USER |
| 14289 | |
| 14290 | an authorization policy digest; may be the Empty Buffer |
| 14291 | TPM2B_DIGEST authPolicy If hashAlg is TPM_ALG_NULL, then this shall be an |
| 14292 | Empty Buffer. |
| 14293 | the hash algorithm to use for the policy |
| 14294 | TPMI_ALG_HASH+ hashAlg If the authPolicy is an Empty Buffer, then this field shall |
| 14295 | be TPM_ALG_NULL. |
| 14296 | |
| 14297 | |
| 14298 | Table 154 — TPM2_SetPrimaryPolicy Response |
| 14299 | Type Name Description |
| 14300 | |
| 14301 | TPM_ST tag see clause 6 |
| 14302 | |
| 14303 | UINT32 responseSize |
| 14304 | |
| 14305 | TPM_RC responseCode |
| 14306 | |
| 14307 | |
| 14308 | |
| 14309 | |
| 14310 | Family “2.0” TCG Published Page 317 |
| 14311 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 14312 | Part 3: Commands Trusted Platform Module Library |
| 14313 | |
| 14314 | |
| 14315 | |
| 14316 | 24.3.3 Detailed Actions |
| 14317 | |
| 14318 | 1 #include "InternalRoutines.h" |
| 14319 | 2 #include "SetPrimaryPolicy_fp.h" |
| 14320 | 3 #ifdef TPM_CC_SetPrimaryPolicy // Conditional expansion of this file |
| 14321 | |
| 14322 | |
| 14323 | Error Returns Meaning |
| 14324 | |
| 14325 | TPM_RC_SIZE size of input authPolicy is not consistent with input hash algorithm |
| 14326 | |
| 14327 | 4 TPM_RC |
| 14328 | 5 TPM2_SetPrimaryPolicy( |
| 14329 | 6 SetPrimaryPolicy_In *in // IN: input parameter list |
| 14330 | 7 ) |
| 14331 | 8 { |
| 14332 | 9 TPM_RC result; |
| 14333 | 10 |
| 14334 | 11 // Input Validation |
| 14335 | 12 |
| 14336 | 13 // Check the authPolicy consistent with hash algorithm. If the policy size is |
| 14337 | 14 // zero, then the algorithm is required to be TPM_ALG_NULL |
| 14338 | 15 if(in->authPolicy.t.size != CryptGetHashDigestSize(in->hashAlg)) |
| 14339 | 16 return TPM_RC_SIZE + RC_SetPrimaryPolicy_authPolicy; |
| 14340 | 17 |
| 14341 | 18 // The command need NV update for OWNER and ENDORSEMENT hierarchy, and |
| 14342 | 19 // might need orderlyState update for PLATFROM hierarchy. |
| 14343 | 20 // Check if NV is available. A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE |
| 14344 | 21 // error may be returned at this point |
| 14345 | 22 result = NvIsAvailable(); |
| 14346 | 23 if(result != TPM_RC_SUCCESS) |
| 14347 | 24 return result; |
| 14348 | 25 |
| 14349 | 26 // Internal Data Update |
| 14350 | 27 |
| 14351 | 28 // Set hierarchy policy |
| 14352 | 29 switch(in->authHandle) |
| 14353 | 30 { |
| 14354 | 31 case TPM_RH_OWNER: |
| 14355 | 32 gp.ownerAlg = in->hashAlg; |
| 14356 | 33 gp.ownerPolicy = in->authPolicy; |
| 14357 | 34 NvWriteReserved(NV_OWNER_ALG, &gp.ownerAlg); |
| 14358 | 35 NvWriteReserved(NV_OWNER_POLICY, &gp.ownerPolicy); |
| 14359 | 36 break; |
| 14360 | 37 case TPM_RH_ENDORSEMENT: |
| 14361 | 38 gp.endorsementAlg = in->hashAlg; |
| 14362 | 39 gp.endorsementPolicy = in->authPolicy; |
| 14363 | 40 NvWriteReserved(NV_ENDORSEMENT_ALG, &gp.endorsementAlg); |
| 14364 | 41 NvWriteReserved(NV_ENDORSEMENT_POLICY, &gp.endorsementPolicy); |
| 14365 | 42 break; |
| 14366 | 43 case TPM_RH_PLATFORM: |
| 14367 | 44 gc.platformAlg = in->hashAlg; |
| 14368 | 45 gc.platformPolicy = in->authPolicy; |
| 14369 | 46 // need to update orderly state |
| 14370 | 47 g_clearOrderly = TRUE; |
| 14371 | 48 break; |
| 14372 | 49 case TPM_RH_LOCKOUT: |
| 14373 | 50 gp.lockoutAlg = in->hashAlg; |
| 14374 | 51 gp.lockoutPolicy = in->authPolicy; |
| 14375 | 52 NvWriteReserved(NV_LOCKOUT_ALG, &gp.lockoutAlg); |
| 14376 | 53 NvWriteReserved(NV_LOCKOUT_POLICY, &gp.lockoutPolicy); |
| 14377 | 54 break; |
| 14378 | 55 |
| 14379 | 56 default: |
| 14380 | |
| 14381 | Page 318 TCG Published Family “2.0” |
| 14382 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 14383 | Trusted Platform Module Library Part 3: Commands |
| 14384 | |
| 14385 | 57 pAssert(FALSE); |
| 14386 | 58 break; |
| 14387 | 59 } |
| 14388 | 60 |
| 14389 | 61 return TPM_RC_SUCCESS; |
| 14390 | 62 } |
| 14391 | 63 #endif // CC_SetPrimaryPolicy |
| 14392 | |
| 14393 | |
| 14394 | |
| 14395 | |
| 14396 | Family “2.0” TCG Published Page 319 |
| 14397 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 14398 | Part 3: Commands Trusted Platform Module Library |
| 14399 | |
| 14400 | |
| 14401 | 24.4 TPM2_ChangePPS |
| 14402 | |
| 14403 | 24.4.1 General Description |
| 14404 | |
| 14405 | This replaces the current PPS with a value from the RNG and sets platformPolicy to the default |
| 14406 | initialization value (the Empty Buffer). |
| 14407 | |
| 14408 | NOTE 1 A policy that is the Empty Buffer can match no policy. |
| 14409 | |
| 14410 | NOTE 2 Platform Authorization is not changed. |
| 14411 | |
| 14412 | All resident transient and persistent objects in the Platform hierarchy are flushed. |
| 14413 | Saved contexts in the Platform hierarchy that were created under the old PPS will no longer be able to be |
| 14414 | loaded. |
| 14415 | The policy hash algorithm for PCR is reset to TPM_ALG_NULL. |
| 14416 | This command does not clear any NV Index values. |
| 14417 | |
| 14418 | NOTE 3 Index values belonging to the Platform are preserved because the indexes may have configuration |
| 14419 | information that will be the same after the PPS changes. The Platform may remove the indexes that |
| 14420 | are no longer needed using TPM2_NV_UndefineSpace(). |
| 14421 | |
| 14422 | This command requires Platform Authorization. |
| 14423 | |
| 14424 | |
| 14425 | |
| 14426 | |
| 14427 | Page 320 TCG Published Family “2.0” |
| 14428 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 14429 | Trusted Platform Module Library Part 3: Commands |
| 14430 | |
| 14431 | |
| 14432 | |
| 14433 | 24.4.2 Command and Response |
| 14434 | |
| 14435 | Table 155 — TPM2_ChangePPS Command |
| 14436 | Type Name Description |
| 14437 | |
| 14438 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 14439 | UINT32 commandSize |
| 14440 | TPM_CC commandCode TPM_CC_ChangePPS {NV E} |
| 14441 | |
| 14442 | TPM_RH_PLATFORM+{PP} |
| 14443 | TPMI_RH_PLATFORM @authHandle Auth Index: 1 |
| 14444 | Auth Role: USER |
| 14445 | |
| 14446 | |
| 14447 | Table 156 — TPM2_ChangePPS Response |
| 14448 | Type Name Description |
| 14449 | TPM_ST tag see clause 6 |
| 14450 | UINT32 responseSize |
| 14451 | TPM_RC responseCode |
| 14452 | |
| 14453 | |
| 14454 | |
| 14455 | |
| 14456 | Family “2.0” TCG Published Page 321 |
| 14457 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 14458 | Part 3: Commands Trusted Platform Module Library |
| 14459 | |
| 14460 | |
| 14461 | |
| 14462 | 24.4.3 Detailed Actions |
| 14463 | |
| 14464 | 1 #include "InternalRoutines.h" |
| 14465 | 2 #include "ChangePPS_fp.h" |
| 14466 | 3 #ifdef TPM_CC_ChangePPS // Conditional expansion of this file |
| 14467 | 4 TPM_RC |
| 14468 | 5 TPM2_ChangePPS( |
| 14469 | 6 ChangePPS_In *in // IN: input parameter list |
| 14470 | 7 ) |
| 14471 | 8 { |
| 14472 | 9 UINT32 i; |
| 14473 | 10 TPM_RC result; |
| 14474 | 11 |
| 14475 | 12 // Check if NV is available. A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE |
| 14476 | 13 // error may be returned at this point |
| 14477 | 14 result = NvIsAvailable(); |
| 14478 | 15 if(result != TPM_RC_SUCCESS) return result; |
| 14479 | 16 |
| 14480 | 17 // Input parameter is not reference in command action |
| 14481 | 18 in = NULL; |
| 14482 | 19 |
| 14483 | 20 // Internal Data Update |
| 14484 | 21 |
| 14485 | 22 // Reset platform hierarchy seed from RNG |
| 14486 | 23 CryptGenerateRandom(PRIMARY_SEED_SIZE, gp.PPSeed.t.buffer); |
| 14487 | 24 |
| 14488 | 25 // Create a new phProof value from RNG to prevent the saved platform |
| 14489 | 26 // hierarchy contexts being loaded |
| 14490 | 27 CryptGenerateRandom(PROOF_SIZE, gp.phProof.t.buffer); |
| 14491 | 28 |
| 14492 | 29 // Set platform authPolicy to null |
| 14493 | 30 gc.platformAlg = TPM_ALG_NULL; |
| 14494 | 31 gc.platformPolicy.t.size = 0; |
| 14495 | 32 |
| 14496 | 33 // Flush loaded object in platform hierarchy |
| 14497 | 34 ObjectFlushHierarchy(TPM_RH_PLATFORM); |
| 14498 | 35 |
| 14499 | 36 // Flush platform evict object and index in NV |
| 14500 | 37 NvFlushHierarchy(TPM_RH_PLATFORM); |
| 14501 | 38 |
| 14502 | 39 // Save hierarchy changes to NV |
| 14503 | 40 NvWriteReserved(NV_PP_SEED, &gp.PPSeed); |
| 14504 | 41 NvWriteReserved(NV_PH_PROOF, &gp.phProof); |
| 14505 | 42 |
| 14506 | 43 // Re-initialize PCR policies |
| 14507 | 44 for(i = 0; i < NUM_POLICY_PCR_GROUP; i++) |
| 14508 | 45 { |
| 14509 | 46 gp.pcrPolicies.hashAlg[i] = TPM_ALG_NULL; |
| 14510 | 47 gp.pcrPolicies.policy[i].t.size = 0; |
| 14511 | 48 } |
| 14512 | 49 NvWriteReserved(NV_PCR_POLICIES, &gp.pcrPolicies); |
| 14513 | 50 |
| 14514 | 51 // orderly state should be cleared because of the update to state clear data |
| 14515 | 52 g_clearOrderly = TRUE; |
| 14516 | 53 |
| 14517 | 54 return TPM_RC_SUCCESS; |
| 14518 | 55 } |
| 14519 | 56 #endif // CC_ChangePPS |
| 14520 | |
| 14521 | |
| 14522 | |
| 14523 | |
| 14524 | Page 322 TCG Published Family “2.0” |
| 14525 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 14526 | Trusted Platform Module Library Part 3: Commands |
| 14527 | |
| 14528 | |
| 14529 | 24.5 TPM2_ChangeEPS |
| 14530 | |
| 14531 | 24.5.1 General Description |
| 14532 | |
| 14533 | This replaces the current EPS with a value from the RNG and sets the Endorsement hierarchy controls to |
| 14534 | their default initialization values: ehEnable is SET, endorsementAuth and endorsementPolicy both equal |
| 14535 | to the Empty Buffer. It will flush any resident objects (transient or persistent) in the EPS hierarchy and not |
| 14536 | allow objects in the hierarchy associated with the previous EPS to be loaded. |
| 14537 | |
| 14538 | NOTE In the reference implementation, ehProof is a non-volatile value from the RNG. It is allowed that the |
| 14539 | ehProof be generated by a KDF using both the EPS and SPS as inputs. If generated with a KDF, the |
| 14540 | ehProof can be generated on an as-needed basis or made a non-volatile value. |
| 14541 | |
| 14542 | This command requires Platform Authorization. |
| 14543 | |
| 14544 | |
| 14545 | |
| 14546 | |
| 14547 | Family “2.0” TCG Published Page 323 |
| 14548 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 14549 | Part 3: Commands Trusted Platform Module Library |
| 14550 | |
| 14551 | |
| 14552 | |
| 14553 | 24.5.2 Command and Response |
| 14554 | |
| 14555 | Table 157 — TPM2_ChangeEPS Command |
| 14556 | Type Name Description |
| 14557 | |
| 14558 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 14559 | UINT32 commandSize |
| 14560 | TPM_CC commandCode TPM_CC_ChangeEPS {NV E} |
| 14561 | |
| 14562 | TPM_RH_PLATFORM+{PP} |
| 14563 | TPMI_RH_PLATFORM @authHandle Auth Handle: 1 |
| 14564 | Auth Role: USER |
| 14565 | |
| 14566 | |
| 14567 | Table 158 — TPM2_ChangeEPS Response |
| 14568 | Type Name Description |
| 14569 | TPM_ST tag see clause 6 |
| 14570 | UINT32 responseSize |
| 14571 | TPM_RC responseCode |
| 14572 | |
| 14573 | |
| 14574 | |
| 14575 | |
| 14576 | Page 324 TCG Published Family “2.0” |
| 14577 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 14578 | Trusted Platform Module Library Part 3: Commands |
| 14579 | |
| 14580 | |
| 14581 | |
| 14582 | 24.5.3 Detailed Actions |
| 14583 | |
| 14584 | 1 #include "InternalRoutines.h" |
| 14585 | 2 #include "ChangeEPS_fp.h" |
| 14586 | 3 #ifdef TPM_CC_ChangeEPS // Conditional expansion of this file |
| 14587 | 4 TPM_RC |
| 14588 | 5 TPM2_ChangeEPS( |
| 14589 | 6 ChangeEPS_In *in // IN: input parameter list |
| 14590 | 7 ) |
| 14591 | 8 { |
| 14592 | 9 TPM_RC result; |
| 14593 | 10 |
| 14594 | 11 // The command needs NV update. Check if NV is available. |
| 14595 | 12 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at |
| 14596 | 13 // this point |
| 14597 | 14 result = NvIsAvailable(); |
| 14598 | 15 if(result != TPM_RC_SUCCESS) return result; |
| 14599 | 16 |
| 14600 | 17 // Input parameter is not reference in command action |
| 14601 | 18 in = NULL; |
| 14602 | 19 |
| 14603 | 20 // Internal Data Update |
| 14604 | 21 |
| 14605 | 22 // Reset endorsement hierarchy seed from RNG |
| 14606 | 23 CryptGenerateRandom(PRIMARY_SEED_SIZE, gp.EPSeed.t.buffer); |
| 14607 | 24 |
| 14608 | 25 // Create new ehProof value from RNG |
| 14609 | 26 CryptGenerateRandom(PROOF_SIZE, gp.ehProof.t.buffer); |
| 14610 | 27 |
| 14611 | 28 // Enable endorsement hierarchy |
| 14612 | 29 gc.ehEnable = TRUE; |
| 14613 | 30 |
| 14614 | 31 // set authValue buffer to zeros |
| 14615 | 32 MemorySet(gp.endorsementAuth.t.buffer, 0, gp.endorsementAuth.t.size); |
| 14616 | 33 // Set endorsement authValue to null |
| 14617 | 34 gp.endorsementAuth.t.size = 0; |
| 14618 | 35 |
| 14619 | 36 // Set endorsement authPolicy to null |
| 14620 | 37 gp.endorsementAlg = TPM_ALG_NULL; |
| 14621 | 38 gp.endorsementPolicy.t.size = 0; |
| 14622 | 39 |
| 14623 | 40 // Flush loaded object in endorsement hierarchy |
| 14624 | 41 ObjectFlushHierarchy(TPM_RH_ENDORSEMENT); |
| 14625 | 42 |
| 14626 | 43 // Flush evict object of endorsement hierarchy stored in NV |
| 14627 | 44 NvFlushHierarchy(TPM_RH_ENDORSEMENT); |
| 14628 | 45 |
| 14629 | 46 // Save hierarchy changes to NV |
| 14630 | 47 NvWriteReserved(NV_EP_SEED, &gp.EPSeed); |
| 14631 | 48 NvWriteReserved(NV_EH_PROOF, &gp.ehProof); |
| 14632 | 49 NvWriteReserved(NV_ENDORSEMENT_AUTH, &gp.endorsementAuth); |
| 14633 | 50 NvWriteReserved(NV_ENDORSEMENT_ALG, &gp.endorsementAlg); |
| 14634 | 51 NvWriteReserved(NV_ENDORSEMENT_POLICY, &gp.endorsementPolicy); |
| 14635 | 52 |
| 14636 | 53 // orderly state should be cleared because of the update to state clear data |
| 14637 | 54 g_clearOrderly = TRUE; |
| 14638 | 55 |
| 14639 | 56 return TPM_RC_SUCCESS; |
| 14640 | 57 } |
| 14641 | 58 #endif // CC_ChangeEPS |
| 14642 | |
| 14643 | |
| 14644 | |
| 14645 | |
| 14646 | Family “2.0” TCG Published Page 325 |
| 14647 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 14648 | Part 3: Commands Trusted Platform Module Library |
| 14649 | |
| 14650 | |
| 14651 | 24.6 TPM2_Clear |
| 14652 | |
| 14653 | 24.6.1 General Description |
| 14654 | |
| 14655 | This command removes all TPM context associated with a specific Owner. |
| 14656 | The clear operation will: |
| 14657 | flush resident objects (persistent and volatile) in the Storage and Endorsement hierarchies; |
| 14658 | delete any NV Index with TPMA_NV_PLATFORMCREATE == CLEAR; |
| 14659 | change the SPS to a new value from the TPM’s random number generator (RNG), |
| 14660 | change shProof and ehProof, |
| 14661 | |
| 14662 | NOTE The proof values may be set from the RNG or derived from the associated new Primary Seed. If |
| 14663 | derived from the Primary Seeds, the derivation of ehProof shall use both the SPS and EPS. The |
| 14664 | computation shall use the SPS as an HMAC key and the derived value may then be a parameter |
| 14665 | in a second HMAC in which the EPS is the HMAC key. The reference design uses values from |
| 14666 | the RNG. |
| 14667 | |
| 14668 | SET shEnable and ehEnable; |
| 14669 | set ownerAuth, endorsementAuth, and lockoutAuth to the Empty Buffer; |
| 14670 | set ownerPolicy, endorsementPolicy, and lockoutPolicy to the Empty Buffer; |
| 14671 | set Clock to zero; |
| 14672 | set resetCount to zero; |
| 14673 | set restartCount to zero; and |
| 14674 | set Safe to YES. |
| 14675 | This command requires Platform Authorization or Lockout Authorization. If TPM2_ClearControl() has |
| 14676 | disabled this command, the TPM shall return TPM_RC_DISABLED. |
| 14677 | If this command is authorized using lockoutAuth, the HMAC in the response shall use the new |
| 14678 | lockoutAuth value (that is, the Empty Buffer) when computing response HMAC. |
| 14679 | |
| 14680 | |
| 14681 | |
| 14682 | |
| 14683 | Page 326 TCG Published Family “2.0” |
| 14684 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 14685 | Trusted Platform Module Library Part 3: Commands |
| 14686 | |
| 14687 | |
| 14688 | |
| 14689 | 24.6.2 Command and Response |
| 14690 | |
| 14691 | Table 159 — TPM2_Clear Command |
| 14692 | Type Name Description |
| 14693 | |
| 14694 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 14695 | UINT32 commandSize |
| 14696 | TPM_CC commandCode TPM_CC_Clear {NV E} |
| 14697 | |
| 14698 | TPM_RH_LOCKOUT or TPM_RH_PLATFORM+{PP} |
| 14699 | TPMI_RH_CLEAR @authHandle Auth Handle: 1 |
| 14700 | Auth Role: USER |
| 14701 | |
| 14702 | |
| 14703 | Table 160 — TPM2_Clear Response |
| 14704 | Type Name Description |
| 14705 | TPM_ST tag see clause 6 |
| 14706 | UINT32 responseSize |
| 14707 | TPM_RC responseCode |
| 14708 | |
| 14709 | |
| 14710 | |
| 14711 | |
| 14712 | Family “2.0” TCG Published Page 327 |
| 14713 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 14714 | Part 3: Commands Trusted Platform Module Library |
| 14715 | |
| 14716 | |
| 14717 | |
| 14718 | 24.6.3 Detailed Actions |
| 14719 | |
| 14720 | 1 #include "InternalRoutines.h" |
| 14721 | 2 #include "Clear_fp.h" |
| 14722 | 3 #ifdef TPM_CC_Clear // Conditional expansion of this file |
| 14723 | |
| 14724 | |
| 14725 | Error Returns Meaning |
| 14726 | |
| 14727 | TPM_RC_DISABLED Clear command has been disabled |
| 14728 | |
| 14729 | 4 TPM_RC |
| 14730 | 5 TPM2_Clear( |
| 14731 | 6 Clear_In *in // IN: input parameter list |
| 14732 | 7 ) |
| 14733 | 8 { |
| 14734 | 9 TPM_RC result; |
| 14735 | 10 |
| 14736 | 11 // Input parameter is not reference in command action |
| 14737 | 12 in = NULL; |
| 14738 | 13 |
| 14739 | 14 // The command needs NV update. Check if NV is available. |
| 14740 | 15 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at |
| 14741 | 16 // this point |
| 14742 | 17 result = NvIsAvailable(); |
| 14743 | 18 if(result != TPM_RC_SUCCESS) return result; |
| 14744 | 19 |
| 14745 | 20 // Input Validation |
| 14746 | 21 |
| 14747 | 22 // If Clear command is disabled, return an error |
| 14748 | 23 if(gp.disableClear) |
| 14749 | 24 return TPM_RC_DISABLED; |
| 14750 | 25 |
| 14751 | 26 // Internal Data Update |
| 14752 | 27 |
| 14753 | 28 // Reset storage hierarchy seed from RNG |
| 14754 | 29 CryptGenerateRandom(PRIMARY_SEED_SIZE, gp.SPSeed.t.buffer); |
| 14755 | 30 |
| 14756 | 31 // Create new shProof and ehProof value from RNG |
| 14757 | 32 CryptGenerateRandom(PROOF_SIZE, gp.shProof.t.buffer); |
| 14758 | 33 CryptGenerateRandom(PROOF_SIZE, gp.ehProof.t.buffer); |
| 14759 | 34 |
| 14760 | 35 // Enable storage and endorsement hierarchy |
| 14761 | 36 gc.shEnable = gc.ehEnable = TRUE; |
| 14762 | 37 |
| 14763 | 38 // set the authValue buffers to zero |
| 14764 | 39 MemorySet(gp.ownerAuth.t.buffer, 0, gp.ownerAuth.t.size); |
| 14765 | 40 MemorySet(gp.endorsementAuth.t.buffer, 0, gp.endorsementAuth.t.size); |
| 14766 | 41 MemorySet(gp.lockoutAuth.t.buffer, 0, gp.lockoutAuth.t.size); |
| 14767 | 42 // Set storage, endorsement and lockout authValue to null |
| 14768 | 43 gp.ownerAuth.t.size = gp.endorsementAuth.t.size = gp.lockoutAuth.t.size = 0; |
| 14769 | 44 |
| 14770 | 45 // Set storage, endorsement, and lockout authPolicy to null |
| 14771 | 46 gp.ownerAlg = gp.endorsementAlg = gp.lockoutAlg = TPM_ALG_NULL; |
| 14772 | 47 gp.ownerPolicy.t.size = 0; |
| 14773 | 48 gp.endorsementPolicy.t.size = 0; |
| 14774 | 49 gp.lockoutPolicy.t.size = 0; |
| 14775 | 50 |
| 14776 | 51 // Flush loaded object in storage and endorsement hierarchy |
| 14777 | 52 ObjectFlushHierarchy(TPM_RH_OWNER); |
| 14778 | 53 ObjectFlushHierarchy(TPM_RH_ENDORSEMENT); |
| 14779 | 54 |
| 14780 | 55 // Flush owner and endorsement object and owner index in NV |
| 14781 | 56 NvFlushHierarchy(TPM_RH_OWNER); |
| 14782 | |
| 14783 | Page 328 TCG Published Family “2.0” |
| 14784 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 14785 | Trusted Platform Module Library Part 3: Commands |
| 14786 | |
| 14787 | 57 NvFlushHierarchy(TPM_RH_ENDORSEMENT); |
| 14788 | 58 |
| 14789 | 59 // Save hierarchy changes to NV |
| 14790 | 60 NvWriteReserved(NV_SP_SEED, &gp.SPSeed); |
| 14791 | 61 NvWriteReserved(NV_SH_PROOF, &gp.shProof); |
| 14792 | 62 NvWriteReserved(NV_EH_PROOF, &gp.ehProof); |
| 14793 | 63 NvWriteReserved(NV_OWNER_AUTH, &gp.ownerAuth); |
| 14794 | 64 NvWriteReserved(NV_ENDORSEMENT_AUTH, &gp.endorsementAuth); |
| 14795 | 65 NvWriteReserved(NV_LOCKOUT_AUTH, &gp.lockoutAuth); |
| 14796 | 66 NvWriteReserved(NV_OWNER_ALG, &gp.ownerAlg); |
| 14797 | 67 NvWriteReserved(NV_ENDORSEMENT_ALG, &gp.endorsementAlg); |
| 14798 | 68 NvWriteReserved(NV_LOCKOUT_ALG, &gp.lockoutAlg); |
| 14799 | 69 NvWriteReserved(NV_OWNER_POLICY, &gp.ownerPolicy); |
| 14800 | 70 NvWriteReserved(NV_ENDORSEMENT_POLICY, &gp.endorsementPolicy); |
| 14801 | 71 NvWriteReserved(NV_LOCKOUT_POLICY, &gp.lockoutPolicy); |
| 14802 | 72 |
| 14803 | 73 // Initialize dictionary attack parameters |
| 14804 | 74 DAPreInstall_Init(); |
| 14805 | 75 |
| 14806 | 76 // Reset clock |
| 14807 | 77 go.clock = 0; |
| 14808 | 78 go.clockSafe = YES; |
| 14809 | 79 // Update the DRBG state whenever writing orderly state to NV |
| 14810 | 80 CryptDrbgGetPutState(GET_STATE); |
| 14811 | 81 NvWriteReserved(NV_ORDERLY_DATA, &go); |
| 14812 | 82 |
| 14813 | 83 // Reset counters |
| 14814 | 84 gp.resetCount = gr.restartCount = gr.clearCount = 0; |
| 14815 | 85 gp.auditCounter = 0; |
| 14816 | 86 NvWriteReserved(NV_RESET_COUNT, &gp.resetCount); |
| 14817 | 87 NvWriteReserved(NV_AUDIT_COUNTER, &gp.auditCounter); |
| 14818 | 88 |
| 14819 | 89 // orderly state should be cleared because of the update to state clear data |
| 14820 | 90 g_clearOrderly = TRUE; |
| 14821 | 91 |
| 14822 | 92 return TPM_RC_SUCCESS; |
| 14823 | 93 } |
| 14824 | 94 #endif // CC_Clear |
| 14825 | |
| 14826 | |
| 14827 | |
| 14828 | |
| 14829 | Family “2.0” TCG Published Page 329 |
| 14830 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 14831 | Part 3: Commands Trusted Platform Module Library |
| 14832 | |
| 14833 | |
| 14834 | 24.7 TPM2_ClearControl |
| 14835 | |
| 14836 | 24.7.1 General Description |
| 14837 | |
| 14838 | TPM2_ClearControl() disables and enables the execution of TPM2_Clear(). |
| 14839 | The TPM will SET the TPM’s TPMA_PERMANENT.disableClear attribute if disable is YES and will |
| 14840 | CLEAR the attribute if disable is NO. When the attribute is SET, TPM2_Clear() may not be executed. |
| 14841 | |
| 14842 | NOTE This is to simplify the logic of TPM2_Clear(). TPM2_ClearControl() can be called using Platform |
| 14843 | Authorization to CLEAR the disableClear attribute and then execute TPM2_Clear(). |
| 14844 | |
| 14845 | Lockout Authorization may be used to SET disableClear but not to CLEAR it. |
| 14846 | Platform Authorization may be used to SET or CLEAR disableClear. |
| 14847 | |
| 14848 | |
| 14849 | |
| 14850 | |
| 14851 | Page 330 TCG Published Family “2.0” |
| 14852 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 14853 | Trusted Platform Module Library Part 3: Commands |
| 14854 | |
| 14855 | |
| 14856 | |
| 14857 | 24.7.2 Command and Response |
| 14858 | |
| 14859 | Table 161 — TPM2_ClearControl Command |
| 14860 | Type Name Description |
| 14861 | |
| 14862 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 14863 | UINT32 commandSize |
| 14864 | TPM_CC commandCode TPM_CC_ClearControl {NV} |
| 14865 | |
| 14866 | TPM_RH_LOCKOUT or TPM_RH_PLATFORM+{PP} |
| 14867 | TPMI_RH_CLEAR @auth Auth Handle: 1 |
| 14868 | Auth Role: USER |
| 14869 | |
| 14870 | YES if the disableOwnerClear flag is to be SET, NO if |
| 14871 | TPMI_YES_NO disable |
| 14872 | the flag is to be CLEAR. |
| 14873 | |
| 14874 | |
| 14875 | Table 162 — TPM2_ClearControl Response |
| 14876 | Type Name Description |
| 14877 | |
| 14878 | TPM_ST tag see clause 6 |
| 14879 | UINT32 responseSize |
| 14880 | TPM_RC responseCode |
| 14881 | |
| 14882 | |
| 14883 | |
| 14884 | |
| 14885 | Family “2.0” TCG Published Page 331 |
| 14886 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 14887 | Part 3: Commands Trusted Platform Module Library |
| 14888 | |
| 14889 | |
| 14890 | |
| 14891 | 24.7.3 Detailed Actions |
| 14892 | |
| 14893 | 1 #include "InternalRoutines.h" |
| 14894 | 2 #include "ClearControl_fp.h" |
| 14895 | 3 #ifdef TPM_CC_ClearControl // Conditional expansion of this file |
| 14896 | |
| 14897 | |
| 14898 | Error Returns Meaning |
| 14899 | |
| 14900 | TPM_RC_AUTH_FAIL authorization is not properly given |
| 14901 | |
| 14902 | 4 TPM_RC |
| 14903 | 5 TPM2_ClearControl( |
| 14904 | 6 ClearControl_In *in // IN: input parameter list |
| 14905 | 7 ) |
| 14906 | 8 { |
| 14907 | 9 TPM_RC result; |
| 14908 | 10 |
| 14909 | 11 // The command needs NV update. Check if NV is available. |
| 14910 | 12 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at |
| 14911 | 13 // this point |
| 14912 | 14 result = NvIsAvailable(); |
| 14913 | 15 if(result != TPM_RC_SUCCESS) return result; |
| 14914 | 16 |
| 14915 | 17 // Input Validation |
| 14916 | 18 |
| 14917 | 19 // LockoutAuth may be used to set disableLockoutClear to TRUE but not to FALSE |
| 14918 | 20 if(in->auth == TPM_RH_LOCKOUT && in->disable == NO) |
| 14919 | 21 return TPM_RC_AUTH_FAIL; |
| 14920 | 22 |
| 14921 | 23 // Internal Data Update |
| 14922 | 24 |
| 14923 | 25 if(in->disable == YES) |
| 14924 | 26 gp.disableClear = TRUE; |
| 14925 | 27 else |
| 14926 | 28 gp.disableClear = FALSE; |
| 14927 | 29 |
| 14928 | 30 // Record the change to NV |
| 14929 | 31 NvWriteReserved(NV_DISABLE_CLEAR, &gp.disableClear); |
| 14930 | 32 |
| 14931 | 33 return TPM_RC_SUCCESS; |
| 14932 | 34 } |
| 14933 | 35 #endif // CC_ClearControl |
| 14934 | |
| 14935 | |
| 14936 | |
| 14937 | |
| 14938 | Page 332 TCG Published Family “2.0” |
| 14939 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 14940 | Trusted Platform Module Library Part 3: Commands |
| 14941 | |
| 14942 | |
| 14943 | 24.8 TPM2_HierarchyChangeAuth |
| 14944 | |
| 14945 | 24.8.1 General Description |
| 14946 | |
| 14947 | This command allows the authorization secret for a hierarchy or lockout to be changed using the current |
| 14948 | authorization value as the command authorization. |
| 14949 | If authHandle is TPM_RH_PLATFORM, then platformAuth is changed. If authHandle is |
| 14950 | TPM_RH_OWNER, then ownerAuth is changed. If authHandle is TPM_RH_ENDORSEMENT, then |
| 14951 | endorsementAuth is changed. If authHandle is TPM_RH_LOCKOUT, then lockoutAuth is changed. |
| 14952 | If authHandle is TPM_RH_PLATFORM, then Physical Presence may need to be asserted for this |
| 14953 | command to succeed (see 26.2, “TPM2_PP_Commands”). |
| 14954 | The authorization value may be no larger than the digest produced by the hash algorithm used for context |
| 14955 | integrity. |
| 14956 | |
| 14957 | EXAMPLE If SHA384 is used in the computation of the integrity values for saved contexts, then the largest |
| 14958 | authorization value is 48 octets. |
| 14959 | |
| 14960 | |
| 14961 | |
| 14962 | |
| 14963 | Family “2.0” TCG Published Page 333 |
| 14964 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 14965 | Part 3: Commands Trusted Platform Module Library |
| 14966 | |
| 14967 | |
| 14968 | 24.8.2 Command and Response |
| 14969 | |
| 14970 | Table 163 — TPM2_HierarchyChangeAuth Command |
| 14971 | Type Name Description |
| 14972 | |
| 14973 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 14974 | UINT32 commandSize |
| 14975 | TPM_CC commandCode TPM_CC_HierarchyChangeAuth {NV} |
| 14976 | |
| 14977 | TPM_RH_LOCKOUT, TPM_RH_ENDORSEMENT, |
| 14978 | TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} |
| 14979 | TPMI_RH_HIERARCHY_AUTH @authHandle |
| 14980 | Auth Index: 1 |
| 14981 | Auth Role: USER |
| 14982 | |
| 14983 | TPM2B_AUTH newAuth new authorization value |
| 14984 | |
| 14985 | |
| 14986 | Table 164 — TPM2_HierarchyChangeAuth Response |
| 14987 | Type Name Description |
| 14988 | |
| 14989 | TPM_ST tag see clause 6 |
| 14990 | UINT32 responseSize |
| 14991 | TPM_RC responseCode |
| 14992 | |
| 14993 | |
| 14994 | |
| 14995 | |
| 14996 | Page 334 TCG Published Family “2.0” |
| 14997 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 14998 | Trusted Platform Module Library Part 3: Commands |
| 14999 | |
| 15000 | |
| 15001 | |
| 15002 | 24.8.3 Detailed Actions |
| 15003 | |
| 15004 | 1 #include "InternalRoutines.h" |
| 15005 | 2 #include "HierarchyChangeAuth_fp.h" |
| 15006 | 3 #ifdef TPM_CC_HierarchyChangeAuth // Conditional expansion of this file |
| 15007 | 4 #include "Object_spt_fp.h" |
| 15008 | |
| 15009 | |
| 15010 | Error Returns Meaning |
| 15011 | |
| 15012 | TPM_RC_SIZE newAuth size is greater than that of integrity hash digest |
| 15013 | |
| 15014 | 5 TPM_RC |
| 15015 | 6 TPM2_HierarchyChangeAuth( |
| 15016 | 7 HierarchyChangeAuth_In *in // IN: input parameter list |
| 15017 | 8 ) |
| 15018 | 9 { |
| 15019 | 10 TPM_RC result; |
| 15020 | 11 |
| 15021 | 12 // The command needs NV update. Check if NV is available. |
| 15022 | 13 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at |
| 15023 | 14 // this point |
| 15024 | 15 result = NvIsAvailable(); |
| 15025 | 16 if(result != TPM_RC_SUCCESS) return result; |
| 15026 | 17 |
| 15027 | 18 // Make sure the the auth value is a reasonable size (not larger than |
| 15028 | 19 // the size of the digest produced by the integrity hash. The integrity |
| 15029 | 20 // hash is assumed to produce the longest digest of any hash implemented |
| 15030 | 21 // on the TPM. |
| 15031 | 22 if( MemoryRemoveTrailingZeros(&in->newAuth) |
| 15032 | 23 > CryptGetHashDigestSize(CONTEXT_INTEGRITY_HASH_ALG)) |
| 15033 | 24 return TPM_RC_SIZE + RC_HierarchyChangeAuth_newAuth; |
| 15034 | 25 |
| 15035 | 26 // Set hierarchy authValue |
| 15036 | 27 switch(in->authHandle) |
| 15037 | 28 { |
| 15038 | 29 case TPM_RH_OWNER: |
| 15039 | 30 gp.ownerAuth = in->newAuth; |
| 15040 | 31 NvWriteReserved(NV_OWNER_AUTH, &gp.ownerAuth); |
| 15041 | 32 break; |
| 15042 | 33 case TPM_RH_ENDORSEMENT: |
| 15043 | 34 gp.endorsementAuth = in->newAuth; |
| 15044 | 35 NvWriteReserved(NV_ENDORSEMENT_AUTH, &gp.endorsementAuth); |
| 15045 | 36 break; |
| 15046 | 37 case TPM_RH_PLATFORM: |
| 15047 | 38 gc.platformAuth = in->newAuth; |
| 15048 | 39 // orderly state should be cleared |
| 15049 | 40 g_clearOrderly = TRUE; |
| 15050 | 41 break; |
| 15051 | 42 case TPM_RH_LOCKOUT: |
| 15052 | 43 gp.lockoutAuth = in->newAuth; |
| 15053 | 44 NvWriteReserved(NV_LOCKOUT_AUTH, &gp.lockoutAuth); |
| 15054 | 45 break; |
| 15055 | 46 default: |
| 15056 | 47 pAssert(FALSE); |
| 15057 | 48 break; |
| 15058 | 49 } |
| 15059 | 50 |
| 15060 | 51 return TPM_RC_SUCCESS; |
| 15061 | 52 } |
| 15062 | 53 #endif // CC_HierarchyChangeAuth |
| 15063 | |
| 15064 | |
| 15065 | |
| 15066 | |
| 15067 | Family “2.0” TCG Published Page 335 |
| 15068 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 15069 | Part 3: Commands Trusted Platform Module Library |
| 15070 | |
| 15071 | |
| 15072 | 25 Dictionary Attack Functions |
| 15073 | |
| 15074 | 25.1 Introduction |
| 15075 | |
| 15076 | A TPM is required to have support for logic that will help prevent a dictionary attack on an authorization |
| 15077 | value. The protection is provided by a counter that increments when a password authorization or an |
| 15078 | HMAC authorization fails. When the counter reaches a predefined value, the TPM will not accept, for |
| 15079 | some time interval, further requests that require authorization and the TPM is in Lockout mode. While the |
| 15080 | TPM is in Lockout mode, the TPM will return TPM_RC_LOCKED if the command requires use of an |
| 15081 | object’s or Index’s authValue unless the authorization applies to an entry in the Platform hierarchy. |
| 15082 | |
| 15083 | NOTE Authorizations for objects and NV Index values in the Platform hierarchy are never locked out. |
| 15084 | However, a command that requires multiple authorizations will not be accepted when the TPM is in |
| 15085 | Lockout mode unless all of the authorizations reference objects and indexes in the Platform |
| 15086 | hierarchy. |
| 15087 | |
| 15088 | If the TPM is continuously powered for the duration of newRecoveryTime and no authorization failures |
| 15089 | occur, the authorization failure counter will be decremented by one. This property is called “self-healing.” |
| 15090 | Self-healing shall not cause the count of failed attempts to decrement below zero. |
| 15091 | The count of failed attempts, the lockout interval, and self-healing interval are settable using |
| 15092 | TPM2_DictionaryAttackParameters(). The lockout parameters and the current value of the lockout |
| 15093 | counter can be read with TPM2_GetCapability(). |
| 15094 | Dictionary attack protection does not apply to an entity associated with a permanent handle (handle type |
| 15095 | == TPM_HT_PERMANENT). |
| 15096 | |
| 15097 | 25.2 TPM2_DictionaryAttackLockReset |
| 15098 | |
| 15099 | 25.2.1 General Description |
| 15100 | |
| 15101 | This command cancels the effect of a TPM lockout due to a number of successive authorization failures. |
| 15102 | If this command is properly authorized, the lockout counter is set to zero. |
| 15103 | Only one lockoutAuth authorization failure is allowed for this command during a lockoutRecovery interval |
| 15104 | (set using TPM2_DictionaryAttackParameters(). |
| 15105 | |
| 15106 | |
| 15107 | |
| 15108 | |
| 15109 | Page 336 TCG Published Family “2.0” |
| 15110 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 15111 | Trusted Platform Module Library Part 3: Commands |
| 15112 | |
| 15113 | |
| 15114 | |
| 15115 | 25.2.2 Command and Response |
| 15116 | |
| 15117 | Table 165 — TPM2_DictionaryAttackLockReset Command |
| 15118 | Type Name Description |
| 15119 | |
| 15120 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 15121 | UINT32 commandSize |
| 15122 | TPM_CC commandCode TPM_CC_DictionaryAttackLockReset {NV} |
| 15123 | |
| 15124 | TPM_RH_LOCKOUT |
| 15125 | TPMI_RH_LOCKOUT @lockHandle Auth Index: 1 |
| 15126 | Auth Role: USER |
| 15127 | |
| 15128 | |
| 15129 | Table 166 — TPM2_DictionaryAttackLockReset Response |
| 15130 | Type Name Description |
| 15131 | TPM_ST tag see clause 6 |
| 15132 | UINT32 responseSize |
| 15133 | TPM_RC responseCode |
| 15134 | |
| 15135 | |
| 15136 | |
| 15137 | |
| 15138 | Family “2.0” TCG Published Page 337 |
| 15139 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 15140 | Part 3: Commands Trusted Platform Module Library |
| 15141 | |
| 15142 | |
| 15143 | |
| 15144 | 25.2.3 Detailed Actions |
| 15145 | |
| 15146 | 1 #include "InternalRoutines.h" |
| 15147 | 2 #include "DictionaryAttackLockReset_fp.h" |
| 15148 | 3 #ifdef TPM_CC_DictionaryAttackLockReset // Conditional expansion of this file |
| 15149 | 4 TPM_RC |
| 15150 | 5 TPM2_DictionaryAttackLockReset( |
| 15151 | 6 DictionaryAttackLockReset_In *in // IN: input parameter list |
| 15152 | 7 ) |
| 15153 | 8 { |
| 15154 | 9 TPM_RC result; |
| 15155 | 10 |
| 15156 | 11 // Input parameter is not reference in command action |
| 15157 | 12 in = NULL; |
| 15158 | 13 |
| 15159 | 14 // The command needs NV update. Check if NV is available. |
| 15160 | 15 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at |
| 15161 | 16 // this point |
| 15162 | 17 result = NvIsAvailable(); |
| 15163 | 18 if(result != TPM_RC_SUCCESS) return result; |
| 15164 | 19 |
| 15165 | 20 // Internal Data Update |
| 15166 | 21 |
| 15167 | 22 // Set failed tries to 0 |
| 15168 | 23 gp.failedTries = 0; |
| 15169 | 24 |
| 15170 | 25 // Record the changes to NV |
| 15171 | 26 NvWriteReserved(NV_FAILED_TRIES, &gp.failedTries); |
| 15172 | 27 |
| 15173 | 28 return TPM_RC_SUCCESS; |
| 15174 | 29 } |
| 15175 | 30 #endif // CC_DictionaryAttackLockReset |
| 15176 | |
| 15177 | |
| 15178 | |
| 15179 | |
| 15180 | Page 338 TCG Published Family “2.0” |
| 15181 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 15182 | Trusted Platform Module Library Part 3: Commands |
| 15183 | |
| 15184 | |
| 15185 | 25.3 TPM2_DictionaryAttackParameters |
| 15186 | |
| 15187 | 25.3.1 General Description |
| 15188 | |
| 15189 | This command changes the lockout parameters. |
| 15190 | The command requires Lockout Authorization. |
| 15191 | The timeout parameters (newRecoveryTime and lockoutRecovery) indicate values that are measured with |
| 15192 | respect to the Time and not Clock. |
| 15193 | |
| 15194 | NOTE Use of Time means that the TPM shall be continuously powered for the duration of a timeout. |
| 15195 | |
| 15196 | If newRecoveryTime is zero, then DA protection is disabled. Authorizations are checked but authorization |
| 15197 | failures will not cause the TPM to enter lockout. |
| 15198 | If newMaxTries is zero, the TPM will be in lockout and use of DA protected entities will be disabled. |
| 15199 | If lockoutRecovery is zero, then the recovery interval is a boot cycle (_TPM_Init followed by |
| 15200 | Startup(CLEAR). |
| 15201 | This command will set the authorization failure count (failedTries) to zero. |
| 15202 | Only one lockoutAuth authorization failure is allowed for this command during a lockoutRecovery interval. |
| 15203 | |
| 15204 | |
| 15205 | |
| 15206 | |
| 15207 | Family “2.0” TCG Published Page 339 |
| 15208 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 15209 | Part 3: Commands Trusted Platform Module Library |
| 15210 | |
| 15211 | |
| 15212 | |
| 15213 | 25.3.2 Command and Response |
| 15214 | |
| 15215 | Table 167 — TPM2_DictionaryAttackParameters Command |
| 15216 | Type Name Description |
| 15217 | |
| 15218 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 15219 | UINT32 commandSize |
| 15220 | TPM_CC commandCode TPM_CC_DictionaryAttackParameters {NV} |
| 15221 | |
| 15222 | TPM_RH_LOCKOUT |
| 15223 | TPMI_RH_LOCKOUT @lockHandle Auth Index: 1 |
| 15224 | Auth Role: USER |
| 15225 | |
| 15226 | count of authorization failures before the lockout is |
| 15227 | UINT32 newMaxTries |
| 15228 | imposed |
| 15229 | time in seconds before the authorization failure count |
| 15230 | is automatically decremented |
| 15231 | UINT32 newRecoveryTime |
| 15232 | A value of zero indicates that DA protection is |
| 15233 | disabled. |
| 15234 | time in seconds after a lockoutAuth failure before use |
| 15235 | UINT32 lockoutRecovery of lockoutAuth is allowed |
| 15236 | A value of zero indicates that a reboot is required. |
| 15237 | |
| 15238 | |
| 15239 | Table 168 — TPM2_DictionaryAttackParameters Response |
| 15240 | Type Name Description |
| 15241 | |
| 15242 | TPM_ST tag see clause 6 |
| 15243 | UINT32 responseSize |
| 15244 | TPM_RC responseCode |
| 15245 | |
| 15246 | |
| 15247 | |
| 15248 | |
| 15249 | Page 340 TCG Published Family “2.0” |
| 15250 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 15251 | Trusted Platform Module Library Part 3: Commands |
| 15252 | |
| 15253 | |
| 15254 | |
| 15255 | 25.3.3 Detailed Actions |
| 15256 | |
| 15257 | 1 #include "InternalRoutines.h" |
| 15258 | 2 #include "DictionaryAttackParameters_fp.h" |
| 15259 | 3 #ifdef TPM_CC_DictionaryAttackParameters // Conditional expansion of this file |
| 15260 | 4 TPM_RC |
| 15261 | 5 TPM2_DictionaryAttackParameters( |
| 15262 | 6 DictionaryAttackParameters_In *in // IN: input parameter list |
| 15263 | 7 ) |
| 15264 | 8 { |
| 15265 | 9 TPM_RC result; |
| 15266 | 10 |
| 15267 | 11 // The command needs NV update. Check if NV is available. |
| 15268 | 12 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at |
| 15269 | 13 // this point |
| 15270 | 14 result = NvIsAvailable(); |
| 15271 | 15 if(result != TPM_RC_SUCCESS) return result; |
| 15272 | 16 |
| 15273 | 17 // Internal Data Update |
| 15274 | 18 |
| 15275 | 19 // Set dictionary attack parameters |
| 15276 | 20 gp.maxTries = in->newMaxTries; |
| 15277 | 21 gp.recoveryTime = in->newRecoveryTime; |
| 15278 | 22 gp.lockoutRecovery = in->lockoutRecovery; |
| 15279 | 23 |
| 15280 | 24 // Set failed tries to 0 |
| 15281 | 25 gp.failedTries = 0; |
| 15282 | 26 |
| 15283 | 27 // Record the changes to NV |
| 15284 | 28 NvWriteReserved(NV_FAILED_TRIES, &gp.failedTries); |
| 15285 | 29 NvWriteReserved(NV_MAX_TRIES, &gp.maxTries); |
| 15286 | 30 NvWriteReserved(NV_RECOVERY_TIME, &gp.recoveryTime); |
| 15287 | 31 NvWriteReserved(NV_LOCKOUT_RECOVERY, &gp.lockoutRecovery); |
| 15288 | 32 |
| 15289 | 33 return TPM_RC_SUCCESS; |
| 15290 | 34 } |
| 15291 | 35 #endif // CC_DictionaryAttackParameters |
| 15292 | |
| 15293 | |
| 15294 | |
| 15295 | |
| 15296 | Family “2.0” TCG Published Page 341 |
| 15297 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 15298 | Part 3: Commands Trusted Platform Module Library |
| 15299 | |
| 15300 | |
| 15301 | 26 Miscellaneous Management Functions |
| 15302 | |
| 15303 | 26.1 Introduction |
| 15304 | |
| 15305 | This clause contains commands that do not logically group with any other commands. |
| 15306 | |
| 15307 | 26.2 TPM2_PP_Commands |
| 15308 | |
| 15309 | 26.2.1 General Description |
| 15310 | |
| 15311 | This command is used to determine which commands require assertion of Physical Presence (PP) in |
| 15312 | addition to platformAuth/platformPolicy. |
| 15313 | This command requires that auth is TPM_RH_PLATFORM and that Physical Presence be asserted. |
| 15314 | After this command executes successfully, the commands listed in setList will be added to the list of |
| 15315 | commands that require that Physical Presence be asserted when the handle associated with the |
| 15316 | authorization is TPM_RH_PLATFORM. The commands in clearList will no longer require assertion of |
| 15317 | Physical Presence in order to authorize a command. |
| 15318 | If a command is not in either list, its state is not changed. If a command is in both lists, then it will no |
| 15319 | longer require Physical Presence (for example, setList is processed first). |
| 15320 | Only commands with handle types of TPMI_RH_PLATFORM, TPMI_RH_PROVISION, |
| 15321 | TPMI_RH_CLEAR, or TPMI_RH_HIERARCHY can be gated with Physical Presence. If any other |
| 15322 | command is in either list, it is discarded. |
| 15323 | When a command requires that Physical Presence be provided, then Physical Presence shall be |
| 15324 | asserted for either an HMAC or a Policy authorization. |
| 15325 | |
| 15326 | NOTE Physical Presence may be made a requirement of any policy. |
| 15327 | |
| 15328 | TPM2_PP_Commands() always requires assertion of Physical Presence. |
| 15329 | |
| 15330 | |
| 15331 | |
| 15332 | |
| 15333 | Page 342 TCG Published Family “2.0” |
| 15334 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 15335 | Trusted Platform Module Library Part 3: Commands |
| 15336 | |
| 15337 | |
| 15338 | |
| 15339 | 26.2.2 Command and Response |
| 15340 | |
| 15341 | Table 169 — TPM2_PP_Commands Command |
| 15342 | Type Name Description |
| 15343 | |
| 15344 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 15345 | UINT32 commandSize |
| 15346 | TPM_CC commandCode TPM_CC_PP_Commands {NV} |
| 15347 | |
| 15348 | TPM_RH_PLATFORM+PP |
| 15349 | TPMI_RH_PLATFORM @auth Auth Index: 1 |
| 15350 | Auth Role: USER + Physical Presence |
| 15351 | |
| 15352 | list of commands to be added to those that will require |
| 15353 | TPML_CC setList |
| 15354 | that Physical Presence be asserted |
| 15355 | list of commands that will no longer require that |
| 15356 | TPML_CC clearList |
| 15357 | Physical Presence be asserted |
| 15358 | |
| 15359 | |
| 15360 | Table 170 — TPM2_PP_Commands Response |
| 15361 | Type Name Description |
| 15362 | |
| 15363 | TPM_ST tag see clause 6 |
| 15364 | UINT32 responseSize |
| 15365 | TPM_RC responseCode |
| 15366 | |
| 15367 | |
| 15368 | |
| 15369 | |
| 15370 | Family “2.0” TCG Published Page 343 |
| 15371 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 15372 | Part 3: Commands Trusted Platform Module Library |
| 15373 | |
| 15374 | |
| 15375 | |
| 15376 | 26.2.3 Detailed Actions |
| 15377 | |
| 15378 | 1 #include "InternalRoutines.h" |
| 15379 | 2 #include "PP_Commands_fp.h" |
| 15380 | 3 #ifdef TPM_CC_PP_Commands // Conditional expansion of this file |
| 15381 | 4 TPM_RC |
| 15382 | 5 TPM2_PP_Commands( |
| 15383 | 6 PP_Commands_In *in // IN: input parameter list |
| 15384 | 7 ) |
| 15385 | 8 { |
| 15386 | 9 UINT32 i; |
| 15387 | 10 |
| 15388 | 11 TPM_RC result; |
| 15389 | 12 |
| 15390 | 13 // The command needs NV update. Check if NV is available. |
| 15391 | 14 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at |
| 15392 | 15 // this point |
| 15393 | 16 result = NvIsAvailable(); |
| 15394 | 17 if(result != TPM_RC_SUCCESS) return result; |
| 15395 | 18 |
| 15396 | 19 // Internal Data Update |
| 15397 | 20 |
| 15398 | 21 // Process set list |
| 15399 | 22 for(i = 0; i < in->setList.count; i++) |
| 15400 | 23 // If command is implemented, set it as PP required. If the input |
| 15401 | 24 // command is not a PP command, it will be ignored at |
| 15402 | 25 // PhysicalPresenceCommandSet(). |
| 15403 | 26 if(CommandIsImplemented(in->setList.commandCodes[i])) |
| 15404 | 27 PhysicalPresenceCommandSet(in->setList.commandCodes[i]); |
| 15405 | 28 |
| 15406 | 29 // Process clear list |
| 15407 | 30 for(i = 0; i < in->clearList.count; i++) |
| 15408 | 31 // If command is implemented, clear it as PP required. If the input |
| 15409 | 32 // command is not a PP command, it will be ignored at |
| 15410 | 33 // PhysicalPresenceCommandClear(). If the input command is |
| 15411 | 34 // TPM2_PP_Commands, it will be ignored as well |
| 15412 | 35 if(CommandIsImplemented(in->clearList.commandCodes[i])) |
| 15413 | 36 PhysicalPresenceCommandClear(in->clearList.commandCodes[i]); |
| 15414 | 37 |
| 15415 | 38 // Save the change of PP list |
| 15416 | 39 NvWriteReserved(NV_PP_LIST, &gp.ppList); |
| 15417 | 40 |
| 15418 | 41 return TPM_RC_SUCCESS; |
| 15419 | 42 } |
| 15420 | 43 #endif // CC_PP_Commands |
| 15421 | |
| 15422 | |
| 15423 | |
| 15424 | |
| 15425 | Page 344 TCG Published Family “2.0” |
| 15426 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 15427 | Trusted Platform Module Library Part 3: Commands |
| 15428 | |
| 15429 | |
| 15430 | 26.3 TPM2_SetAlgorithmSet |
| 15431 | |
| 15432 | 26.3.1 General Description |
| 15433 | |
| 15434 | This command allows the platform to change the set of algorithms that are used by the TPM. The |
| 15435 | algorithmSet setting is a vendor-dependent value. |
| 15436 | If the changing of the algorithm set results in a change of the algorithms of PCR banks, then the TPM will |
| 15437 | need to be reset (_TPM_Init and TPM2_Startup(TPM_SU_CLEAR)) before the new PCR settings take |
| 15438 | effect. After this command executes successfully, if startupType in the next TPM2_Startup() is not |
| 15439 | TPM_SU_CLEAR, the TPM shall return TPM_RC_VALUE and enter Failure mode. |
| 15440 | This command does not change the algorithms available to the platform. |
| 15441 | |
| 15442 | NOTE The reference implementation does not have support for this command. In particular, it does not |
| 15443 | support use of this command to selectively disable algorithms. Proper support would require |
| 15444 | modification of the unmarshaling code so that each time an algorithm is unmarshaled, it would be |
| 15445 | verified as being enabled. |
| 15446 | |
| 15447 | |
| 15448 | |
| 15449 | |
| 15450 | Family “2.0” TCG Published Page 345 |
| 15451 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 15452 | Part 3: Commands Trusted Platform Module Library |
| 15453 | |
| 15454 | |
| 15455 | 26.3.2 Command and Response |
| 15456 | |
| 15457 | Table 171 — TPM2_SetAlgorithmSet Command |
| 15458 | Type Name Description |
| 15459 | |
| 15460 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 15461 | UINT32 commandSize |
| 15462 | TPM_CC commandCode TPM_CC_SetAlgorithmSet {NV} |
| 15463 | |
| 15464 | TPM_RH_PLATFORM |
| 15465 | TPMI_RH_PLATFORM @authHandle Auth Index: 1 |
| 15466 | Auth Role: USER |
| 15467 | |
| 15468 | a TPM vendor-dependent value indicating the |
| 15469 | UINT32 algorithmSet |
| 15470 | algorithm set selection |
| 15471 | |
| 15472 | |
| 15473 | Table 172 — TPM2_SetAlgorithmSet Response |
| 15474 | Type Name Description |
| 15475 | |
| 15476 | TPM_ST tag see clause 6 |
| 15477 | UINT32 responseSize |
| 15478 | TPM_RC responseCode |
| 15479 | |
| 15480 | |
| 15481 | |
| 15482 | |
| 15483 | Page 346 TCG Published Family “2.0” |
| 15484 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 15485 | Trusted Platform Module Library Part 3: Commands |
| 15486 | |
| 15487 | |
| 15488 | |
| 15489 | 26.3.3 Detailed Actions |
| 15490 | |
| 15491 | 1 #include "InternalRoutines.h" |
| 15492 | 2 #include "SetAlgorithmSet_fp.h" |
| 15493 | 3 #ifdef TPM_CC_SetAlgorithmSet // Conditional expansion of this file |
| 15494 | 4 TPM_RC |
| 15495 | 5 TPM2_SetAlgorithmSet( |
| 15496 | 6 SetAlgorithmSet_In *in // IN: input parameter list |
| 15497 | 7 ) |
| 15498 | 8 { |
| 15499 | 9 TPM_RC result; |
| 15500 | 10 |
| 15501 | 11 // The command needs NV update. Check if NV is available. |
| 15502 | 12 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at |
| 15503 | 13 // this point |
| 15504 | 14 result = NvIsAvailable(); |
| 15505 | 15 if(result != TPM_RC_SUCCESS) return result; |
| 15506 | 16 |
| 15507 | 17 // Internal Data Update |
| 15508 | 18 gp.algorithmSet = in->algorithmSet; |
| 15509 | 19 |
| 15510 | 20 // Write the algorithm set changes to NV |
| 15511 | 21 NvWriteReserved(NV_ALGORITHM_SET, &gp.algorithmSet); |
| 15512 | 22 |
| 15513 | 23 return TPM_RC_SUCCESS; |
| 15514 | 24 } |
| 15515 | 25 #endif // CC_SetAlgorithmSet |
| 15516 | |
| 15517 | |
| 15518 | |
| 15519 | |
| 15520 | Family “2.0” TCG Published Page 347 |
| 15521 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 15522 | Part 3: Commands Trusted Platform Module Library |
| 15523 | |
| 15524 | |
| 15525 | 27 Field Upgrade |
| 15526 | |
| 15527 | 27.1 Introduction |
| 15528 | |
| 15529 | This clause contains the commands for managing field upgrade of the firmware in the TPM. The field |
| 15530 | upgrade scheme may be used for replacement or augmentation of the firmware installed in the TPM. |
| 15531 | |
| 15532 | EXAMPLE 1 If an algorithm is found to be flawed, a patch of that algori thm might be installed using the firmware |
| 15533 | upgrade process. The patch might be a replacement of a portion of the code or a complete |
| 15534 | replacement of the firmware. |
| 15535 | |
| 15536 | EXAMPLE 2 If an additional set of ECC parameters is needed, the firmware process may be used to add the |
| 15537 | parameters to the TPM data set. |
| 15538 | |
| 15539 | The field upgrade process uses two commands (TPM2_FieldUpgradeStart() and |
| 15540 | TPM2_FieldUpgradeData()). TPM2_FieldUpgradeStart() validates that a signature on the provided digest |
| 15541 | is from the TPM manufacturer and that proper authorization is provided using platformPolicy. |
| 15542 | |
| 15543 | NOTE 1 The platformPolicy for field upgraded is defined by the PM and may include requirements that the |
| 15544 | upgrade be signed by the PM or the TPM owner and include any other constraints that are desired |
| 15545 | by the PM. |
| 15546 | |
| 15547 | If the proper authorization is given, the TPM will retain the signed digest and enter the Field Upgrade |
| 15548 | mode (FUM). While in FUM, the TPM will accept TPM2_FieldUpgradeData() commands. It may accept |
| 15549 | other commands if it is able to complete them using the previously installed firmware. Otherwise, it will |
| 15550 | return TPM_RC_UPGRADE. |
| 15551 | Each block of the field upgrade shall contain the digest of the next block of the field upgrade data. That |
| 15552 | digest shall be included in the digest of the previous block. The digest of the first block is signed by the |
| 15553 | TPM manufacturer. That signature and first block digest are the parameters for |
| 15554 | TPM2_FieldUpgradeStart(). The digest is saved in the TPM as the required digest for the next field |
| 15555 | upgrade data block and as the identifier of the field upgrade sequence. |
| 15556 | For each field upgrade data block that is sent to the TPM by TPM2_FieldUpgradeData(), the TPM shall |
| 15557 | validate that the digest matches the required digest and if not, shall return TPM_RC_VALUE. The TPM |
| 15558 | shall extract the digest of the next expected block and return that value to the caller, along with the digest |
| 15559 | of the first data block of the update sequence. |
| 15560 | The system may attempt to abandon the firmware upgrade by using a zero-length buffer in |
| 15561 | TPM2_FieldUpdateData(). If the TPM is able to resume operation using the firmware present when the |
| 15562 | upgrade started, then the TPM will indicate that it has abandon the update by setting the digest of the |
| 15563 | next block to the Empty Buffer. If the TPM cannot abandon the update, it will return the expected next |
| 15564 | digest. |
| 15565 | The system may also attempt to abandon the update because of a power interruption. If the TPM is able |
| 15566 | to resume normal operations, then it will respond normally to TPM2_Startup(). If the TPM is not able to |
| 15567 | resume normal operations, then it will respond to any command but TPM2_FieldUpgradeData() with |
| 15568 | TPM_RC_FIELDUPGRADE. |
| 15569 | After a _TPM_Init, system software may not be able to resume the field upgrade that was in process |
| 15570 | when the power interruption occurred. In such case, the TPM firmware may be reset to one of two other |
| 15571 | values: |
| 15572 | the original firmware that was installed at the factory (“initial firmware”); or |
| 15573 | the firmware that was in the TPM when the field upgrade process started (“previous firmware”). |
| 15574 | The TPM retains the digest of the first block for these firmware images and checks to see if the first block |
| 15575 | after _TPM_Init matches either of those digests. If so, the firmware update process restarts and the |
| 15576 | original firmware may be loaded. |
| 15577 | |
| 15578 | |
| 15579 | Page 348 TCG Published Family “2.0” |
| 15580 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 15581 | Trusted Platform Module Library Part 3: Commands |
| 15582 | |
| 15583 | NOTE 2 The TPM is required to accept the previous firmware as either a vendor-provided update or as |
| 15584 | recovered from the TPM using TPM2_FirmwareRead(). |
| 15585 | |
| 15586 | When the last block of the firmware upgrade is loaded into the TPM (indicated to the TPM by data in the |
| 15587 | data block in a TPM vendor-specific manner), the TPM will complete the upgrade process. If the TPM is |
| 15588 | able to resume normal operations without a reboot, it will set the hash algorithm of the next block to |
| 15589 | TPM_ALG_NULL and return TPM_RC_SUCCESS. If a reboot is required, the TPM shall return |
| 15590 | TPM_RC_REBOOT in response to the last TPM2_FieldUpgradeData() and all subsequent TPM |
| 15591 | commands until a _TPM_Init is received. |
| 15592 | |
| 15593 | NOTE 3 Because no additional data is allowed when the response code is not TPM_RC_SUCCESS, the TPM |
| 15594 | returns TPM_RC_SUCCESS for all calls to TPM2_FieldUpgradeData() except the last. In this |
| 15595 | manner, the TPM is able to indicate the digest of the next block. If a _TPM_Init occurs while the |
| 15596 | TPM is in FUM, the next block may be the digest for the first block of the original firmware. If it is |
| 15597 | not, then the TPM will not accept the original firmware until the next _TPM_Init when the TPM is in |
| 15598 | FUM. |
| 15599 | |
| 15600 | During the field upgrade process, either the one specified in this clause or a vendor proprietary field |
| 15601 | upgrade process, the TPM shall preserve: |
| 15602 | Primary Seeds; |
| 15603 | Hierarchy authValue, authPolicy, and proof values; |
| 15604 | Lockout authValue and authorization failure count values; |
| 15605 | PCR authValue and authPolicy values; |
| 15606 | NV Index allocations and contents; |
| 15607 | Persistent object allocations and contents; and |
| 15608 | Clock. |
| 15609 | |
| 15610 | NOTE 4 A platform manufacturer may provide a means to change preserved data to accommodate a case |
| 15611 | where a field upgrade fixes a flaw that might have compromised TPM secrets. |
| 15612 | |
| 15613 | |
| 15614 | |
| 15615 | |
| 15616 | Family “2.0” TCG Published Page 349 |
| 15617 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 15618 | Part 3: Commands Trusted Platform Module Library |
| 15619 | |
| 15620 | |
| 15621 | 27.2 TPM2_FieldUpgradeStart |
| 15622 | |
| 15623 | 27.2.1 General Description |
| 15624 | |
| 15625 | This command uses platformPolicy and a TPM Vendor Authorization Key to authorize a Field Upgrade |
| 15626 | Manifest. |
| 15627 | If the signature checks succeed, the authorization is valid and the TPM will accept |
| 15628 | TPM2_FieldUpgradeData(). |
| 15629 | This signature is checked against the loaded key referenced by keyHandle. This key will have a Name |
| 15630 | that is the same as a value that is part of the TPM firmware data. If the signature is not valid, the TPM |
| 15631 | shall return TPM_RC_SIGNATURE. |
| 15632 | |
| 15633 | NOTE A loaded key is used rather than a hard -coded key to reduce the amount of memory needed for this |
| 15634 | key data in case more than one vendor key is needed. |
| 15635 | |
| 15636 | |
| 15637 | |
| 15638 | |
| 15639 | Page 350 TCG Published Family “2.0” |
| 15640 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 15641 | Trusted Platform Module Library Part 3: Commands |
| 15642 | |
| 15643 | |
| 15644 | 27.2.2 Command and Response |
| 15645 | |
| 15646 | Table 173 — TPM2_FieldUpgradeStart Command |
| 15647 | Type Name Description |
| 15648 | |
| 15649 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 15650 | UINT32 commandSize |
| 15651 | TPM_CC commandCode TPM_CC_FieldUpgradeStart |
| 15652 | |
| 15653 | TPM_RH_PLATFORM+{PP} |
| 15654 | TPMI_RH_PLATFORM @authorization Auth Index:1 |
| 15655 | Auth Role: ADMIN |
| 15656 | handle of a public area that contains the TPM Vendor |
| 15657 | Authorization Key that will be used to validate |
| 15658 | TPMI_DH_OBJECT keyHandle manifestSignature |
| 15659 | Auth Index: None |
| 15660 | |
| 15661 | TPM2B_DIGEST fuDigest digest of the first block in the field upgrade sequence |
| 15662 | signature over fuDigest using the key associated with |
| 15663 | TPMT_SIGNATURE manifestSignature |
| 15664 | keyHandle (not optional) |
| 15665 | |
| 15666 | |
| 15667 | Table 174 — TPM2_FieldUpgradeStart Response |
| 15668 | Type Name Description |
| 15669 | |
| 15670 | TPM_ST tag see clause 6 |
| 15671 | UINT32 responseSize |
| 15672 | TPM_RC responseCode |
| 15673 | |
| 15674 | |
| 15675 | |
| 15676 | |
| 15677 | Family “2.0” TCG Published Page 351 |
| 15678 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 15679 | Part 3: Commands Trusted Platform Module Library |
| 15680 | |
| 15681 | |
| 15682 | |
| 15683 | 27.2.3 Detailed Actions |
| 15684 | |
| 15685 | 1 #include "InternalRoutines.h" |
| 15686 | 2 #include "FieldUpgradeStart_fp.h" |
| 15687 | 3 #ifdef TPM_CC_FieldUpgradeStart // Conditional expansion of this file |
| 15688 | 4 TPM_RC |
| 15689 | 5 TPM2_FieldUpgradeStart( |
| 15690 | 6 FieldUpgradeStart_In *in // IN: input parameter list |
| 15691 | 7 ) |
| 15692 | 8 { |
| 15693 | 9 // Not implemented |
| 15694 | 10 UNUSED_PARAMETER(in); |
| 15695 | 11 return TPM_RC_SUCCESS; |
| 15696 | 12 } |
| 15697 | 13 #endif |
| 15698 | |
| 15699 | |
| 15700 | |
| 15701 | |
| 15702 | Page 352 TCG Published Family “2.0” |
| 15703 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 15704 | Trusted Platform Module Library Part 3: Commands |
| 15705 | |
| 15706 | |
| 15707 | 27.3 TPM2_FieldUpgradeData |
| 15708 | |
| 15709 | 27.3.1 General Description |
| 15710 | |
| 15711 | This command will take the actual field upgrade image to be installed on the TPM. The exact format of |
| 15712 | fuData is vendor-specific. This command is only possible following a successful |
| 15713 | TPM2_FieldUpgradeStart(). If the TPM has not received a properly authorized |
| 15714 | TPM2_FieldUpgradeStart(), then the TPM shall return TPM_RC_FIELDUPGRADE. |
| 15715 | The TPM will validate that the digest of fuData matches an expected value. If so, the TPM may buffer or |
| 15716 | immediately apply the update. If the digest of fuData does not match an expected value, the TPM shall |
| 15717 | return TPM_RC_VALUE. |
| 15718 | |
| 15719 | |
| 15720 | |
| 15721 | |
| 15722 | Family “2.0” TCG Published Page 353 |
| 15723 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 15724 | Part 3: Commands Trusted Platform Module Library |
| 15725 | |
| 15726 | |
| 15727 | |
| 15728 | 27.3.2 Command and Response |
| 15729 | |
| 15730 | Table 175 — TPM2_FieldUpgradeData Command |
| 15731 | Type Name Description |
| 15732 | |
| 15733 | TPM_ST_SESSIONS if an audit or decrypt session is |
| 15734 | TPMI_ST_COMMAND_TAG tag |
| 15735 | present; otherwise, TPM_ST_NO_SESSIONS |
| 15736 | UINT32 commandSize |
| 15737 | TPM_CC commandCode TPM_CC_FieldUpgradeData {NV} |
| 15738 | |
| 15739 | TPM2B_MAX_BUFFER fuData field upgrade image data |
| 15740 | |
| 15741 | |
| 15742 | Table 176 — TPM2_FieldUpgradeData Response |
| 15743 | Type Name Description |
| 15744 | |
| 15745 | TPM_ST tag see clause 6 |
| 15746 | UINT32 responseSize |
| 15747 | TPM_RC responseCode |
| 15748 | |
| 15749 | tagged digest of the next block |
| 15750 | TPMT_HA+ nextDigest |
| 15751 | TPM_ALG_NULL if field update is complete |
| 15752 | TPMT_HA firstDigest tagged digest of the first block of the sequence |
| 15753 | |
| 15754 | |
| 15755 | |
| 15756 | |
| 15757 | Page 354 TCG Published Family “2.0” |
| 15758 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 15759 | Trusted Platform Module Library Part 3: Commands |
| 15760 | |
| 15761 | |
| 15762 | |
| 15763 | 27.3.3 Detailed Actions |
| 15764 | |
| 15765 | 1 #include "InternalRoutines.h" |
| 15766 | 2 #include "FieldUpgradeData_fp.h" |
| 15767 | 3 #ifdef TPM_CC_FieldUpgradeData // Conditional expansion of this file |
| 15768 | 4 TPM_RC |
| 15769 | 5 TPM2_FieldUpgradeData( |
| 15770 | 6 FieldUpgradeData_In *in, // IN: input parameter list |
| 15771 | 7 FieldUpgradeData_Out *out // OUT: output parameter list |
| 15772 | 8 ) |
| 15773 | 9 { |
| 15774 | 10 // Not implemented |
| 15775 | 11 UNUSED_PARAMETER(in); |
| 15776 | 12 UNUSED_PARAMETER(out); |
| 15777 | 13 return TPM_RC_SUCCESS; |
| 15778 | 14 } |
| 15779 | 15 #endif |
| 15780 | |
| 15781 | |
| 15782 | |
| 15783 | |
| 15784 | Family “2.0” TCG Published Page 355 |
| 15785 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 15786 | Part 3: Commands Trusted Platform Module Library |
| 15787 | |
| 15788 | |
| 15789 | 27.4 TPM2_FirmwareRead |
| 15790 | |
| 15791 | 27.4.1 General Description |
| 15792 | |
| 15793 | This command is used to read a copy of the current firmware installed in the TPM. |
| 15794 | The presumption is that the data will be returned in reverse order so that the last block in the sequence |
| 15795 | would be the first block given to the TPM in case of a failure recovery. If the TPM2_FirmwareRead |
| 15796 | sequence completes successfully, then the data provided from the TPM will be sufficient to allow the TPM |
| 15797 | to recover from an abandoned upgrade of this firmware. |
| 15798 | To start the sequence of retrieving the data, the caller sets sequenceNumber to zero. When the TPM has |
| 15799 | returned all the firmware data, the TPM will return the Empty Buffer as fuData. |
| 15800 | The contents of fuData are opaque to the caller. |
| 15801 | |
| 15802 | NOTE 1 The caller should retain the ordering of the update blocks so that the blocks sent to the TPM have |
| 15803 | the same size and inverse order as the blocks returned by a sequence of calls to this command. |
| 15804 | |
| 15805 | NOTE 2 Support for this command is optional even if the TPM implements TPM2_FieldUpgradeStart() a nd |
| 15806 | TPM2_FieldUpgradeData(). |
| 15807 | |
| 15808 | |
| 15809 | |
| 15810 | |
| 15811 | Page 356 TCG Published Family “2.0” |
| 15812 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 15813 | Trusted Platform Module Library Part 3: Commands |
| 15814 | |
| 15815 | |
| 15816 | 27.4.2 Command and Response |
| 15817 | |
| 15818 | Table 177 — TPM2_FirmwareRead Command |
| 15819 | Type Name Description |
| 15820 | |
| 15821 | TPM_ST_SESSIONS if an audit or encrypt session is |
| 15822 | TPMI_ST_COMMAND_TAG tag |
| 15823 | present; otherwise, TPM_ST_NO_SESSIONS |
| 15824 | UINT32 commandSize |
| 15825 | TPM_CC commandCode TPM_CC_FirmwareRead |
| 15826 | |
| 15827 | the number of previous calls to this command in this |
| 15828 | UINT32 sequenceNumber sequence |
| 15829 | set to 0 on the first call |
| 15830 | |
| 15831 | |
| 15832 | Table 178 — TPM2_FirmwareRead Response |
| 15833 | Type Name Description |
| 15834 | |
| 15835 | TPM_ST tag see clause 6 |
| 15836 | UINT32 responseSize |
| 15837 | TPM_RC responseCode |
| 15838 | |
| 15839 | TPM2B_MAX_BUFFER fuData field upgrade image data |
| 15840 | |
| 15841 | |
| 15842 | |
| 15843 | |
| 15844 | Family “2.0” TCG Published Page 357 |
| 15845 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 15846 | Part 3: Commands Trusted Platform Module Library |
| 15847 | |
| 15848 | |
| 15849 | |
| 15850 | 27.4.3 Detailed Actions |
| 15851 | |
| 15852 | 1 #include "InternalRoutines.h" |
| 15853 | 2 #include "FirmwareRead_fp.h" |
| 15854 | 3 #ifdef TPM_CC_FirmwareRead // Conditional expansion of this file |
| 15855 | 4 TPM_RC |
| 15856 | 5 TPM2_FirmwareRead( |
| 15857 | 6 FirmwareRead_In *in, // IN: input parameter list |
| 15858 | 7 FirmwareRead_Out *out // OUT: output parameter list |
| 15859 | 8 ) |
| 15860 | 9 { |
| 15861 | 10 // Not implemented |
| 15862 | 11 UNUSED_PARAMETER(in); |
| 15863 | 12 UNUSED_PARAMETER(out); |
| 15864 | 13 return TPM_RC_SUCCESS; |
| 15865 | 14 } |
| 15866 | 15 #endif // CC_FirmwareRead |
| 15867 | |
| 15868 | |
| 15869 | |
| 15870 | |
| 15871 | Page 358 TCG Published Family “2.0” |
| 15872 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 15873 | Trusted Platform Module Library Part 3: Commands |
| 15874 | |
| 15875 | |
| 15876 | 28 Context Management |
| 15877 | |
| 15878 | 28.1 Introduction |
| 15879 | |
| 15880 | Three of the commands in this clause (TPM2_ContextSave(), TPM2_ContextLoad(), and |
| 15881 | TPM2_FlushContext()) implement the resource management described in the "Context Management" |
| 15882 | clause in TPM 2.0 Part 1. |
| 15883 | The fourth command in this clause (TPM2_EvictControl()) is used to control the persistence of loadable |
| 15884 | objects in TPM memory. Background for this command may be found in the "Owner and Platform Evict |
| 15885 | Objects" clause in TPM 2.0 Part 1. |
| 15886 | |
| 15887 | 28.2 TPM2_ContextSave |
| 15888 | |
| 15889 | 28.2.1 General Description |
| 15890 | |
| 15891 | This command saves a session context, object context, or sequence object context outside the TPM. |
| 15892 | No authorization sessions of any type are allowed with this command and tag is required to be |
| 15893 | TPM_ST_NO_SESSIONS. |
| 15894 | |
| 15895 | NOTE This preclusion avoids complex issues of dealing with the same session in handle and in the session |
| 15896 | area. While it might be possible to provide specificity, it would add unnecessary complexity to the |
| 15897 | TPM and, because this capability would provide no application benefit, use of authorization sessions |
| 15898 | for audit or encryption is prohibited. |
| 15899 | |
| 15900 | The TPM shall encrypt and integrity protect the TPM2B_CONTEXT_SENSITIVE context as described in |
| 15901 | the "Context Protection" clause in TPM 2.0 Part 1. |
| 15902 | See the “Context Data” clause in TPM 2.0 Part 2 for a description of the context structure in the response. |
| 15903 | |
| 15904 | |
| 15905 | |
| 15906 | |
| 15907 | Family “2.0” TCG Published Page 359 |
| 15908 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 15909 | Part 3: Commands Trusted Platform Module Library |
| 15910 | |
| 15911 | |
| 15912 | |
| 15913 | 28.2.2 Command and Response |
| 15914 | |
| 15915 | Table 179 — TPM2_ContextSave Command |
| 15916 | Type Name Description |
| 15917 | |
| 15918 | TPMI_ST_COMMAND_TAG tag TPM_ST_NO_SESSIONS |
| 15919 | UINT32 commandSize |
| 15920 | TPM_CC commandCode TPM_CC_ContextSave |
| 15921 | |
| 15922 | handle of the resource to save |
| 15923 | TPMI_DH_CONTEXT saveHandle |
| 15924 | Auth Index: None |
| 15925 | |
| 15926 | |
| 15927 | Table 180 — TPM2_ContextSave Response |
| 15928 | Type Name Description |
| 15929 | |
| 15930 | TPM_ST tag see clause 6 |
| 15931 | UINT32 responseSize |
| 15932 | TPM_RC responseCode |
| 15933 | |
| 15934 | TPMS_CONTEXT context |
| 15935 | |
| 15936 | |
| 15937 | |
| 15938 | |
| 15939 | Page 360 TCG Published Family “2.0” |
| 15940 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 15941 | Trusted Platform Module Library Part 3: Commands |
| 15942 | |
| 15943 | |
| 15944 | |
| 15945 | 28.2.3 Detailed Actions |
| 15946 | |
| 15947 | 1 #include "InternalRoutines.h" |
| 15948 | 2 #include "ContextSave_fp.h" |
| 15949 | 3 #ifdef TPM_CC_ContextSave // Conditional expansion of this file |
| 15950 | 4 #include "Context_spt_fp.h" |
| 15951 | |
| 15952 | |
| 15953 | Error Returns Meaning |
| 15954 | |
| 15955 | TPM_RC_CONTEXT_GAP a contextID could not be assigned for a session context save |
| 15956 | TPM_RC_TOO_MANY_CONTEXTS no more contexts can be saved as the counter has maxed out |
| 15957 | |
| 15958 | 5 TPM_RC |
| 15959 | 6 TPM2_ContextSave( |
| 15960 | 7 ContextSave_In *in, // IN: input parameter list |
| 15961 | 8 ContextSave_Out *out // OUT: output parameter list |
| 15962 | 9 ) |
| 15963 | 10 { |
| 15964 | 11 TPM_RC result; |
| 15965 | 12 UINT16 fingerprintSize; // The size of fingerprint in context |
| 15966 | 13 // blob. |
| 15967 | 14 UINT64 contextID = 0; // session context ID |
| 15968 | 15 TPM2B_SYM_KEY symKey; |
| 15969 | 16 TPM2B_IV iv; |
| 15970 | 17 |
| 15971 | 18 TPM2B_DIGEST integrity; |
| 15972 | 19 UINT16 integritySize; |
| 15973 | 20 BYTE *buffer; |
| 15974 | 21 |
| 15975 | 22 // This command may cause the orderlyState to be cleared due to |
| 15976 | 23 // the update of state reset data. If this is the case, check if NV is |
| 15977 | 24 // available first |
| 15978 | 25 if(gp.orderlyState != SHUTDOWN_NONE) |
| 15979 | 26 { |
| 15980 | 27 // The command needs NV update. Check if NV is available. |
| 15981 | 28 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at |
| 15982 | 29 // this point |
| 15983 | 30 result = NvIsAvailable(); |
| 15984 | 31 if(result != TPM_RC_SUCCESS) return result; |
| 15985 | 32 } |
| 15986 | 33 |
| 15987 | 34 // Internal Data Update |
| 15988 | 35 |
| 15989 | 36 // Initialize output handle. At the end of command action, the output |
| 15990 | 37 // handle of an object will be replaced, while the output handle |
| 15991 | 38 // for a session will be the same as input |
| 15992 | 39 out->context.savedHandle = in->saveHandle; |
| 15993 | 40 |
| 15994 | 41 // Get the size of fingerprint in context blob. The sequence value in |
| 15995 | 42 // TPMS_CONTEXT structure is used as the fingerprint |
| 15996 | 43 fingerprintSize = sizeof(out->context.sequence); |
| 15997 | 44 |
| 15998 | 45 // Compute the integrity size at the beginning of context blob |
| 15999 | 46 integritySize = sizeof(integrity.t.size) |
| 16000 | 47 + CryptGetHashDigestSize(CONTEXT_INTEGRITY_HASH_ALG); |
| 16001 | 48 |
| 16002 | 49 // Perform object or session specific context save |
| 16003 | 50 switch(HandleGetType(in->saveHandle)) |
| 16004 | 51 { |
| 16005 | 52 case TPM_HT_TRANSIENT: |
| 16006 | 53 { |
| 16007 | 54 OBJECT *object = ObjectGet(in->saveHandle); |
| 16008 | |
| 16009 | Family “2.0” TCG Published Page 361 |
| 16010 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 16011 | Part 3: Commands Trusted Platform Module Library |
| 16012 | |
| 16013 | 55 OBJECT *outObject = |
| 16014 | 56 (OBJECT *)(out->context.contextBlob.t.buffer |
| 16015 | 57 + integritySize + fingerprintSize); |
| 16016 | 58 |
| 16017 | 59 // Set size of the context data. The contents of context blob is vendor |
| 16018 | 60 // defined. In this implementation, the size is size of integrity |
| 16019 | 61 // plus fingerprint plus the whole internal OBJECT structure |
| 16020 | 62 out->context.contextBlob.t.size = integritySize + |
| 16021 | 63 fingerprintSize + sizeof(OBJECT); |
| 16022 | 64 // Make sure things fit |
| 16023 | 65 pAssert(out->context.contextBlob.t.size |
| 16024 | 66 < sizeof(out->context.contextBlob.t.buffer)); |
| 16025 | 67 |
| 16026 | 68 // Copy the whole internal OBJECT structure to context blob, leave |
| 16027 | 69 // the size for fingerprint |
| 16028 | 70 *outObject = *object; |
| 16029 | 71 |
| 16030 | 72 // Increment object context ID |
| 16031 | 73 gr.objectContextID++; |
| 16032 | 74 // If object context ID overflows, TPM should be put in failure mode |
| 16033 | 75 if(gr.objectContextID == 0) |
| 16034 | 76 FAIL(FATAL_ERROR_INTERNAL); |
| 16035 | 77 |
| 16036 | 78 // Fill in other return values for an object. |
| 16037 | 79 out->context.sequence = gr.objectContextID; |
| 16038 | 80 // For regular object, savedHandle is 0x80000000. For sequence object, |
| 16039 | 81 // savedHandle is 0x80000001. For object with stClear, savedHandle |
| 16040 | 82 // is 0x80000002 |
| 16041 | 83 if(ObjectIsSequence(object)) |
| 16042 | 84 { |
| 16043 | 85 out->context.savedHandle = 0x80000001; |
| 16044 | 86 SequenceDataImportExport(object, outObject, EXPORT_STATE); |
| 16045 | 87 } |
| 16046 | 88 else if(object->attributes.stClear == SET) |
| 16047 | 89 { |
| 16048 | 90 out->context.savedHandle = 0x80000002; |
| 16049 | 91 } |
| 16050 | 92 else |
| 16051 | 93 { |
| 16052 | 94 out->context.savedHandle = 0x80000000; |
| 16053 | 95 } |
| 16054 | 96 |
| 16055 | 97 // Get object hierarchy |
| 16056 | 98 out->context.hierarchy = ObjectDataGetHierarchy(object); |
| 16057 | 99 |
| 16058 | 100 break; |
| 16059 | 101 } |
| 16060 | 102 case TPM_HT_HMAC_SESSION: |
| 16061 | 103 case TPM_HT_POLICY_SESSION: |
| 16062 | 104 { |
| 16063 | 105 SESSION *session = SessionGet(in->saveHandle); |
| 16064 | 106 |
| 16065 | 107 // Set size of the context data. The contents of context blob is vendor |
| 16066 | 108 // defined. In this implementation, the size of context blob is the |
| 16067 | 109 // size of a internal session structure plus the size of |
| 16068 | 110 // fingerprint plus the size of integrity |
| 16069 | 111 out->context.contextBlob.t.size = integritySize + |
| 16070 | 112 fingerprintSize + sizeof(*session); |
| 16071 | 113 |
| 16072 | 114 // Make sure things fit |
| 16073 | 115 pAssert(out->context.contextBlob.t.size |
| 16074 | 116 < sizeof(out->context.contextBlob.t.buffer)); |
| 16075 | 117 |
| 16076 | 118 // Copy the whole internal SESSION structure to context blob. |
| 16077 | 119 // Save space for fingerprint at the beginning of the buffer |
| 16078 | 120 // This is done before anything else so that the actual context |
| 16079 | |
| 16080 | Page 362 TCG Published Family “2.0” |
| 16081 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 16082 | Trusted Platform Module Library Part 3: Commands |
| 16083 | |
| 16084 | 121 // can be reclaimed after this call |
| 16085 | 122 MemoryCopy(out->context.contextBlob.t.buffer |
| 16086 | 123 + integritySize + fingerprintSize, |
| 16087 | 124 session, sizeof(*session), |
| 16088 | 125 sizeof(out->context.contextBlob.t.buffer) |
| 16089 | 126 - integritySize - fingerprintSize); |
| 16090 | 127 |
| 16091 | 128 // Fill in the other return parameters for a session |
| 16092 | 129 // Get a context ID and set the session tracking values appropriately |
| 16093 | 130 // TPM_RC_CONTEXT_GAP is a possible error. |
| 16094 | 131 // SessionContextSave() will flush the in-memory context |
| 16095 | 132 // so no additional errors may occur after this call. |
| 16096 | 133 result = SessionContextSave(out->context.savedHandle, &contextID); |
| 16097 | 134 if(result != TPM_RC_SUCCESS) return result; |
| 16098 | 135 |
| 16099 | 136 // sequence number is the current session contextID |
| 16100 | 137 out->context.sequence = contextID; |
| 16101 | 138 |
| 16102 | 139 // use TPM_RH_NULL as hierarchy for session context |
| 16103 | 140 out->context.hierarchy = TPM_RH_NULL; |
| 16104 | 141 |
| 16105 | 142 break; |
| 16106 | 143 } |
| 16107 | 144 default: |
| 16108 | 145 // SaveContext may only take an object handle or a session handle. |
| 16109 | 146 // All the other handle type should be filtered out at unmarshal |
| 16110 | 147 pAssert(FALSE); |
| 16111 | 148 break; |
| 16112 | 149 } |
| 16113 | 150 |
| 16114 | 151 // Save fingerprint at the beginning of encrypted area of context blob. |
| 16115 | 152 // Reserve the integrity space |
| 16116 | 153 MemoryCopy(out->context.contextBlob.t.buffer + integritySize, |
| 16117 | 154 &out->context.sequence, sizeof(out->context.sequence), |
| 16118 | 155 sizeof(out->context.contextBlob.t.buffer) - integritySize); |
| 16119 | 156 |
| 16120 | 157 // Compute context encryption key |
| 16121 | 158 ComputeContextProtectionKey(&out->context, &symKey, &iv); |
| 16122 | 159 |
| 16123 | 160 // Encrypt context blob |
| 16124 | 161 CryptSymmetricEncrypt(out->context.contextBlob.t.buffer + integritySize, |
| 16125 | 162 CONTEXT_ENCRYPT_ALG, CONTEXT_ENCRYPT_KEY_BITS, |
| 16126 | 163 TPM_ALG_CFB, symKey.t.buffer, &iv, |
| 16127 | 164 out->context.contextBlob.t.size - integritySize, |
| 16128 | 165 out->context.contextBlob.t.buffer + integritySize); |
| 16129 | 166 |
| 16130 | 167 // Compute integrity hash for the object |
| 16131 | 168 // In this implementation, the same routine is used for both sessions |
| 16132 | 169 // and objects. |
| 16133 | 170 ComputeContextIntegrity(&out->context, &integrity); |
| 16134 | 171 |
| 16135 | 172 // add integrity at the beginning of context blob |
| 16136 | 173 buffer = out->context.contextBlob.t.buffer; |
| 16137 | 174 TPM2B_DIGEST_Marshal(&integrity, &buffer, NULL); |
| 16138 | 175 |
| 16139 | 176 // orderly state should be cleared because of the update of state reset and |
| 16140 | 177 // state clear data |
| 16141 | 178 g_clearOrderly = TRUE; |
| 16142 | 179 |
| 16143 | 180 return TPM_RC_SUCCESS; |
| 16144 | 181 } |
| 16145 | 182 #endif // CC_ContextSave |
| 16146 | |
| 16147 | |
| 16148 | |
| 16149 | |
| 16150 | Family “2.0” TCG Published Page 363 |
| 16151 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 16152 | Part 3: Commands Trusted Platform Module Library |
| 16153 | |
| 16154 | |
| 16155 | 28.3 TPM2_ContextLoad |
| 16156 | |
| 16157 | 28.3.1 General Description |
| 16158 | |
| 16159 | This command is used to reload a context that has been saved by TPM2_ContextSave(). |
| 16160 | No authorization sessions of any type are allowed with this command and tag is required to be |
| 16161 | TPM_ST_NO_SESSIONS (see note in 28.2.1). |
| 16162 | The TPM will return TPM_RC_HIERARCHY if the context is associated with a hierarchy that is disabled. |
| 16163 | |
| 16164 | NOTE Contexts for authorization sessions and for sequence objects belong to the NULL hierarchy which is |
| 16165 | never disabled. |
| 16166 | |
| 16167 | See the “Context Data” clause in TPM 2.0 Part 2 for a description of the values in the context parameter. |
| 16168 | If the integrity HMAC of the saved context is not valid, the TPM shall return TPM_RC_INTEGRITY. |
| 16169 | The TPM shall perform a check on the decrypted context as described in the "Context Confidentiality |
| 16170 | Protections" clause of TPM 2.0 Part 1 and enter failure mode if the check fails. |
| 16171 | |
| 16172 | |
| 16173 | |
| 16174 | |
| 16175 | Page 364 TCG Published Family “2.0” |
| 16176 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 16177 | Trusted Platform Module Library Part 3: Commands |
| 16178 | |
| 16179 | |
| 16180 | |
| 16181 | 28.3.2 Command and Response |
| 16182 | |
| 16183 | Table 181 — TPM2_ContextLoad Command |
| 16184 | Type Name Description |
| 16185 | |
| 16186 | TPMI_ST_COMMAND_TAG tag TPM_ST_NO_SESSIONS |
| 16187 | UINT32 commandSize |
| 16188 | TPM_CC commandCode TPM_CC_ContextLoad |
| 16189 | |
| 16190 | TPMS_CONTEXT context the context blob |
| 16191 | |
| 16192 | |
| 16193 | Table 182 — TPM2_ContextLoad Response |
| 16194 | Type Name Description |
| 16195 | |
| 16196 | TPM_ST tag see clause 6 |
| 16197 | UINT32 responseSize |
| 16198 | TPM_RC responseCode |
| 16199 | |
| 16200 | the handle assigned to the resource after it has been |
| 16201 | TPMI_DH_CONTEXT loadedHandle |
| 16202 | successfully loaded |
| 16203 | |
| 16204 | |
| 16205 | |
| 16206 | |
| 16207 | Family “2.0” TCG Published Page 365 |
| 16208 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 16209 | Part 3: Commands Trusted Platform Module Library |
| 16210 | |
| 16211 | |
| 16212 | |
| 16213 | 28.3.3 Detailed Actions |
| 16214 | |
| 16215 | 1 #include "InternalRoutines.h" |
| 16216 | 2 #include "ContextLoad_fp.h" |
| 16217 | 3 #ifdef TPM_CC_ContextLoad // Conditional expansion of this file |
| 16218 | 4 #include "Context_spt_fp.h" |
| 16219 | |
| 16220 | |
| 16221 | Error Returns Meaning |
| 16222 | |
| 16223 | TPM_RC_CONTEXT_GAP there is only one available slot and this is not the oldest saved |
| 16224 | session context |
| 16225 | TPM_RC_HANDLE 'context. savedHandle' does not reference a saved session |
| 16226 | TPM_RC_HIERARCHY 'context.hierarchy' is disabled |
| 16227 | TPM_RC_INTEGRITY context integrity check fail |
| 16228 | TPM_RC_OBJECT_MEMORY no free slot for an object |
| 16229 | TPM_RC_SESSION_MEMORY no free session slots |
| 16230 | TPM_RC_SIZE incorrect context blob size |
| 16231 | |
| 16232 | 5 TPM_RC |
| 16233 | 6 TPM2_ContextLoad( |
| 16234 | 7 ContextLoad_In *in, // IN: input parameter list |
| 16235 | 8 ContextLoad_Out *out // OUT: output parameter list |
| 16236 | 9 ) |
| 16237 | 10 { |
| 16238 | 11 // Local Variables |
| 16239 | 12 TPM_RC result = TPM_RC_SUCCESS; |
| 16240 | 13 |
| 16241 | 14 TPM2B_DIGEST integrityToCompare; |
| 16242 | 15 TPM2B_DIGEST integrity; |
| 16243 | 16 UINT16 integritySize; |
| 16244 | 17 UINT64 fingerprint; |
| 16245 | 18 BYTE *buffer; |
| 16246 | 19 INT32 size; |
| 16247 | 20 |
| 16248 | 21 TPM_HT handleType; |
| 16249 | 22 TPM2B_SYM_KEY symKey; |
| 16250 | 23 TPM2B_IV iv; |
| 16251 | 24 |
| 16252 | 25 // Input Validation |
| 16253 | 26 |
| 16254 | 27 // Check context blob size |
| 16255 | 28 handleType = HandleGetType(in->context.savedHandle); |
| 16256 | 29 |
| 16257 | 30 // Check integrity |
| 16258 | 31 // In this implementation, the same routine is used for both sessions |
| 16259 | 32 // and objects. |
| 16260 | 33 integritySize = CryptGetHashDigestSize(CONTEXT_INTEGRITY_HASH_ALG); |
| 16261 | 34 |
| 16262 | 35 // Get integrity from context blob |
| 16263 | 36 buffer = in->context.contextBlob.t.buffer; |
| 16264 | 37 size = (INT32) in->context.contextBlob.t.size; |
| 16265 | 38 result = TPM2B_DIGEST_Unmarshal(&integrity, &buffer, &size); |
| 16266 | 39 if(result != TPM_RC_SUCCESS) |
| 16267 | 40 return result; |
| 16268 | 41 if(integrity.t.size != integritySize) |
| 16269 | 42 return TPM_RC_SIZE; |
| 16270 | 43 |
| 16271 | 44 integritySize += sizeof(integrity.t.size); |
| 16272 | |
| 16273 | |
| 16274 | Page 366 TCG Published Family “2.0” |
| 16275 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 16276 | Trusted Platform Module Library Part 3: Commands |
| 16277 | |
| 16278 | 45 |
| 16279 | 46 // Compute context integrity |
| 16280 | 47 ComputeContextIntegrity(&in->context, &integrityToCompare); |
| 16281 | 48 |
| 16282 | 49 // Compare integrity |
| 16283 | 50 if(!Memory2BEqual(&integrity.b, &integrityToCompare.b)) |
| 16284 | 51 return TPM_RC_INTEGRITY + RC_ContextLoad_context; |
| 16285 | 52 |
| 16286 | 53 // Compute context encryption key |
| 16287 | 54 ComputeContextProtectionKey(&in->context, &symKey, &iv); |
| 16288 | 55 |
| 16289 | 56 // Decrypt context data in place |
| 16290 | 57 CryptSymmetricDecrypt(in->context.contextBlob.t.buffer + integritySize, |
| 16291 | 58 CONTEXT_ENCRYPT_ALG, CONTEXT_ENCRYPT_KEY_BITS, |
| 16292 | 59 TPM_ALG_CFB, symKey.t.buffer, &iv, |
| 16293 | 60 in->context.contextBlob.t.size - integritySize, |
| 16294 | 61 in->context.contextBlob.t.buffer + integritySize); |
| 16295 | 62 |
| 16296 | 63 // Read the fingerprint value, skip the leading integrity size |
| 16297 | 64 MemoryCopy(&fingerprint, in->context.contextBlob.t.buffer + integritySize, |
| 16298 | 65 sizeof(fingerprint), sizeof(fingerprint)); |
| 16299 | 66 // Check fingerprint. If the check fails, TPM should be put to failure mode |
| 16300 | 67 if(fingerprint != in->context.sequence) |
| 16301 | 68 FAIL(FATAL_ERROR_INTERNAL); |
| 16302 | 69 |
| 16303 | 70 // Perform object or session specific input check |
| 16304 | 71 switch(handleType) |
| 16305 | 72 { |
| 16306 | 73 case TPM_HT_TRANSIENT: |
| 16307 | 74 { |
| 16308 | 75 // Get a pointer to the object in the context blob |
| 16309 | 76 OBJECT *outObject = (OBJECT *)(in->context.contextBlob.t.buffer |
| 16310 | 77 + integritySize + sizeof(fingerprint)); |
| 16311 | 78 |
| 16312 | 79 // Discard any changes to the handle that the TRM might have made |
| 16313 | 80 in->context.savedHandle = TRANSIENT_FIRST; |
| 16314 | 81 |
| 16315 | 82 // If hierarchy is disabled, no object context can be loaded in this |
| 16316 | 83 // hierarchy |
| 16317 | 84 if(!HierarchyIsEnabled(in->context.hierarchy)) |
| 16318 | 85 return TPM_RC_HIERARCHY + RC_ContextLoad_context; |
| 16319 | 86 |
| 16320 | 87 // Restore object. A TPM_RC_OBJECT_MEMORY error may be returned at |
| 16321 | 88 // this point |
| 16322 | 89 result = ObjectContextLoad(outObject, &out->loadedHandle); |
| 16323 | 90 if(result != TPM_RC_SUCCESS) |
| 16324 | 91 return result; |
| 16325 | 92 |
| 16326 | 93 // If this is a sequence object, the crypto library may need to |
| 16327 | 94 // reformat the data into an internal format |
| 16328 | 95 if(ObjectIsSequence(outObject)) |
| 16329 | 96 SequenceDataImportExport(ObjectGet(out->loadedHandle), |
| 16330 | 97 outObject, IMPORT_STATE); |
| 16331 | 98 |
| 16332 | 99 break; |
| 16333 | 100 } |
| 16334 | 101 case TPM_HT_POLICY_SESSION: |
| 16335 | 102 case TPM_HT_HMAC_SESSION: |
| 16336 | 103 { |
| 16337 | 104 |
| 16338 | 105 SESSION *session = (SESSION *)(in->context.contextBlob.t.buffer |
| 16339 | 106 + integritySize + sizeof(fingerprint)); |
| 16340 | 107 |
| 16341 | 108 // This command may cause the orderlyState to be cleared due to |
| 16342 | 109 // the update of state reset data. If this is the case, check if NV is |
| 16343 | 110 // available first |
| 16344 | |
| 16345 | Family “2.0” TCG Published Page 367 |
| 16346 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 16347 | Part 3: Commands Trusted Platform Module Library |
| 16348 | |
| 16349 | 111 if(gp.orderlyState != SHUTDOWN_NONE) |
| 16350 | 112 { |
| 16351 | 113 // The command needs NV update. Check if NV is available. |
| 16352 | 114 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned |
| 16353 | 115 // at this point |
| 16354 | 116 result = NvIsAvailable(); |
| 16355 | 117 if(result != TPM_RC_SUCCESS) |
| 16356 | 118 return result; |
| 16357 | 119 } |
| 16358 | 120 |
| 16359 | 121 // Check if input handle points to a valid saved session |
| 16360 | 122 if(!SessionIsSaved(in->context.savedHandle)) |
| 16361 | 123 return TPM_RC_HANDLE + RC_ContextLoad_context; |
| 16362 | 124 |
| 16363 | 125 // Restore session. A TPM_RC_SESSION_MEMORY, TPM_RC_CONTEXT_GAP error |
| 16364 | 126 // may be returned at this point |
| 16365 | 127 result = SessionContextLoad(session, &in->context.savedHandle); |
| 16366 | 128 if(result != TPM_RC_SUCCESS) |
| 16367 | 129 return result; |
| 16368 | 130 |
| 16369 | 131 out->loadedHandle = in->context.savedHandle; |
| 16370 | 132 |
| 16371 | 133 // orderly state should be cleared because of the update of state |
| 16372 | 134 // reset and state clear data |
| 16373 | 135 g_clearOrderly = TRUE; |
| 16374 | 136 |
| 16375 | 137 break; |
| 16376 | 138 } |
| 16377 | 139 default: |
| 16378 | 140 // Context blob may only have an object handle or a session handle. |
| 16379 | 141 // All the other handle type should be filtered out at unmarshal |
| 16380 | 142 pAssert(FALSE); |
| 16381 | 143 break; |
| 16382 | 144 } |
| 16383 | 145 |
| 16384 | 146 return TPM_RC_SUCCESS; |
| 16385 | 147 } |
| 16386 | 148 #endif // CC_ContextLoad |
| 16387 | |
| 16388 | |
| 16389 | |
| 16390 | |
| 16391 | Page 368 TCG Published Family “2.0” |
| 16392 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 16393 | Trusted Platform Module Library Part 3: Commands |
| 16394 | |
| 16395 | |
| 16396 | 28.4 TPM2_FlushContext |
| 16397 | |
| 16398 | 28.4.1 General Description |
| 16399 | |
| 16400 | This command causes all context associated with a loaded object or session to be removed from TPM |
| 16401 | memory. |
| 16402 | This command may not be used to remove a persistent object from the TPM. |
| 16403 | A session does not have to be loaded in TPM memory to have its context flushed. The saved session |
| 16404 | context associated with the indicated handle is invalidated. |
| 16405 | No sessions of any type are allowed with this command and tag is required to be |
| 16406 | TPM_ST_NO_SESSIONS (see note in 28.2.1). |
| 16407 | If the handle is for a transient object and the handle is not associated with a loaded object, then the TPM |
| 16408 | shall return TPM_RC_HANDLE. |
| 16409 | If the handle is for an authorization session and the handle does not reference a loaded or active session, |
| 16410 | then the TPM shall return TPM_RC_HANDLE. |
| 16411 | NOTE flushHandle is a parameter and not a handle. If it were in the handle area, the TPM would |
| 16412 | validate that the context for the referenced entity is in the TPM. When a TPM2_FlushContext references a |
| 16413 | saved session context, it is not necessary for the context to be in the TPM. When the flushHandle is in |
| 16414 | the parameter area, the TPM does not validate that associated context is actually in the TPM. |
| 16415 | |
| 16416 | |
| 16417 | |
| 16418 | |
| 16419 | Family “2.0” TCG Published Page 369 |
| 16420 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 16421 | Part 3: Commands Trusted Platform Module Library |
| 16422 | |
| 16423 | |
| 16424 | |
| 16425 | 28.4.2 Command and Response |
| 16426 | |
| 16427 | Table 183 — TPM2_FlushContext Command |
| 16428 | Type Name Description |
| 16429 | |
| 16430 | TPMI_ST_COMMAND_TAG tag TPM_ST_NO_SESSIONS |
| 16431 | UINT32 commandSize |
| 16432 | TPM_CC commandCode TPM_CC_FlushContext |
| 16433 | |
| 16434 | the handle of the item to flush |
| 16435 | TPMI_DH_CONTEXT flushHandle |
| 16436 | NOTE This is a use of a handle as a parameter. |
| 16437 | |
| 16438 | |
| 16439 | Table 184 — TPM2_FlushContext Response |
| 16440 | Type Name Description |
| 16441 | |
| 16442 | TPM_ST tag see clause 6 |
| 16443 | UINT32 responseSize |
| 16444 | TPM_RC responseCode |
| 16445 | |
| 16446 | |
| 16447 | |
| 16448 | |
| 16449 | Page 370 TCG Published Family “2.0” |
| 16450 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 16451 | Trusted Platform Module Library Part 3: Commands |
| 16452 | |
| 16453 | |
| 16454 | |
| 16455 | 28.4.3 Detailed Actions |
| 16456 | |
| 16457 | 1 #include "InternalRoutines.h" |
| 16458 | 2 #include "FlushContext_fp.h" |
| 16459 | 3 #ifdef TPM_CC_FlushContext // Conditional expansion of this file |
| 16460 | |
| 16461 | |
| 16462 | Error Returns Meaning |
| 16463 | |
| 16464 | TPM_RC_HANDLE flushHandle does not reference a loaded object or session |
| 16465 | |
| 16466 | 4 TPM_RC |
| 16467 | 5 TPM2_FlushContext( |
| 16468 | 6 FlushContext_In *in // IN: input parameter list |
| 16469 | 7 ) |
| 16470 | 8 { |
| 16471 | 9 // Internal Data Update |
| 16472 | 10 |
| 16473 | 11 // Call object or session specific routine to flush |
| 16474 | 12 switch(HandleGetType(in->flushHandle)) |
| 16475 | 13 { |
| 16476 | 14 case TPM_HT_TRANSIENT: |
| 16477 | 15 if(!ObjectIsPresent(in->flushHandle)) |
| 16478 | 16 return TPM_RC_HANDLE; |
| 16479 | 17 // Flush object |
| 16480 | 18 ObjectFlush(in->flushHandle); |
| 16481 | 19 break; |
| 16482 | 20 case TPM_HT_HMAC_SESSION: |
| 16483 | 21 case TPM_HT_POLICY_SESSION: |
| 16484 | 22 if( !SessionIsLoaded(in->flushHandle) |
| 16485 | 23 && !SessionIsSaved(in->flushHandle) |
| 16486 | 24 ) |
| 16487 | 25 return TPM_RC_HANDLE; |
| 16488 | 26 |
| 16489 | 27 // If the session to be flushed is the exclusive audit session, then |
| 16490 | 28 // indicate that there is no exclusive audit session any longer. |
| 16491 | 29 if(in->flushHandle == g_exclusiveAuditSession) |
| 16492 | 30 g_exclusiveAuditSession = TPM_RH_UNASSIGNED; |
| 16493 | 31 |
| 16494 | 32 // Flush session |
| 16495 | 33 SessionFlush(in->flushHandle); |
| 16496 | 34 break; |
| 16497 | 35 default: |
| 16498 | 36 // This command only take object or session handle. Other handles |
| 16499 | 37 // should be filtered out at handle unmarshal |
| 16500 | 38 pAssert(FALSE); |
| 16501 | 39 break; |
| 16502 | 40 } |
| 16503 | 41 |
| 16504 | 42 return TPM_RC_SUCCESS; |
| 16505 | 43 } |
| 16506 | 44 #endif // CC_FlushContext |
| 16507 | |
| 16508 | |
| 16509 | |
| 16510 | |
| 16511 | Family “2.0” TCG Published Page 371 |
| 16512 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 16513 | Part 3: Commands Trusted Platform Module Library |
| 16514 | |
| 16515 | |
| 16516 | 28.5 TPM2_EvictControl |
| 16517 | |
| 16518 | 28.5.1 General Description |
| 16519 | |
| 16520 | This command allows a transient object to be made persistent or a persistent object to be evicted. |
| 16521 | |
| 16522 | NOTE 1 A transient object is one that may be removed from TPM memory using either TPM2_FlushContext |
| 16523 | or TPM2_Startup(). A persistent object is not removed from TPM memory by TPM2_FlushContext() |
| 16524 | or TPM2_Startup(). |
| 16525 | |
| 16526 | If objectHandle is a transient object, then the call is to make the object persistent and assign |
| 16527 | persistentHandle to the persistent version of the object. If objectHandle is a persistent object, then the call |
| 16528 | is to evict the persistent object. |
| 16529 | Before execution of TPM2_EvictControl code below, the TPM verifies that objectHandle references an |
| 16530 | object that is resident on the TPM and that persistentHandle is a valid handle for a persistent object. |
| 16531 | |
| 16532 | NOTE 2 This requirement simplifies the unmarshaling code so that it only need check that persistentHandle |
| 16533 | is always a persistent object. |
| 16534 | |
| 16535 | If objectHandle references a transient object: |
| 16536 | a) The TPM shall return TPM_RC_ATTRIBUTES if |
| 16537 | 1) it is in the hierarchy of TPM_RH_NULL, |
| 16538 | 2) only the public portion of the object is loaded, or |
| 16539 | 3) the stClear is SET in the object or in an ancestor key. |
| 16540 | b) The TPM shall return TPM_RC_HIERARCHY if the object is not in the proper hierarchy as |
| 16541 | determined by auth. |
| 16542 | 1) If auth is TPM_RH_PLATFORM, the proper hierarchy is the Platform hierarchy. |
| 16543 | 2) If auth is TPM_RH_OWNER, the proper hierarchy is either the Storage or the Endorsement |
| 16544 | hierarchy. |
| 16545 | c) The TPM shall return TPM_RC_RANGE if persistentHandle is not in the proper range as determined |
| 16546 | by auth. |
| 16547 | 1) If auth is TPM_RH_OWNER, then persistentHandle shall be in the inclusive range of |
| 16548 | 81 00 00 0016 to 81 7F FF FF16. |
| 16549 | 2) If auth is TPM_RH_PLATFORM, then persistentHandle shall be in the inclusive range of |
| 16550 | 81 80 00 0016 to 81 FF FF FF16. |
| 16551 | d) The TPM shall return TPM_RC_NV_DEFINED if a persistent object exists with the same handle as |
| 16552 | persistentHandle. |
| 16553 | e) The TPM shall return TPM_RC_NV_SPACE if insufficient space is available to make the object |
| 16554 | persistent. |
| 16555 | f) The TPM shall return TPM_RC_NV_SPACE if execution of this command will prevent the TPM from |
| 16556 | being able to hold two transient objects of any kind. |
| 16557 | |
| 16558 | NOTE 3 This requirement anticipates that a TPM may be implemented suc h that all TPM memory is non- |
| 16559 | volatile and not subject to endurance issues. In such case, there is no movement of an object |
| 16560 | between memory of different types and it is necessary that the TPM ensure that it is always |
| 16561 | possible for the management software to m ove objects to/from TPM memory in order to ensure |
| 16562 | that the objects required for command execution can be context restored. |
| 16563 | |
| 16564 | g) If the TPM returns TPM_RC_SUCCESS, the object referenced by objectHandle will not be flushed |
| 16565 | and both objectHandle and persistentHandle may be used to access the object. |
| 16566 | |
| 16567 | Page 372 TCG Published Family “2.0” |
| 16568 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 16569 | Trusted Platform Module Library Part 3: Commands |
| 16570 | |
| 16571 | If objectHandle references a persistent object: |
| 16572 | a) The TPM shall return TPM_RC_RANGE if objectHandle is not in the proper range as determined by |
| 16573 | auth. If auth is TPM_RC_OWNER, objectHandle shall be in the inclusive range of 81 00 00 0016 to |
| 16574 | 81 7F FF FF16. If auth is TPM_RC_PLATFORM, objectHandle may be any valid persistent object |
| 16575 | handle. |
| 16576 | b) If the TPM returns TPM_RC_SUCCESS, objectHandle will be removed from persistent memory and |
| 16577 | no longer be accessible. |
| 16578 | |
| 16579 | NOTE 4 The persistent object is not converted to a transient object, as this would prevent the immediate |
| 16580 | revocation of an object by removing it from persistent memory. |
| 16581 | |
| 16582 | |
| 16583 | |
| 16584 | |
| 16585 | Family “2.0” TCG Published Page 373 |
| 16586 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 16587 | Part 3: Commands Trusted Platform Module Library |
| 16588 | |
| 16589 | |
| 16590 | 28.5.2 Command and Response |
| 16591 | |
| 16592 | Table 185 — TPM2_EvictControl Command |
| 16593 | Type Name Description |
| 16594 | |
| 16595 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 16596 | UINT32 commandSize |
| 16597 | TPM_CC commandCode TPM_CC_EvictControl {NV} |
| 16598 | |
| 16599 | TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} |
| 16600 | TPMI_RH_PROVISION @auth Auth Handle: 1 |
| 16601 | Auth Role: USER |
| 16602 | the handle of a loaded object |
| 16603 | TPMI_DH_OBJECT objectHandle |
| 16604 | Auth Index: None |
| 16605 | |
| 16606 | if objectHandle is a transient object handle, then this is |
| 16607 | the persistent handle for the object |
| 16608 | TPMI_DH_PERSISTENT persistentHandle |
| 16609 | if objectHandle is a persistent object handle, then it |
| 16610 | shall be the same value as persistentHandle |
| 16611 | |
| 16612 | |
| 16613 | Table 186 — TPM2_EvictControl Response |
| 16614 | Type Name Description |
| 16615 | |
| 16616 | TPM_ST tag see clause 6 |
| 16617 | UINT32 responseSize |
| 16618 | TPM_RC responseCode |
| 16619 | |
| 16620 | |
| 16621 | |
| 16622 | |
| 16623 | Page 374 TCG Published Family “2.0” |
| 16624 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 16625 | Trusted Platform Module Library Part 3: Commands |
| 16626 | |
| 16627 | |
| 16628 | |
| 16629 | 28.5.3 Detailed Actions |
| 16630 | |
| 16631 | 1 #include "InternalRoutines.h" |
| 16632 | 2 #include "EvictControl_fp.h" |
| 16633 | 3 #ifdef TPM_CC_EvictControl // Conditional expansion of this file |
| 16634 | |
| 16635 | |
| 16636 | Error Returns Meaning |
| 16637 | |
| 16638 | TPM_RC_ATTRIBUTES an object with temporary, stClear or publicOnly attribute SET cannot |
| 16639 | be made persistent |
| 16640 | TPM_RC_HIERARCHY auth cannot authorize the operation in the hierarchy of evictObject |
| 16641 | TPM_RC_HANDLE evictHandle of the persistent object to be evicted is not the same as |
| 16642 | the persistentHandle argument |
| 16643 | TPM_RC_NV_HANDLE persistentHandle is unavailable |
| 16644 | TPM_RC_NV_SPACE no space in NV to make evictHandle persistent |
| 16645 | TPM_RC_RANGE persistentHandle is not in the range corresponding to the hierarchy of |
| 16646 | evictObject |
| 16647 | |
| 16648 | 4 TPM_RC |
| 16649 | 5 TPM2_EvictControl( |
| 16650 | 6 EvictControl_In *in // IN: input parameter list |
| 16651 | 7 ) |
| 16652 | 8 { |
| 16653 | 9 TPM_RC result; |
| 16654 | 10 OBJECT *evictObject; |
| 16655 | 11 |
| 16656 | 12 // The command needs NV update. Check if NV is available. |
| 16657 | 13 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at |
| 16658 | 14 // this point |
| 16659 | 15 result = NvIsAvailable(); |
| 16660 | 16 if(result != TPM_RC_SUCCESS) return result; |
| 16661 | 17 |
| 16662 | 18 // Input Validation |
| 16663 | 19 |
| 16664 | 20 // Get internal object pointer |
| 16665 | 21 evictObject = ObjectGet(in->objectHandle); |
| 16666 | 22 |
| 16667 | 23 // Temporary, stClear or public only objects can not be made persistent |
| 16668 | 24 if( evictObject->attributes.temporary == SET |
| 16669 | 25 || evictObject->attributes.stClear == SET |
| 16670 | 26 || evictObject->attributes.publicOnly == SET |
| 16671 | 27 ) |
| 16672 | 28 return TPM_RC_ATTRIBUTES + RC_EvictControl_objectHandle; |
| 16673 | 29 |
| 16674 | 30 // If objectHandle refers to a persistent object, it should be the same as |
| 16675 | 31 // input persistentHandle |
| 16676 | 32 if( evictObject->attributes.evict == SET |
| 16677 | 33 && evictObject->evictHandle != in->persistentHandle |
| 16678 | 34 ) |
| 16679 | 35 return TPM_RC_HANDLE + RC_EvictControl_objectHandle; |
| 16680 | 36 |
| 16681 | 37 // Additional auth validation |
| 16682 | 38 if(in->auth == TPM_RH_PLATFORM) |
| 16683 | 39 { |
| 16684 | 40 // To make persistent |
| 16685 | 41 if(evictObject->attributes.evict == CLEAR) |
| 16686 | 42 { |
| 16687 | 43 // Platform auth can not set evict object in storage or endorsement |
| 16688 | 44 // hierarchy |
| 16689 | |
| 16690 | Family “2.0” TCG Published Page 375 |
| 16691 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 16692 | Part 3: Commands Trusted Platform Module Library |
| 16693 | |
| 16694 | 45 if(evictObject->attributes.ppsHierarchy == CLEAR) |
| 16695 | 46 return TPM_RC_HIERARCHY + RC_EvictControl_objectHandle; |
| 16696 | 47 |
| 16697 | 48 // Platform cannot use a handle outside of platform persistent range. |
| 16698 | 49 if(!NvIsPlatformPersistentHandle(in->persistentHandle)) |
| 16699 | 50 return TPM_RC_RANGE + RC_EvictControl_persistentHandle; |
| 16700 | 51 } |
| 16701 | 52 // Platform auth can delete any persistent object |
| 16702 | 53 } |
| 16703 | 54 else if(in->auth == TPM_RH_OWNER) |
| 16704 | 55 { |
| 16705 | 56 // Owner auth can not set or clear evict object in platform hierarchy |
| 16706 | 57 if(evictObject->attributes.ppsHierarchy == SET) |
| 16707 | 58 return TPM_RC_HIERARCHY + RC_EvictControl_objectHandle; |
| 16708 | 59 |
| 16709 | 60 // Owner cannot use a handle outside of owner persistent range. |
| 16710 | 61 if( evictObject->attributes.evict == CLEAR |
| 16711 | 62 && !NvIsOwnerPersistentHandle(in->persistentHandle) |
| 16712 | 63 ) |
| 16713 | 64 return TPM_RC_RANGE + RC_EvictControl_persistentHandle; |
| 16714 | 65 } |
| 16715 | 66 else |
| 16716 | 67 { |
| 16717 | 68 // Other auth is not allowed in this command and should be filtered out |
| 16718 | 69 // at unmarshal process |
| 16719 | 70 pAssert(FALSE); |
| 16720 | 71 } |
| 16721 | 72 |
| 16722 | 73 // Internal Data Update |
| 16723 | 74 |
| 16724 | 75 // Change evict state |
| 16725 | 76 if(evictObject->attributes.evict == CLEAR) |
| 16726 | 77 { |
| 16727 | 78 // Make object persistent |
| 16728 | 79 // A TPM_RC_NV_HANDLE or TPM_RC_NV_SPACE error may be returned at this |
| 16729 | 80 // point |
| 16730 | 81 result = NvAddEvictObject(in->persistentHandle, evictObject); |
| 16731 | 82 if(result != TPM_RC_SUCCESS) return result; |
| 16732 | 83 } |
| 16733 | 84 else |
| 16734 | 85 { |
| 16735 | 86 // Delete the persistent object in NV |
| 16736 | 87 NvDeleteEntity(evictObject->evictHandle); |
| 16737 | 88 } |
| 16738 | 89 |
| 16739 | 90 return TPM_RC_SUCCESS; |
| 16740 | 91 |
| 16741 | 92 } |
| 16742 | 93 #endif // CC_EvictControl |
| 16743 | |
| 16744 | |
| 16745 | |
| 16746 | |
| 16747 | Page 376 TCG Published Family “2.0” |
| 16748 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 16749 | Trusted Platform Module Library Part 3: Commands |
| 16750 | |
| 16751 | |
| 16752 | 29 Clocks and Timers |
| 16753 | |
| 16754 | 29.1 TPM2_ReadClock |
| 16755 | |
| 16756 | 29.1.1 General Description |
| 16757 | |
| 16758 | This command reads the current TPMS_TIME_INFO structure that contains the current setting of Time, |
| 16759 | Clock, resetCount, and restartCount. |
| 16760 | No authorization sessions of any type are allowed with this command and tag is required to be |
| 16761 | TPM_ST_NO_SESSIONS. |
| 16762 | |
| 16763 | NOTE This command is intended to allow the TCB to have access to values that have the potential to be |
| 16764 | privacy sensitive. The values may be read without authorization because the TCB will not disclose |
| 16765 | these values. Since they are not signed and cannot be accessed in a command that uses an |
| 16766 | authorization session, it is not possible for any entity, other than the TCB, to be assured that the |
| 16767 | values are accurate. |
| 16768 | |
| 16769 | |
| 16770 | |
| 16771 | |
| 16772 | Family “2.0” TCG Published Page 377 |
| 16773 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 16774 | Part 3: Commands Trusted Platform Module Library |
| 16775 | |
| 16776 | |
| 16777 | 29.1.2 Command and Response |
| 16778 | |
| 16779 | Table 187 — TPM2_ReadClock Command |
| 16780 | Type Name Description |
| 16781 | |
| 16782 | TPMI_ST_COMMAND_TAG tag TPM_ST_NO_SESSIONS |
| 16783 | UINT32 commandSize |
| 16784 | TPM_CC commandCode TPM_CC_ReadClock |
| 16785 | |
| 16786 | |
| 16787 | Table 188 — TPM2_ReadClock Response |
| 16788 | Type Name Description |
| 16789 | |
| 16790 | TPM_ST tag see clause 6 |
| 16791 | UINT32 responseSize |
| 16792 | TPM_RC responseCode |
| 16793 | |
| 16794 | TPMS_TIME_INFO currentTime |
| 16795 | |
| 16796 | |
| 16797 | |
| 16798 | |
| 16799 | Page 378 TCG Published Family “2.0” |
| 16800 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 16801 | Trusted Platform Module Library Part 3: Commands |
| 16802 | |
| 16803 | |
| 16804 | |
| 16805 | 29.1.3 Detailed Actions |
| 16806 | |
| 16807 | 1 #include "InternalRoutines.h" |
| 16808 | 2 #include "ReadClock_fp.h" |
| 16809 | 3 #ifdef TPM_CC_ReadClock // Conditional expansion of this file |
| 16810 | 4 TPM_RC |
| 16811 | 5 TPM2_ReadClock( |
| 16812 | 6 ReadClock_Out *out // OUT: output parameter list |
| 16813 | 7 ) |
| 16814 | 8 { |
| 16815 | 9 // Command Output |
| 16816 | 10 |
| 16817 | 11 out->currentTime.time = g_time; |
| 16818 | 12 TimeFillInfo(&out->currentTime.clockInfo); |
| 16819 | 13 |
| 16820 | 14 return TPM_RC_SUCCESS; |
| 16821 | 15 } |
| 16822 | 16 #endif // CC_ReadClock |
| 16823 | |
| 16824 | |
| 16825 | |
| 16826 | |
| 16827 | Family “2.0” TCG Published Page 379 |
| 16828 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 16829 | Part 3: Commands Trusted Platform Module Library |
| 16830 | |
| 16831 | |
| 16832 | 29.2 TPM2_ClockSet |
| 16833 | |
| 16834 | 29.2.1 General Description |
| 16835 | |
| 16836 | This command is used to advance the value of the TPM’s Clock. The command will fail if newTime is less |
| 16837 | 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 |
| 16838 | these checks succeed, Clock is set to newTime. If either of these checks fails, the TPM shall return |
| 16839 | TPM_RC_VALUE and make no change to Clock. |
| 16840 | |
| 16841 | NOTE This maximum setting would prevent Clock from rolling over to zero for approximately 8,000 year s if |
| 16842 | the Clock update rate was set so that TPM time was passing 33 percent faster than real time. This |
| 16843 | would still be more than 6,000 years before Clock would roll over to zero. Because Clock will not roll |
| 16844 | over in the lifetime of the TPM, there is no need for external software to deal with the possibility that |
| 16845 | Clock may wrap around. |
| 16846 | |
| 16847 | If the value of Clock after the update makes the volatile and non-volatile versions of |
| 16848 | TPMS_CLOCK_INFO.clock differ by more than the reported update interval, then the TPM shall update |
| 16849 | the non-volatile version of TPMS_CLOCK_INFO.clock before returning. |
| 16850 | This command requires Platform Authorization or Owner Authorization. |
| 16851 | |
| 16852 | |
| 16853 | |
| 16854 | |
| 16855 | Page 380 TCG Published Family “2.0” |
| 16856 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 16857 | Trusted Platform Module Library Part 3: Commands |
| 16858 | |
| 16859 | |
| 16860 | |
| 16861 | 29.2.2 Command and Response |
| 16862 | |
| 16863 | Table 189 — TPM2_ClockSet Command |
| 16864 | Type Name Description |
| 16865 | |
| 16866 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 16867 | UINT32 commandSize |
| 16868 | TPM_CC commandCode TPM_CC_ClockSet {NV} |
| 16869 | |
| 16870 | TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} |
| 16871 | TPMI_RH_PROVISION @auth Auth Handle: 1 |
| 16872 | Auth Role: USER |
| 16873 | |
| 16874 | UINT64 newTime new Clock setting in milliseconds |
| 16875 | |
| 16876 | |
| 16877 | Table 190 — TPM2_ClockSet Response |
| 16878 | Type Name Description |
| 16879 | |
| 16880 | TPM_ST tag see clause 6 |
| 16881 | UINT32 responseSize |
| 16882 | TPM_RC responseCode |
| 16883 | |
| 16884 | |
| 16885 | |
| 16886 | |
| 16887 | Family “2.0” TCG Published Page 381 |
| 16888 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 16889 | Part 3: Commands Trusted Platform Module Library |
| 16890 | |
| 16891 | |
| 16892 | |
| 16893 | 29.2.3 Detailed Actions |
| 16894 | |
| 16895 | 1 #include "InternalRoutines.h" |
| 16896 | 2 #include "ClockSet_fp.h" |
| 16897 | 3 #ifdef TPM_CC_ClockSet // Conditional expansion of this file |
| 16898 | |
| 16899 | Read the current TPMS_TIMER_INFO structure settings |
| 16900 | |
| 16901 | Error Returns Meaning |
| 16902 | |
| 16903 | TPM_RC_VALUE invalid new clock |
| 16904 | |
| 16905 | 4 TPM_RC |
| 16906 | 5 TPM2_ClockSet( |
| 16907 | 6 ClockSet_In *in // IN: input parameter list |
| 16908 | 7 ) |
| 16909 | 8 { |
| 16910 | 9 #define CLOCK_UPDATE_MASK ((1ULL << NV_CLOCK_UPDATE_INTERVAL)- 1) |
| 16911 | 10 UINT64 clockNow; |
| 16912 | 11 |
| 16913 | 12 // Input Validation |
| 16914 | 13 |
| 16915 | 14 // new time can not be bigger than 0xFFFF000000000000 or smaller than |
| 16916 | 15 // current clock |
| 16917 | 16 if(in->newTime > 0xFFFF000000000000ULL |
| 16918 | 17 || in->newTime < go.clock) |
| 16919 | 18 return TPM_RC_VALUE + RC_ClockSet_newTime; |
| 16920 | 19 |
| 16921 | 20 // Internal Data Update |
| 16922 | 21 |
| 16923 | 22 // Internal Data Update |
| 16924 | 23 clockNow = go.clock; // grab the old value |
| 16925 | 24 go.clock = in->newTime; // set the new value |
| 16926 | 25 // Check to see if the update has caused a need for an nvClock update |
| 16927 | 26 if((in->newTime & CLOCK_UPDATE_MASK) > (clockNow & CLOCK_UPDATE_MASK)) |
| 16928 | 27 { |
| 16929 | 28 CryptDrbgGetPutState(GET_STATE); |
| 16930 | 29 NvWriteReserved(NV_ORDERLY_DATA, &go); |
| 16931 | 30 |
| 16932 | 31 // Now the time state is safe |
| 16933 | 32 go.clockSafe = YES; |
| 16934 | 33 } |
| 16935 | 34 |
| 16936 | 35 return TPM_RC_SUCCESS; |
| 16937 | 36 } |
| 16938 | 37 #endif // CC_ClockSet |
| 16939 | |
| 16940 | |
| 16941 | |
| 16942 | |
| 16943 | Page 382 TCG Published Family “2.0” |
| 16944 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 16945 | Trusted Platform Module Library Part 3: Commands |
| 16946 | |
| 16947 | |
| 16948 | 29.3 TPM2_ClockRateAdjust |
| 16949 | |
| 16950 | 29.3.1 General Description |
| 16951 | |
| 16952 | This command adjusts the rate of advance of Clock and Time to provide a better approximation to real |
| 16953 | time. |
| 16954 | The rateAdjust value is relative to the current rate and not the nominal rate of advance. |
| 16955 | |
| 16956 | EXAMPLE 1 If this command had been called three times with rateAdjust = TPM_CLOCK_COARSE_SLOWER |
| 16957 | and once with rateAdjust = TPM_CLOCK_COARSE_FASTER, the net effect will be as if the |
| 16958 | command had been called twice with rateAdjust = TPM_CLOCK_COARSE_SLOWER. |
| 16959 | |
| 16960 | The range of adjustment shall be sufficient to allow Clock and Time to advance at real time but no more. |
| 16961 | If the requested adjustment would make the rate advance faster or slower than the nominal accuracy of |
| 16962 | the input frequency, the TPM shall return TPM_RC_VALUE. |
| 16963 | |
| 16964 | EXAMPLE 2 If the frequency tolerance of the TPM's input clock is +/-10 percent, then the TPM will return |
| 16965 | TPM_RC_VALUE if the adjustment would make Clock run more than 10 percent faster or slower than |
| 16966 | nominal. That is, if the input oscillator were nominally 100 megahertz (MHz), then 1 millisecond (ms) |
| 16967 | would normally take 100,000 counts. The update Clock should be adjustable so that 1 ms is between |
| 16968 | 90,000 and 110,000 counts. |
| 16969 | |
| 16970 | The interpretation of “fine” and “coarse” adjustments is implementation-specific. |
| 16971 | The nominal rate of advance for Clock and Time shall be accurate to within 15 percent. That is, with no |
| 16972 | adjustment applied, Clock and Time shall be advanced at a rate within 15 percent of actual time. |
| 16973 | |
| 16974 | NOTE If the adjustments are incorrect, it will be possible to make the difference between advance of |
| 16975 | Clock/Time and real time to be as much as 1.15 2 or ~1.33. |
| 16976 | |
| 16977 | Changes to the current Clock update rate adjustment need not be persisted across TPM power cycles. |
| 16978 | |
| 16979 | |
| 16980 | |
| 16981 | |
| 16982 | Family “2.0” TCG Published Page 383 |
| 16983 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 16984 | Part 3: Commands Trusted Platform Module Library |
| 16985 | |
| 16986 | |
| 16987 | |
| 16988 | 29.3.2 Command and Response |
| 16989 | |
| 16990 | Table 191 — TPM2_ClockRateAdjust Command |
| 16991 | Type Name Description |
| 16992 | |
| 16993 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 16994 | UINT32 commandSize |
| 16995 | TPM_CC commandCode TPM_CC_ClockRateAdjust |
| 16996 | |
| 16997 | TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} |
| 16998 | TPMI_RH_PROVISION @auth Auth Handle: 1 |
| 16999 | Auth Role: USER |
| 17000 | |
| 17001 | TPM_CLOCK_ADJUST rateAdjust Adjustment to current Clock update rate |
| 17002 | |
| 17003 | |
| 17004 | Table 192 — TPM2_ClockRateAdjust Response |
| 17005 | Type Name Description |
| 17006 | |
| 17007 | TPM_ST tag see clause 6 |
| 17008 | UINT32 responseSize |
| 17009 | TPM_RC responseCode |
| 17010 | |
| 17011 | |
| 17012 | |
| 17013 | |
| 17014 | Page 384 TCG Published Family “2.0” |
| 17015 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 17016 | Trusted Platform Module Library Part 3: Commands |
| 17017 | |
| 17018 | |
| 17019 | |
| 17020 | 29.3.3 Detailed Actions |
| 17021 | |
| 17022 | 1 #include "InternalRoutines.h" |
| 17023 | 2 #include "ClockRateAdjust_fp.h" |
| 17024 | 3 #ifdef TPM_CC_ClockRateAdjust // Conditional expansion of this file |
| 17025 | 4 TPM_RC |
| 17026 | 5 TPM2_ClockRateAdjust( |
| 17027 | 6 ClockRateAdjust_In *in // IN: input parameter list |
| 17028 | 7 ) |
| 17029 | 8 { |
| 17030 | 9 // Internal Data Update |
| 17031 | 10 TimeSetAdjustRate(in->rateAdjust); |
| 17032 | 11 |
| 17033 | 12 return TPM_RC_SUCCESS; |
| 17034 | 13 } |
| 17035 | 14 #endif // CC_ClockRateAdjust |
| 17036 | |
| 17037 | |
| 17038 | |
| 17039 | |
| 17040 | Family “2.0” TCG Published Page 385 |
| 17041 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 17042 | Part 3: Commands Trusted Platform Module Library |
| 17043 | |
| 17044 | |
| 17045 | 30 Capability Commands |
| 17046 | |
| 17047 | 30.1 Introduction |
| 17048 | |
| 17049 | The TPM has numerous values that indicate the state, capabilities, and properties of the TPM. These |
| 17050 | values are needed for proper management of the TPM. The TPM2_GetCapability() command is used to |
| 17051 | access these values. |
| 17052 | TPM2_GetCapability() allows reporting of multiple values in a single call. The values are grouped |
| 17053 | according to type. |
| 17054 | |
| 17055 | NOTE TPM2_TestParms()is used to determine if a TPM supports a particular combination of algorith m |
| 17056 | parameters |
| 17057 | |
| 17058 | |
| 17059 | 30.2 TPM2_GetCapability |
| 17060 | |
| 17061 | 30.2.1 General Description |
| 17062 | |
| 17063 | This command returns various information regarding the TPM and its current state. |
| 17064 | The capability parameter determines the category of data returned. The property parameter selects the |
| 17065 | first value of the selected category to be returned. If there is no property that corresponds to the value of |
| 17066 | property, the next higher value is returned, if it exists. |
| 17067 | |
| 17068 | EXAMPLE 1 The list of handles of transient objects currently loaded in the TPM may be read one at a time. O n |
| 17069 | the first read, set the property to TRANSIENT_FIRST and propertyCount to one. If a transient object |
| 17070 | is present, the lowest numbered handle is returned and moreData will be YES if transient objects |
| 17071 | with higher handles are loaded. On the subsequent call, u se returned handle value plus 1 in order to |
| 17072 | access the next higher handle. |
| 17073 | |
| 17074 | The propertyCount parameter indicates the number of capabilities in the indicated group that are |
| 17075 | requested. The TPM will return the number of requested values (propertyCount) or until the last property |
| 17076 | of the requested type has been returned. |
| 17077 | |
| 17078 | NOTE 1 The type of the capability is determined by a combination of capability and property. |
| 17079 | |
| 17080 | NOTE 2 If the propertyCount selects an unimplemented property, the next higher implemented property is |
| 17081 | returned. |
| 17082 | |
| 17083 | When all of the properties of the requested type have been returned, the moreData parameter in the |
| 17084 | response will be set to NO. Otherwise, it will be set to YES. |
| 17085 | |
| 17086 | NOTE 3 The moreData parameter will be YES if there are more properties even if the requested number of |
| 17087 | capabilities has been returned. |
| 17088 | |
| 17089 | The TPM is not required to return more than one value at a time. It is not required to provide the same |
| 17090 | number of values in response to subsequent requests. |
| 17091 | |
| 17092 | EXAMPLE 2 A TPM may return 4 properties in response to a TPM2_GetCapability( capability = |
| 17093 | TPM_CAP_TPM_PROPERTY, property = TPM_PT_MANUFACTURER, propertyCount = 8 ) and for a |
| 17094 | latter request with the same parameters, the TPM m ay return as few as one and as many as 8 |
| 17095 | values. |
| 17096 | |
| 17097 | When the TPM is in Failure mode, a TPM is required to allow use of this command for access of the |
| 17098 | following capabilities: |
| 17099 | |
| 17100 | |
| 17101 | |
| 17102 | |
| 17103 | Page 386 TCG Published Family “2.0” |
| 17104 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 17105 | Trusted Platform Module Library Part 3: Commands |
| 17106 | |
| 17107 | |
| 17108 | TPM_PT_MANUFACTURER |
| 17109 | TPM_PT_VENDOR_STRING_1 |
| 17110 | |
| 17111 | (3) |
| 17112 | TPM_PT_VENDOR_STRING_2 |
| 17113 | |
| 17114 | (3) |
| 17115 | TPM_PT_VENDOR_STRING_3 |
| 17116 | |
| 17117 | (3) |
| 17118 | TPM_PT_VENDOR_STRING_4 |
| 17119 | TPM_PT_VENDOR_TPM_TYPE |
| 17120 | TPM_PT_FIRMWARE_VERSION_1 |
| 17121 | TPM_PT_FIRMWARE_VERSION_2 |
| 17122 | |
| 17123 | NOTE 4 If the vendor string does not require one of these values, the property type does not need to exist. |
| 17124 | |
| 17125 | A vendor may optionally allow the TPM to return other values. |
| 17126 | If in Failure mode and a capability is requested that is not available in Failure mode, the TPM shall return |
| 17127 | no value. |
| 17128 | |
| 17129 | EXAMPLE 3 Assume the TPM is in Failure mode and the TPM only supports reporting of the minimum required |
| 17130 | set of properties (the limited set to TPML_TAGGED_PCR_PROPERTY values). If a |
| 17131 | TPM2_GetCapability is received requesting a capability that has a property type value greater than |
| 17132 | TPM_PT_FIRMWARE_VERSION_2, the TPM will return a zero length list with the moreData |
| 17133 | parameter set to NO. If the property type is less than TPM_PT_MANUFACTURER, the TPM will |
| 17134 | return TPM_PT_MANUFACTURER. |
| 17135 | |
| 17136 | In Failure mode, tag is required to be TPM_ST_NO_SESSIONS or the TPM shall return |
| 17137 | TPM_RC_FAILURE. |
| 17138 | The capability categories and the types of the return values are: |
| 17139 | |
| 17140 | capability property Return Type |
| 17141 | (1) |
| 17142 | TPM_CAP_ALGS TPM_ALG_ID TPML_ALG_PROPERTY |
| 17143 | TPM_CAP_HANDLES TPM_HANDLE TPML_HANDLE |
| 17144 | TPM_CAP_COMMANDS TPM_CC TPML_CCA |
| 17145 | TPM_CAP_PP_COMMANDS TPM_CC TPML_CC |
| 17146 | TPM_CAP_AUDIT_COMMANDS TPM_CC TPML_CC |
| 17147 | TPM_CAP_PCRS Reserved TPML_PCR_SELECTION |
| 17148 | TPM_CAP_TPM_PROPERTIES TPM_PT TPML_TAGGED_TPM_PROPERTY |
| 17149 | TPM_CAP_PCR_PROPERTIES TPM_PT_PCR TPML_TAGGED_PCR_PROPERTY |
| 17150 | (1) |
| 17151 | TPM_CAP_ECC_CURVE TPM_ECC_CURVE TPML_ECC_CURVE |
| 17152 | TPM_CAP_VENDOR_PROPERTY manufacturer specific manufacturer-specific values |
| 17153 | NOTES: |
| 17154 | (1) The TPM_ALG_ID or TPM_ECC_CURVE is cast to a UINT32 |
| 17155 | |
| 17156 | |
| 17157 | |
| 17158 | |
| 17159 | Family “2.0” TCG Published Page 387 |
| 17160 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 17161 | Part 3: Commands Trusted Platform Module Library |
| 17162 | |
| 17163 | |
| 17164 | TPM_CAP_ALGS – Returns a list of TPMS_ALG_PROPERTIES. Each entry is an algorithm ID |
| 17165 | and a set of properties of the algorithm. |
| 17166 | TPM_CAP_HANDLES – Returns a list of all of the handles within the handle range of the |
| 17167 | property parameter. The range of the returned handles is determined by the handle type (the |
| 17168 | most-significant octet (MSO) of the property). Any of the defined handle types is allowed |
| 17169 | |
| 17170 | EXAMPLE 4 If the MSO of property is TPM_HT_NV_INDEX, then the TPM will return a list of NV Index |
| 17171 | values. |
| 17172 | |
| 17173 | EXAMPLE 5 If the MSO of property is TPM_HT_PCR, then the TPM will return a list of PCR. |
| 17174 | |
| 17175 | For this capability, use of TPM_HT_LOADED_SESSION and TPM_HT_SAVED_SESSION is |
| 17176 | allowed. Requesting handles with a handle type of TPM_HT_LOADED_SESSION will return |
| 17177 | handles for loaded sessions. The returned handle values will have a handle type of either |
| 17178 | TPM_HT_HMAC_SESSION or TPM_HT_POLICY_SESSION. If saved sessions are requested, |
| 17179 | all returned values will have the TPM_HT_HMAC_SESSION handle type because the TPM does |
| 17180 | not track the session type of saved sessions. |
| 17181 | |
| 17182 | NOTE 5 TPM_HT_LOADED_SESSION and TPM_HT_HMAC_SESSION have the same value, as do |
| 17183 | TPM_HT_SAVED_SESSION and TPM_HT_POLICY_SESSION. It is not possible to request that |
| 17184 | the TPM return a list of loaded HMAC sessions without including the policy sessions. |
| 17185 | |
| 17186 | TPM_CAP_COMMANDS – Returns a list of the command attributes for all of the commands |
| 17187 | implemented in the TPM, starting with the TPM_CC indicated by the property parameter. If |
| 17188 | vendor specific commands are implemented, the vendor-specific command attribute with the |
| 17189 | lowest commandIndex, is returned after the non-vendor-specific (base) command. |
| 17190 | |
| 17191 | NOTE 6 The type of the property parameter is a TPM_CC while the type of the returned list is |
| 17192 | TPML_CCA. |
| 17193 | |
| 17194 | TPM_CAP_PP_COMMANDS – Returns a list of all of the commands currently requiring Physical |
| 17195 | Presence for confirmation of platform authorization. The list will start with the TPM_CC indicated |
| 17196 | by property. |
| 17197 | TPM_CAP_AUDIT_COMMANDS – Returns a list of all of the commands currently set for |
| 17198 | command audit. |
| 17199 | TPM_CAP_PCRS – Returns the current allocation of PCR in a TPML_PCR_SELECTION. The |
| 17200 | property parameter shall be zero. The TPM will always respond to this command with the full |
| 17201 | PCR allocation and moreData will be NO. |
| 17202 | TPM_CAP_TPM_PROPERTIES – Returns a list of tagged properties. The tag is a TPM_PT and |
| 17203 | the property is a 32-bit value. The properties are returned in groups. Each property group is on a |
| 17204 | 256-value boundary (that is, the boundary occurs when the TPM_PT is evenly divisible by 256). |
| 17205 | The TPM will only return values in the same group as the property parameter in the command. |
| 17206 | TPM_CAP_PCR_PROPERTIES – Returns a list of tagged PCR properties. The tag is a |
| 17207 | TPM_PT_PCR and the property is a TPMS_PCR_SELECT. |
| 17208 | The input command property is a TPM_PT_PCR (see TPM 2.0 Part 2 for PCR properties to be |
| 17209 | requested) that specifies the first property to be returned. If propertyCount is greater than 1, the list of |
| 17210 | properties begins with that property and proceeds in TPM_PT_PCR sequence. |
| 17211 | Each item in the list is a TPMS_PCR_SELECT structure that contains a bitmap of all PCR. |
| 17212 | |
| 17213 | NOTE 7 A PCR index in all banks (all hash algorithms) has the same properties, so the hash algorithm is |
| 17214 | not specified here. |
| 17215 | |
| 17216 | |
| 17217 | |
| 17218 | |
| 17219 | Page 388 TCG Published Family “2.0” |
| 17220 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 17221 | Trusted Platform Module Library Part 3: Commands |
| 17222 | |
| 17223 | |
| 17224 | TPM_CAP_TPM_ECC_CURVES – Returns a list of ECC curve identifiers currently available for |
| 17225 | use in the TPM. |
| 17226 | The moreData parameter will have a value of YES if there are more values of the requested type that |
| 17227 | were not returned. |
| 17228 | If no next capability exists, the TPM will return a zero-length list and moreData will have a value of NO. |
| 17229 | |
| 17230 | |
| 17231 | |
| 17232 | |
| 17233 | Family “2.0” TCG Published Page 389 |
| 17234 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 17235 | Part 3: Commands Trusted Platform Module Library |
| 17236 | |
| 17237 | |
| 17238 | |
| 17239 | 30.2.2 Command and Response |
| 17240 | |
| 17241 | Table 193 — TPM2_GetCapability Command |
| 17242 | Type Name Description |
| 17243 | |
| 17244 | TPM_ST_SESSIONS if an audit session is present; |
| 17245 | TPMI_ST_COMMAND_TAG tag |
| 17246 | otherwise, TPM_ST_NO_SESSIONS |
| 17247 | UINT32 commandSize |
| 17248 | TPM_CC commandCode TPM_CC_GetCapability |
| 17249 | |
| 17250 | TPM_CAP capability group selection; determines the format of the response |
| 17251 | UINT32 property further definition of information |
| 17252 | UINT32 propertyCount number of properties of the indicated type to return |
| 17253 | |
| 17254 | |
| 17255 | Table 194 — TPM2_GetCapability Response |
| 17256 | Type Name Description |
| 17257 | |
| 17258 | TPM_ST tag see clause 6 |
| 17259 | UINT32 responseSize |
| 17260 | TPM_RC responseCode |
| 17261 | |
| 17262 | TPMI_YES_NO moreData flag to indicate if there are more values of this type |
| 17263 | TPMS_CAPABILITY_DATA capabilityData the capability data |
| 17264 | |
| 17265 | |
| 17266 | |
| 17267 | |
| 17268 | Page 390 TCG Published Family “2.0” |
| 17269 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 17270 | Trusted Platform Module Library Part 3: Commands |
| 17271 | |
| 17272 | |
| 17273 | |
| 17274 | 30.2.3 Detailed Actions |
| 17275 | |
| 17276 | 1 #include "InternalRoutines.h" |
| 17277 | 2 #include "GetCapability_fp.h" |
| 17278 | 3 #ifdef TPM_CC_GetCapability // Conditional expansion of this file |
| 17279 | |
| 17280 | |
| 17281 | Error Returns Meaning |
| 17282 | |
| 17283 | TPM_RC_HANDLE value of property is in an unsupported handle range for the |
| 17284 | TPM_CAP_HANDLES capability value |
| 17285 | TPM_RC_VALUE invalid capability; or property is not 0 for the TPM_CAP_PCRS |
| 17286 | capability value |
| 17287 | |
| 17288 | 4 TPM_RC |
| 17289 | 5 TPM2_GetCapability( |
| 17290 | 6 GetCapability_In *in, // IN: input parameter list |
| 17291 | 7 GetCapability_Out *out // OUT: output parameter list |
| 17292 | 8 ) |
| 17293 | 9 { |
| 17294 | 10 // Command Output |
| 17295 | 11 |
| 17296 | 12 // Set output capability type the same as input type |
| 17297 | 13 out->capabilityData.capability = in->capability; |
| 17298 | 14 |
| 17299 | 15 switch(in->capability) |
| 17300 | 16 { |
| 17301 | 17 case TPM_CAP_ALGS: |
| 17302 | 18 out->moreData = AlgorithmCapGetImplemented((TPM_ALG_ID) in->property, |
| 17303 | 19 in->propertyCount, &out->capabilityData.data.algorithms); |
| 17304 | 20 break; |
| 17305 | 21 case TPM_CAP_HANDLES: |
| 17306 | 22 switch(HandleGetType((TPM_HANDLE) in->property)) |
| 17307 | 23 { |
| 17308 | 24 case TPM_HT_TRANSIENT: |
| 17309 | 25 // Get list of handles of loaded transient objects |
| 17310 | 26 out->moreData = ObjectCapGetLoaded((TPM_HANDLE) in->property, |
| 17311 | 27 in->propertyCount, |
| 17312 | 28 &out->capabilityData.data.handles); |
| 17313 | 29 break; |
| 17314 | 30 case TPM_HT_PERSISTENT: |
| 17315 | 31 // Get list of handles of persistent objects |
| 17316 | 32 out->moreData = NvCapGetPersistent((TPM_HANDLE) in->property, |
| 17317 | 33 in->propertyCount, |
| 17318 | 34 &out->capabilityData.data.handles); |
| 17319 | 35 break; |
| 17320 | 36 case TPM_HT_NV_INDEX: |
| 17321 | 37 // Get list of defined NV index |
| 17322 | 38 out->moreData = NvCapGetIndex((TPM_HANDLE) in->property, |
| 17323 | 39 in->propertyCount, |
| 17324 | 40 &out->capabilityData.data.handles); |
| 17325 | 41 break; |
| 17326 | 42 case TPM_HT_LOADED_SESSION: |
| 17327 | 43 // Get list of handles of loaded sessions |
| 17328 | 44 out->moreData = SessionCapGetLoaded((TPM_HANDLE) in->property, |
| 17329 | 45 in->propertyCount, |
| 17330 | 46 &out->capabilityData.data.handles); |
| 17331 | 47 break; |
| 17332 | 48 case TPM_HT_ACTIVE_SESSION: |
| 17333 | 49 // Get list of handles of |
| 17334 | 50 out->moreData = SessionCapGetSaved((TPM_HANDLE) in->property, |
| 17335 | 51 in->propertyCount, |
| 17336 | 52 &out->capabilityData.data.handles); |
| 17337 | |
| 17338 | Family “2.0” TCG Published Page 391 |
| 17339 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 17340 | Part 3: Commands Trusted Platform Module Library |
| 17341 | |
| 17342 | 53 break; |
| 17343 | 54 case TPM_HT_PCR: |
| 17344 | 55 // Get list of handles of PCR |
| 17345 | 56 out->moreData = PCRCapGetHandles((TPM_HANDLE) in->property, |
| 17346 | 57 in->propertyCount, |
| 17347 | 58 &out->capabilityData.data.handles); |
| 17348 | 59 break; |
| 17349 | 60 case TPM_HT_PERMANENT: |
| 17350 | 61 // Get list of permanent handles |
| 17351 | 62 out->moreData = PermanentCapGetHandles( |
| 17352 | 63 (TPM_HANDLE) in->property, |
| 17353 | 64 in->propertyCount, |
| 17354 | 65 &out->capabilityData.data.handles); |
| 17355 | 66 break; |
| 17356 | 67 default: |
| 17357 | 68 // Unsupported input handle type |
| 17358 | 69 return TPM_RC_HANDLE + RC_GetCapability_property; |
| 17359 | 70 break; |
| 17360 | 71 } |
| 17361 | 72 break; |
| 17362 | 73 case TPM_CAP_COMMANDS: |
| 17363 | 74 out->moreData = CommandCapGetCCList((TPM_CC) in->property, |
| 17364 | 75 in->propertyCount, |
| 17365 | 76 &out->capabilityData.data.command); |
| 17366 | 77 break; |
| 17367 | 78 case TPM_CAP_PP_COMMANDS: |
| 17368 | 79 out->moreData = PhysicalPresenceCapGetCCList((TPM_CC) in->property, |
| 17369 | 80 in->propertyCount, &out->capabilityData.data.ppCommands); |
| 17370 | 81 break; |
| 17371 | 82 case TPM_CAP_AUDIT_COMMANDS: |
| 17372 | 83 out->moreData = CommandAuditCapGetCCList((TPM_CC) in->property, |
| 17373 | 84 in->propertyCount, |
| 17374 | 85 &out->capabilityData.data.auditCommands); |
| 17375 | 86 break; |
| 17376 | 87 case TPM_CAP_PCRS: |
| 17377 | 88 // Input property must be 0 |
| 17378 | 89 if(in->property != 0) |
| 17379 | 90 return TPM_RC_VALUE + RC_GetCapability_property; |
| 17380 | 91 out->moreData = PCRCapGetAllocation(in->propertyCount, |
| 17381 | 92 &out->capabilityData.data.assignedPCR); |
| 17382 | 93 break; |
| 17383 | 94 case TPM_CAP_PCR_PROPERTIES: |
| 17384 | 95 out->moreData = PCRCapGetProperties((TPM_PT_PCR) in->property, |
| 17385 | 96 in->propertyCount, |
| 17386 | 97 &out->capabilityData.data.pcrProperties); |
| 17387 | 98 break; |
| 17388 | 99 case TPM_CAP_TPM_PROPERTIES: |
| 17389 | 100 out->moreData = TPMCapGetProperties((TPM_PT) in->property, |
| 17390 | 101 in->propertyCount, |
| 17391 | 102 &out->capabilityData.data.tpmProperties); |
| 17392 | 103 break; |
| 17393 | 104 #ifdef TPM_ALG_ECC |
| 17394 | 105 case TPM_CAP_ECC_CURVES: |
| 17395 | 106 out->moreData = CryptCapGetECCCurve((TPM_ECC_CURVE ) in->property, |
| 17396 | 107 in->propertyCount, |
| 17397 | 108 &out->capabilityData.data.eccCurves); |
| 17398 | 109 break; |
| 17399 | 110 #endif // TPM_ALG_ECC |
| 17400 | 111 case TPM_CAP_VENDOR_PROPERTY: |
| 17401 | 112 // vendor property is not implemented |
| 17402 | 113 default: |
| 17403 | 114 // Unexpected TPM_CAP value |
| 17404 | 115 return TPM_RC_VALUE; |
| 17405 | 116 break; |
| 17406 | 117 } |
| 17407 | 118 |
| 17408 | |
| 17409 | Page 392 TCG Published Family “2.0” |
| 17410 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 17411 | Trusted Platform Module Library Part 3: Commands |
| 17412 | |
| 17413 | 119 return TPM_RC_SUCCESS; |
| 17414 | 120 } |
| 17415 | 121 #endif // CC_GetCapability |
| 17416 | |
| 17417 | |
| 17418 | |
| 17419 | |
| 17420 | Family “2.0” TCG Published Page 393 |
| 17421 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 17422 | Part 3: Commands Trusted Platform Module Library |
| 17423 | |
| 17424 | |
| 17425 | 30.3 TPM2_TestParms |
| 17426 | |
| 17427 | 30.3.1 General Description |
| 17428 | |
| 17429 | This command is used to check to see if specific combinations of algorithm parameters are supported. |
| 17430 | The TPM will unmarshal the provided TPMT_PUBLIC_PARMS. If the parameters unmarshal correctly, |
| 17431 | then the TPM will return TPM_RC_SUCCESS, indicating that the parameters are valid for the TPM. The |
| 17432 | TPM will return the appropriate unmarshaling error if a parameter is not valid. |
| 17433 | |
| 17434 | |
| 17435 | |
| 17436 | |
| 17437 | Page 394 TCG Published Family “2.0” |
| 17438 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 17439 | Trusted Platform Module Library Part 3: Commands |
| 17440 | |
| 17441 | |
| 17442 | |
| 17443 | 30.3.2 Command and Response |
| 17444 | |
| 17445 | Table 195 — TPM2_TestParms Command |
| 17446 | Type Name Description |
| 17447 | |
| 17448 | TPM_ST_SESSIONS if an audit session is present; |
| 17449 | TPMI_ST_COMMAND_TAG tag |
| 17450 | otherwise, TPM_ST_NO_SESSIONS |
| 17451 | UINT32 commandSize |
| 17452 | TPM_CC commandCode TPM_CC_TestParms |
| 17453 | |
| 17454 | TPMT_PUBLIC_PARMS parameters algorithm parameters to be validated |
| 17455 | |
| 17456 | |
| 17457 | Table 196 — TPM2_TestParms Response |
| 17458 | Type Name Description |
| 17459 | |
| 17460 | TPM_ST tag see clause 6 |
| 17461 | UINT32 responseSize |
| 17462 | TPM_RC responseCode TPM_RC |
| 17463 | |
| 17464 | |
| 17465 | |
| 17466 | |
| 17467 | Family “2.0” TCG Published Page 395 |
| 17468 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 17469 | Part 3: Commands Trusted Platform Module Library |
| 17470 | |
| 17471 | |
| 17472 | |
| 17473 | 30.3.3 Detailed Actions |
| 17474 | |
| 17475 | 1 #include "InternalRoutines.h" |
| 17476 | 2 #include "TestParms_fp.h" |
| 17477 | 3 #ifdef TPM_CC_TestParms // Conditional expansion of this file |
| 17478 | 4 TPM_RC |
| 17479 | 5 TPM2_TestParms( |
| 17480 | 6 TestParms_In *in // IN: input parameter list |
| 17481 | 7 ) |
| 17482 | 8 { |
| 17483 | 9 // Input parameter is not reference in command action |
| 17484 | 10 in = NULL; |
| 17485 | 11 |
| 17486 | 12 // The parameters are tested at unmarshal process. We do nothing in command |
| 17487 | 13 // action |
| 17488 | 14 return TPM_RC_SUCCESS; |
| 17489 | 15 } |
| 17490 | 16 #endif // CC_TestParms |
| 17491 | |
| 17492 | |
| 17493 | |
| 17494 | |
| 17495 | Page 396 TCG Published Family “2.0” |
| 17496 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 17497 | Trusted Platform Module Library Part 3: Commands |
| 17498 | |
| 17499 | |
| 17500 | 31 Non-volatile Storage |
| 17501 | |
| 17502 | 31.1 Introduction |
| 17503 | |
| 17504 | The NV commands are used to create, update, read, and delete allocations of space in NV memory. |
| 17505 | Before an Index may be used, it must be defined (TPM2_NV_DefineSpace()). |
| 17506 | An Index may be modified if the proper write authorization is provided or read if the proper read |
| 17507 | authorization is provided. Different controls are available for reading and writing. |
| 17508 | An Index may have an Index-specific authValue and authPolicy. The authValue may be used to authorize |
| 17509 | reading if TPMA_NV_AUTHREAD is SET and writing if TPMA_NV_AUTHREAD is SET. The authPolicy |
| 17510 | may be used to authorize reading if TPMA_NV_POLICYREAD is SET and writing if |
| 17511 | TPMA_NV_POLICYWRITE is SET. |
| 17512 | For commands that have both authHandle and nvIndex parameters, authHandle can be an NV Index, |
| 17513 | Platform Authorization, or Owner Authorization. If authHandle is an NV Index, it must be the same as |
| 17514 | nvIndex (TPM_RC_NV_AUTHORIZATION). |
| 17515 | TPMA_NV_PPREAD and TPMA_NV_PPWRITE indicate if reading or writing of the NV Index may be |
| 17516 | authorized by platformAuth or platformPolicy. |
| 17517 | TPMA_NV_OWNERREAD and TPMA_NV_OWNERWRITE indicate if reading or writing of the NV Index |
| 17518 | may be authorized by ownerAuth or ownerPolicy. |
| 17519 | If an operation on an NV index requires authorization, and the authHandle parameter is the handle of an |
| 17520 | NV Index, then the nvIndex parameter must have the same value or the TPM will return |
| 17521 | TPM_RC_NV_AUTHORIZATION. |
| 17522 | |
| 17523 | NOTE 1 This check ensures that the authorization that was provided is associated with the NV Index being |
| 17524 | authorized. |
| 17525 | |
| 17526 | For creating an Index, Owner Authorization may not be used if shEnable is CLEAR and Platform |
| 17527 | Authorization may not be used if phEnableNV is CLEAR. |
| 17528 | If an Index was defined using Platform Authorization, then that Index is not accessible when phEnableNV |
| 17529 | is CLEAR. If an Index was defined using Owner Authorization, then that Index is not accessible when |
| 17530 | shEnable is CLEAR. |
| 17531 | For read access control, any combination of TPMA_NV_PPREAD, TPMA_NV_OWNERREAD, |
| 17532 | TPMA_NV_AUTHREAD, or TPMA_NV_POLICYREAD is allowed as long as at least one is SET. |
| 17533 | For write access control, any combination of TPMA_NV_PPWRITE, TPMA_NV_OWNERWRITE, |
| 17534 | TPMA_NV_AUTHWRITE, or TPMA_NV_POLICYWRITE is allowed as long as at least one is SET. |
| 17535 | If an Index has been defined and not written, then any operation on the NV Index that requires read |
| 17536 | authorization will fail (TPM_RC_NV_INITIALIZED). This check may be made before or after other |
| 17537 | authorization checks but shall be performed before checking the NV Index authValue. An authorization |
| 17538 | failure due to the NV Index not having been written shall not be logged by the dictionary attack logic. |
| 17539 | If TPMA_NV_CLEAR_STCLEAR is SET, then the TPMA_NV_WRITTEN will be CLEAR on each |
| 17540 | TPM2_Startup(TPM_SU_CLEAR). TPMA_NV_CLEAR_STCLEAR shall not be SET if |
| 17541 | TPMA_NV_COUNTER is SET. |
| 17542 | The code in the “Detailed Actions” clause of each command is written to interface with an implementation- |
| 17543 | dependent library that allows access to NV memory. The actions assume no specific layout of the |
| 17544 | structure of the NV data. |
| 17545 | Only one NV Index may be directly referenced in a command. |
| 17546 | |
| 17547 | NOTE 2 This means that, if authHandle references an NV Index, then nvIndex will have the same value. |
| 17548 | However, this does not limit the number of changes that may occur as side effects. For example, any |
| 17549 | number of NV Indexes might be relocated as a result of deleting or adding a NV Index. |
| 17550 | |
| 17551 | Family “2.0” TCG Published Page 397 |
| 17552 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 17553 | Part 3: Commands Trusted Platform Module Library |
| 17554 | |
| 17555 | |
| 17556 | 31.2 NV Counters |
| 17557 | |
| 17558 | When an Index has the TPMA_NV_COUNTER attribute set, it behaves as a monotonic counter and may |
| 17559 | only be updated using TPM2_NV_Increment(). |
| 17560 | When an NV counter is created, the TPM shall initialize the 8-octet counter value with a number that is |
| 17561 | greater than any count value for any NV counter on the TPM since the time of TPM manufacture. |
| 17562 | An NV counter may be defined with the TPMA_NV_ORDERLY attribute to indicate that the NV Index is |
| 17563 | expected to be modified at a high frequency and that the data is only required to persist when the TPM |
| 17564 | goes through an orderly shutdown process. The TPM may update the counter value in RAM and |
| 17565 | occasionally update the non-volatile version of the counter. An orderly shutdown is one occasion to |
| 17566 | update the non-volatile count. If the difference between the volatile and non-volatile version of the counter |
| 17567 | becomes as large as MAX_ORDERLY_COUNT, this shall be another occasion for updating the non- |
| 17568 | volatile count. |
| 17569 | Before an NV counter can be used, the TPM shall validate that the count is not less than a previously |
| 17570 | reported value. If the TPMA_NV_ORDERLY attribute is not SET, or if the TPM experienced an orderly |
| 17571 | shutdown, then the count is assumed to be correct. If the TPMA_NV_ORDERLY attribute is SET, and the |
| 17572 | TPM shutdown was not orderly, then the TPM shall OR MAX_ORDERLY_COUNT to the contents of the |
| 17573 | non-volatile counter and set that as the current count. |
| 17574 | |
| 17575 | NOTE 1 Because the TPM would have updated the NV Index if the difference between the count values was |
| 17576 | equal to MAX_ORDERLY_COUNT + 1, the highest value that could have been in the NV Index is |
| 17577 | MAX_ORDERLY_COUNT so it is safe to restore that value. |
| 17578 | |
| 17579 | NOTE 2 The TPM may implement the RAM portion of the counter such that the effective value of the NV |
| 17580 | counter is the sum of both the volatile and non-volatile parts. If so, then the TPM may initialize the |
| 17581 | RAM version of the counter to MAX_ORDERLY_COUNT and no update of NV is necessary. |
| 17582 | |
| 17583 | NOTE 3 When a new NV counter is created, the TPM may search all the coun ters to determine which has the |
| 17584 | highest value. In this search, the TPM would use the sum of the non -volatile and RAM portions of |
| 17585 | the counter. The RAM portion of the counter shall be properly initialized to reflect shutdown process |
| 17586 | (orderly or not) of the TPM. |
| 17587 | |
| 17588 | |
| 17589 | |
| 17590 | |
| 17591 | Page 398 TCG Published Family “2.0” |
| 17592 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 17593 | Trusted Platform Module Library Part 3: Commands |
| 17594 | |
| 17595 | |
| 17596 | 31.3 TPM2_NV_DefineSpace |
| 17597 | |
| 17598 | 31.3.1 General Description |
| 17599 | |
| 17600 | This command defines the attributes of an NV Index and causes the TPM to reserve space to hold the |
| 17601 | data associated with the NV Index. If a definition already exists at the NV Index, the TPM will return |
| 17602 | TPM_RC_NV_DEFINED. |
| 17603 | The TPM will return TPM_RC_ATTRIBUTES if more than one of TPMA_NV_COUNTER, |
| 17604 | TPMA_NV_BITS, or TPMA_NV_EXTEND is SET in publicInfo. |
| 17605 | |
| 17606 | NOTE 1 It is not required that any of these three attributes be set. |
| 17607 | |
| 17608 | The TPM shall return TPM_RC_ATTRIBUTES if TPMA_NV_WRITTEN, TPM_NV_READLOCKED, or |
| 17609 | TPMA_NV_WRITELOCKED is SET. |
| 17610 | If TPMA_NV_COUNTER or TPMA_NV_BITS is SET, then publicInfo→dataSize shall be set to eight (8) or |
| 17611 | the TPM shall return TPM_RC_SIZE. |
| 17612 | If TPMA_NV_EXTEND is SET, then publicInfo→dataSize shall match the digest size of the |
| 17613 | publicInfo.nameAlg or the TPM shall return TPM_RC_SIZE. |
| 17614 | If the NV Index is an ordinary Index and publicInfo→dataSize is larger than supported by the TPM |
| 17615 | implementation then the TPM shall return TPM_RC_SIZE. |
| 17616 | |
| 17617 | NOTE 2 The limit for the data size may vary according to the type of the index. For example, if the index has |
| 17618 | TPMA_NV_ORDERLY SET, then the maximum size of an ordinary NV Index may be less than the |
| 17619 | size of an ordinary NV Index that has TPMA_NV_ORDERLY CLEAR. |
| 17620 | |
| 17621 | At least one of TPMA_NV_PPREAD, TPMA_NV_OWNERREAD, TPMA_NV_AUTHREAD, or |
| 17622 | TPMA_NV_POLICYREAD shall be SET or the TPM shall return TPM_RC_ATTRIBUTES. |
| 17623 | At least one of TPMA_NV_PPWRITE, TPMA_NV_OWNERWRITE, TPMA_NV_AUTHWRITE, or |
| 17624 | TPMA_NV_POLICYWRITE shall be SET or the TPM shall return TPM_RC_ATTRIBUTES. |
| 17625 | If TPMA_NV_CLEAR_STCLEAR is SET, then TPMA_NV_COUNTER shall be CLEAR or the TPM shall |
| 17626 | return TPM_RC_ATTRIBUTES. |
| 17627 | If platformAuth/platformPolicy is used for authorization, then TPMA_NV_PLATFORMCREATE shall be |
| 17628 | SET in publicInfo. If ownerAuth/ownerPolicy is used for authorization, TPMA_NV_PLATFORMCREATE |
| 17629 | shall be CLEAR in publicInfo. If TPMA_NV_PLATFORMCREATE is not set correctly for the authorization, |
| 17630 | the TPM shall return TPM_RC_ATTRIBUTES. |
| 17631 | If TPMA_NV_POLICY_DELETE is SET, then the authorization shall be with Platform Authorization or the |
| 17632 | TPM shall return TPM_RC_ATTRIBUTES. |
| 17633 | If the implementation does not support TPM2_NV_Increment(), the TPM shall return |
| 17634 | TPM_RC_ATTRIBUTES if TPMA_NV_COUNTER is SET. |
| 17635 | If the implementation does not support TPM2_NV_SetBits(), the TPM shall return |
| 17636 | TPM_RC_ATTRIBUTES if TPMA_NV_BITS is SET. |
| 17637 | If the implementation does not support TPM2_NV_Extend(), the TPM shall return |
| 17638 | TPM_RC_ATTRIBUTES if TPMA_NV_EXTEND is SET. |
| 17639 | If the implementation does not support TPM2_NV_UndefineSpaceSpecial(), the TPM shall return |
| 17640 | TPM_RC_ATTRIBUTES if TPMA_NV_POLICY_DELETE is SET. |
| 17641 | After the successful completion of this command, the NV Index exists but TPMA_NV_WRITTEN will be |
| 17642 | CLEAR. Any access of the NV data will return TPM_RC_NV_UINITIALIZED. |
| 17643 | |
| 17644 | |
| 17645 | |
| 17646 | |
| 17647 | Family “2.0” TCG Published Page 399 |
| 17648 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 17649 | Part 3: Commands Trusted Platform Module Library |
| 17650 | |
| 17651 | In some implementations, an NV Index with the TPMA_NV_COUNTER attribute may require special TPM |
| 17652 | resources that provide higher endurance than regular NV. For those implementations, if this command |
| 17653 | fails because of lack of resources, the TPM will return TPM_RC_NV_SPACE. |
| 17654 | The value of auth is saved in the created structure. The size of auth is limited to be no larger than the size |
| 17655 | of the digest produced by the NV Index's nameAlg (TPM_RC_SIZE). |
| 17656 | |
| 17657 | |
| 17658 | |
| 17659 | |
| 17660 | Page 400 TCG Published Family “2.0” |
| 17661 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 17662 | Trusted Platform Module Library Part 3: Commands |
| 17663 | |
| 17664 | |
| 17665 | |
| 17666 | 31.3.2 Command and Response |
| 17667 | |
| 17668 | Table 197 — TPM2_NV_DefineSpace Command |
| 17669 | Type Name Description |
| 17670 | |
| 17671 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 17672 | UINT32 commandSize |
| 17673 | TPM_CC commandCode TPM_CC_NV_DefineSpace {NV} |
| 17674 | |
| 17675 | TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} |
| 17676 | TPMI_RH_PROVISION @authHandle Auth Index: 1 |
| 17677 | Auth Role: USER |
| 17678 | |
| 17679 | TPM2B_AUTH auth the authorization value |
| 17680 | TPM2B_NV_PUBLIC publicInfo the public parameters of the NV area |
| 17681 | |
| 17682 | |
| 17683 | Table 198 — TPM2_NV_DefineSpace Response |
| 17684 | Type Name Description |
| 17685 | |
| 17686 | TPM_ST tag see clause 6 |
| 17687 | UINT32 responseSize |
| 17688 | TPM_RC responseCode |
| 17689 | |
| 17690 | |
| 17691 | |
| 17692 | |
| 17693 | Family “2.0” TCG Published Page 401 |
| 17694 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 17695 | Part 3: Commands Trusted Platform Module Library |
| 17696 | |
| 17697 | |
| 17698 | |
| 17699 | 31.3.3 Detailed Actions |
| 17700 | |
| 17701 | 1 #include "InternalRoutines.h" |
| 17702 | 2 #include "NV_DefineSpace_fp.h" |
| 17703 | 3 #ifdef TPM_CC_NV_DefineSpace // Conditional expansion of this file |
| 17704 | |
| 17705 | |
| 17706 | Error Returns Meaning |
| 17707 | |
| 17708 | TPM_RC_NV_ATTRIBUTES attributes of the index are not consistent |
| 17709 | TPM_RC_NV_DEFINED index already exists |
| 17710 | TPM_RC_HIERARCHY for authorizations using TPM_RH_PLATFORM phEnable_NV is |
| 17711 | clear. |
| 17712 | TPM_RC_NV_SPACE Insufficient space for the index |
| 17713 | TPM_RC_SIZE 'auth->size' or 'publicInfo->authPolicy.size' is larger than the digest |
| 17714 | size of 'publicInfo->nameAlg', or 'publicInfo->dataSize' is not |
| 17715 | consistent with 'publicInfo->attributes'. |
| 17716 | |
| 17717 | 4 TPM_RC |
| 17718 | 5 TPM2_NV_DefineSpace( |
| 17719 | 6 NV_DefineSpace_In *in // IN: input parameter list |
| 17720 | 7 ) |
| 17721 | 8 { |
| 17722 | 9 TPM_RC result; |
| 17723 | 10 TPMA_NV attributes; |
| 17724 | 11 UINT16 nameSize; |
| 17725 | 12 |
| 17726 | 13 nameSize = CryptGetHashDigestSize(in->publicInfo.t.nvPublic.nameAlg); |
| 17727 | 14 |
| 17728 | 15 // Check if NV is available. NvIsAvailable may return TPM_RC_NV_UNAVAILABLE |
| 17729 | 16 // TPM_RC_NV_RATE or TPM_RC_SUCCESS. |
| 17730 | 17 result = NvIsAvailable(); |
| 17731 | 18 if(result != TPM_RC_SUCCESS) |
| 17732 | 19 return result; |
| 17733 | 20 |
| 17734 | 21 // Input Validation |
| 17735 | 22 // If an index is being created by the owner and shEnable is |
| 17736 | 23 // clear, then we would not reach this point because ownerAuth |
| 17737 | 24 // can't be given when shEnable is CLEAR. However, if phEnable |
| 17738 | 25 // is SET but phEnableNV is CLEAR, we have to check here |
| 17739 | 26 if(in->authHandle == TPM_RH_PLATFORM && gc.phEnableNV == CLEAR) |
| 17740 | 27 return TPM_RC_HIERARCHY + RC_NV_DefineSpace_authHandle; |
| 17741 | 28 |
| 17742 | 29 attributes = in->publicInfo.t.nvPublic.attributes; |
| 17743 | 30 |
| 17744 | 31 //TPMS_NV_PUBLIC validation. |
| 17745 | 32 // Counters and bit fields must have a size of 8 |
| 17746 | 33 if ( (attributes.TPMA_NV_COUNTER == SET || attributes.TPMA_NV_BITS == SET) |
| 17747 | 34 && (in->publicInfo.t.nvPublic.dataSize != 8)) |
| 17748 | 35 return TPM_RC_SIZE + RC_NV_DefineSpace_publicInfo; |
| 17749 | 36 |
| 17750 | 37 // check that the authPolicy consistent with hash algorithm |
| 17751 | 38 if( in->publicInfo.t.nvPublic.authPolicy.t.size != 0 |
| 17752 | 39 && in->publicInfo.t.nvPublic.authPolicy.t.size != nameSize) |
| 17753 | 40 return TPM_RC_SIZE + RC_NV_DefineSpace_publicInfo; |
| 17754 | 41 |
| 17755 | 42 // make sure that the authValue is not too large |
| 17756 | 43 MemoryRemoveTrailingZeros(&in->auth); |
| 17757 | 44 if(in->auth.t.size > nameSize) |
| 17758 | 45 return TPM_RC_SIZE + RC_NV_DefineSpace_auth; |
| 17759 | 46 |
| 17760 | |
| 17761 | Page 402 TCG Published Family “2.0” |
| 17762 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 17763 | Trusted Platform Module Library Part 3: Commands |
| 17764 | |
| 17765 | 47 //TPMA_NV validation. |
| 17766 | 48 // Locks may not be SET and written cannot be SET |
| 17767 | 49 if( attributes.TPMA_NV_WRITTEN == SET |
| 17768 | 50 || attributes.TPMA_NV_WRITELOCKED == SET |
| 17769 | 51 || attributes.TPMA_NV_READLOCKED == SET) |
| 17770 | 52 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; |
| 17771 | 53 |
| 17772 | 54 // There must be a way to read the index |
| 17773 | 55 if( attributes.TPMA_NV_OWNERREAD == CLEAR |
| 17774 | 56 && attributes.TPMA_NV_PPREAD == CLEAR |
| 17775 | 57 && attributes.TPMA_NV_AUTHREAD == CLEAR |
| 17776 | 58 && attributes.TPMA_NV_POLICYREAD == CLEAR) |
| 17777 | 59 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; |
| 17778 | 60 |
| 17779 | 61 // There must be a way to write the index |
| 17780 | 62 if( attributes.TPMA_NV_OWNERWRITE == CLEAR |
| 17781 | 63 && attributes.TPMA_NV_PPWRITE == CLEAR |
| 17782 | 64 && attributes.TPMA_NV_AUTHWRITE == CLEAR |
| 17783 | 65 && attributes.TPMA_NV_POLICYWRITE == CLEAR) |
| 17784 | 66 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; |
| 17785 | 67 |
| 17786 | 68 // Make sure that no attribute is used that is not supported by the proper |
| 17787 | 69 // command |
| 17788 | 70 #if CC_NV_Increment == NO |
| 17789 | 71 if( attributes.TPMA_NV_COUNTER == SET) |
| 17790 | 72 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; |
| 17791 | 73 #endif |
| 17792 | 74 #if CC_NV_SetBits == NO |
| 17793 | 75 if( attributes.TPMA_NV_BITS == SET) |
| 17794 | 76 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; |
| 17795 | 77 #endif |
| 17796 | 78 #if CC_NV_Extend == NO |
| 17797 | 79 if( attributes.TPMA_NV_EXTEND == SET) |
| 17798 | 80 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; |
| 17799 | 81 #endif |
| 17800 | 82 #if CC_NV_UndefineSpaceSpecial == NO |
| 17801 | 83 if( attributes.TPMA_NV_POLICY_DELETE == SET) |
| 17802 | 84 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; |
| 17803 | 85 #endif |
| 17804 | 86 |
| 17805 | 87 // Can be COUNTER or BITS or EXTEND but not more than one |
| 17806 | 88 if( attributes.TPMA_NV_COUNTER == SET |
| 17807 | 89 && attributes.TPMA_NV_BITS == SET) |
| 17808 | 90 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; |
| 17809 | 91 if( attributes.TPMA_NV_COUNTER == SET |
| 17810 | 92 && attributes.TPMA_NV_EXTEND == SET) |
| 17811 | 93 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; |
| 17812 | 94 if( attributes.TPMA_NV_BITS == SET |
| 17813 | 95 && attributes.TPMA_NV_EXTEND == SET) |
| 17814 | 96 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; |
| 17815 | 97 |
| 17816 | 98 // An index with TPMA_NV_CLEAR_STCLEAR can't be a counter and can't have |
| 17817 | 99 // TPMA_NV_WRITEDEFINE SET |
| 17818 | 100 if( attributes.TPMA_NV_CLEAR_STCLEAR == SET |
| 17819 | 101 && ( attributes.TPMA_NV_COUNTER == SET |
| 17820 | 102 || attributes.TPMA_NV_WRITEDEFINE == SET) |
| 17821 | 103 ) |
| 17822 | 104 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; |
| 17823 | 105 |
| 17824 | 106 // Make sure that the creator of the index can delete the index |
| 17825 | 107 if( ( in->publicInfo.t.nvPublic.attributes.TPMA_NV_PLATFORMCREATE == SET |
| 17826 | 108 && in->authHandle == TPM_RH_OWNER |
| 17827 | 109 ) |
| 17828 | 110 || ( in->publicInfo.t.nvPublic.attributes.TPMA_NV_PLATFORMCREATE == CLEAR |
| 17829 | 111 && in->authHandle == TPM_RH_PLATFORM |
| 17830 | 112 ) |
| 17831 | |
| 17832 | Family “2.0” TCG Published Page 403 |
| 17833 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 17834 | Part 3: Commands Trusted Platform Module Library |
| 17835 | |
| 17836 | 113 ) |
| 17837 | 114 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_authHandle; |
| 17838 | 115 |
| 17839 | 116 // If TPMA_NV_POLICY_DELETE is SET, then the index must be defined by |
| 17840 | 117 // the platform |
| 17841 | 118 if( in->publicInfo.t.nvPublic.attributes.TPMA_NV_POLICY_DELETE == SET |
| 17842 | 119 && TPM_RH_PLATFORM != in->authHandle |
| 17843 | 120 ) |
| 17844 | 121 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; |
| 17845 | 122 |
| 17846 | 123 // If the NV index is used as a PCR, the data size must match the digest |
| 17847 | 124 // size |
| 17848 | 125 if( in->publicInfo.t.nvPublic.attributes.TPMA_NV_EXTEND == SET |
| 17849 | 126 && in->publicInfo.t.nvPublic.dataSize != nameSize |
| 17850 | 127 ) |
| 17851 | 128 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo; |
| 17852 | 129 |
| 17853 | 130 // See if the index is already defined. |
| 17854 | 131 if(NvIsUndefinedIndex(in->publicInfo.t.nvPublic.nvIndex)) |
| 17855 | 132 return TPM_RC_NV_DEFINED; |
| 17856 | 133 |
| 17857 | 134 // Internal Data Update |
| 17858 | 135 // define the space. A TPM_RC_NV_SPACE error may be returned at this point |
| 17859 | 136 result = NvDefineIndex(&in->publicInfo.t.nvPublic, &in->auth); |
| 17860 | 137 if(result != TPM_RC_SUCCESS) |
| 17861 | 138 return result; |
| 17862 | 139 |
| 17863 | 140 return TPM_RC_SUCCESS; |
| 17864 | 141 |
| 17865 | 142 } |
| 17866 | 143 #endif // CC_NV_DefineSpace |
| 17867 | |
| 17868 | |
| 17869 | |
| 17870 | |
| 17871 | Page 404 TCG Published Family “2.0” |
| 17872 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 17873 | Trusted Platform Module Library Part 3: Commands |
| 17874 | |
| 17875 | |
| 17876 | 31.4 TPM2_NV_UndefineSpace |
| 17877 | |
| 17878 | 31.4.1 General Description |
| 17879 | |
| 17880 | This command removes an Index from the TPM. |
| 17881 | If nvIndex is not defined, the TPM shall return TPM_RC_HANDLE. |
| 17882 | If nvIndex references an Index that has its TPMA_NV_PLATFORMCREATE attribute SET, the TPM shall |
| 17883 | return TPM_RC_NV_AUTHORIZATION unless Platform Authorization is provided. |
| 17884 | If nvIndex references an Index that has its TPMA_NV_POLICY_DELETE attribute SET, the TPM shall |
| 17885 | return TPM_RC_ATTRIBUTES. |
| 17886 | |
| 17887 | NOTE An Index with TPMA_NV_PLATFORMCREATE CLEAR may be deleted with Platform Authorization |
| 17888 | as long as shEnable is SET. If shEnable is CLEAR, indexes created using Owner Authorization are |
| 17889 | not accessible even for deletion by the platform . |
| 17890 | |
| 17891 | |
| 17892 | |
| 17893 | |
| 17894 | Family “2.0” TCG Published Page 405 |
| 17895 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 17896 | Part 3: Commands Trusted Platform Module Library |
| 17897 | |
| 17898 | |
| 17899 | 31.4.2 Command and Response |
| 17900 | |
| 17901 | Table 199 — TPM2_NV_UndefineSpace Command |
| 17902 | Type Name Description |
| 17903 | |
| 17904 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 17905 | UINT32 commandSize |
| 17906 | TPM_CC commandCode TPM_CC_NV_UndefineSpace {NV} |
| 17907 | |
| 17908 | TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} |
| 17909 | TPMI_RH_PROVISION @authHandle Auth Index: 1 |
| 17910 | Auth Role: USER |
| 17911 | the NV Index to remove from NV space |
| 17912 | TPMI_RH_NV_INDEX nvIndex |
| 17913 | Auth Index: None |
| 17914 | |
| 17915 | |
| 17916 | Table 200 — TPM2_NV_UndefineSpace Response |
| 17917 | Type Name Description |
| 17918 | |
| 17919 | TPM_ST tag see clause 6 |
| 17920 | UINT32 responseSize |
| 17921 | TPM_RC responseCode |
| 17922 | |
| 17923 | |
| 17924 | |
| 17925 | |
| 17926 | Page 406 TCG Published Family “2.0” |
| 17927 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 17928 | Trusted Platform Module Library Part 3: Commands |
| 17929 | |
| 17930 | |
| 17931 | |
| 17932 | 31.4.3 Detailed Actions |
| 17933 | |
| 17934 | 1 #include "InternalRoutines.h" |
| 17935 | 2 #include "NV_UndefineSpace_fp.h" |
| 17936 | 3 #ifdef TPM_CC_NV_UndefineSpace // Conditional expansion of this file |
| 17937 | |
| 17938 | |
| 17939 | Error Returns Meaning |
| 17940 | |
| 17941 | TPM_RC_ATTRIBUTES TPMA_NV_POLICY_DELETE is SET in the Index referenced by |
| 17942 | nvIndex so this command may not be used to delete this Index (see |
| 17943 | TPM2_NV_UndefineSpaceSpecial()) |
| 17944 | TPM_RC_NV_AUTHORIZATION attempt to use ownerAuth to delete an index created by the platform |
| 17945 | |
| 17946 | 4 TPM_RC |
| 17947 | 5 TPM2_NV_UndefineSpace( |
| 17948 | 6 NV_UndefineSpace_In *in // IN: input parameter list |
| 17949 | 7 ) |
| 17950 | 8 { |
| 17951 | 9 TPM_RC result; |
| 17952 | 10 NV_INDEX nvIndex; |
| 17953 | 11 |
| 17954 | 12 // The command needs NV update. Check if NV is available. |
| 17955 | 13 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at |
| 17956 | 14 // this point |
| 17957 | 15 result = NvIsAvailable(); |
| 17958 | 16 if(result != TPM_RC_SUCCESS) return result; |
| 17959 | 17 |
| 17960 | 18 // Input Validation |
| 17961 | 19 |
| 17962 | 20 // Get NV index info |
| 17963 | 21 NvGetIndexInfo(in->nvIndex, &nvIndex); |
| 17964 | 22 |
| 17965 | 23 // This command can't be used to delete an index with TPMA_NV_POLICY_DELETE SET |
| 17966 | 24 if(SET == nvIndex.publicArea.attributes.TPMA_NV_POLICY_DELETE) |
| 17967 | 25 return TPM_RC_ATTRIBUTES + RC_NV_UndefineSpace_nvIndex; |
| 17968 | 26 |
| 17969 | 27 // The owner may only delete an index that was defined with ownerAuth. The |
| 17970 | 28 // platform may delete an index that was created with either auth. |
| 17971 | 29 if( in->authHandle == TPM_RH_OWNER |
| 17972 | 30 && nvIndex.publicArea.attributes.TPMA_NV_PLATFORMCREATE == SET) |
| 17973 | 31 return TPM_RC_NV_AUTHORIZATION; |
| 17974 | 32 |
| 17975 | 33 // Internal Data Update |
| 17976 | 34 |
| 17977 | 35 // Call implementation dependent internal routine to delete NV index |
| 17978 | 36 NvDeleteEntity(in->nvIndex); |
| 17979 | 37 |
| 17980 | 38 return TPM_RC_SUCCESS; |
| 17981 | 39 } |
| 17982 | 40 #endif // CC_NV_UndefineSpace |
| 17983 | |
| 17984 | |
| 17985 | |
| 17986 | |
| 17987 | Family “2.0” TCG Published Page 407 |
| 17988 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 17989 | Part 3: Commands Trusted Platform Module Library |
| 17990 | |
| 17991 | |
| 17992 | 31.5 TPM2_NV_UndefineSpaceSpecial |
| 17993 | |
| 17994 | 31.5.1 General Description |
| 17995 | |
| 17996 | This command allows removal of a platform-created NV Index that has TPMA_NV_POLICY_DELETE |
| 17997 | SET. |
| 17998 | This command requires that the policy of the NV Index be satisfied before the NV Index may be deleted. |
| 17999 | Because administrative role is required, the policy must contain a command that sets the policy command |
| 18000 | code to TPM_CC_NV_UndefineSpaceSpecial. This indicates that the policy that is being used is a policy |
| 18001 | that is for this command, and not a policy that would approve another use. That is, authority to use an |
| 18002 | object does not grant authority to undefine the object. |
| 18003 | If nvIndex is not defined, the TPM shall return TPM_RC_HANDLE. |
| 18004 | If nvIndex references an Index that has its TPMA_NV_PLATFORMCREATE or |
| 18005 | TPMA_NV_POLICY_DELETE attribute CLEAR, the TPM shall return TPM_RC_ATTRIBUTES. |
| 18006 | |
| 18007 | NOTE An Index with TPMA_NV_PLATFORMCREATE CLEAR may be deleted with |
| 18008 | TPM2_UndefineSpace()as long as shEnable is SET. If shEnable is CLEAR, indexes created using |
| 18009 | Owner Authorization are not accessible even for deletion by the platform . |
| 18010 | |
| 18011 | |
| 18012 | |
| 18013 | |
| 18014 | Page 408 TCG Published Family “2.0” |
| 18015 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 18016 | Trusted Platform Module Library Part 3: Commands |
| 18017 | |
| 18018 | |
| 18019 | 31.5.2 Command and Response |
| 18020 | |
| 18021 | Table 201 — TPM2_NV_UndefineSpaceSpecial Command |
| 18022 | Type Name Description |
| 18023 | |
| 18024 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 18025 | UINT32 commandSize |
| 18026 | TPM_CC commandCode TPM_CC_NV_UndefineSpaceSpecial {NV} |
| 18027 | |
| 18028 | Index to be deleted |
| 18029 | TPMI_RH_NV_INDEX @nvIndex Auth Index: 1 |
| 18030 | Auth Role: ADMIN |
| 18031 | TPM_RH_PLATFORM + {PP} |
| 18032 | TPMI_RH_PLATFORM @platform Auth Index: 2 |
| 18033 | Auth Role: USER |
| 18034 | |
| 18035 | |
| 18036 | Table 202 — TPM2_NV_UndefineSpaceSpecial Response |
| 18037 | Type Name Description |
| 18038 | |
| 18039 | TPM_ST tag see clause 6 |
| 18040 | UINT32 responseSize |
| 18041 | TPM_RC responseCode |
| 18042 | |
| 18043 | |
| 18044 | |
| 18045 | |
| 18046 | Family “2.0” TCG Published Page 409 |
| 18047 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 18048 | Part 3: Commands Trusted Platform Module Library |
| 18049 | |
| 18050 | |
| 18051 | |
| 18052 | 31.5.3 Detailed Actions |
| 18053 | |
| 18054 | 1 #include "InternalRoutines.h" |
| 18055 | 2 #include "NV_UndefineSpaceSpecial_fp.h" |
| 18056 | 3 #ifdef TPM_CC_NV_UndefineSpaceSpecial // Conditional expansion of this file |
| 18057 | |
| 18058 | |
| 18059 | Error Returns Meaning |
| 18060 | |
| 18061 | TPM_RC_ATTRIBUTES TPMA_NV_POLICY_DELETE is not SET in the Index referenced by |
| 18062 | nvIndex |
| 18063 | |
| 18064 | 4 TPM_RC |
| 18065 | 5 TPM2_NV_UndefineSpaceSpecial( |
| 18066 | 6 NV_UndefineSpaceSpecial_In *in // IN: input parameter list |
| 18067 | 7 ) |
| 18068 | 8 { |
| 18069 | 9 TPM_RC result; |
| 18070 | 10 NV_INDEX nvIndex; |
| 18071 | 11 |
| 18072 | 12 // The command needs NV update. Check if NV is available. |
| 18073 | 13 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at |
| 18074 | 14 // this point |
| 18075 | 15 result = NvIsAvailable(); |
| 18076 | 16 if(result != TPM_RC_SUCCESS) |
| 18077 | 17 return result; |
| 18078 | 18 |
| 18079 | 19 // Input Validation |
| 18080 | 20 |
| 18081 | 21 // Get NV index info |
| 18082 | 22 NvGetIndexInfo(in->nvIndex, &nvIndex); |
| 18083 | 23 |
| 18084 | 24 // This operation only applies when the TPMA_NV_POLICY_DELETE attribute is SET |
| 18085 | 25 if(CLEAR == nvIndex.publicArea.attributes.TPMA_NV_POLICY_DELETE) |
| 18086 | 26 return TPM_RC_ATTRIBUTES + RC_NV_UndefineSpaceSpecial_nvIndex; |
| 18087 | 27 |
| 18088 | 28 // Internal Data Update |
| 18089 | 29 |
| 18090 | 30 // Call implementation dependent internal routine to delete NV index |
| 18091 | 31 NvDeleteEntity(in->nvIndex); |
| 18092 | 32 |
| 18093 | 33 return TPM_RC_SUCCESS; |
| 18094 | 34 } |
| 18095 | 35 #endif // CC_NV_UndefineSpaceSpecial |
| 18096 | |
| 18097 | |
| 18098 | |
| 18099 | |
| 18100 | Page 410 TCG Published Family “2.0” |
| 18101 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 18102 | Trusted Platform Module Library Part 3: Commands |
| 18103 | |
| 18104 | |
| 18105 | 31.6 TPM2_NV_ReadPublic |
| 18106 | |
| 18107 | 31.6.1 General Description |
| 18108 | |
| 18109 | This command is used to read the public area and Name of an NV Index. The public area of an Index is |
| 18110 | not privacy-sensitive and no authorization is required to read this data. |
| 18111 | |
| 18112 | |
| 18113 | |
| 18114 | |
| 18115 | Family “2.0” TCG Published Page 411 |
| 18116 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 18117 | Part 3: Commands Trusted Platform Module Library |
| 18118 | |
| 18119 | |
| 18120 | |
| 18121 | 31.6.2 Command and Response |
| 18122 | |
| 18123 | Table 203 — TPM2_NV_ReadPublic Command |
| 18124 | Type Name Description |
| 18125 | |
| 18126 | TPM_ST_SESSIONS if an audit or encrypt session is |
| 18127 | TPMI_ST_COMMAND_TAG tag |
| 18128 | present; otherwise, TPM_ST_NO_SESSIONS |
| 18129 | UINT32 commandSize |
| 18130 | TPM_CC commandCode TPM_CC_NV_ReadPublic |
| 18131 | |
| 18132 | the NV Index |
| 18133 | TPMI_RH_NV_INDEX nvIndex |
| 18134 | Auth Index: None |
| 18135 | |
| 18136 | |
| 18137 | Table 204 — TPM2_NV_ReadPublic Response |
| 18138 | Type Name Description |
| 18139 | TPM_ST tag see clause 6 |
| 18140 | UINT32 responseSize |
| 18141 | TPM_RC responseCode |
| 18142 | |
| 18143 | TPM2B_NV_PUBLIC nvPublic the public area of the NV Index |
| 18144 | TPM2B_NAME nvName the Name of the nvIndex |
| 18145 | |
| 18146 | |
| 18147 | |
| 18148 | |
| 18149 | Page 412 TCG Published Family “2.0” |
| 18150 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 18151 | Trusted Platform Module Library Part 3: Commands |
| 18152 | |
| 18153 | |
| 18154 | |
| 18155 | 31.6.3 Detailed Actions |
| 18156 | |
| 18157 | 1 #include "InternalRoutines.h" |
| 18158 | 2 #include "NV_ReadPublic_fp.h" |
| 18159 | 3 #ifdef TPM_CC_NV_ReadPublic // Conditional expansion of this file |
| 18160 | 4 TPM_RC |
| 18161 | 5 TPM2_NV_ReadPublic( |
| 18162 | 6 NV_ReadPublic_In *in, // IN: input parameter list |
| 18163 | 7 NV_ReadPublic_Out *out // OUT: output parameter list |
| 18164 | 8 ) |
| 18165 | 9 { |
| 18166 | 10 NV_INDEX nvIndex; |
| 18167 | 11 |
| 18168 | 12 // Command Output |
| 18169 | 13 |
| 18170 | 14 // Get NV index info |
| 18171 | 15 NvGetIndexInfo(in->nvIndex, &nvIndex); |
| 18172 | 16 |
| 18173 | 17 // Copy data to output |
| 18174 | 18 out->nvPublic.t.nvPublic = nvIndex.publicArea; |
| 18175 | 19 |
| 18176 | 20 // Compute NV name |
| 18177 | 21 out->nvName.t.size = NvGetName(in->nvIndex, &out->nvName.t.name); |
| 18178 | 22 |
| 18179 | 23 return TPM_RC_SUCCESS; |
| 18180 | 24 } |
| 18181 | 25 #endif // CC_NV_ReadPublic |
| 18182 | |
| 18183 | |
| 18184 | |
| 18185 | |
| 18186 | Family “2.0” TCG Published Page 413 |
| 18187 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 18188 | Part 3: Commands Trusted Platform Module Library |
| 18189 | |
| 18190 | |
| 18191 | 31.7 TPM2_NV_Write |
| 18192 | |
| 18193 | 31.7.1 General Description |
| 18194 | |
| 18195 | This command writes a value to an area in NV memory that was previously defined by |
| 18196 | TPM2_NV_DefineSpace(). |
| 18197 | Proper authorizations are required for this command as determined by TPMA_NV_PPWRITE; |
| 18198 | TPMA_NV_OWNERWRITE; TPMA_NV_AUTHWRITE; and, if TPMA_NV_POLICY_WRITE is SET, the |
| 18199 | authPolicy of the NV Index. |
| 18200 | If the TPMA_NV_WRITELOCKED attribute of the NV Index is SET, then the TPM shall return |
| 18201 | TPM_RC_NV_LOCKED. |
| 18202 | |
| 18203 | NOTE 1 If authorization sessions are present, they are checked before checks to see if writes to the NV |
| 18204 | Index are locked. |
| 18205 | |
| 18206 | If TPMA_NV_COUNTER, TPMA_NV_BITS or TPMA_NV_EXTEND of the NV Index is SET, then the |
| 18207 | TPM shall return TPM_RC_ATTRIBUTES. |
| 18208 | If the size of the data parameter plus the offset parameter adds to a value that is greater than the size of |
| 18209 | the NV Index data, the TPM shall return TPM_RC_NV_RANGE and not write any data to the NV Index. |
| 18210 | If the TPMA_NV_WRITEALL attribute of the NV Index is SET, then the TPM shall return |
| 18211 | TPM_RC_NV_RANGE if the size of the data parameter of the command is not the same as the data field |
| 18212 | of the NV Index. |
| 18213 | If all checks succeed, the TPM will merge the data.size octets of data.buffer value into the nvIndex→data |
| 18214 | starting at nvIndex→data[offset]. If the NV memory is implemented with a technology that has endurance |
| 18215 | limitations, the TPM shall check that the merged data is different from the current contents of the NV |
| 18216 | Index and only perform a write to NV memory if they differ. |
| 18217 | After successful completion of this command, TPMA_NV_WRITTEN for the NV Index will be SET. |
| 18218 | |
| 18219 | NOTE 2 Once SET, TPMA_NV_WRITTEN remains SET until the NV Index is undefined or the NV Index is |
| 18220 | cleared. |
| 18221 | |
| 18222 | |
| 18223 | |
| 18224 | |
| 18225 | Page 414 TCG Published Family “2.0” |
| 18226 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 18227 | Trusted Platform Module Library Part 3: Commands |
| 18228 | |
| 18229 | |
| 18230 | 31.7.2 Command and Response |
| 18231 | |
| 18232 | Table 205 — TPM2_NV_Write Command |
| 18233 | Type Name Description |
| 18234 | |
| 18235 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 18236 | UINT32 commandSize |
| 18237 | TPM_CC commandCode TPM_CC_NV_Write {NV} |
| 18238 | |
| 18239 | handle indicating the source of the authorization value |
| 18240 | TPMI_RH_NV_AUTH @authHandle Auth Index: 1 |
| 18241 | Auth Role: USER |
| 18242 | the NV Index of the area to write |
| 18243 | TPMI_RH_NV_INDEX nvIndex |
| 18244 | Auth Index: None |
| 18245 | |
| 18246 | TPM2B_MAX_NV_BUFFER data the data to write |
| 18247 | UINT16 offset the offset into the NV Area |
| 18248 | |
| 18249 | |
| 18250 | Table 206 — TPM2_NV_Write Response |
| 18251 | Type Name Description |
| 18252 | |
| 18253 | TPM_ST tag see clause 6 |
| 18254 | UINT32 responseSize |
| 18255 | TPM_RC responseCode |
| 18256 | |
| 18257 | |
| 18258 | |
| 18259 | |
| 18260 | Family “2.0” TCG Published Page 415 |
| 18261 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 18262 | Part 3: Commands Trusted Platform Module Library |
| 18263 | |
| 18264 | |
| 18265 | |
| 18266 | 31.7.3 Detailed Actions |
| 18267 | |
| 18268 | 1 #include "InternalRoutines.h" |
| 18269 | 2 #include "NV_Write_fp.h" |
| 18270 | 3 #ifdef TPM_CC_NV_Write // Conditional expansion of this file |
| 18271 | 4 #include "NV_spt_fp.h" |
| 18272 | |
| 18273 | |
| 18274 | Error Returns Meaning |
| 18275 | |
| 18276 | TPM_RC_ATTRIBUTES Index referenced by nvIndex has either TPMA_NV_BITS, |
| 18277 | TPMA_NV_COUNTER, or TPMA_NV_EVENT attribute SET |
| 18278 | TPM_RC_NV_AUTHORIZATION the authorization was valid but the authorizing entity (authHandle) is |
| 18279 | not allowed to write to the Index referenced by nvIndex |
| 18280 | TPM_RC_NV_LOCKED Index referenced by nvIndex is write locked |
| 18281 | TPM_RC_NV_RANGE if TPMA_NV_WRITEALL is SET then the write is not the size of the |
| 18282 | Index referenced by nvIndex; otherwise, the write extends beyond the |
| 18283 | limits of the Index |
| 18284 | |
| 18285 | 5 TPM_RC |
| 18286 | 6 TPM2_NV_Write( |
| 18287 | 7 NV_Write_In *in // IN: input parameter list |
| 18288 | 8 ) |
| 18289 | 9 { |
| 18290 | 10 NV_INDEX nvIndex; |
| 18291 | 11 TPM_RC result; |
| 18292 | 12 |
| 18293 | 13 // Input Validation |
| 18294 | 14 |
| 18295 | 15 // Get NV index info |
| 18296 | 16 NvGetIndexInfo(in->nvIndex, &nvIndex); |
| 18297 | 17 |
| 18298 | 18 // common access checks. NvWrtieAccessChecks() may return |
| 18299 | 19 // TPM_RC_NV_AUTHORIZATION or TPM_RC_NV_LOCKED |
| 18300 | 20 result = NvWriteAccessChecks(in->authHandle, in->nvIndex); |
| 18301 | 21 if(result != TPM_RC_SUCCESS) |
| 18302 | 22 return result; |
| 18303 | 23 |
| 18304 | 24 // Bits index, extend index or counter index may not be updated by |
| 18305 | 25 // TPM2_NV_Write |
| 18306 | 26 if( nvIndex.publicArea.attributes.TPMA_NV_COUNTER == SET |
| 18307 | 27 || nvIndex.publicArea.attributes.TPMA_NV_BITS == SET |
| 18308 | 28 || nvIndex.publicArea.attributes.TPMA_NV_EXTEND == SET) |
| 18309 | 29 return TPM_RC_ATTRIBUTES; |
| 18310 | 30 |
| 18311 | 31 // Too much data |
| 18312 | 32 if((in->data.t.size + in->offset) > nvIndex.publicArea.dataSize) |
| 18313 | 33 return TPM_RC_NV_RANGE; |
| 18314 | 34 |
| 18315 | 35 // If this index requires a full sized write, make sure that input range is |
| 18316 | 36 // full sized |
| 18317 | 37 if( nvIndex.publicArea.attributes.TPMA_NV_WRITEALL == SET |
| 18318 | 38 && in->data.t.size < nvIndex.publicArea.dataSize) |
| 18319 | 39 return TPM_RC_NV_RANGE; |
| 18320 | 40 |
| 18321 | 41 // Internal Data Update |
| 18322 | 42 |
| 18323 | 43 // Perform the write. This called routine will SET the TPMA_NV_WRITTEN |
| 18324 | 44 // attribute if it has not already been SET. If NV isn't available, an error |
| 18325 | 45 // will be returned. |
| 18326 | 46 return NvWriteIndexData(in->nvIndex, &nvIndex, in->offset, |
| 18327 | 47 in->data.t.size, in->data.t.buffer); |
| 18328 | |
| 18329 | Page 416 TCG Published Family “2.0” |
| 18330 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 18331 | Trusted Platform Module Library Part 3: Commands |
| 18332 | |
| 18333 | 48 |
| 18334 | 49 } |
| 18335 | 50 #endif // CC_NV_Write |
| 18336 | |
| 18337 | |
| 18338 | |
| 18339 | |
| 18340 | Family “2.0” TCG Published Page 417 |
| 18341 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 18342 | Part 3: Commands Trusted Platform Module Library |
| 18343 | |
| 18344 | |
| 18345 | 31.8 TPM2_NV_Increment |
| 18346 | |
| 18347 | 31.8.1 General Description |
| 18348 | |
| 18349 | This command is used to increment the value in an NV Index that has TPMA_NV_COUNTER SET. The |
| 18350 | data value of the NV Index is incremented by one. |
| 18351 | |
| 18352 | NOTE 1 The NV Index counter is an unsigned value. |
| 18353 | |
| 18354 | If TPMA_NV_COUNTER is not SET in the indicated NV Index, the TPM shall return |
| 18355 | TPM_RC_ATTRIBUTES. |
| 18356 | If TPMA_NV_WRITELOCKED is SET, the TPM shall return TPM_RC_NV_LOCKED. |
| 18357 | If TPMA_NV_WRITTEN is CLEAR, it will be SET. |
| 18358 | If TPMA_NV_ORDERLY is SET, and the difference between the volatile and non-volatile versions of this |
| 18359 | field is greater than MAX_ORDERLY_COUNT, then the non-volatile version of the counter is updated. |
| 18360 | |
| 18361 | NOTE 2 If a TPM implements TPMA_NV_ORDERLY and an Index is defined with TPMA_NV_ORDERLY and |
| 18362 | TPM_NV_COUNTER both SET, then in the Event of a non-orderly shutdown, the non-volatile value |
| 18363 | for the counter Index will be advanced by MAX_ORDERLY_COUNT at the next TPM2_Startup(). |
| 18364 | |
| 18365 | NOTE 3 An allowed implementation would keep a counter value in NV and a resettable counter in RAM. The |
| 18366 | reported value of the NV Index would be the sum of the two values. When the RAM count increments |
| 18367 | past the maximum allowed value (MAX_ORDERLY_COUNT), the non-volatile version of the count is |
| 18368 | updated with the sum of the values and the RAM count is reset to zero. |
| 18369 | |
| 18370 | |
| 18371 | |
| 18372 | |
| 18373 | Page 418 TCG Published Family “2.0” |
| 18374 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 18375 | Trusted Platform Module Library Part 3: Commands |
| 18376 | |
| 18377 | |
| 18378 | 31.8.2 Command and Response |
| 18379 | |
| 18380 | Table 207 — TPM2_NV_Increment Command |
| 18381 | Type Name Description |
| 18382 | |
| 18383 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 18384 | UINT32 commandSize |
| 18385 | TPM_CC commandCode TPM_CC_NV_Increment {NV} |
| 18386 | |
| 18387 | handle indicating the source of the authorization value |
| 18388 | TPMI_RH_NV_AUTH @authHandle Auth Index: 1 |
| 18389 | Auth Role: USER |
| 18390 | the NV Index to increment |
| 18391 | TPMI_RH_NV_INDEX nvIndex |
| 18392 | Auth Index: None |
| 18393 | |
| 18394 | |
| 18395 | Table 208 — TPM2_NV_Increment Response |
| 18396 | Type Name Description |
| 18397 | |
| 18398 | TPM_ST tag see clause 6 |
| 18399 | UINT32 responseSize |
| 18400 | TPM_RC responseCode |
| 18401 | |
| 18402 | |
| 18403 | |
| 18404 | |
| 18405 | Family “2.0” TCG Published Page 419 |
| 18406 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 18407 | Part 3: Commands Trusted Platform Module Library |
| 18408 | |
| 18409 | |
| 18410 | |
| 18411 | 31.8.3 Detailed Actions |
| 18412 | |
| 18413 | 1 #include "InternalRoutines.h" |
| 18414 | 2 #include "NV_Increment_fp.h" |
| 18415 | 3 #ifdef TPM_CC_NV_Increment // Conditional expansion of this file |
| 18416 | 4 #include "NV_spt_fp.h" |
| 18417 | |
| 18418 | |
| 18419 | Error Returns Meaning |
| 18420 | |
| 18421 | TPM_RC_ATTRIBUTES NV index is not a counter |
| 18422 | TPM_RC_NV_AUTHORIZATION authorization failure |
| 18423 | TPM_RC_NV_LOCKED Index is write locked |
| 18424 | |
| 18425 | 5 TPM_RC |
| 18426 | 6 TPM2_NV_Increment( |
| 18427 | 7 NV_Increment_In *in // IN: input parameter list |
| 18428 | 8 ) |
| 18429 | 9 { |
| 18430 | 10 TPM_RC result; |
| 18431 | 11 NV_INDEX nvIndex; |
| 18432 | 12 UINT64 countValue; |
| 18433 | 13 |
| 18434 | 14 // Input Validation |
| 18435 | 15 |
| 18436 | 16 // Common access checks, a TPM_RC_NV_AUTHORIZATION or TPM_RC_NV_LOCKED |
| 18437 | 17 // error may be returned at this point |
| 18438 | 18 result = NvWriteAccessChecks(in->authHandle, in->nvIndex); |
| 18439 | 19 if(result != TPM_RC_SUCCESS) |
| 18440 | 20 return result; |
| 18441 | 21 |
| 18442 | 22 // Get NV index info |
| 18443 | 23 NvGetIndexInfo(in->nvIndex, &nvIndex); |
| 18444 | 24 |
| 18445 | 25 // Make sure that this is a counter |
| 18446 | 26 if(nvIndex.publicArea.attributes.TPMA_NV_COUNTER != SET) |
| 18447 | 27 return TPM_RC_ATTRIBUTES + RC_NV_Increment_nvIndex; |
| 18448 | 28 |
| 18449 | 29 // Internal Data Update |
| 18450 | 30 |
| 18451 | 31 // If counter index is not been written, initialize it |
| 18452 | 32 if(nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == CLEAR) |
| 18453 | 33 countValue = NvInitialCounter(); |
| 18454 | 34 else |
| 18455 | 35 // Read NV data in native format for TPM CPU. |
| 18456 | 36 NvGetIntIndexData(in->nvIndex, &nvIndex, &countValue); |
| 18457 | 37 |
| 18458 | 38 // Do the increment |
| 18459 | 39 countValue++; |
| 18460 | 40 |
| 18461 | 41 // If this is an orderly counter that just rolled over, need to be able to |
| 18462 | 42 // write to NV to proceed. This check is done here, because NvWriteIndexData() |
| 18463 | 43 // does not see if the update is for counter rollover. |
| 18464 | 44 if( nvIndex.publicArea.attributes.TPMA_NV_ORDERLY == SET |
| 18465 | 45 && (countValue & MAX_ORDERLY_COUNT) == 0) |
| 18466 | 46 { |
| 18467 | 47 result = NvIsAvailable(); |
| 18468 | 48 if(result != TPM_RC_SUCCESS) |
| 18469 | 49 return result; |
| 18470 | 50 |
| 18471 | 51 // Need to force an NV update |
| 18472 | 52 g_updateNV = TRUE; |
| 18473 | |
| 18474 | |
| 18475 | Page 420 TCG Published Family “2.0” |
| 18476 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 18477 | Trusted Platform Module Library Part 3: Commands |
| 18478 | |
| 18479 | 53 } |
| 18480 | 54 |
| 18481 | 55 // Write NV data back. A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may |
| 18482 | 56 // be returned at this point. If necessary, this function will set the |
| 18483 | 57 // TPMA_NV_WRITTEN attribute |
| 18484 | 58 return NvWriteIndexData(in->nvIndex, &nvIndex, 0, 8, &countValue); |
| 18485 | 59 |
| 18486 | 60 } |
| 18487 | 61 #endif // CC_NV_Increment |
| 18488 | |
| 18489 | |
| 18490 | |
| 18491 | |
| 18492 | Family “2.0” TCG Published Page 421 |
| 18493 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 18494 | Part 3: Commands Trusted Platform Module Library |
| 18495 | |
| 18496 | |
| 18497 | 31.9 TPM2_NV_Extend |
| 18498 | |
| 18499 | 31.9.1 General Description |
| 18500 | |
| 18501 | This command extends a value to an area in NV memory that was previously defined by |
| 18502 | TPM2_NV_DefineSpace. |
| 18503 | If TPMA_NV_EXTEND is not SET, then the TPM shall return TPM_RC_ATTRIBUTES. |
| 18504 | Proper write authorizations are required for this command as determined by TPMA_NV_PPWRITE, |
| 18505 | TPMA_NV_OWNERWRITE, TPMA_NV_AUTHWRITE, and the authPolicy of the NV Index. |
| 18506 | After successful completion of this command, TPMA_NV_WRITTEN for the NV Index will be SET. |
| 18507 | |
| 18508 | NOTE 1 Once SET, TPMA_NV_WRITTEN remains SET until the NV Index is undefined, unless the |
| 18509 | TPMA_NV_CLEAR_STCLEAR attribute is SET and a TPM Reset or TPM Restart occurs. |
| 18510 | |
| 18511 | If the TPMA_NV_WRITELOCKED attribute of the NV Index is SET, then the TPM shall return |
| 18512 | TPM_RC_NV_LOCKED. |
| 18513 | |
| 18514 | NOTE 2 If authorization sessions are present, they are checked before checks to see if writes to the NV |
| 18515 | Index are locked. |
| 18516 | |
| 18517 | The data.buffer parameter may be larger than the defined size of the NV Index. |
| 18518 | The Index will be updated by: |
| 18519 | nvIndex→datanew ≔ HnameAkg(nvIndex→dataold || data.buffer) (39) |
| 18520 | where |
| 18521 | HnameAkg() the hash algorithm indicated in nvIndex→nameAlg |
| 18522 | nvIndex→data the value of the data field in the NV Index |
| 18523 | data.buffer the data buffer of the command parameter |
| 18524 | |
| 18525 | NOTE 3 If TPMA_NV_WRITTEN is CLEAR, then nvIndex→data is a Zero Digest. |
| 18526 | |
| 18527 | |
| 18528 | |
| 18529 | |
| 18530 | Page 422 TCG Published Family “2.0” |
| 18531 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 18532 | Trusted Platform Module Library Part 3: Commands |
| 18533 | |
| 18534 | |
| 18535 | 31.9.2 Command and Response |
| 18536 | |
| 18537 | Table 209 — TPM2_NV_Extend Command |
| 18538 | Type Name Description |
| 18539 | |
| 18540 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 18541 | UINT32 commandSize |
| 18542 | TPM_CC commandCode TPM_CC_NV_Extend {NV} |
| 18543 | |
| 18544 | handle indicating the source of the authorization value |
| 18545 | TPMI_RH_NV_AUTH @authHandle Auth Index: 1 |
| 18546 | Auth Role: USER |
| 18547 | the NV Index to extend |
| 18548 | TPMI_RH_NV_INDEX nvIndex |
| 18549 | Auth Index: None |
| 18550 | |
| 18551 | TPM2B_MAX_NV_BUFFER data the data to extend |
| 18552 | |
| 18553 | |
| 18554 | Table 210 — TPM2_NV_Extend Response |
| 18555 | Type Name Description |
| 18556 | |
| 18557 | TPM_ST tag see clause 6 |
| 18558 | UINT32 responseSize |
| 18559 | TPM_RC responseCode |
| 18560 | |
| 18561 | |
| 18562 | |
| 18563 | |
| 18564 | Family “2.0” TCG Published Page 423 |
| 18565 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 18566 | Part 3: Commands Trusted Platform Module Library |
| 18567 | |
| 18568 | |
| 18569 | |
| 18570 | 31.9.3 Detailed Actions |
| 18571 | |
| 18572 | 1 #include "InternalRoutines.h" |
| 18573 | 2 #include "NV_Extend_fp.h" |
| 18574 | 3 #ifdef TPM_CC_NV_Extend // Conditional expansion of this file |
| 18575 | 4 #include "NV_spt_fp.h" |
| 18576 | |
| 18577 | |
| 18578 | Error Returns Meaning |
| 18579 | |
| 18580 | TPM_RC_ATTRIBUTES the TPMA_NV_EXTEND attribute is not SET in the Index referenced |
| 18581 | by nvIndex |
| 18582 | TPM_RC_NV_AUTHORIZATION the authorization was valid but the authorizing entity (authHandle) is |
| 18583 | not allowed to write to the Index referenced by nvIndex |
| 18584 | TPM_RC_NV_LOCKED the Index referenced by nvIndex is locked for writing |
| 18585 | |
| 18586 | 5 TPM_RC |
| 18587 | 6 TPM2_NV_Extend( |
| 18588 | 7 NV_Extend_In *in // IN: input parameter list |
| 18589 | 8 ) |
| 18590 | 9 { |
| 18591 | 10 TPM_RC result; |
| 18592 | 11 NV_INDEX nvIndex; |
| 18593 | 12 |
| 18594 | 13 TPM2B_DIGEST oldDigest; |
| 18595 | 14 TPM2B_DIGEST newDigest; |
| 18596 | 15 HASH_STATE hashState; |
| 18597 | 16 |
| 18598 | 17 // Input Validation |
| 18599 | 18 |
| 18600 | 19 // Common access checks, NvWriteAccessCheck() may return TPM_RC_NV_AUTHORIZATION |
| 18601 | 20 // or TPM_RC_NV_LOCKED |
| 18602 | 21 result = NvWriteAccessChecks(in->authHandle, in->nvIndex); |
| 18603 | 22 if(result != TPM_RC_SUCCESS) |
| 18604 | 23 return result; |
| 18605 | 24 |
| 18606 | 25 // Get NV index info |
| 18607 | 26 NvGetIndexInfo(in->nvIndex, &nvIndex); |
| 18608 | 27 |
| 18609 | 28 // Make sure that this is an extend index |
| 18610 | 29 if(nvIndex.publicArea.attributes.TPMA_NV_EXTEND != SET) |
| 18611 | 30 return TPM_RC_ATTRIBUTES + RC_NV_Extend_nvIndex; |
| 18612 | 31 |
| 18613 | 32 // If the Index is not-orderly, or if this is the first write, NV will |
| 18614 | 33 // need to be updated. |
| 18615 | 34 if( nvIndex.publicArea.attributes.TPMA_NV_ORDERLY == CLEAR |
| 18616 | 35 || nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == CLEAR) |
| 18617 | 36 { |
| 18618 | 37 // Check if NV is available. NvIsAvailable may return TPM_RC_NV_UNAVAILABLE |
| 18619 | 38 // TPM_RC_NV_RATE or TPM_RC_SUCCESS. |
| 18620 | 39 result = NvIsAvailable(); |
| 18621 | 40 if(result != TPM_RC_SUCCESS) |
| 18622 | 41 return result; |
| 18623 | 42 } |
| 18624 | 43 |
| 18625 | 44 // Internal Data Update |
| 18626 | 45 |
| 18627 | 46 // Perform the write. |
| 18628 | 47 oldDigest.t.size = CryptGetHashDigestSize(nvIndex.publicArea.nameAlg); |
| 18629 | 48 pAssert(oldDigest.t.size <= sizeof(oldDigest.t.buffer)); |
| 18630 | 49 if(nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == SET) |
| 18631 | 50 { |
| 18632 | |
| 18633 | Page 424 TCG Published Family “2.0” |
| 18634 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 18635 | Trusted Platform Module Library Part 3: Commands |
| 18636 | |
| 18637 | 51 NvGetIndexData(in->nvIndex, &nvIndex, 0, |
| 18638 | 52 oldDigest.t.size, oldDigest.t.buffer); |
| 18639 | 53 } |
| 18640 | 54 else |
| 18641 | 55 { |
| 18642 | 56 MemorySet(oldDigest.t.buffer, 0, oldDigest.t.size); |
| 18643 | 57 } |
| 18644 | 58 // Start hash |
| 18645 | 59 newDigest.t.size = CryptStartHash(nvIndex.publicArea.nameAlg, &hashState); |
| 18646 | 60 |
| 18647 | 61 // Adding old digest |
| 18648 | 62 CryptUpdateDigest2B(&hashState, &oldDigest.b); |
| 18649 | 63 |
| 18650 | 64 // Adding new data |
| 18651 | 65 CryptUpdateDigest2B(&hashState, &in->data.b); |
| 18652 | 66 |
| 18653 | 67 // Complete hash |
| 18654 | 68 CryptCompleteHash2B(&hashState, &newDigest.b); |
| 18655 | 69 |
| 18656 | 70 // Write extended hash back. |
| 18657 | 71 // Note, this routine will SET the TPMA_NV_WRITTEN attribute if necessary |
| 18658 | 72 return NvWriteIndexData(in->nvIndex, &nvIndex, 0, |
| 18659 | 73 newDigest.t.size, newDigest.t.buffer); |
| 18660 | 74 } |
| 18661 | 75 #endif // CC_NV_Extend |
| 18662 | |
| 18663 | |
| 18664 | |
| 18665 | |
| 18666 | Family “2.0” TCG Published Page 425 |
| 18667 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 18668 | Part 3: Commands Trusted Platform Module Library |
| 18669 | |
| 18670 | |
| 18671 | 31.10 TPM2_NV_SetBits |
| 18672 | |
| 18673 | 31.10.1 General Description |
| 18674 | |
| 18675 | This command is used to SET bits in an NV Index that was created as a bit field. Any number of bits from |
| 18676 | 0 to 64 may be SET. The contents of data are ORed with the current contents of the NV Index starting at |
| 18677 | offset. |
| 18678 | If TPMA_NV_WRITTEN is not SET, then, for the purposes of this command, the NV Index is considered |
| 18679 | to contain all zero bits and data is OR with that value. |
| 18680 | If TPMA_NV_BITS is not SET, then the TPM shall return TPM_RC_ATTRIBUTES. |
| 18681 | After successful completion of this command, TPMA_NV_WRITTEN for the NV Index will be SET. |
| 18682 | |
| 18683 | NOTE TPMA_NV_WRITTEN will be SET even if no bits were SET. |
| 18684 | |
| 18685 | |
| 18686 | |
| 18687 | |
| 18688 | Page 426 TCG Published Family “2.0” |
| 18689 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 18690 | Trusted Platform Module Library Part 3: Commands |
| 18691 | |
| 18692 | |
| 18693 | 31.10.2 Command and Response |
| 18694 | |
| 18695 | Table 211 — TPM2_NV_SetBits Command |
| 18696 | Type Name Description |
| 18697 | |
| 18698 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 18699 | UINT32 commandSize |
| 18700 | TPM_CC commandCode TPM_CC_NV_SetBits {NV} |
| 18701 | |
| 18702 | handle indicating the source of the authorization value |
| 18703 | TPMI_RH_NV_AUTH @authHandle Auth Index: 1 |
| 18704 | Auth Role: USER |
| 18705 | NV Index of the area in which the bit is to be set |
| 18706 | TPMI_RH_NV_INDEX nvIndex |
| 18707 | Auth Index: None |
| 18708 | |
| 18709 | UINT64 bits the data to OR with the current contents |
| 18710 | |
| 18711 | |
| 18712 | Table 212 — TPM2_NV_SetBits Response |
| 18713 | Type Name Description |
| 18714 | |
| 18715 | TPM_ST tag see clause 6 |
| 18716 | UINT32 responseSize |
| 18717 | TPM_RC responseCode |
| 18718 | |
| 18719 | |
| 18720 | |
| 18721 | |
| 18722 | Family “2.0” TCG Published Page 427 |
| 18723 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 18724 | Part 3: Commands Trusted Platform Module Library |
| 18725 | |
| 18726 | |
| 18727 | |
| 18728 | 31.10.3 Detailed Actions |
| 18729 | |
| 18730 | 1 #include "InternalRoutines.h" |
| 18731 | 2 #include "NV_SetBits_fp.h" |
| 18732 | 3 #ifdef TPM_CC_NV_SetBits // Conditional expansion of this file |
| 18733 | 4 #include "NV_spt_fp.h" |
| 18734 | |
| 18735 | |
| 18736 | Error Returns Meaning |
| 18737 | |
| 18738 | TPM_RC_ATTRIBUTES the TPMA_NV_BITS attribute is not SET in the Index referenced by |
| 18739 | nvIndex |
| 18740 | TPM_RC_NV_AUTHORIZATION the authorization was valid but the authorizing entity (authHandle) is |
| 18741 | not allowed to write to the Index referenced by nvIndex |
| 18742 | TPM_RC_NV_LOCKED the Index referenced by nvIndex is locked for writing |
| 18743 | |
| 18744 | 5 TPM_RC |
| 18745 | 6 TPM2_NV_SetBits( |
| 18746 | 7 NV_SetBits_In *in // IN: input parameter list |
| 18747 | 8 ) |
| 18748 | 9 { |
| 18749 | 10 TPM_RC result; |
| 18750 | 11 NV_INDEX nvIndex; |
| 18751 | 12 UINT64 oldValue; |
| 18752 | 13 UINT64 newValue; |
| 18753 | 14 |
| 18754 | 15 // Input Validation |
| 18755 | 16 |
| 18756 | 17 // Common access checks, NvWriteAccessCheck() may return TPM_RC_NV_AUTHORIZATION |
| 18757 | 18 // or TPM_RC_NV_LOCKED |
| 18758 | 19 // error may be returned at this point |
| 18759 | 20 result = NvWriteAccessChecks(in->authHandle, in->nvIndex); |
| 18760 | 21 if(result != TPM_RC_SUCCESS) |
| 18761 | 22 return result; |
| 18762 | 23 |
| 18763 | 24 // Get NV index info |
| 18764 | 25 NvGetIndexInfo(in->nvIndex, &nvIndex); |
| 18765 | 26 |
| 18766 | 27 // Make sure that this is a bit field |
| 18767 | 28 if(nvIndex.publicArea.attributes.TPMA_NV_BITS != SET) |
| 18768 | 29 return TPM_RC_ATTRIBUTES + RC_NV_SetBits_nvIndex; |
| 18769 | 30 |
| 18770 | 31 // If index is not been written, initialize it |
| 18771 | 32 if(nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == CLEAR) |
| 18772 | 33 oldValue = 0; |
| 18773 | 34 else |
| 18774 | 35 // Read index data |
| 18775 | 36 NvGetIntIndexData(in->nvIndex, &nvIndex, &oldValue); |
| 18776 | 37 |
| 18777 | 38 // Figure out what the new value is going to be |
| 18778 | 39 newValue = oldValue | in->bits; |
| 18779 | 40 |
| 18780 | 41 // If the Index is not-orderly and it has changed, or if this is the first |
| 18781 | 42 // write, NV will need to be updated. |
| 18782 | 43 if( ( nvIndex.publicArea.attributes.TPMA_NV_ORDERLY == CLEAR |
| 18783 | 44 && newValue != oldValue) |
| 18784 | 45 || nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == CLEAR) |
| 18785 | 46 { |
| 18786 | 47 |
| 18787 | 48 // Internal Data Update |
| 18788 | 49 // Check if NV is available. NvIsAvailable may return TPM_RC_NV_UNAVAILABLE |
| 18789 | 50 // TPM_RC_NV_RATE or TPM_RC_SUCCESS. |
| 18790 | |
| 18791 | Page 428 TCG Published Family “2.0” |
| 18792 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 18793 | Trusted Platform Module Library Part 3: Commands |
| 18794 | |
| 18795 | 51 result = NvIsAvailable(); |
| 18796 | 52 if(result != TPM_RC_SUCCESS) |
| 18797 | 53 return result; |
| 18798 | 54 |
| 18799 | 55 // Write index data back. If necessary, this function will SET |
| 18800 | 56 // TPMA_NV_WRITTEN. |
| 18801 | 57 result = NvWriteIndexData(in->nvIndex, &nvIndex, 0, 8, &newValue); |
| 18802 | 58 } |
| 18803 | 59 return result; |
| 18804 | 60 |
| 18805 | 61 } |
| 18806 | 62 #endif // CC_NV_SetBits |
| 18807 | |
| 18808 | |
| 18809 | |
| 18810 | |
| 18811 | Family “2.0” TCG Published Page 429 |
| 18812 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 18813 | Part 3: Commands Trusted Platform Module Library |
| 18814 | |
| 18815 | |
| 18816 | 31.11 TPM2_NV_WriteLock |
| 18817 | |
| 18818 | 31.11.1 General Description |
| 18819 | |
| 18820 | If the TPMA_NV_WRITEDEFINE or TPMA_NV_WRITE_STCLEAR attributes of an NV location are SET, |
| 18821 | then this command may be used to inhibit further writes of the NV Index. |
| 18822 | Proper write authorization is required for this command as determined by TPMA_NV_PPWRITE, |
| 18823 | TPMA_NV_OWNERWRITE, TPMA_NV_AUTHWRITE, and the authPolicy of the NV Index. |
| 18824 | It is not an error if TPMA_NV_WRITELOCKED for the NV Index is already SET. |
| 18825 | If neither TPMA_NV_WRITEDEFINE nor TPMA_NV_WRITE_STCLEAR of the NV Index is SET, then the |
| 18826 | TPM shall return TPM_RC_ATTRIBUTES. |
| 18827 | If the command is properly authorized and TPMA_NV_WRITE_STCLEAR or TPMA_NV_WRITEDEFINE |
| 18828 | is SET, then the TPM shall SET TPMA_NV_WRITELOCKED for the NV Index. |
| 18829 | TPMA_NV_WRITELOCKED will be clear on the next TPM2_Startup(TPM_SU_CLEAR) unless |
| 18830 | TPMA_NV_WRITEDEFINE is SET or if TPM_NV_WRITTEN is CLEAR. |
| 18831 | |
| 18832 | |
| 18833 | |
| 18834 | |
| 18835 | Page 430 TCG Published Family “2.0” |
| 18836 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 18837 | Trusted Platform Module Library Part 3: Commands |
| 18838 | |
| 18839 | |
| 18840 | |
| 18841 | 31.11.2 Command and Response |
| 18842 | |
| 18843 | Table 213 — TPM2_NV_WriteLock Command |
| 18844 | Type Name Description |
| 18845 | |
| 18846 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 18847 | UINT32 commandSize |
| 18848 | TPM_CC commandCode TPM_CC_NV_WriteLock {NV} |
| 18849 | |
| 18850 | handle indicating the source of the authorization value |
| 18851 | TPMI_RH_NV_AUTH @authHandle Auth Index: 1 |
| 18852 | Auth Role: USER |
| 18853 | the NV Index of the area to lock |
| 18854 | TPMI_RH_NV_INDEX nvIndex |
| 18855 | Auth Index: None |
| 18856 | |
| 18857 | |
| 18858 | Table 214 — TPM2_NV_WriteLock Response |
| 18859 | Type Name Description |
| 18860 | |
| 18861 | TPM_ST tag see clause 6 |
| 18862 | UINT32 responseSize |
| 18863 | TPM_RC responseCode |
| 18864 | |
| 18865 | |
| 18866 | |
| 18867 | |
| 18868 | Family “2.0” TCG Published Page 431 |
| 18869 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 18870 | Part 3: Commands Trusted Platform Module Library |
| 18871 | |
| 18872 | |
| 18873 | |
| 18874 | 31.11.3 Detailed Actions |
| 18875 | |
| 18876 | 1 #include "InternalRoutines.h" |
| 18877 | 2 #include "NV_WriteLock_fp.h" |
| 18878 | 3 #ifdef TPM_CC_NV_WriteLock // Conditional expansion of this file |
| 18879 | 4 #include "NV_spt_fp.h" |
| 18880 | |
| 18881 | |
| 18882 | Error Returns Meaning |
| 18883 | |
| 18884 | TPM_RC_ATTRIBUTES neither TPMA_NV_WRITEDEFINE nor |
| 18885 | TPMA_NV_WRITE_STCLEAR is SET in Index referenced by |
| 18886 | nvIndex |
| 18887 | TPM_RC_NV_AUTHORIZATION the authorization was valid but the authorizing entity (authHandle) is |
| 18888 | not allowed to write to the Index referenced by nvIndex |
| 18889 | |
| 18890 | 5 TPM_RC |
| 18891 | 6 TPM2_NV_WriteLock( |
| 18892 | 7 NV_WriteLock_In *in // IN: input parameter list |
| 18893 | 8 ) |
| 18894 | 9 { |
| 18895 | 10 TPM_RC result; |
| 18896 | 11 NV_INDEX nvIndex; |
| 18897 | 12 |
| 18898 | 13 // Input Validation: |
| 18899 | 14 |
| 18900 | 15 // Common write access checks, a TPM_RC_NV_AUTHORIZATION or TPM_RC_NV_LOCKED |
| 18901 | 16 // error may be returned at this point |
| 18902 | 17 result = NvWriteAccessChecks(in->authHandle, in->nvIndex); |
| 18903 | 18 if(result != TPM_RC_SUCCESS) |
| 18904 | 19 { |
| 18905 | 20 if(result == TPM_RC_NV_AUTHORIZATION) |
| 18906 | 21 return TPM_RC_NV_AUTHORIZATION; |
| 18907 | 22 // If write access failed because the index is already locked, then it is |
| 18908 | 23 // no error. |
| 18909 | 24 return TPM_RC_SUCCESS; |
| 18910 | 25 } |
| 18911 | 26 |
| 18912 | 27 // Get NV index info |
| 18913 | 28 NvGetIndexInfo(in->nvIndex, &nvIndex); |
| 18914 | 29 |
| 18915 | 30 // if neither TPMA_NV_WRITEDEFINE nor TPMA_NV_WRITE_STCLEAR is set, the index |
| 18916 | 31 // can not be write-locked |
| 18917 | 32 if( nvIndex.publicArea.attributes.TPMA_NV_WRITEDEFINE == CLEAR |
| 18918 | 33 && nvIndex.publicArea.attributes.TPMA_NV_WRITE_STCLEAR == CLEAR) |
| 18919 | 34 return TPM_RC_ATTRIBUTES + RC_NV_WriteLock_nvIndex; |
| 18920 | 35 |
| 18921 | 36 // Internal Data Update |
| 18922 | 37 |
| 18923 | 38 // The command needs NV update. Check if NV is available. |
| 18924 | 39 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at |
| 18925 | 40 // this point |
| 18926 | 41 result = NvIsAvailable(); |
| 18927 | 42 if(result != TPM_RC_SUCCESS) |
| 18928 | 43 return result; |
| 18929 | 44 |
| 18930 | 45 // Set the WRITELOCK attribute. |
| 18931 | 46 // Note: if TPMA_NV_WRITELOCKED were already SET, then the write access check |
| 18932 | 47 // above would have failed and this code isn't executed. |
| 18933 | 48 nvIndex.publicArea.attributes.TPMA_NV_WRITELOCKED = SET; |
| 18934 | 49 |
| 18935 | 50 // Write index info back |
| 18936 | 51 NvWriteIndexInfo(in->nvIndex, &nvIndex); |
| 18937 | |
| 18938 | Page 432 TCG Published Family “2.0” |
| 18939 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 18940 | Trusted Platform Module Library Part 3: Commands |
| 18941 | |
| 18942 | 52 |
| 18943 | 53 return TPM_RC_SUCCESS; |
| 18944 | 54 } |
| 18945 | 55 #endif // CC_NV_WriteLock |
| 18946 | |
| 18947 | |
| 18948 | |
| 18949 | |
| 18950 | Family “2.0” TCG Published Page 433 |
| 18951 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 18952 | Part 3: Commands Trusted Platform Module Library |
| 18953 | |
| 18954 | |
| 18955 | 31.12 TPM2_NV_GlobalWriteLock |
| 18956 | |
| 18957 | 31.12.1 General Description |
| 18958 | |
| 18959 | The command will SET TPMA_NV_WRITELOCKED for all indexes that have their |
| 18960 | TPMA_NV_GLOBALLOCK attribute SET. |
| 18961 | If an Index has both TPMA_NV_WRITELOCKED and TPMA_NV_WRITEDEFINE SET, then this |
| 18962 | command will permanently lock the NV Index for writing unless TPMA_NV_WRITTEN is CLEAR. |
| 18963 | |
| 18964 | NOTE If an Index is defined with TPMA_NV_GLOBALLOCK SET, then the global lock does not apply until |
| 18965 | the next time this command is executed. |
| 18966 | |
| 18967 | This command requires either platformAuth/platformPolicy or ownerAuth/ownerPolicy. |
| 18968 | |
| 18969 | |
| 18970 | |
| 18971 | |
| 18972 | Page 434 TCG Published Family “2.0” |
| 18973 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 18974 | Trusted Platform Module Library Part 3: Commands |
| 18975 | |
| 18976 | |
| 18977 | |
| 18978 | 31.12.2 Command and Response |
| 18979 | |
| 18980 | Table 215 — TPM2_NV_GlobalWriteLock Command |
| 18981 | Type Name Description |
| 18982 | |
| 18983 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 18984 | UINT32 commandSize |
| 18985 | TPM_CC commandCode TPM_CC_NV_GlobalWriteLock |
| 18986 | |
| 18987 | TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} |
| 18988 | TPMI_RH_PROVISION @authHandle Auth Index: 1 |
| 18989 | Auth Role: USER |
| 18990 | |
| 18991 | |
| 18992 | Table 216 — TPM2_NV_GlobalWriteLock Response |
| 18993 | Type Name Description |
| 18994 | TPM_ST tag see clause 6 |
| 18995 | UINT32 responseSize |
| 18996 | TPM_RC responseCode |
| 18997 | |
| 18998 | |
| 18999 | |
| 19000 | |
| 19001 | Family “2.0” TCG Published Page 435 |
| 19002 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 19003 | Part 3: Commands Trusted Platform Module Library |
| 19004 | |
| 19005 | |
| 19006 | |
| 19007 | 31.12.3 Detailed Actions |
| 19008 | |
| 19009 | 1 #include "InternalRoutines.h" |
| 19010 | 2 #include "NV_GlobalWriteLock_fp.h" |
| 19011 | 3 #ifdef TPM_CC_NV_GlobalWriteLock // Conditional expansion of this file |
| 19012 | 4 TPM_RC |
| 19013 | 5 TPM2_NV_GlobalWriteLock( |
| 19014 | 6 NV_GlobalWriteLock_In *in // IN: input parameter list |
| 19015 | 7 ) |
| 19016 | 8 { |
| 19017 | 9 TPM_RC result; |
| 19018 | 10 |
| 19019 | 11 // Input parameter is not reference in command action |
| 19020 | 12 in = NULL; // to silence compiler warnings. |
| 19021 | 13 |
| 19022 | 14 // The command needs NV update. Check if NV is available. |
| 19023 | 15 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at |
| 19024 | 16 // this point |
| 19025 | 17 result = NvIsAvailable(); |
| 19026 | 18 if(result != TPM_RC_SUCCESS) |
| 19027 | 19 return result; |
| 19028 | 20 |
| 19029 | 21 // Internal Data Update |
| 19030 | 22 |
| 19031 | 23 // Implementation dependent method of setting the global lock |
| 19032 | 24 NvSetGlobalLock(); |
| 19033 | 25 |
| 19034 | 26 return TPM_RC_SUCCESS; |
| 19035 | 27 } |
| 19036 | 28 #endif // CC_NV_GlobalWriteLock |
| 19037 | |
| 19038 | |
| 19039 | |
| 19040 | |
| 19041 | Page 436 TCG Published Family “2.0” |
| 19042 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 19043 | Trusted Platform Module Library Part 3: Commands |
| 19044 | |
| 19045 | |
| 19046 | 31.13 TPM2_NV_Read |
| 19047 | |
| 19048 | 31.13.1 General Description |
| 19049 | |
| 19050 | This command reads a value from an area in NV memory previously defined by |
| 19051 | TPM2_NV_DefineSpace(). |
| 19052 | Proper authorizations are required for this command as determined by TPMA_NV_PPREAD, |
| 19053 | TPMA_NV_OWNERREAD, TPMA_NV_AUTHREAD, and the authPolicy of the NV Index. |
| 19054 | If TPMA_NV_READLOCKED of the NV Index is SET, then the TPM shall return TPM_RC_NV_LOCKED. |
| 19055 | |
| 19056 | NOTE If authorization sessions are present, they are checked before the read -lock status of the NV Index |
| 19057 | is checked. |
| 19058 | |
| 19059 | If the size parameter plus the offset parameter adds to a value that is greater than the size of the NV |
| 19060 | Index data area, the TPM shall return TPM_RC_NV_RANGE and not read any data from the NV Index. |
| 19061 | If the NV Index has been defined but the TPMA_NV_WRITTEN attribute is CLEAR, then this command |
| 19062 | shall return TPM_RC_NV_UINITIALIZED even if size is zero. |
| 19063 | The data parameter in the response may be encrypted using parameter encryption. |
| 19064 | |
| 19065 | |
| 19066 | |
| 19067 | |
| 19068 | Family “2.0” TCG Published Page 437 |
| 19069 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 19070 | Part 3: Commands Trusted Platform Module Library |
| 19071 | |
| 19072 | |
| 19073 | |
| 19074 | 31.13.2 Command and Response |
| 19075 | |
| 19076 | Table 217 — TPM2_NV_Read Command |
| 19077 | Type Name Description |
| 19078 | |
| 19079 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 19080 | UINT32 commandSize |
| 19081 | TPM_CC commandCode TPM_CC_NV_Read |
| 19082 | |
| 19083 | the handle indicating the source of the authorization |
| 19084 | value |
| 19085 | TPMI_RH_NV_AUTH @authHandle |
| 19086 | Auth Index: 1 |
| 19087 | Auth Role: USER |
| 19088 | the NV Index to be read |
| 19089 | TPMI_RH_NV_INDEX nvIndex |
| 19090 | Auth Index: None |
| 19091 | |
| 19092 | UINT16 size number of octets to read |
| 19093 | octet offset into the area |
| 19094 | UINT16 offset This value shall be less than or equal to the size of the |
| 19095 | nvIndex data. |
| 19096 | |
| 19097 | |
| 19098 | Table 218 — TPM2_NV_Read Response |
| 19099 | Type Name Description |
| 19100 | |
| 19101 | TPM_ST tag see clause 6 |
| 19102 | UINT32 responseSize |
| 19103 | TPM_RC responseCode |
| 19104 | |
| 19105 | TPM2B_MAX_NV_BUFFER data the data read |
| 19106 | |
| 19107 | |
| 19108 | |
| 19109 | |
| 19110 | Page 438 TCG Published Family “2.0” |
| 19111 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 19112 | Trusted Platform Module Library Part 3: Commands |
| 19113 | |
| 19114 | |
| 19115 | |
| 19116 | 31.13.3 Detailed Actions |
| 19117 | |
| 19118 | 1 #include "InternalRoutines.h" |
| 19119 | 2 #include "NV_Read_fp.h" |
| 19120 | 3 #ifdef TPM_CC_NV_Read // Conditional expansion of this file |
| 19121 | 4 #include "NV_spt_fp.h" |
| 19122 | |
| 19123 | |
| 19124 | Error Returns Meaning |
| 19125 | |
| 19126 | TPM_RC_NV_AUTHORIZATION the authorization was valid but the authorizing entity (authHandle) is |
| 19127 | not allowed to read from the Index referenced by nvIndex |
| 19128 | TPM_RC_NV_LOCKED the Index referenced by nvIndex is read locked |
| 19129 | TPM_RC_NV_RANGE read range defined by size and offset is outside the range of the |
| 19130 | Index referenced by nvIndex |
| 19131 | TPM_RC_NV_UNINITIALIZED the Index referenced by nvIndex has not been initialized (written) |
| 19132 | |
| 19133 | 5 TPM_RC |
| 19134 | 6 TPM2_NV_Read( |
| 19135 | 7 NV_Read_In *in, // IN: input parameter list |
| 19136 | 8 NV_Read_Out *out // OUT: output parameter list |
| 19137 | 9 ) |
| 19138 | 10 { |
| 19139 | 11 NV_INDEX nvIndex; |
| 19140 | 12 TPM_RC result; |
| 19141 | 13 |
| 19142 | 14 // Input Validation |
| 19143 | 15 |
| 19144 | 16 // Get NV index info |
| 19145 | 17 NvGetIndexInfo(in->nvIndex, &nvIndex); |
| 19146 | 18 |
| 19147 | 19 // Common read access checks. NvReadAccessChecks() returns |
| 19148 | 20 // TPM_RC_NV_AUTHORIZATION, TPM_RC_NV_LOCKED, or TPM_RC_NV_UNINITIALIZED |
| 19149 | 21 // error may be returned at this point |
| 19150 | 22 result = NvReadAccessChecks(in->authHandle, in->nvIndex); |
| 19151 | 23 if(result != TPM_RC_SUCCESS) |
| 19152 | 24 return result; |
| 19153 | 25 |
| 19154 | 26 // Too much data |
| 19155 | 27 if((in->size + in->offset) > nvIndex.publicArea.dataSize) |
| 19156 | 28 return TPM_RC_NV_RANGE; |
| 19157 | 29 |
| 19158 | 30 // Command Output |
| 19159 | 31 |
| 19160 | 32 // Set the return size |
| 19161 | 33 out->data.t.size = in->size; |
| 19162 | 34 // Perform the read |
| 19163 | 35 NvGetIndexData(in->nvIndex, &nvIndex, in->offset, in->size, out->data.t.buffer); |
| 19164 | 36 |
| 19165 | 37 return TPM_RC_SUCCESS; |
| 19166 | 38 } |
| 19167 | 39 #endif // CC_NV_Read |
| 19168 | |
| 19169 | |
| 19170 | |
| 19171 | |
| 19172 | Family “2.0” TCG Published Page 439 |
| 19173 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 19174 | Part 3: Commands Trusted Platform Module Library |
| 19175 | |
| 19176 | |
| 19177 | 31.14 TPM2_NV_ReadLock |
| 19178 | |
| 19179 | 31.14.1 General Description |
| 19180 | |
| 19181 | If TPMA_NV_READ_STCLEAR is SET in an Index, then this command may be used to prevent further |
| 19182 | reads of the NV Index until the next TPM2_Startup (TPM_SU_CLEAR). |
| 19183 | Proper authorizations are required for this command as determined by TPMA_NV_PPREAD, |
| 19184 | TPMA_NV_OWNERREAD, TPMA_NV_AUTHREAD, and the authPolicy of the NV Index. |
| 19185 | |
| 19186 | NOTE Only an entity that may read an Index is allowed to lock the NV Index for read. |
| 19187 | |
| 19188 | If the command is properly authorized and TPMA_NV_READ_STCLEAR of the NV Index is SET, then the |
| 19189 | TPM shall SET TPMA_NV_READLOCKED for the NV Index. If TPMA_NV_READ_STCLEAR of the NV |
| 19190 | Index is CLEAR, then the TPM shall return TPM_RC_ATTRIBUTES. TPMA_NV_READLOCKED will be |
| 19191 | CLEAR by the next TPM2_Startup(TPM_SU_CLEAR). |
| 19192 | It is not an error to use this command for an Index that is already locked for reading. |
| 19193 | An Index that had not been written may be locked for reading. |
| 19194 | |
| 19195 | |
| 19196 | |
| 19197 | |
| 19198 | Page 440 TCG Published Family “2.0” |
| 19199 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 19200 | Trusted Platform Module Library Part 3: Commands |
| 19201 | |
| 19202 | |
| 19203 | |
| 19204 | 31.14.2 Command and Response |
| 19205 | |
| 19206 | Table 219 — TPM2_NV_ReadLock Command |
| 19207 | Type Name Description |
| 19208 | |
| 19209 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 19210 | UINT32 commandSize |
| 19211 | TPM_CC commandCode TPM_CC_NV_ReadLock |
| 19212 | |
| 19213 | the handle indicating the source of the authorization |
| 19214 | value |
| 19215 | TPMI_RH_NV_AUTH @authHandle |
| 19216 | Auth Index: 1 |
| 19217 | Auth Role: USER |
| 19218 | the NV Index to be locked |
| 19219 | TPMI_RH_NV_INDEX nvIndex |
| 19220 | Auth Index: None |
| 19221 | |
| 19222 | |
| 19223 | Table 220 — TPM2_NV_ReadLock Response |
| 19224 | Type Name Description |
| 19225 | |
| 19226 | TPM_ST tag see clause 6 |
| 19227 | UINT32 responseSize |
| 19228 | TPM_RC responseCode |
| 19229 | |
| 19230 | |
| 19231 | |
| 19232 | |
| 19233 | Family “2.0” TCG Published Page 441 |
| 19234 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 19235 | Part 3: Commands Trusted Platform Module Library |
| 19236 | |
| 19237 | |
| 19238 | |
| 19239 | 31.14.3 Detailed Actions |
| 19240 | |
| 19241 | 1 #include "InternalRoutines.h" |
| 19242 | 2 #include "NV_ReadLock_fp.h" |
| 19243 | 3 #ifdef TPM_CC_NV_ReadLock // Conditional expansion of this file |
| 19244 | 4 #include "NV_spt_fp.h" |
| 19245 | |
| 19246 | |
| 19247 | Error Returns Meaning |
| 19248 | |
| 19249 | TPM_RC_ATTRIBUTES TPMA_NV_READ_STCLEAR is not SET so Index referenced by |
| 19250 | nvIndex may not be write locked |
| 19251 | TPM_RC_NV_AUTHORIZATION the authorization was valid but the authorizing entity (authHandle) is |
| 19252 | not allowed to read from the Index referenced by nvIndex |
| 19253 | |
| 19254 | 5 TPM_RC |
| 19255 | 6 TPM2_NV_ReadLock( |
| 19256 | 7 NV_ReadLock_In *in // IN: input parameter list |
| 19257 | 8 ) |
| 19258 | 9 { |
| 19259 | 10 TPM_RC result; |
| 19260 | 11 NV_INDEX nvIndex; |
| 19261 | 12 |
| 19262 | 13 // The command needs NV update. Check if NV is available. |
| 19263 | 14 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at |
| 19264 | 15 // this point |
| 19265 | 16 result = NvIsAvailable(); |
| 19266 | 17 if(result != TPM_RC_SUCCESS) return result; |
| 19267 | 18 |
| 19268 | 19 // Input Validation |
| 19269 | 20 |
| 19270 | 21 // Common read access checks. NvReadAccessChecks() returns |
| 19271 | 22 // TPM_RC_NV_AUTHORIZATION, TPM_RC_NV_LOCKED, or TPM_RC_NV_UNINITIALIZED |
| 19272 | 23 // error may be returned at this point |
| 19273 | 24 result = NvReadAccessChecks(in->authHandle, in->nvIndex); |
| 19274 | 25 if(result != TPM_RC_SUCCESS) |
| 19275 | 26 { |
| 19276 | 27 if(result == TPM_RC_NV_AUTHORIZATION) |
| 19277 | 28 return TPM_RC_NV_AUTHORIZATION; |
| 19278 | 29 // Index is already locked for write |
| 19279 | 30 else if(result == TPM_RC_NV_LOCKED) |
| 19280 | 31 return TPM_RC_SUCCESS; |
| 19281 | 32 |
| 19282 | 33 // If NvReadAccessChecks return TPM_RC_NV_UNINITALIZED, then continue. |
| 19283 | 34 // It is not an error to read lock an uninitialized Index. |
| 19284 | 35 } |
| 19285 | 36 |
| 19286 | 37 // Get NV index info |
| 19287 | 38 NvGetIndexInfo(in->nvIndex, &nvIndex); |
| 19288 | 39 |
| 19289 | 40 // if TPMA_NV_READ_STCLEAR is not set, the index can not be read-locked |
| 19290 | 41 if(nvIndex.publicArea.attributes.TPMA_NV_READ_STCLEAR == CLEAR) |
| 19291 | 42 return TPM_RC_ATTRIBUTES + RC_NV_ReadLock_nvIndex; |
| 19292 | 43 |
| 19293 | 44 // Internal Data Update |
| 19294 | 45 |
| 19295 | 46 // Set the READLOCK attribute |
| 19296 | 47 nvIndex.publicArea.attributes.TPMA_NV_READLOCKED = SET; |
| 19297 | 48 // Write NV info back |
| 19298 | 49 NvWriteIndexInfo(in->nvIndex, &nvIndex); |
| 19299 | 50 |
| 19300 | 51 return TPM_RC_SUCCESS; |
| 19301 | 52 } |
| 19302 | |
| 19303 | Page 442 TCG Published Family “2.0” |
| 19304 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 19305 | Trusted Platform Module Library Part 3: Commands |
| 19306 | |
| 19307 | 53 #endif // CC_NV_ReadLock |
| 19308 | |
| 19309 | |
| 19310 | |
| 19311 | |
| 19312 | Family “2.0” TCG Published Page 443 |
| 19313 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 19314 | Part 3: Commands Trusted Platform Module Library |
| 19315 | |
| 19316 | |
| 19317 | 31.15 TPM2_NV_ChangeAuth |
| 19318 | |
| 19319 | 31.15.1 General Description |
| 19320 | |
| 19321 | This command allows the authorization secret for an NV Index to be changed. |
| 19322 | If successful, the authorization secret (authValue) of the NV Index associated with nvIndex is changed. |
| 19323 | This command requires that a policy session be used for authorization of nvIndex so that the ADMIN role |
| 19324 | may be asserted and that commandCode in the policy session context shall be |
| 19325 | TPM_CC_NV_ChangeAuth. That is, the policy must contain a specific authorization for changing the |
| 19326 | authorization value of the referenced object. |
| 19327 | |
| 19328 | NOTE The reason for this restriction is to ensure that the administrative actions on nvIndex require explicit |
| 19329 | approval while other commands may use policy that is not command -dependent. |
| 19330 | |
| 19331 | The size of the newAuth value may be no larger than the size of authorization indicated when the NV |
| 19332 | Index was defined. |
| 19333 | Since the NV Index authorization is changed before the response HMAC is calculated, the newAuth value |
| 19334 | is used when generating the response HMAC key if required. See TPM 2.0 Part 4 |
| 19335 | ComputeResponseHMAC(). |
| 19336 | |
| 19337 | |
| 19338 | |
| 19339 | |
| 19340 | Page 444 TCG Published Family “2.0” |
| 19341 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 19342 | Trusted Platform Module Library Part 3: Commands |
| 19343 | |
| 19344 | |
| 19345 | |
| 19346 | 31.15.2 Command and Response |
| 19347 | |
| 19348 | Table 221 — TPM2_NV_ChangeAuth Command |
| 19349 | Type Name Description |
| 19350 | |
| 19351 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 19352 | UINT32 commandSize |
| 19353 | TPM_CC commandCode TPM_CC_NV_ChangeAuth {NV} |
| 19354 | |
| 19355 | handle of the object |
| 19356 | TPMI_RH_NV_INDEX @nvIndex Auth Index: 1 |
| 19357 | Auth Role: ADMIN |
| 19358 | |
| 19359 | TPM2B_AUTH newAuth new authorization value |
| 19360 | |
| 19361 | |
| 19362 | Table 222 — TPM2_NV_ChangeAuth Response |
| 19363 | Type Name Description |
| 19364 | |
| 19365 | TPM_ST tag see clause 6 |
| 19366 | UINT32 responseSize |
| 19367 | TPM_RC responseCode |
| 19368 | |
| 19369 | |
| 19370 | |
| 19371 | |
| 19372 | Family “2.0” TCG Published Page 445 |
| 19373 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 19374 | Part 3: Commands Trusted Platform Module Library |
| 19375 | |
| 19376 | |
| 19377 | |
| 19378 | 31.15.3 Detailed Actions |
| 19379 | |
| 19380 | 1 #include "InternalRoutines.h" |
| 19381 | 2 #include "NV_ChangeAuth_fp.h" |
| 19382 | 3 #ifdef TPM_CC_NV_ChangeAuth // Conditional expansion of this file |
| 19383 | |
| 19384 | |
| 19385 | Error Returns Meaning |
| 19386 | |
| 19387 | TPM_RC_SIZE newAuth size is larger than the digest size of the Name algorithm for |
| 19388 | the Index referenced by 'nvIndex |
| 19389 | |
| 19390 | 4 TPM_RC |
| 19391 | 5 TPM2_NV_ChangeAuth( |
| 19392 | 6 NV_ChangeAuth_In *in // IN: input parameter list |
| 19393 | 7 ) |
| 19394 | 8 { |
| 19395 | 9 TPM_RC result; |
| 19396 | 10 NV_INDEX nvIndex; |
| 19397 | 11 |
| 19398 | 12 // Input Validation |
| 19399 | 13 // Check if NV is available. NvIsAvailable may return TPM_RC_NV_UNAVAILABLE |
| 19400 | 14 // TPM_RC_NV_RATE or TPM_RC_SUCCESS. |
| 19401 | 15 result = NvIsAvailable(); |
| 19402 | 16 if(result != TPM_RC_SUCCESS) return result; |
| 19403 | 17 |
| 19404 | 18 // Read index info from NV |
| 19405 | 19 NvGetIndexInfo(in->nvIndex, &nvIndex); |
| 19406 | 20 |
| 19407 | 21 // Remove any trailing zeros that might have been added by the caller |
| 19408 | 22 // to obfuscate the size. |
| 19409 | 23 MemoryRemoveTrailingZeros(&(in->newAuth)); |
| 19410 | 24 |
| 19411 | 25 // Make sure that the authValue is no larger than the nameAlg of the Index |
| 19412 | 26 if(in->newAuth.t.size > CryptGetHashDigestSize(nvIndex.publicArea.nameAlg)) |
| 19413 | 27 return TPM_RC_SIZE + RC_NV_ChangeAuth_newAuth; |
| 19414 | 28 |
| 19415 | 29 // Internal Data Update |
| 19416 | 30 // Change auth |
| 19417 | 31 nvIndex.authValue = in->newAuth; |
| 19418 | 32 // Write index info back to NV |
| 19419 | 33 NvWriteIndexInfo(in->nvIndex, &nvIndex); |
| 19420 | 34 |
| 19421 | 35 return TPM_RC_SUCCESS; |
| 19422 | 36 } |
| 19423 | 37 #endif // CC_NV_ChangeAuth |
| 19424 | |
| 19425 | |
| 19426 | |
| 19427 | |
| 19428 | Page 446 TCG Published Family “2.0” |
| 19429 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 19430 | Trusted Platform Module Library Part 3: Commands |
| 19431 | |
| 19432 | |
| 19433 | 31.16 TPM2_NV_Certify |
| 19434 | |
| 19435 | 31.16.1 General Description |
| 19436 | |
| 19437 | The purpose of this command is to certify the contents of an NV Index or portion of an NV Index. |
| 19438 | If proper authorization for reading the NV Index is provided, the portion of the NV Index selected by size |
| 19439 | and offset are included in an attestation block and signed using the key indicated by signHandle. The |
| 19440 | attestation also includes size and offset so that the range of the data can be determined. |
| 19441 | |
| 19442 | NOTE 1 See 18.1 for description of how the signing scheme is selected. |
| 19443 | |
| 19444 | NOTE 2 If signHandle is TPM_RH_NULL, the TPMS_ATTEST structure is returned and signature is a NULL |
| 19445 | Signature. |
| 19446 | |
| 19447 | |
| 19448 | |
| 19449 | |
| 19450 | Family “2.0” TCG Published Page 447 |
| 19451 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 19452 | Part 3: Commands Trusted Platform Module Library |
| 19453 | |
| 19454 | |
| 19455 | 31.16.2 Command and Response |
| 19456 | |
| 19457 | Table 223 — TPM2_NV_Certify Command |
| 19458 | Type Name Description |
| 19459 | |
| 19460 | TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS |
| 19461 | UINT32 commandSize |
| 19462 | TPM_CC commandCode TPM_CC_NV_Certify |
| 19463 | |
| 19464 | handle of the key used to sign the attestation structure |
| 19465 | TPMI_DH_OBJECT+ @signHandle Auth Index: 1 |
| 19466 | Auth Role: USER |
| 19467 | handle indicating the source of the authorization value |
| 19468 | for the NV Index |
| 19469 | TPMI_RH_NV_AUTH @authHandle |
| 19470 | Auth Index: 2 |
| 19471 | Auth Role: USER |
| 19472 | Index for the area to be certified |
| 19473 | TPMI_RH_NV_INDEX nvIndex |
| 19474 | Auth Index: None |
| 19475 | |
| 19476 | TPM2B_DATA qualifyingData user-provided qualifying data |
| 19477 | signing scheme to use if the scheme for signHandle is |
| 19478 | TPMT_SIG_SCHEME+ inScheme |
| 19479 | TPM_ALG_NULL |
| 19480 | UINT16 size number of octets to certify |
| 19481 | octet offset into the area |
| 19482 | UINT16 offset This value shall be less than or equal to the size of the |
| 19483 | nvIndex data. |
| 19484 | |
| 19485 | |
| 19486 | Table 224 — TPM2_NV_Certify Response |
| 19487 | Type Name Description |
| 19488 | |
| 19489 | TPM_ST tag see clause 6 |
| 19490 | UINT32 responseSize |
| 19491 | TPM_RC responseCode . |
| 19492 | |
| 19493 | TPM2B_ATTEST certifyInfo the structure that was signed |
| 19494 | the asymmetric signature over certifyInfo using the key |
| 19495 | TPMT_SIGNATURE signature |
| 19496 | referenced by signHandle |
| 19497 | |
| 19498 | |
| 19499 | |
| 19500 | |
| 19501 | Page 448 TCG Published Family “2.0” |
| 19502 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 19503 | Trusted Platform Module Library Part 3: Commands |
| 19504 | |
| 19505 | |
| 19506 | |
| 19507 | 31.16.3 Detailed Actions |
| 19508 | |
| 19509 | 1 #include "InternalRoutines.h" |
| 19510 | 2 #include "Attest_spt_fp.h" |
| 19511 | 3 #include "NV_spt_fp.h" |
| 19512 | 4 #include "NV_Certify_fp.h" |
| 19513 | 5 #ifdef TPM_CC_NV_Certify // Conditional expansion of this file |
| 19514 | |
| 19515 | |
| 19516 | Error Returns Meaning |
| 19517 | |
| 19518 | TPM_RC_NV_AUTHORIZATION the authorization was valid but the authorizing entity (authHandle) is |
| 19519 | not allowed to read from the Index referenced by nvIndex |
| 19520 | TPM_RC_KEY signHandle does not reference a signing key |
| 19521 | TPM_RC_NV_LOCKED Index referenced by nvIndex is locked for reading |
| 19522 | TPM_RC_NV_RANGE offset plus size extends outside of the data range of the Index |
| 19523 | referenced by nvIndex |
| 19524 | TPM_RC_NV_UNINITIALIZED Index referenced by nvIndex has not been written |
| 19525 | TPM_RC_SCHEME inScheme is not an allowed value for the key definition |
| 19526 | |
| 19527 | 6 TPM_RC |
| 19528 | 7 TPM2_NV_Certify( |
| 19529 | 8 NV_Certify_In *in, // IN: input parameter list |
| 19530 | 9 NV_Certify_Out *out // OUT: output parameter list |
| 19531 | 10 ) |
| 19532 | 11 { |
| 19533 | 12 TPM_RC result; |
| 19534 | 13 NV_INDEX nvIndex; |
| 19535 | 14 TPMS_ATTEST certifyInfo; |
| 19536 | 15 |
| 19537 | 16 // Attestation command may cause the orderlyState to be cleared due to |
| 19538 | 17 // the reporting of clock info. If this is the case, check if NV is |
| 19539 | 18 // available first |
| 19540 | 19 if(gp.orderlyState != SHUTDOWN_NONE) |
| 19541 | 20 { |
| 19542 | 21 // The command needs NV update. Check if NV is available. |
| 19543 | 22 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at |
| 19544 | 23 // this point |
| 19545 | 24 result = NvIsAvailable(); |
| 19546 | 25 if(result != TPM_RC_SUCCESS) |
| 19547 | 26 return result; |
| 19548 | 27 } |
| 19549 | 28 |
| 19550 | 29 // Input Validation |
| 19551 | 30 |
| 19552 | 31 // Get NV index info |
| 19553 | 32 NvGetIndexInfo(in->nvIndex, &nvIndex); |
| 19554 | 33 |
| 19555 | 34 // Common access checks. A TPM_RC_NV_AUTHORIZATION or TPM_RC_NV_LOCKED |
| 19556 | 35 // error may be returned at this point |
| 19557 | 36 result = NvReadAccessChecks(in->authHandle, in->nvIndex); |
| 19558 | 37 if(result != TPM_RC_SUCCESS) |
| 19559 | 38 return result; |
| 19560 | 39 |
| 19561 | 40 // See if the range to be certified is out of the bounds of the defined |
| 19562 | 41 // Index |
| 19563 | 42 if((in->size + in->offset) > nvIndex.publicArea.dataSize) |
| 19564 | 43 return TPM_RC_NV_RANGE; |
| 19565 | 44 |
| 19566 | 45 // Command Output |
| 19567 | |
| 19568 | Family “2.0” TCG Published Page 449 |
| 19569 | Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014 |
| 19570 | Part 3: Commands Trusted Platform Module Library |
| 19571 | |
| 19572 | 46 |
| 19573 | 47 // Filling in attest information |
| 19574 | 48 // Common fields |
| 19575 | 49 // FillInAttestInfo can return TPM_RC_SCHEME or TPM_RC_KEY |
| 19576 | 50 result = FillInAttestInfo(in->signHandle, |
| 19577 | 51 &in->inScheme, |
| 19578 | 52 &in->qualifyingData, |
| 19579 | 53 &certifyInfo); |
| 19580 | 54 if(result != TPM_RC_SUCCESS) |
| 19581 | 55 { |
| 19582 | 56 if(result == TPM_RC_KEY) |
| 19583 | 57 return TPM_RC_KEY + RC_NV_Certify_signHandle; |
| 19584 | 58 else |
| 19585 | 59 return RcSafeAddToResult(result, RC_NV_Certify_inScheme); |
| 19586 | 60 } |
| 19587 | 61 // NV certify specific fields |
| 19588 | 62 // Attestation type |
| 19589 | 63 certifyInfo.type = TPM_ST_ATTEST_NV; |
| 19590 | 64 |
| 19591 | 65 // Get the name of the index |
| 19592 | 66 certifyInfo.attested.nv.indexName.t.size = |
| 19593 | 67 NvGetName(in->nvIndex, &certifyInfo.attested.nv.indexName.t.name); |
| 19594 | 68 |
| 19595 | 69 // Set the return size |
| 19596 | 70 certifyInfo.attested.nv.nvContents.t.size = in->size; |
| 19597 | 71 |
| 19598 | 72 // Set the offset |
| 19599 | 73 certifyInfo.attested.nv.offset = in->offset; |
| 19600 | 74 |
| 19601 | 75 // Perform the read |
| 19602 | 76 NvGetIndexData(in->nvIndex, &nvIndex, |
| 19603 | 77 in->offset, in->size, |
| 19604 | 78 certifyInfo.attested.nv.nvContents.t.buffer); |
| 19605 | 79 |
| 19606 | 80 // Sign attestation structure. A NULL signature will be returned if |
| 19607 | 81 // signHandle is TPM_RH_NULL. SignAttestInfo() may return TPM_RC_VALUE, |
| 19608 | 82 // TPM_RC_SCHEME or TPM_RC_ATTRUBUTES. |
| 19609 | 83 // Note: SignAttestInfo may return TPM_RC_ATTRIBUTES if the key is not a |
| 19610 | 84 // signing key but that was checked above. TPM_RC_VALUE would mean that the |
| 19611 | 85 // data to sign is too large but the data to sign is a digest |
| 19612 | 86 result = SignAttestInfo(in->signHandle, |
| 19613 | 87 &in->inScheme, |
| 19614 | 88 &certifyInfo, |
| 19615 | 89 &in->qualifyingData, |
| 19616 | 90 &out->certifyInfo, |
| 19617 | 91 &out->signature); |
| 19618 | 92 if(result != TPM_RC_SUCCESS) |
| 19619 | 93 return result; |
| 19620 | 94 |
| 19621 | 95 // orderly state should be cleared because of the reporting of clock info |
| 19622 | 96 // if signing happens |
| 19623 | 97 if(in->signHandle != TPM_RH_NULL) |
| 19624 | 98 g_clearOrderly = TRUE; |
| 19625 | 99 |
| 19626 | 100 return TPM_RC_SUCCESS; |
| 19627 | 101 } |
| 19628 | 102 #endif // CC_NV_Certify |
| 19629 | |
| 19630 | |
| 19631 | |
| 19632 | |
| 19633 | Page 450 TCG Published Family “2.0” |
| 19634 | October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16 |
| 19635 | |