Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / tpm2 / 7c2f61d943dd0e34764aae12e845ee3f1f98fdd3 / . / part3.txt
blob: 1f8f6bda8e41d3b027a9785113dabb5797f50ae0 [file] [log] [blame]
Vadim Bendebury56797522015-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
24TCG
25 Part 3: Commands Trusted Platform Module Library
26
27
28Licenses and Notices
29
301. 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.
382. 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.
443. 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.
62Any marks and brands contained herein are the property of their respective owner.
63
64
65
66
67Page ii TCG Published Family “2.0”
68October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
69 Trusted Platform Module Library Part 3: Commands
70
71
72 CONTENTS
73
741 Scope .................................................................................................................................................... 1
752 Terms and Definitions ........................................................................................................................... 1
763 Symbols and abbreviated terms ............................................................................................................ 1
774 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
825 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
926 Response Values ................................................................................................................................ 12
93 6.1 Tag ................................................................................................................................................ 12
94 6.2 Response Codes .......................................................................................................................... 12
957 Implementation Dependent ................................................................................................................. 15
968 Detailed Actions Assumptions ............................................................................................................. 16
97 8.1 Introduction ................................................................................................................................... 16
98 8.2 Pre-processing .............................................................................................................................. 16
99 8.3 Post Processing ............................................................................................................................ 16
1009 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
10510 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
11011 Session Commands ............................................................................................................................ 40
111 11.1 TPM2_StartAuthSession .............................................................................................................. 40
112 11.2 TPM2_PolicyRestart ..................................................................................................................... 45
11312 Object Commands............................................................................................................................... 48
114 12.1 TPM2_Create................................................................................................................................ 48
115 12.2 TPM2_Load .................................................................................................................................. 54
116
117Family “2.0” TCG Published Page iii
118Level 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
12813 Duplication Commands ....................................................................................................................... 80
129 13.1 TPM2_Duplicate ........................................................................................................................... 80
130 13.2 TPM2_Rewrap .............................................................................................................................. 84
131 13.3 TPM2_Import ................................................................................................................................ 88
13214 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
14015 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
14516 Random Number Generator .............................................................................................................. 129
146 16.1 TPM2_GetRandom ..................................................................................................................... 129
147 16.2 TPM2_StirRandom ..................................................................................................................... 132
14817 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
15518 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
16319 Ephemeral EC Keys .......................................................................................................................... 180
164 19.1 Introduction ................................................................................................................................. 180
165 19.2 TPM2_Commit ............................................................................................................................ 181
166
167
168Page iv TCG Published Family “2.0”
169October 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
17420 Signing and Signature Verification .................................................................................................... 189
175 20.1 TPM2_VerifySignature ................................................................................................................ 189
176 20.2 TPM2_Sign ................................................................................................................................. 193
17721 Command Audit ................................................................................................................................. 197
178 21.1 Introduction ................................................................................................................................. 197
179 21.2 TPM2_SetCommandCodeAuditStatus ....................................................................................... 198
18022 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
19223 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
21324 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
220Family “2.0” TCG Published Page v
221Level 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
22825 Dictionary Attack Functions ............................................................................................................... 336
229 25.1 Introduction ................................................................................................................................. 336
230 25.2 TPM2_DictionaryAttackLockReset ............................................................................................. 336
231 25.3 TPM2_DictionaryAttackParameters............................................................................................ 339
23226 Miscellaneous Management Functions ............................................................................................. 342
233 26.1 Introduction ................................................................................................................................. 342
234 26.2 TPM2_PP_Commands ............................................................................................................... 342
235 26.3 TPM2_SetAlgorithmSet .............................................................................................................. 345
23627 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
24128 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
24729 Clocks and Timers............................................................................................................................. 377
248 29.1 TPM2_ReadClock ....................................................................................................................... 377
249 29.2 TPM2_ClockSet .......................................................................................................................... 380
250 29.3 TPM2_ClockRateAdjust .............................................................................................................. 383
25130 Capability Commands ....................................................................................................................... 386
252 30.1 Introduction ................................................................................................................................. 386
253 30.2 TPM2_GetCapability ................................................................................................................... 386
254 30.3 TPM2_TestParms ....................................................................................................................... 394
25531 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
271Page vi TCG Published Family “2.0”
272October 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
283Family “2.0” TCG Published Page vii
284Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
285 Part 3: Commands Trusted Platform Module Library
286
287Tables
288Table 1 — Command Modifiers and Decoration ........................................................................................... 2
289Table 2 — Separators ................................................................................................................................... 3
290Table 3 — Unmarshaling Errors ................................................................................................................. 10
291Table 4 — Command-Independent Response Codes ................................................................................ 13
292Table 5 — TPM2_Startup Command .......................................................................................................... 22
293Table 6 — TPM2_Startup Response .......................................................................................................... 22
294Table 7 — TPM2_Shutdown Command ..................................................................................................... 27
295Table 8 — TPM2_Shutdown Response ...................................................................................................... 27
296Table 9 — TPM2_SelfTest Command ........................................................................................................ 32
297Table 10 — TPM2_SelfTest Response ...................................................................................................... 32
298Table 11 — TPM2_IncrementalSelfTest Command ................................................................................... 35
299Table 12 — TPM2_IncrementalSelfTest Response ................................................................................... 35
300Table 13 — TPM2_GetTestResult Command ............................................................................................ 38
301Table 14 — TPM2_GetTestResult Response............................................................................................. 38
302Table 15 — TPM2_StartAuthSession Command ....................................................................................... 42
303Table 16 — TPM2_StartAuthSession Response ........................................................................................ 42
304Table 17 — TPM2_PolicyRestart Command .............................................................................................. 46
305Table 18 — TPM2_PolicyRestart Response .............................................................................................. 46
306Table 19 — TPM2_Create Command ........................................................................................................ 51
307Table 20 — TPM2_Create Response ......................................................................................................... 51
308Table 21 — TPM2_Load Command ........................................................................................................... 55
309Table 22 — TPM2_Load Response ............................................................................................................ 55
310Table 23 — TPM2_LoadExternal Command .............................................................................................. 60
311Table 24 — TPM2_LoadExternal Response .............................................................................................. 60
312Table 25 — TPM2_ReadPublic Command ................................................................................................. 64
313Table 26 — TPM2_ReadPublic Response ................................................................................................. 64
314Table 27 — TPM2_ActivateCredential Command ...................................................................................... 67
315Table 28 — TPM2_ActivateCredential Response ...................................................................................... 67
316Table 29 — TPM2_MakeCredential Command .......................................................................................... 71
317Table 30 — TPM2_MakeCredential Response .......................................................................................... 71
318Table 31 — TPM2_Unseal Command ........................................................................................................ 74
319Table 32 — TPM2_Unseal Response ........................................................................................................ 74
320Table 33 — TPM2_ObjectChangeAuth Command ..................................................................................... 77
321Table 34 — TPM2_ObjectChangeAuth Response ..................................................................................... 77
322Table 35 — TPM2_Duplicate Command .................................................................................................... 81
323Table 36 — TPM2_Duplicate Response ..................................................................................................... 81
324Table 37 — TPM2_Rewrap Command ....................................................................................................... 85
325Table 38 — TPM2_Rewrap Response ....................................................................................................... 85
326
327Page viii TCG Published Family “2.0”
328October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
329 Trusted Platform Module Library Part 3: Commands
330
331Table 39 — TPM2_Import Command ......................................................................................................... 90
332Table 40 — TPM2_Import Response ......................................................................................................... 90
333Table 41 — Padding Scheme Selection ..................................................................................................... 94
334Table 42 — Message Size Limits Based on Padding ................................................................................. 95
335Table 43 — TPM2_RSA_Encrypt Command.............................................................................................. 96
336Table 44 — TPM2_RSA_Encrypt Response .............................................................................................. 96
337Table 45 — TPM2_RSA_Decrypt Command ........................................................................................... 100
338Table 46 — TPM2_RSA_Decrypt Response ............................................................................................ 100
339Table 47 — TPM2_ECDH_KeyGen Command ........................................................................................ 104
340Table 48 — TPM2_ECDH_KeyGen Response ........................................................................................ 104
341Table 49 — TPM2_ECDH_ZGen Command ............................................................................................ 108
342Table 50 — TPM2_ECDH_ZGen Response ............................................................................................ 108
343Table 51 — TPM2_ECC_Parameters Command ..................................................................................... 110
344Table 52 — TPM2_ECC_Parameters Response ..................................................................................... 110
345Table 53 — TPM2_ZGen_2Phase Command .......................................................................................... 113
346Table 54 — TPM2_ZGen_2Phase Response .......................................................................................... 113
347Table 55 — Symmetric Chaining Process ................................................................................................ 117
348Table 56 — TPM2_EncryptDecrypt Command......................................................................................... 119
349Table 57 — TPM2_EncryptDecrypt Response ......................................................................................... 119
350Table 58 — TPM2_Hash Command ......................................................................................................... 123
351Table 59 — TPM2_Hash Response ......................................................................................................... 123
352Table 60 — TPM2_HMAC Command ....................................................................................................... 126
353Table 61 — TPM2_HMAC Response ....................................................................................................... 126
354Table 62 — TPM2_GetRandom Command .............................................................................................. 130
355Table 63 — TPM2_GetRandom Response .............................................................................................. 130
356Table 64 — TPM2_StirRandom Command .............................................................................................. 133
357Table 65 — TPM2_StirRandom Response ............................................................................................... 133
358Table 66 — Hash Selection Matrix ........................................................................................................... 135
359Table 67 — TPM2_HMAC_Start Command ............................................................................................. 136
360Table 68 — TPM2_HMAC_Start Response ............................................................................................. 136
361Table 69 — TPM2_HashSequenceStart Command ................................................................................. 140
362Table 70 — TPM2_HashSequenceStart Response ................................................................................. 140
363Table 71 — TPM2_SequenceUpdate Command ..................................................................................... 143
364Table 72 — TPM2_SequenceUpdate Response ...................................................................................... 143
365Table 73 — TPM2_SequenceComplete Command ................................................................................. 147
366Table 74 — TPM2_SequenceComplete Response .................................................................................. 147
367Table 75 — TPM2_EventSequenceComplete Command ........................................................................ 151
368Table 76 — TPM2_EventSequenceComplete Response ......................................................................... 151
369Table 77 — TPM2_Certify Command ....................................................................................................... 157
370Family “2.0” TCG Published Page ix
371Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
372 Part 3: Commands Trusted Platform Module Library
373
374Table 78 — TPM2_Certify Response ....................................................................................................... 157
375Table 79 — TPM2_CertifyCreation Command ......................................................................................... 161
376Table 80 — TPM2_CertifyCreation Response .......................................................................................... 161
377Table 81 — TPM2_Quote Command ....................................................................................................... 165
378Table 82 — TPM2_Quote Response ........................................................................................................ 165
379Table 83 — TPM2_GetSessionAuditDigest Command ............................................................................ 169
380Table 84 — TPM2_GetSessionAuditDigest Response ............................................................................ 169
381Table 85 — TPM2_GetCommandAuditDigest Command ........................................................................ 173
382Table 86 — TPM2_GetCommandAuditDigest Response ......................................................................... 173
383Table 87 — TPM2_GetTime Command ................................................................................................... 177
384Table 88 — TPM2_GetTime Response .................................................................................................... 177
385Table 89 — TPM2_Commit Command ..................................................................................................... 182
386Table 90 — TPM2_Commit Response ..................................................................................................... 182
387Table 91 — TPM2_EC_Ephemeral Command ......................................................................................... 187
388Table 92 — TPM2_EC_Ephemeral Response ......................................................................................... 187
389Table 93 — TPM2_VerifySignature Command......................................................................................... 190
390Table 94 — TPM2_VerifySignature Response ......................................................................................... 190
391Table 95 — TPM2_Sign Command .......................................................................................................... 194
392Table 96 — TPM2_Sign Response .......................................................................................................... 194
393Table 97 — TPM2_SetCommandCodeAuditStatus Command ................................................................ 199
394Table 98 — TPM2_SetCommandCodeAuditStatus Response ................................................................ 199
395Table 99 — TPM2_PCR_Extend Command ............................................................................................ 204
396Table 100 — TPM2_PCR_Extend Response ........................................................................................... 204
397Table 101 — TPM2_PCR_Event Command ............................................................................................ 207
398Table 102 — TPM2_PCR_Event Response ............................................................................................. 207
399Table 103 — TPM2_PCR_Read Command ............................................................................................. 210
400Table 104 — TPM2_PCR_Read Response ............................................................................................. 210
401Table 105 — TPM2_PCR_Allocate Command ......................................................................................... 213
402Table 106 — TPM2_PCR_Allocate Response ......................................................................................... 213
403Table 107 — TPM2_PCR_SetAuthPolicy Command ............................................................................... 216
404Table 108 — TPM2_PCR_SetAuthPolicy Response ............................................................................... 216
405Table 109 — TPM2_PCR_SetAuthValue Command ............................................................................... 219
406Table 110 — TPM2_PCR_SetAuthValue Response ................................................................................ 219
407Table 111 — TPM2_PCR_Reset Command ............................................................................................ 222
408Table 112 — TPM2_PCR_Reset Response ............................................................................................. 222
409Table 113 — TPM2_PolicySigned Command .......................................................................................... 238
410Table 114 — TPM2_PolicySigned Response ........................................................................................... 238
411Table 115 — TPM2_PolicySecret Command ........................................................................................... 243
412Table 116 — TPM2_PolicySecret Response ............................................................................................ 243
413Page x TCG Published Family “2.0”
414October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
415 Trusted Platform Module Library Part 3: Commands
416
417Table 117 — TPM2_PolicyTicket Command ............................................................................................ 247
418Table 118 — TPM2_PolicyTicket Response ............................................................................................ 247
419Table 119 — TPM2_PolicyOR Command ................................................................................................ 251
420Table 120 — TPM2_PolicyOR Response ................................................................................................. 251
421Table 121 — TPM2_PolicyPCR Command .............................................................................................. 256
422Table 122 — TPM2_PolicyPCR Response .............................................................................................. 256
423Table 123 — TPM2_PolicyLocality Command ......................................................................................... 260
424Table 124 — TPM2_PolicyLocality Response .......................................................................................... 260
425Table 125 — TPM2_PolicyNV Command ................................................................................................. 264
426Table 126 — TPM2_PolicyNV Response ................................................................................................. 264
427Table 127 — TPM2_PolicyCounterTimer Command ............................................................................... 269
428Table 128 — TPM2_PolicyCounterTimer Response ................................................................................ 269
429Table 129 — TPM2_PolicyCommandCode Command ............................................................................ 274
430Table 130 — TPM2_PolicyCommandCode Response ............................................................................. 274
431Table 131 — TPM2_PolicyPhysicalPresence Command ......................................................................... 277
432Table 132 — TPM2_PolicyPhysicalPresence Response ......................................................................... 277
433Table 133 — TPM2_PolicyCpHash Command......................................................................................... 280
434Table 134 — TPM2_PolicyCpHash Response ......................................................................................... 280
435Table 135 — TPM2_PolicyNameHash Command.................................................................................... 284
436Table 136 — TPM2_PolicyNameHash Response .................................................................................... 284
437Table 137 — TPM2_PolicyDuplicationSelect Command .......................................................................... 288
438Table 138 — TPM2_PolicyDuplicationSelect Response .......................................................................... 288
439Table 139 — TPM2_PolicyAuthorize Command ...................................................................................... 292
440Table 140 — TPM2_PolicyAuthorize Response ....................................................................................... 292
441Table 141 — TPM2_PolicyAuthValue Command ..................................................................................... 296
442Table 142 — TPM2_PolicyAuthValue Response ..................................................................................... 296
443Table 143 — TPM2_PolicyPassword Command ...................................................................................... 299
444Table 144 — TPM2_PolicyPassword Response ...................................................................................... 299
445Table 145 — TPM2_PolicyGetDigest Command...................................................................................... 302
446Table 146 — TPM2_PolicyGetDigest Response ...................................................................................... 302
447Table 147 — TPM2_PolicyNvWritten Command ...................................................................................... 305
448Table 148 — TPM2_PolicyNvWritten Response ...................................................................................... 305
449Table 149 — TPM2_CreatePrimary Command ........................................................................................ 309
450Table 150 — TPM2_CreatePrimary Response ........................................................................................ 309
451Table 151 — TPM2_HierarchyControl Command .................................................................................... 313
452Table 152 — TPM2_HierarchyControl Response .................................................................................... 313
453Table 153 — TPM2_SetPrimaryPolicy Command .................................................................................... 317
454Table 154 — TPM2_SetPrimaryPolicy Response .................................................................................... 317
455Table 155 — TPM2_ChangePPS Command ........................................................................................... 321
456Family “2.0” TCG Published Page xi
457Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
458 Part 3: Commands Trusted Platform Module Library
459
460Table 156 — TPM2_ChangePPS Response ............................................................................................ 321
461Table 157 — TPM2_ChangeEPS Command ........................................................................................... 324
462Table 158 — TPM2_ChangeEPS Response ............................................................................................ 324
463Table 159 — TPM2_Clear Command ....................................................................................................... 327
464Table 160 — TPM2_Clear Response ....................................................................................................... 327
465Table 161 — TPM2_ClearControl Command ........................................................................................... 331
466Table 162 — TPM2_ClearControl Response ........................................................................................... 331
467Table 163 — TPM2_HierarchyChangeAuth Command ............................................................................ 334
468Table 164 — TPM2_HierarchyChangeAuth Response ............................................................................ 334
469Table 165 — TPM2_DictionaryAttackLockReset Command .................................................................... 337
470Table 166 — TPM2_DictionaryAttackLockReset Response .................................................................... 337
471Table 167 — TPM2_DictionaryAttackParameters Command .................................................................. 340
472Table 168 — TPM2_DictionaryAttackParameters Response ................................................................... 340
473Table 169 — TPM2_PP_Commands Command ...................................................................................... 343
474Table 170 — TPM2_PP_Commands Response ...................................................................................... 343
475Table 171 — TPM2_SetAlgorithmSet Command ..................................................................................... 346
476Table 172 — TPM2_SetAlgorithmSet Response...................................................................................... 346
477Table 173 — TPM2_FieldUpgradeStart Command .................................................................................. 351
478Table 174 — TPM2_FieldUpgradeStart Response .................................................................................. 351
479Table 175 — TPM2_FieldUpgradeData Command .................................................................................. 354
480Table 176 — TPM2_FieldUpgradeData Response .................................................................................. 354
481Table 177 — TPM2_FirmwareRead Command........................................................................................ 357
482Table 178 — TPM2_FirmwareRead Response ........................................................................................ 357
483Table 179 — TPM2_ContextSave Command........................................................................................... 360
484Table 180 — TPM2_ContextSave Response ........................................................................................... 360
485Table 181 — TPM2_ContextLoad Command ........................................................................................... 365
486Table 182 — TPM2_ContextLoad Response ........................................................................................... 365
487Table 183 — TPM2_FlushContext Command .......................................................................................... 370
488Table 184 — TPM2_FlushContext Response .......................................................................................... 370
489Table 185 — TPM2_EvictControl Command ............................................................................................ 374
490Table 186 — TPM2_EvictControl Response ............................................................................................ 374
491Table 187 — TPM2_ReadClock Command.............................................................................................. 378
492Table 188 — TPM2_ReadClock Response .............................................................................................. 378
493Table 189 — TPM2_ClockSet Command ................................................................................................. 381
494Table 190 — TPM2_ClockSet Response ................................................................................................. 381
495Table 191 — TPM2_ClockRateAdjust Command..................................................................................... 384
496Table 192 — TPM2_ClockRateAdjust Response ..................................................................................... 384
497Table 193 — TPM2_GetCapability Command.......................................................................................... 390
498Table 194 — TPM2_GetCapability Response .......................................................................................... 390
499Page xii TCG Published Family “2.0”
500October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
501 Trusted Platform Module Library Part 3: Commands
502
503Table 195 — TPM2_TestParms Command .............................................................................................. 395
504Table 196 — TPM2_TestParms Response .............................................................................................. 395
505Table 197 — TPM2_NV_DefineSpace Command ................................................................................... 401
506Table 198 — TPM2_NV_DefineSpace Response .................................................................................... 401
507Table 199 — TPM2_NV_UndefineSpace Command ............................................................................... 406
508Table 200 — TPM2_NV_UndefineSpace Response ................................................................................ 406
509Table 201 — TPM2_NV_UndefineSpaceSpecial Command .................................................................... 409
510Table 202 — TPM2_NV_UndefineSpaceSpecial Response .................................................................... 409
511Table 203 — TPM2_NV_ReadPublic Command ...................................................................................... 412
512Table 204 — TPM2_NV_ReadPublic Response ...................................................................................... 412
513Table 205 — TPM2_NV_Write Command ................................................................................................ 415
514Table 206 — TPM2_NV_Write Response ................................................................................................ 415
515Table 207 — TPM2_NV_Increment Command ........................................................................................ 419
516Table 208 — TPM2_NV_Increment Response......................................................................................... 419
517Table 209 — TPM2_NV_Extend Command ............................................................................................. 423
518Table 210 — TPM2_NV_Extend Response ............................................................................................. 423
519Table 211 — TPM2_NV_SetBits Command ............................................................................................. 427
520Table 212 — TPM2_NV_SetBits Response ............................................................................................. 427
521Table 213 — TPM2_NV_WriteLock Command ........................................................................................ 431
522Table 214 — TPM2_NV_WriteLock Response......................................................................................... 431
523Table 215 — TPM2_NV_GlobalWriteLock Command .............................................................................. 435
524Table 216 — TPM2_NV_GlobalWriteLock Response .............................................................................. 435
525Table 217 — TPM2_NV_Read Command................................................................................................ 438
526Table 218 — TPM2_NV_Read Response ................................................................................................ 438
527Table 219 — TPM2_NV_ReadLock Command ........................................................................................ 441
528Table 220 — TPM2_NV_ReadLock Response ........................................................................................ 441
529Table 221 — TPM2_NV_ChangeAuth Command .................................................................................... 445
530Table 222 — TPM2_NV_ChangeAuth Response .................................................................................... 445
531Table 223 — TPM2_NV_Certify Command .............................................................................................. 448
532Table 224 — TPM2_NV_Certify Response .............................................................................................. 448
533
534
535
536
537Family “2.0” TCG Published Page xiii
538Level 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
5451 Scope
546
547This TPM 2.0 Part 3 of the Trusted Platform Module Library specification contains the definitions of the
548TPM commands. These commands make use of the constants, flags, structures, and union definitions
549defined in TPM 2.0 Part 2.
550The detailed description of the operation of the commands is written in the C language with extensive
551comments. The behavior of the C code in this TPM 2.0 Part 3 is normative but does not fully describe the
552behavior of a TPM. The combination of this TPM 2.0 Part 3 and TPM 2.0 Part 4 is sufficient to fully
553describe the required behavior of a TPM.
554The code in parts 3 and 4 is written to define the behavior of a compliant TPM. In some cases (e.g.,
555firmware update), it is not possible to provide a compliant implementation. In those cases, any
556implementation provided by the vendor that meets the general description of the function provided in TPM
5572.0 Part 3 would be compliant.
558The code in parts 3 and 4 is not written to meet any particular level of conformance nor does this
559specification require that a TPM meet any particular level of conformance.
560
561
5622 Terms and Definitions
563
564For the purposes of this document, the terms and definitions given in TPM 2.0 Part 1 apply.
565
566
5673 Symbols and abbreviated terms
568
569For the purposes of this document, the symbols and abbreviated terms given in TPM 2.0 Part 1 apply.
570
571
5724 Notation
573
5744.1 Introduction
575
576For the purposes of this document, the notation given in TPM 2.0 Part 1 applies.
577Command and response tables use various decorations to indicate the fields of the command and the
578allowed types. These decorations are described in this clause.
579
5804.2 Table Decorations
581
582The symbols and terms in the Notation column of Table 1 are used in the tables for the command
583schematics. These values indicate various qualifiers for the parameters or descriptions with which they
584are associated.
585
586
587
588
589Family “2.0” TCG Published Page 1
590Level 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
642Page 2 TCG Published Family “2.0”
643October 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
6734.3 Handle and Parameter Demarcation
674
675The 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
6844.4 AuthorizationSize and ParameterSize
685
686Authorization sessions are not shown in the command or response schematics. When the tag of a
687command or response is TPM_ST_SESSIONS, then a 32-bit value will be present in the
688command/response buffer to indicate the size of the authorization field or the parameter field. This value
689shall 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
691response, this value (parameterSize) indicates the size of the parameter area and may have a value of
692zero.
693If the authorizationSize field is present in the command, parameterSize will be present in the response,
694but only if the responseCode is TPM_RC_SUCCESS.
695When authorization is required to use the TPM entity associated with a handle, then at least one session
696will be present. To indicate this, the command tag Description field contains TPM_ST_SESSIONS.
697Addional sessions for audit, encrypt, and decrypt may be present.
698When the command tag Description field contains TPM_ST_NO_SESSIONS, then no sessions are
699allowed and the authorizationSize field is not present.
700When a command allows use of sessions when not required, the command tag Description field will
701indicate the types of sessions that may be used with the command.
702
703
704Family “2.0” TCG Published Page 3
705Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
706 Part 3: Commands Trusted Platform Module Library
707
708
7095 Command Processing
710
7115.1 Introduction
712
713This clause defines the command validations that are required of any implementation and the response
714code returned if the indicated check fails. Unless stated otherwise, the order of the checks is not
715normative and different TPM may give different responses when a command has multiple errors.
716In the description below, some statements that describe a check may be followed by a response code in
717parentheses. This is the normative response code should the indicated check fail. A normative response
718code may also be included in the statement.
719
7205.2 Command Header Validation
721
722Before a TPM may begin the actions associated with a command, a set of command format and
723consistency checks shall be performed. These checks are listed below and should be performed in the
724indicated order.
725a) 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).
727b) 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
734c) The TPM shall successfully unmarshal a TPM_CC and verify that the command is implemented
735 (TPM_RC_COMMAND_CODE).
736
7375.3 Mode Checks
738
739The following mode checks shall be performed in the order listed:
740a) 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
747b) The TPM is in Field Upgrade mode (FUM), the commandCode is TPM_CC_FieldUpgradeData
748 (TPM_RC_UPGRADE).
749c) 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
765Page 4 TCG Published Family “2.0”
766October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
767 Trusted Platform Module Library Part 3: Commands
768
769The mode checks may be performed before or after the command header validation.
770
7715.4 Handle Area Validation
772
773After successfully unmarshaling and validating the command header, the TPM shall perform the following
774checks on the handles and sessions. These checks may be performed in any order.
775
776NOTE 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
781a) 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
791b) 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
824Family “2.0” TCG Published Page 5
825Level 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
8385.5 Session Area Validation
839
840a) If the tag is TPM_ST_SESSIONS and the command requires TPM_ST_NO_SESSIONS, the TPM will
841 return TPM_RC_AUTH_CONTEXT.
842b) If the tag is TPM_ST_NO_SESSIONS and the command requires TPM_ST_SESSIONS, the TPM will
843 return TPM_RC_AUTH_MISSING.
844c) 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
856d) 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
881Page 6 TCG Published Family “2.0”
882October 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
8975.6 Authorization Checks
898
899After unmarshaling and validating the handles and the consistency of the authorization sessions, the
900authorizations shall be checked. Authorization checks only apply to handles if the handle in the command
901schematic has the “@” decoration.
902a) The public and sensitive portions of the object shall be present on the TPM
903 (TPM_RC_AUTH_UNAVAILABLE).
904b) 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).
906c) 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
915d) 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).
917e) 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
929f) 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
940Family “2.0” TCG Published Page 7
941Level 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).
951g) 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
964h) 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
971i) 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).
973If the TPM returns an error other than TPM_RC_AUTH_FAIL then the TPM shall not alter any TPM state.
974If the TPM return TPM_RC_AUTH_FAIL, then the TPM shall not alter any TPM state other than
975lockoutCount.
976
977NOTE 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
9815.7 Parameter Decryption
982
983If an authorization session has the TPMA_SESSION.decrypt attribute SET, and the command does not
984allow a command parameter to be encrypted, then the TPM will return TPM_RC_ATTRIBUTES.
985Otherwise, the TPM will decrypt the parameter using the values associated with the session before
986parsing parameters.
987
9885.8 Parameter Unmarshaling
989
9905.8.1 Introduction
991
992The detailed actions for each command assume that the input parameters of the command have been
993unmarshaled into a command-specific structure with the structure defined by the command schematic.
994
995
996Page 8 TCG Published Family “2.0”
997October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
998 Trusted Platform Module Library Part 3: Commands
999
1000Additionally, a response-specific output structure is assumed which will receive the values produced by
1001the detailed actions.
1002
1003NOTE 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
1007Unmarshaling is the process of processing the parameters in the input buffer and preparing the
1008parameters for use by the command-specific action code. No data movement need take place but it is
1009required that the TPM validate that the parameters meet the requirements of the expected data type as
1010defined in TPM 2.0 Part 2.
1011
10125.8.2 Unmarshaling Errors
1013
1014When an error is encountered while unmarshaling a command parameter, an error response code is
1015returned and no command processing occurs. A table defining a data type may have response codes
1016embedded in the table to indicate the error returned when the input value does not match the parameters
1017of the table.
1018
1019NOTE 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
1022In many cases, the table contains no specific response code value and the return code will be determined
1023as defined in Table 3.
1024
1025
1026
1027
1028Family “2.0” TCG Published Page 9
1029Level 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
1062In some commands, a parameter may not be used because of various options of that command.
1063However, the unmarshaling code is required to validate that all parameters have values that are allowed
1064by the TPM 2.0 Part 2 definition of the parameter type even if that parameter is not used in the command
1065actions.
1066
10675.9 Command Post Processing
1068
1069When the code that implements the detailed actions of the command completes, it returns a response
1070code. If that code is not TPM_RC_SUCCESS, the post processing code will not update any session or
1071audit data and will return a 10-octet response packet.
1072If the command completes successfully, the tag of the command determines if any authorization sessions
1073will be in the response. If so, the TPM will encrypt the first parameter of the response if indicated by the
1074authorization attributes. The TPM will then generate a new nonce value for each session and, if
1075appropriate, generate an HMAC.
1076If authorization HMAC computations are performed on the response, the HMAC keys used in the
1077response will be the same as the HMAC keys used in processing the HMAC in the command.
1078
1079
1080
1081
1082Page 10 TCG Published Family “2.0”
1083October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
1084 Trusted Platform Module Library Part 3: Commands
1085
1086NOTE 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
1091NOTE 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
1095NOTE 3 No session nonce value is used for a password authorization but the session data is present.
1096
1097Additionally, if the command is being audited by Command Audit, the audit digest is updated with the
1098cpHash of the command and rpHash of the response.
1099
1100
1101
1102
1103Family “2.0” TCG Published Page 11
1104Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
1105 Part 3: Commands Trusted Platform Module Library
1106
1107
1108
11096 Response Values
1110
11116.1 Tag
1112
1113When a command completes successfully, the tag parameter in the response shall have the same value
1114as the tag parameter in the command (TPM_ST_SESSIONS or TPM_RC_NO_SESSIONS). When a
1115command fails (the responseCode is not TPM_RC_SUCCESS), then the tag parameter in the response
1116shall be TPM_ST_NO_SESSIONS.
1117A special case exists when the command tag parameter is not an allowed value (TPM_ST_SESSIONS or
1118TPM_ST_NO_SESSIONS). For this case, it is assumed that the system software is attempting to send a
1119command formatted for a TPM 1.2 but the TPM is not capable of executing TPM 1.2 commands. So that
1120the TPM 1.2 compatible software will have a recognizable response, the TPM sets tag to
1121TPM_ST_RSP_COMMAND, responseSize to 00 00 00 0A16 and responseCode to TPM_RC_BAD_TAG.
1122This is the same response as the TPM 1.2 fatal error for TPM_BADTAG.
1123
11246.2 Response Codes
1125
1126The normal response for any command is TPM_RC_SUCCESS. Any other value indicates that the
1127command did not complete and the state of the TPM is unchanged. An exception to this general rule is
1128that the logic associated with dictionary attack protection is allowed to be modified when an authorization
1129failure occurs.
1130Commands have response codes that are specific to that command, and those response codes are
1131enumerated in the detailed actions of each command. The codes associated with the unmarshaling of
1132parameters are documented Table 3. Another set of response code values are not command specific and
1133indicate a problem that is not specific to the command. That is, if the indicated problem is remedied, the
1134same command could be resubmitted and may complete normally.
1135The response codes that are not command specific are listed and described in Table 4.
1136The reference code for the command actions may have code that generates specific response codes
1137associated with a specific check but the listing of responses may not have that response code listed.
1138
1139
1140
1141
1142Page 12 TCG Published Family “2.0”
1143October 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
1147Response 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
1151TPM_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
1156TPM_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
1160TPM_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
1165TPM_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
1171TPM_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
1176TPM_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
1182TPM_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
1192TPM_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
1202TPM_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
1210Family “2.0” TCG Published Page 13
1211Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
1212 Part 3: Commands Trusted Platform Module Library
1213
1214
1215Response 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
1221TPM_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.
1225TPM_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
1228TPM_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()).
1234TPM_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
1240TPM_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
1244TPM_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.
1248TPM_RC_YIELDED
1249 See TPM 2.0 Part 1, “Multi-tasking.”
1250 NOTE This cannot occur on the reference implementation.
1251
1252
1253
1254
1255Page 14 TCG Published Family “2.0”
1256October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
1257 Trusted Platform Module Library Part 3: Commands
1258
1259
1260
12617 Implementation Dependent
1262
1263The actions code for each command makes assumptions about the behavior of various sub-systems.
1264There are many possible implementations of the subsystems that would achieve equivalent results. The
1265actions code is not written to anticipate all possible implementations of the sub-systems. Therefore, it is
1266the responsibility of the implementer to ensure that the necessary changes are made to the actions code
1267when the sub-system behavior changes.
1268
1269
1270
1271
1272Family “2.0” TCG Published Page 15
1273Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
1274 Part 3: Commands Trusted Platform Module Library
1275
1276
1277
12788 Detailed Actions Assumptions
1279
12808.1 Introduction
1281
1282The C code in the Detailed Actions for each command is written with a set of assumptions about the
1283processing performed before the action code is called and the processing that will be done after the
1284action code completes.
1285
12868.2 Pre-processing
1287
1288Before 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
13078.3 Post Processing
1308
1309When 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
1320Page 16 TCG Published Family “2.0”
1321October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
1322 Trusted Platform Module Library Part 3: Commands
1323
1324
1325
13269 Start-up
1327
13289.1 Introduction
1329
1330This clause contains the commands used to manage the startup and restart state of a TPM.
1331
13329.2 _TPM_Init
1333
13349.2.1 General Description
1335
1336_TPM_Init initializes a TPM.
1337Initialization actions include testing code required to execute the next expected command. If the TPM is in
1338FUM, the next expected command is TPM2_FieldUpgradeData(); otherwise, the next expected command
1339is TPM2_Startup().
1340
1341NOTE 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
1345The means of signaling _TPM_Init shall be defined in the platform-specific specifications that define the
1346physical interface to the TPM. The platform shall send this indication whenever the platform starts its boot
1347process and only when the platform starts its boot process.
1348There shall be no software method of generating this indication that does not also reset the platform and
1349begin execution of the CRTM.
1350
1351NOTE 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
1357Family “2.0” TCG Published Page 17
1358Level 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;
137510
137611 // Initialize the NvEnvironment.
137712 g_nvOk = NvPowerOn();
137813
137914 // Initialize crypto engine
138015 CryptInitUnits();
138116
138217 // Start clock
138318 TimePowerOn();
138419
138520 // Set initialization state
138621 TPMInit();
138722
138823 // Initialize object table
138924 ObjectStartup();
139025
139126 // Set g_DRTMHandle as unassigned
139227 g_DRTMHandle = TPM_RH_UNASSIGNED;
139328
139429 // No H-CRTM, yet.
139530 g_DrtmPreStartup = FALSE;
139631
139732 return;
139833 }
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
14099.3 TPM2_Startup
1410
14119.3.1 General Description
1412
1413TPM2_Startup() is always preceded by _TPM_Init, which is the physical indication that TPM initialization
1414is necessary because of a system-wide reset. TPM2_Startup() is only valid after _TPM_Init. Additional
1415TPM2_Startup() commands are not allowed after it has completed successfully. If a TPM requires
1416TPM2_Startup() and another command is received, or if the TPM receives TPM2_Startup() when it is not
1417required, the TPM shall return TPM_RC_INITIALIZE.
1418
1419NOTE 1 See 9.2.1 for other command options for a TPM supporting field upgrade mode.
1420
1421NOTE 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
1424If in Failure mode, the TPM shall accept TPM2_GetTestResult() and TPM2_GetCapability() even if
1425TPM2_Startup() is not completed successfully or processed at all.
1426A platform-specific specification may restrict the localities at which TPM2_Startup() may be received.
1427A Shutdown/Startup sequence determines the way in which the TPM will operate in response to
1428TPM2_Startup(). The three sequences are:
14291) 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
14372) 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;
14403) 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.
1443If a TPM receives Startup(STATE) and that was not preceded by Shutdown(STATE), the TPM shall return
1444TPM_RC_VALUE.
1445If, during TPM Restart or TPM Resume, the TPM fails to restore the state saved at the last
1446Shutdown(STATE), the TPM shall enter Failure Mode and return TPM_RC_FAILURE.
1447On 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.
1452Additional actions are performed based on the Shutdown/Startup sequence.
1453On TPM Reset
1454
1455
1456
1457
1458Family “2.0” TCG Published Page 19
1459Level 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
1485On 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.
1496On 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.
1504Other TPM state may change as required to meet the needs of the implementation.
1505If the startupType is TPM_SU_STATE and the TPM requires TPM_SU_CLEAR, then the TPM shall return
1506TPM_RC_VALUE.
1507
1508
1509
1510Page 20 TCG Published Family “2.0”
1511October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
1512 Trusted Platform Module Library Part 3: Commands
1513
1514NOTE 6 The TPM will require TPM_SU_CLEAR when no shutdown was performed or after
1515 Shutdown(CLEAR).
1516
1517NOTE 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
1523Family “2.0” TCG Published Page 21
1524Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
1525 Part 3: Commands Trusted Platform Module Library
1526
1527
15289.3.2 Command and Response
1529
1530 Table 5 — TPM2_Startup Command
1531Type Name Description
1532
1533TPMI_ST_COMMAND_TAG tag TPM_ST_NO_SESSIONS
1534UINT32 commandSize
1535TPM_CC commandCode TPM_CC_Startup {NV}
1536
1537TPM_SU startupType TPM_SU_CLEAR or TPM_SU_STATE
1538
1539
1540 Table 6 — TPM2_Startup Response
1541Type Name Description
1542
1543TPM_ST tag see clause 6
1544UINT32 responseSize
1545TPM_RC responseCode
1546
1547
1548
1549
1550Page 22 TCG Published Family “2.0”
1551October 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
15581 #include "InternalRoutines.h"
15592 #include "Startup_fp.h"
15603 #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;
157710 TPM_RC result;
157811 BOOL prevDrtmPreStartup;
157912 BOOL prevStartupLoc3;
158013 BYTE locality = _plat__LocalityGet();
158114
158215 // In the PC Client specification, only locality 0 and 3 are allowed
158316 if(locality != 0 && locality != 3)
158417 return TPM_RC_LOCALITY;
158518 // Indicate that the locality was 3 unless there was an H-CRTM
158619 if(g_DrtmPreStartup)
158720 locality = 0;
158821 g_StartupLocality3 = (locality == 3);
158922
159023 // The command needs NV update. Check if NV is available.
159124 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
159225 // this point
159326 result = NvIsAvailable();
159427 if(result != TPM_RC_SUCCESS)
159528 return result;
159629
159730 // Input Validation
159831
159932 // Read orderly shutdown states from previous power cycle
160033 NvReadReserved(NV_ORDERLY, &g_prevOrderlyState);
160134
160235 // See if the orderly state indicates that state was saved
160336 if( (g_prevOrderlyState & ~(PRE_STARTUP_FLAG | STARTUP_LOCALITY_3))
160437 == TPM_SU_STATE)
160538 {
160639 // If so, extrat the saved flags (HACK)
160740 prevDrtmPreStartup = (g_prevOrderlyState & PRE_STARTUP_FLAG) != 0;
160841 prevStartupLoc3 = (g_prevOrderlyState & STARTUP_LOCALITY_3) != 0;
160942 g_prevOrderlyState = TPM_SU_STATE;
161043 }
161144 else
161245 {
161346 prevDrtmPreStartup = 0;
161447 prevStartupLoc3 = 0;
161548 }
161649 // if this startup is a TPM Resume, then the H-CRTM states have to match.
161750 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
1672100 // Crypto Startup
1673101 CryptUtilStartup(startup);
1674102
1675103 // Read the platform unique value that is used as VENDOR_PERMANENT auth value
1676104 g_platformUniqueDetails.t.size = (UINT16)_plat__GetUnique(1,
1677105 sizeof(g_platformUniqueDetails.t.buffer),
1678106 g_platformUniqueDetails.t.buffer);
1679107
1680108 // Start up subsystems
1681109 // Start counters and timers
1682110 TimeStartup(startup);
1683111
1684112 // Start dictionary attack subsystem
1685113 DAStartup(startup);
1686114
1687115 // Enable hierarchies
1688116 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
1694117
1695118 // Restore/Initialize PCR
1696119 PCRStartup(startup, locality);
1697120
1698121 // Restore/Initialize command audit information
1699122 CommandAuditStartup(startup);
1700123
1701124 // Object context variables
1702125 if(startup == SU_RESET)
1703126 {
1704127 // Reset object context ID to 0
1705128 gr.objectContextID = 0;
1706129 // Reset clearCount to 0
1707130 gr.clearCount= 0;
1708131 }
1709132
1710133 // Initialize session table
1711134 SessionStartup(startup);
1712135
1713136 // Initialize index/evict data. This function clear read/write locks
1714137 // in NV index
1715138 NvEntityStartup(startup);
1716139
1717140 // Initialize the orderly shut down flag for this cycle to SHUTDOWN_NONE.
1718141 gp.orderlyState = SHUTDOWN_NONE;
1719142 NvWriteReserved(NV_ORDERLY, &gp.orderlyState);
1720143
1721144 // Update TPM internal states if command succeeded.
1722145 // Record a TPM2_Startup command has been received.
1723146 TPMRegisterStartup();
1724147
1725148 // The H-CRTM state no longer matters
1726149 g_DrtmPreStartup = FALSE;
1727150
1728151 return TPM_RC_SUCCESS;
1729152
1730153 }
1731154 #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
17419.4 TPM2_Shutdown
1742
17439.4.1 General Description
1744
1745This command is used to prepare the TPM for a power cycle. The shutdownType parameter indicates
1746how the subsequent TPM2_Startup() will be processed.
1747For a shutdownType of any type, the volatile portion of Clock is saved to NV memory and the orderly
1748shutdown indication is SET. NV with the TPMA_NV_ORDERY attribute will be updated.
1749For 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.
1757The 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().
1761Some values may be either derived from other values or saved to NV memory.
1762This command saves TPM state but does not change the state other than the internal indication that the
1763context has been saved. The TPM shall continue to accept commands. If a subsequent command
1764changes TPM state saved by this command, then the effect of this command is nullified. The TPM MAY
1765nullify this command for any subsequent command rather than check whether the command changed
1766state saved by this command. If this command is nullified. and if no TPM2_Shutdown() occurs before the
1767next TPM2_Startup(), then the next TPM2_Startup() shall be TPM2_Startup(CLEAR).
1768
1769
1770
1771
1772Page 26 TCG Published Family “2.0”
1773October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
1774 Trusted Platform Module Library Part 3: Commands
1775
1776
1777
17789.4.2 Command and Response
1779
1780 Table 7 — TPM2_Shutdown Command
1781Type Name Description
1782
1783 TPM_ST_SESSIONS if an audit session is present;
1784TPMI_ST_COMMAND_TAG tag
1785 otherwise, TPM_ST_NO_SESSIONS
1786UINT32 commandSize
1787TPM_CC commandCode TPM_CC_Shutdown {NV}
1788
1789TPM_SU shutdownType TPM_SU_CLEAR or TPM_SU_STATE
1790
1791
1792 Table 8 — TPM2_Shutdown Response
1793Type Name Description
1794
1795TPM_ST tag see clause 6
1796UINT32 responseSize
1797TPM_RC responseCode
1798
1799
1800
1801
1802Family “2.0” TCG Published Page 27
1803Level 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
18101 #include "InternalRoutines.h"
18112 #include "Shutdown_fp.h"
18123 #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;
182610
182711 // The command needs NV update. Check if NV is available.
182812 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
182913 // this point
183014 result = NvIsAvailable();
183115 if(result != TPM_RC_SUCCESS) return result;
183216
183317 // Input Validation
183418
183519 // If PCR bank has been reconfigured, a CLEAR state save is required
183620 if(g_pcrReConfig && in->shutdownType == TPM_SU_STATE)
183721 return TPM_RC_TYPE + RC_Shutdown_shutdownType;
183822
183923 // Internal Data Update
184024
184125 // PCR private date state save
184226 PCRStateSave(in->shutdownType);
184327
184428 // Get DRBG state
184529 CryptDrbgGetPutState(GET_STATE);
184630
184731 // Save all orderly data
184832 NvWriteReserved(NV_ORDERLY_DATA, &go);
184933
185034 // Save RAM backed NV index data
185135 NvStateSave();
185236
185337 if(in->shutdownType == TPM_SU_STATE)
185438 {
185539 // Save STATE_RESET and STATE_CLEAR data
185640 NvWriteReserved(NV_STATE_CLEAR, &gc);
185741 NvWriteReserved(NV_STATE_RESET, &gr);
185842 }
185943 else if(in->shutdownType == TPM_SU_CLEAR)
186044 {
186145 // Save STATE_RESET data
186246 NvWriteReserved(NV_STATE_RESET, &gr);
186347 }
186448
186549 // Write orderly shut down state
186650 if(in->shutdownType == TPM_SU_CLEAR)
186751 gp.orderlyState = TPM_SU_CLEAR;
186852 else if(in->shutdownType == TPM_SU_STATE)
186953 {
187054 gp.orderlyState = TPM_SU_STATE;
187155 // 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
187756 if(g_DrtmPreStartup)
187857 gp.orderlyState |= PRE_STARTUP_FLAG;
187958 else if(g_StartupLocality3)
188059 gp.orderlyState |= STARTUP_LOCALITY_3;
188160 }
188261 else
188362 pAssert(FALSE);
188463
188564 NvWriteReserved(NV_ORDERLY, &gp.orderlyState);
188665
188766 // If PRE_STARTUP_FLAG was SET, then it will stay set in gp.orderlyState even
188867 // if the TPM isn't actually shut down. This is OK because all other checks
188968 // of gp.orderlyState are to see if it is SHUTDOWN_NONE. So, having
189069 // gp.orderlyState set to another value that is also not SHUTDOWN_NONE, is not
189170 // an issue. This must be the case, otherwise, it would be impossible to add
189271 // an additional shutdown type without major changes to the code.
189372
189473 return TPM_RC_SUCCESS;
189574 }
189675 #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
190610 Testing
1907
190810.1 Introduction
1909
1910Compliance to standards for hardware security modules may require that the TPM test its functions
1911before the results that depend on those functions may be returned. The TPM may perform operations
1912using testable functions before those functions have been tested as long as the TPM returns no value
1913that depends on the correctness of the testable function.
1914
1915EXAMPLE 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
1922If a command is received that requires return of a value that depends on untested functions, the TPM
1923shall test the required functions before completing the command.
1924Once the TPM has received TPM2_SelfTest() and before completion of all tests, the TPM is required to
1925return TPM_RC_TESTING for any command that uses a function that requires a test.
1926If a self-test fails at any time, the TPM will enter Failure mode. While in Failure mode, the TPM will return
1927TPM_RC_FAILURE for any command other than TPM2_GetTestResult() and TPM2_GetCapability(). The
1928TPM will remain in Failure mode until the next _TPM_Init.
1929
1930
1931
1932
1933Page 30 TCG Published Family “2.0”
1934October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
1935 Trusted Platform Module Library Part 3: Commands
1936
1937
1938
193910.2 TPM2_SelfTest
1940
194110.2.1 General Description
1942
1943This command causes the TPM to perform a test of its capabilities. If the fullTest is YES, the TPM will test
1944all functions. If fullTest = NO, the TPM will only test those functions that have not previously been tested.
1945If any tests are required, the TPM shall either
1946a) 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
1950b) perform the tests and return the test result when complete.
1951If the TPM uses option a), the TPM shall return TPM_RC_TESTING for any command that requires use
1952of a testable function, even if the functions required for completion of the command have already been
1953tested.
1954
1955NOTE 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
1965Family “2.0” TCG Published Page 31
1966Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
1967 Part 3: Commands Trusted Platform Module Library
1968
1969
197010.2.2 Command and Response
1971
1972 Table 9 — TPM2_SelfTest Command
1973Type Name Description
1974
1975 TPM_ST_SESSIONS if an audit session is present;
1976TPMI_ST_COMMAND_TAG tag
1977 otherwise, TPM_ST_NO_SESSIONS
1978UINT32 commandSize
1979TPM_CC commandCode TPM_CC_SelfTest {NV}
1980
1981 YES if full test to be performed
1982TPMI_YES_NO fullTest
1983 NO if only test of untested functions required
1984
1985
1986 Table 10 — TPM2_SelfTest Response
1987Type Name Description
1988
1989TPM_ST tag see clause 6
1990UINT32 responseSize
1991TPM_RC responseCode
1992
1993
1994
1995
1996Page 32 TCG Published Family “2.0”
1997October 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
20041 #include "InternalRoutines.h"
20052 #include "SelfTest_fp.h"
20063 #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
202110
202211 // Call self test function in crypt module
202312 return CryptSelfTest(in->fullTest);
202413 }
202514 #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
203510.3 TPM2_IncrementalSelfTest
2036
203710.3.1 General Description
2038
2039This command causes the TPM to perform a test of the selected algorithms.
2040
2041NOTE 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
2048EXAMPLE 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
2053If toTest contains an algorithm that has already been tested, it will not be tested again.
2054
2055NOTE 2 The only way to force retesting of an algorithm is with TPM2_SelfTest( fullTest = YES).
2056
2057The TPM will return in toDoList a list of algorithms that are yet to be tested. This list is not the list of
2058algorithms that are scheduled to be tested but the algorithms/functions that have not been tested. Only
2059the algorithms on the toTest list are scheduled to be tested by this command.
2060
2061NOTE 3 An algorithm remains on the toDoList while any part of it remains untested.
2062
2063EXAMPLE A symmetric algorithm remains untested until it is tested with all its modes.
2064
2065Making toTest an empty list allows the determination of the algorithms that remain untested without
2066triggering any testing.
2067If toTest is not an empty list, the TPM shall return TPM_RC_SUCCESS for this command and then return
2068TPM_RC_TESTING for any subsequent command (including TPM2_IncrementalSelfTest()) until the
2069requested testing is complete.
2070
2071NOTE 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
2074NOTE 5 If none of the algorithms listed in toTest is in the toDoList, then no tests will be performed.
2075
2076NOTE 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
2079If all the parameters in this command are valid, the TPM returns TPM_RC_SUCCESS and the toDoList
2080(which may be empty).
2081
2082NOTE 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
2090Page 34 TCG Published Family “2.0”
2091October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
2092 Trusted Platform Module Library Part 3: Commands
2093
2094
2095
209610.3.2 Command and Response
2097
2098 Table 11 — TPM2_IncrementalSelfTest Command
2099Type Name Description
2100
2101 TPM_ST_SESSIONS if an audit session is present;
2102TPMI_ST_COMMAND_TAG tag
2103 otherwise, TPM_ST_NO_SESSIONS
2104UINT32 commandSize
2105TPM_CC commandCode TPM_CC_IncrementalSelfTest {NV}
2106
2107TPML_ALG toTest list of algorithms that should be tested
2108
2109
2110 Table 12 — TPM2_IncrementalSelfTest Response
2111Type Name Description
2112
2113TPM_ST tag see clause 6
2114UINT32 responseSize
2115TPM_RC responseCode
2116
2117TPML_ALG toDoList list of algorithms that need testing
2118
2119
2120
2121
2122Family “2.0” TCG Published Page 35
2123Level 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
21301 #include "InternalRoutines.h"
21312 #include "IncrementalSelfTest_fp.h"
21323 #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 {
214610 TPM_RC result;
214711 // Command Output
214812
214913 // Call incremental self test function in crypt module. If this function
215014 // returns TPM_RC_VALUE, it means that an algorithm on the 'toTest' list is
215115 // not implemented.
215216 result = CryptIncrementalSelfTest(&in->toTest, &out->toDoList);
215317 if(result == TPM_RC_VALUE)
215418 return TPM_RCS_VALUE + RC_IncrementalSelfTest_toTest;
215519 return result;
215620 }
215721 #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
216710.4 TPM2_GetTestResult
2168
216910.4.1 General Description
2170
2171This command returns manufacturer-specific information regarding the results of a self-test and an
2172indication of the test status.
2173If TPM2_SelfTest() has not been executed and a testable function has not been tested, testResult will be
2174TPM_RC_NEEDS_TEST. If TPM2_SelfTest() has been received and the tests are not complete,
2175testResult will be TPM_RC_TESTING. If testing of all functions is complete without functional failures,
2176testResult will be TPM_RC_SUCCESS. If any test failed, testResult will be TPM_RC_FAILURE.
2177This command will operate when the TPM is in Failure mode so that software can determine the test
2178status of the TPM and so that diagnostic information can be obtained for use in failure analysis. If the
2179TPM is in Failure mode, then tag is required to be TPM_ST_NO_SESSIONS or the TPM shall return
2180TPM_RC_FAILURE.
2181
2182
2183
2184
2185Family “2.0” TCG Published Page 37
2186Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
2187 Part 3: Commands Trusted Platform Module Library
2188
2189
2190
219110.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
2218Page 38 TCG Published Family “2.0”
2219October 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
22261 #include "InternalRoutines.h"
22272 #include "GetTestResult_fp.h"
22283 #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
224010
224111 // Call incremental self test function in crypt module
224212 out->testResult = CryptGetTestResult(&out->outData);
224313
224414 return TPM_RC_SUCCESS;
224515 }
224616 #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
225611 Session Commands
2257
225811.1 TPM2_StartAuthSession
2259
226011.1.1 General Description
2261
2262This command is used to start an authorization session using alternative methods of establishing the
2263session key (sessionKey). The session key is then used to derive values used for authorization and for
2264encrypting parameters.
2265This command allows injection of a secret into the TPM using either asymmetric or symmetric encryption.
2266The type of tpmKey determines how the value in encryptedSalt is encrypted. The decrypted secret value
2267is used to compute the sessionKey.
2268
2269NOTE 1 If tpmKey Is TPM_RH_NULL, then encryptedSalt is required to be an Empty Buffer.
2270
2271The label value of “SECRET” (see “Terms and Definitions” in TPM 2.0 Part 1) is used in the recovery of
2272the secret value.
2273The TPM generates the sessionKey from the recovered secret value.
2274No authorization is required for tpmKey or bind.
2275
2276NOTE 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
2281The entity referenced with the bind parameter contributes an authorization value to the sessionKey
2282generation process.
2283If both tpmKey and bind are TPM_ALG_NULL, then sessionKey is set to the Empty Buffer. If tpmKey is
2284not TPM_ALG_NULL, then encryptedSalt is used in the computation of sessionKey. If bind is not
2285TPM_ALG_NULL, the authValue of bind is used in the sessionKey computation.
2286If symmetric specifies a block cipher, then TPM_ALG_CFB is the only allowed value for the mode field in
2287the symmetric parameter (TPM_RC_MODE).
2288This command starts an authorization session and returns the session handle along with an initial
2289nonceTPM in the response.
2290If the TPM does not have a free slot for an authorization session, it shall return
2291TPM_RC_SESSION_HANDLES.
2292If the TPM implements a “gap” scheme for assigning contextID values, then the TPM shall return
2293TPM_RC_CONTEXT_GAP if creating the session would prevent recycling of old saved contexts (See
2294“Context Management” in TPM 2.0 Part 1).
2295If tpmKey is not TPM_ALG_NULL then encryptedSalt shall be a TPM2B_ENCRYPTED_SECRET of the
2296proper type for tpmKey. The TPM shall return TPM_RC_HANDLE if the sensitive portion of tpmKey is not
2297loaded. The TPM shall return TPM_RC_VALUE if:
2298a) 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
2306Page 40 TCG Published Family “2.0”
2307October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
2308 Trusted Platform Module Library Part 3: Commands
2309
2310b) 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
2318c) 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.
2320If bind references a transient object, then the TPM shall return TPM_RC_HANDLE if the sensitive portion
2321of the object is not loaded.
2322For all session types, this command will cause initialization of the sessionKey and may establish binding
2323between the session and an object (the bind object). If sessionType is TPM_SE_POLICY or
2324TPM_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.
2335Additionally, if sessionType is TPM_SE_TRIAL, the session will not be usable for authorization but can be
2336used to compute the authPolicy for an object.
2337
2338NOTE 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
2344The TPM shall return TPM_RC_SIZE if nonceCaller is less than 16 octets or is greater than the size of
2345the digest produced by authHash.
2346
2347
2348
2349
2350Family “2.0” TCG Published Page 41
2351Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
2352 Part 3: Commands Trusted Platform Module Library
2353
2354
2355
235611.1.2 Command and Response
2357
2358 Table 15 — TPM2_StartAuthSession Command
2359Type Name Description
2360
2361 TPM_ST_SESSIONS if an audit, decrypt, or encrypt
2362TPMI_ST_COMMAND_TAG tag session is present; otherwise,
2363 TPM_ST_NO_SESSIONS
2364UINT32 commandSize
2365TPM_CC commandCode TPM_CC_StartAuthSession
2366
2367 handle of a loaded decrypt key used to encrypt salt
2368TPMI_DH_OBJECT+ tpmKey may be TPM_RH_NULL
2369 Auth Index: None
2370 entity providing the authValue
2371TPMI_DH_ENTITY+ bind may be TPM_RH_NULL
2372 Auth Index: None
2373
2374 initial nonceCaller, sets nonce size for the session
2375TPM2B_NONCE nonceCaller
2376 shall be at least 16 octets
2377 value encrypted according to the type of tpmKey
2378TPM2B_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
2381TPM_SE sessionType
2382 (including a trial policy)
2383 the algorithm and key size for parameter encryption
2384TPMT_SYM_DEF+ symmetric
2385 may select TPM_ALG_NULL
2386 hash algorithm to use for the session
2387TPMI_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
2392Type Name Description
2393TPM_ST tag see clause 6
2394UINT32 responseSize
2395TPM_RC responseCode
2396
2397TPMI_SH_AUTH_SESSION sessionHandle handle for the newly created session
2398
2399 the initial nonce from the TPM, used in the computation
2400TPM2B_NONCE nonceTPM
2401 of the sessionKey
2402
2403
2404
2405
2406Page 42 TCG Published Family “2.0”
2407October 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
24141 #include "InternalRoutines.h"
24152 #include "StartAuthSession_fp.h"
24163 #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 {
244210 TPM_RC result = TPM_RC_SUCCESS;
244311 OBJECT *tpmKey; // TPM key for decrypt salt
244412 SESSION *session; // session internal data
244513 TPM2B_DATA salt;
244614
244715 // Input Validation
244816
244917 // Check input nonce size. IT should be at least 16 bytes but not larger
245018 // than the digest size of session hash.
245119 if( in->nonceCaller.t.size < 16
245220 || in->nonceCaller.t.size > CryptGetHashDigestSize(in->authHash))
245321 return TPM_RC_SIZE + RC_StartAuthSession_nonceCaller;
245422
245523 // If an decrypt key is passed in, check its validation
245624 if(in->tpmKey != TPM_RH_NULL)
245725 {
245826 // secret size cannot be 0
245927 if(in->encryptedSalt.t.size == 0)
246028 return TPM_RC_VALUE + RC_StartAuthSession_encryptedSalt;
246129
246230 // Get pointer to loaded decrypt key
246331 tpmKey = ObjectGet(in->tpmKey);
246432
246533 // Decrypting salt requires accessing the private portion of a key.
246634 // Therefore, tmpKey can not be a key with only public portion loaded
246735 if(tpmKey->attributes.publicOnly)
246836 return TPM_RC_HANDLE + RC_StartAuthSession_tpmKey;
246937
247038 // 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
247639 // tpmKey should be a decryption key
247740 if(tpmKey->publicArea.objectAttributes.decrypt != SET)
247841 return TPM_RC_ATTRIBUTES + RC_StartAuthSession_tpmKey;
247942
248043 // Secret Decryption. A TPM_RC_VALUE, TPM_RC_KEY or Unmarshal errors
248144 // may be returned at this point
248245 result = CryptSecretDecrypt(in->tpmKey, &in->nonceCaller, "SECRET",
248346 &in->encryptedSalt, &salt);
248447 if(result != TPM_RC_SUCCESS)
248548 return TPM_RC_VALUE + RC_StartAuthSession_encryptedSalt;
248649
248750 }
248851 else
248952 {
249053 // secret size must be 0
249154 if(in->encryptedSalt.t.size != 0)
249255 return TPM_RC_VALUE + RC_StartAuthSession_encryptedSalt;
249356 salt.t.size = 0;
249457 }
249558 // If the bind handle references a transient object, make sure that the
249659 // sensitive area is loaded so that the authValue can be accessed.
249760 if( HandleGetType(in->bind) == TPM_HT_TRANSIENT
249861 && ObjectGet(in->bind)->attributes.publicOnly == SET)
249962 return TPM_RC_HANDLE + RC_StartAuthSession_bind;
250063
250164 // If 'symmetric' is a symmetric block cipher (not TPM_ALG_NULL or TPM_ALG_XOR)
250265 // then the mode must be CFB.
250366 if( in->symmetric.algorithm != TPM_ALG_NULL
250467 && in->symmetric.algorithm != TPM_ALG_XOR
250568 && in->symmetric.mode.sym != TPM_ALG_CFB)
250669 return TPM_RC_MODE + RC_StartAuthSession_symmetric;
250770
250871 // Internal Data Update
250972
251073 // Create internal session structure. TPM_RC_CONTEXT_GAP, TPM_RC_NO_HANDLES
251174 // or TPM_RC_SESSION_MEMORY errors may be returned returned at this point.
251275 //
251376 // The detailed actions for creating the session context are not shown here
251477 // as the details are implementation dependent
251578 // SessionCreate sets the output handle
251679 result = SessionCreate(in->sessionType, in->authHash,
251780 &in->nonceCaller, &in->symmetric,
251881 in->bind, &salt, &out->sessionHandle);
251982
252083 if(result != TPM_RC_SUCCESS)
252184 return result;
252285
252386 // Command Output
252487
252588 // Get session pointer
252689 session = SessionGet(out->sessionHandle);
252790
252891 // Copy nonceTPM
252992 out->nonceTPM = session->nonceTPM;
253093
253194 return TPM_RC_SUCCESS;
253295 }
253396 #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
254311.2 TPM2_PolicyRestart
2544
254511.2.1 General Description
2546
2547This command allows a policy authorization session to be returned to its initial state. This command is
2548used after the TPM returns TPM_RC_PCR_CHANGED. That response code indicates that a policy will
2549fail because the PCR have changed after TPM2_PolicyPCR() was executed. Restarting the session
2550allows the authorizations to be replayed because the session restarts with the same nonceTPM. If the
2551PCR are valid for the policy, the policy may then succeed.
2552This command does not reset the policy ID or the policy start time.
2553
2554
2555
2556
2557Family “2.0” TCG Published Page 45
2558Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
2559 Part 3: Commands Trusted Platform Module Library
2560
2561
2562
256311.2.2 Command and Response
2564
2565 Table 17 — TPM2_PolicyRestart Command
2566Type Name Description
2567
2568 TPM_ST_SESSIONS if an audit session is present;
2569TPMI_ST_COMMAND_TAG tag
2570 otherwise, TPM_ST_NO_SESSIONS
2571UINT32 commandSize
2572TPM_CC commandCode TPM_CC_PolicyRestart
2573
2574TPMI_SH_POLICY sessionHandle the handle for the policy session
2575
2576
2577 Table 18 — TPM2_PolicyRestart Response
2578Type Name Description
2579
2580TPM_ST tag see clause 6
2581UINT32 responseSize
2582TPM_RC responseCode
2583
2584
2585
2586
2587Page 46 TCG Published Family “2.0”
2588October 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;
260410 BOOL wasTrialSession;
260511
260612 // Internal Data Update
260713
260814 session = SessionGet(in->sessionHandle);
260915 wasTrialSession = session->attributes.isTrialPolicy == SET;
261016
261117 // Initialize policy session
261218 SessionResetPolicyData(session);
261319
261420 session->attributes.isTrialPolicy = wasTrialSession;
261521
261622 return TPM_RC_SUCCESS;
261723 }
261824 #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
262812 Object Commands
2629
263012.1 TPM2_Create
2631
263212.1.1 General Description
2633
2634This command is used to create an object that can be loaded into a TPM using TPM2_Load(). If the
2635command completes successfully, the TPM will create the new object and return the object’s creation
2636data (creationData), its public area (outPublic), and its encrypted sensitive area (outPrivate). Preservation
2637of the returned data is the responsibility of the caller. The object will need to be loaded (TPM2_Load())
2638before it may be used.
2639TPM2B_PUBLIC template (inPublic) contains all of the fields necessary to define the properties of the
2640new 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.
2642The parentHandle parameter shall reference a loaded decryption key that has both the public and
2643sensitive area loaded.
2644When defining the object, the caller provides a template structure for the object in a TPM2B_PUBLIC
2645structure (inPublic), an initial value for the object’s authValue (inSensitive.userAuth), and, if the object is a
2646symmetric object, an optional initial data value (inSensitive.data). The TPM shall validate the consistency
2647of inPublic.attributes according to the Creation rules in “TPMA_OBJECT” in TPM 2.0 Part 2.
2648The inSensitive parameter may be encrypted using parameter encryption.
2649The methods in this clause are used by both TPM2_Create() and TPM2_CreatePrimary(). When a value
2650is indicated as being TPM-generated, the value is filled in by bits from the RNG if the command is
2651TPM2_Create() and with values from KDFa() if the command is TPM2_CreatePrimary(). The parameters
2652of each creation value are specified in TPM 2.0 Part 1.
2653The sensitiveDataOrigin attribute of inPublic shall be SET if inSensitive.data is an Empty Buffer and
2654CLEAR if inSensitive.data is not an Empty Buffer or the TPM shall return TPM_RC_ATTRIBUTES.
2655The TPM will create new data for the sensitive area and compute a TPMT_PUBLIC.unique from the
2656sensitive area based on the object type:
2657a) 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)
2671b) 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
2676Page 48 TCG Published Family “2.0”
2677October 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
2700c) 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.
2717For TPM2_Load(), the TPM will apply normal symmetric protections to the created TPMT_SENSITIVE to
2718create outPublic.
2719
2720NOTE 4 The encryption key is derived from the symmetric seed in the sensitive area of the parent.
2721
2722In addition to outPublic and outPrivate, the TPM will build a TPMS_CREATION_DATA structure for the
2723object. TPMS_CREATION_DATA.outsideInfo is set to outsideInfo. This structure is returned in
2724creationData. Additionally, the digest of this structure is returned in creationHash, and, finally, a
2725TPMT_TK_CREATION is created so that the association between the creation data and the object may
2726be validated by TPM2_CertifyCreation().
2727If the object being created is a Storage Key and inPublic.objectAttributes.fixedParent is SET, then the
2728algorithms and parameters of inPublic are required to match those of the parent. The algorithms that must
2729match are inPublic.type, inPublic.nameAlg, and inPublic.parameters. If inPublic.type does not match, the
2730TPM shall return TPM_RC_TYPE. If inPublic.nameAlg does not match, the TPM shall return
2731TPM_RC_HASH. If inPublic.parameters does not match, the TPM shall return TPM_RC_ASSYMETRIC.
2732The TPM shall not differentiate between mismatches of the components of inPublic.parameters.
2733
2734
2735Family “2.0” TCG Published Page 49
2736Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
2737 Part 3: Commands Trusted Platform Module Library
2738
2739EXAMPLE 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
2745Page 50 TCG Published Family “2.0”
2746October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
2747 Trusted Platform Module Library Part 3: Commands
2748
2749
275012.1.2 Command and Response
2751
2752 Table 19 — TPM2_Create Command
2753Type Name Description
2754
2755TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
2756UINT32 commandSize
2757TPM_CC commandCode TPM_CC_Create
2758
2759 handle of parent for new object
2760TPMI_DH_OBJECT @parentHandle Auth Index: 1
2761 Auth Role: USER
2762
2763TPM2B_SENSITIVE_CREATE inSensitive the sensitive data
2764TPM2B_PUBLIC inPublic the public template
2765 data that will be included in the creation data for this
2766TPM2B_DATA outsideInfo object to provide permanent, verifiable linkage between
2767 this object and some object owner data
2768TPML_PCR_SELECTION creationPCR PCR that will be used in creation data
2769
2770
2771 Table 20 — TPM2_Create Response
2772Type Name Description
2773
2774TPM_ST tag see clause 6
2775UINT32 responseSize
2776TPM_RC responseCode
2777
2778TPM2B_PRIVATE outPrivate the private portion of the object
2779TPM2B_PUBLIC outPublic the public portion of the created object
2780TPM2B_CREATION_DATA creationData contains a TPMS_CREATION_DATA
2781TPM2B_DIGEST creationHash digest of creationData using nameAlg of outPublic
2782 ticket used by TPM2_CertifyCreation() to validate that
2783TPMT_TK_CREATION creationTicket
2784 the creation data was produced by the TPM
2785
2786
2787
2788
2789Family “2.0” TCG Published Page 51
2790Level 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
27971 #include "InternalRoutines.h"
27982 #include "Object_spt_fp.h"
27993 #include "Create_fp.h"
28004 #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 )
284510 {
284611 TPM_RC result = TPM_RC_SUCCESS;
284712 TPMT_SENSITIVE sensitive;
284813 TPM2B_NAME name;
284914
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
285515 // Input Validation
285616
285717 OBJECT *parentObject;
285818
285919 parentObject = ObjectGet(in->parentHandle);
286020
286121 // Does parent have the proper attributes?
286222 if(!AreAttributesForParent(parentObject))
286323 return TPM_RC_TYPE + RC_Create_parentHandle;
286424
286525 // The sensitiveDataOrigin attribute must be consistent with the setting of
286626 // the size of the data object in inSensitive.
286727 if( (in->inPublic.t.publicArea.objectAttributes.sensitiveDataOrigin == SET)
286828 != (in->inSensitive.t.sensitive.data.t.size == 0))
286929 // Mismatch between the object attributes and the parameter.
287030 return TPM_RC_ATTRIBUTES + RC_Create_inSensitive;
287131
287232 // Check attributes in input public area. TPM_RC_ASYMMETRIC, TPM_RC_ATTRIBUTES,
287333 // TPM_RC_HASH, TPM_RC_KDF, TPM_RC_SCHEME, TPM_RC_SIZE, TPM_RC_SYMMETRIC,
287434 // or TPM_RC_TYPE error may be returned at this point.
287535 result = PublicAttributesValidation(FALSE, in->parentHandle,
287636 &in->inPublic.t.publicArea);
287737 if(result != TPM_RC_SUCCESS)
287838 return RcSafeAddToResult(result, RC_Create_inPublic);
287939
288040 // Validate the sensitive area values
288141 if( MemoryRemoveTrailingZeros(&in->inSensitive.t.sensitive.userAuth)
288242 > CryptGetHashDigestSize(in->inPublic.t.publicArea.nameAlg))
288343 return TPM_RC_SIZE + RC_Create_inSensitive;
288444
288545 // Command Output
288646
288747 // Create object crypto data
288848 result = CryptCreateObject(in->parentHandle, &in->inPublic.t.publicArea,
288949 &in->inSensitive.t.sensitive, &sensitive);
289050 if(result != TPM_RC_SUCCESS)
289151 return result;
289252
289353 // Fill in creation data
289454 FillInCreationData(in->parentHandle, in->inPublic.t.publicArea.nameAlg,
289555 &in->creationPCR, &in->outsideInfo,
289656 &out->creationData, &out->creationHash);
289757
289858 // Copy public area from input to output
289959 out->outPublic.t.publicArea = in->inPublic.t.publicArea;
290060
290161 // Compute name from public area
290262 ObjectComputeName(&(out->outPublic.t.publicArea), &name);
290363
290464 // Compute creation ticket
290565 TicketComputeCreation(EntityGetHierarchy(in->parentHandle), &name,
290666 &out->creationHash, &out->creationTicket);
290767
290868 // Prepare output private data from sensitive
290969 SensitiveToPrivate(&sensitive, &name, in->parentHandle,
291070 out->outPublic.t.publicArea.nameAlg,
291171 &out->outPrivate);
291272
291373 return TPM_RC_SUCCESS;
291474 }
291575 #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
292512.2 TPM2_Load
2926
292712.2.1 General Description
2928
2929This command is used to load objects into the TPM. This command is used when both a TPM2B_PUBLIC
2930and TPM2B_PRIVATE are to be loaded. If only a TPM2B_PUBLIC is to be loaded, the
2931TPM2_LoadExternal command is used.
2932
2933NOTE 1 Loading an object is not the same as restoring a saved object context.
2934
2935The 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.
2937Objects loaded using this command will have a Name. The Name is the concatenation of nameAlg and
2938the digest of the public area using the nameAlg.
2939
2940NOTE 2 nameAlg is a parameter in the public area of the inPublic structure.
2941
2942If inPrivate.size is zero, the load will fail.
2943After inPrivate.buffer is decrypted using the symmetric key of the parent, the integrity value shall be
2944checked before the sensitive area is used, or unmarshaled.
2945
2946NOTE 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
2949The command returns a handle for the loaded object and the Name that the TPM computed for
2950inPublic.public (that is, the digest of the TPMT_PUBLIC structure in inPublic).
2951
2952NOTE 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
2955NOTE 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
2958For all objects, the size of the key in the sensitive area shall be consistent with the key size indicated in
2959the public area or the TPM shall return TPM_RC_KEY_SIZE.
2960Before use, a loaded object shall be checked to validate that the public and sensitive portions are
2961properly linked, cryptographically. Use of an object includes use in any policy command. If the parts of the
2962object are not properly linked, the TPM shall return TPM_RC_BINDING.
2963
2964EXAMPLE 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
2967EXAMPLE 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
2971EXAMPLE 3 For an ECC key, the public point shall be f(x) where x is the private key.
2972
2973
2974
2975
2976Page 54 TCG Published Family “2.0”
2977October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
2978 Trusted Platform Module Library Part 3: Commands
2979
2980
298112.2.2 Command and Response
2982
2983 Table 21 — TPM2_Load Command
2984Type Name Description
2985
2986TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
2987UINT32 commandSize
2988TPM_CC commandCode TPM_CC_Load
2989
2990 TPM handle of parent key; shall not be a reserved
2991 handle
2992TPMI_DH_OBJECT @parentHandle
2993 Auth Index: 1
2994 Auth Role: USER
2995
2996TPM2B_PRIVATE inPrivate the private portion of the object
2997TPM2B_PUBLIC inPublic the public portion of the object
2998
2999
3000 Table 22 — TPM2_Load Response
3001Type Name Description
3002
3003TPM_ST tag see clause 6
3004UINT32 responseSize
3005TPM_RC responseCode
3006
3007 handle of type TPM_HT_TRANSIENT for the loaded
3008TPM_HANDLE objectHandle
3009 object
3010
3011TPM2B_NAME name Name of the loaded object
3012
3013
3014
3015
3016Family “2.0” TCG Published Page 55
3017Level 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
30241 #include "InternalRoutines.h"
30252 #include "Load_fp.h"
30263 #ifdef TPM_CC_Load // Conditional expansion of this file
30274 #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 )
305410 {
305511 TPM_RC result = TPM_RC_SUCCESS;
305612 TPMT_SENSITIVE sensitive;
305713 TPMI_RH_HIERARCHY hierarchy;
305814 OBJECT *parentObject = NULL;
305915 BOOL skipChecks = FALSE;
306016
306117 // Input Validation
306218 if(in->inPrivate.t.size == 0)
306319 return TPM_RC_SIZE + RC_Load_inPrivate;
306420
306521 parentObject = ObjectGet(in->parentHandle);
306622 // Is the object that is being used as the parent actually a parent.
306723 if(!AreAttributesForParent(parentObject))
306824 return TPM_RC_TYPE + RC_Load_parentHandle;
306925
307026 // If the parent is fixedTPM, then the attributes of the object
307127 // are either "correct by construction" or were validated
307228 // when the object was imported. If they pass the integrity
307329 // check, then the values are valid
307430 if(parentObject->publicArea.objectAttributes.fixedTPM)
307531 skipChecks = TRUE;
307632 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
308233 {
308334 // If parent doesn't have fixedTPM SET, then this can't have
308435 // fixedTPM SET.
308536 if(in->inPublic.t.publicArea.objectAttributes.fixedTPM == SET)
308637 return TPM_RC_ATTRIBUTES + RC_Load_inPublic;
308738
308839 // Perform self check on input public area. A TPM_RC_SIZE, TPM_RC_SCHEME,
308940 // TPM_RC_VALUE, TPM_RC_SYMMETRIC, TPM_RC_TYPE, TPM_RC_HASH,
309041 // TPM_RC_ASYMMETRIC, TPM_RC_ATTRIBUTES or TPM_RC_KDF error may be returned
309142 // at this point
309243 result = PublicAttributesValidation(TRUE, in->parentHandle,
309344 &in->inPublic.t.publicArea);
309445 if(result != TPM_RC_SUCCESS)
309546 return RcSafeAddToResult(result, RC_Load_inPublic);
309647 }
309748
309849 // Compute the name of object
309950 ObjectComputeName(&in->inPublic.t.publicArea, &out->name);
310051
310152 // Retrieve sensitive data. PrivateToSensitive() may return TPM_RC_INTEGRITY or
310253 // TPM_RC_SENSITIVE
310354 // errors may be returned at this point
310455 result = PrivateToSensitive(&in->inPrivate, &out->name, in->parentHandle,
310556 in->inPublic.t.publicArea.nameAlg,
310657 &sensitive);
310758 if(result != TPM_RC_SUCCESS)
310859 return RcSafeAddToResult(result, RC_Load_inPrivate);
310960
311061 // Internal Data Update
311162
311263 // Get hierarchy of parent
311364 hierarchy = ObjectGetHierarchy(in->parentHandle);
311465
311566 // Create internal object. A lot of different errors may be returned by this
311667 // loading operation as it will do several validations, including the public
311768 // binding check
311869 result = ObjectLoad(hierarchy, &in->inPublic.t.publicArea, &sensitive,
311970 &out->name, in->parentHandle, skipChecks,
312071 &out->objectHandle);
312172
312273 if(result != TPM_RC_SUCCESS)
312374 return result;
312475
312576 return TPM_RC_SUCCESS;
312677 }
312778 #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
313712.3 TPM2_LoadExternal
3138
313912.3.1 General Description
3140
3141This command is used to load an object that is not a Protected Object into the TPM. The command allows
3142loading of a public area or both a public and sensitive area.
3143
3144NOTE 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
3148Load of a public external object area allows the object be associated with a hierarchy so that the correct
3149algorithms may be used when creating tickets. The hierarchy parameter provides this association. If the
3150public and sensitive portions of the object are loaded, hierarchy is required to be TPM_RH_NULL.
3151
3152NOTE 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
3155The 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
3157if inPrivate is not the Empty Buffer.
3158
3159NOTE 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
3164Objects loaded using this command will have a Name. The Name is the nameAlg of the object
3165concatenated with the digest of the public area using the nameAlg. The Qualified Name for the object will
3166be the same as its Name. The TPM will validate that the authPolicy is either the size of the digest
3167produced by nameAlg or the Empty Buffer.
3168
3169NOTE 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
3173NOTE 5 The digest size for TPM_ALG_NULL is zero.
3174
3175If the nameAlg is TPM_ALG_NULL, the TPM shall not verify the cryptographic binding between the public
3176and sensitive areas, but the TPM will validate that the size of the key in the sensitive area is consistent
3177with the size indicated in the public area. If it is not, the TPM shall return TPM_RC_KEY_SIZE.
3178
3179NOTE 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
3182If nameAlg is not TPM_ALG_NULL, then the same consistency checks between inPublic and inPrivate
3183are made as for TPM2_Load().
3184
3185NOTE 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
3188The command returns a handle for the loaded object and the Name that the TPM computed for
3189inPublic.public (that is, the TPMT_PUBLIC structure in inPublic).
3190
3191NOTE 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
3197Page 58 TCG Published Family “2.0”
3198October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
3199 Trusted Platform Module Library Part 3: Commands
3200
3201The hierarchy parameter associates the external object with a hierarchy. External objects are flushed
3202when their associated hierarchy is disabled. If hierarchy is TPM_RH_NULL, the object is part of no
3203hierarchy, and there is no implicit flush.
3204If hierarchy is TPM_RH_NULL or nameAlg is TPM_ALG_NULL, a ticket produced using the object shall
3205be a NULL Ticket.
3206
3207EXAMPLE 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
3210External objects are Temporary Objects. The saved external object contexts shall be invalidated at the
3211next TPM Reset.
3212
3213
3214
3215
3216Family “2.0” TCG Published Page 59
3217Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
3218 Part 3: Commands Trusted Platform Module Library
3219
3220
3221
322212.3.2 Command and Response
3223
3224 Table 23 — TPM2_LoadExternal Command
3225Type Name Description
3226
3227 TPM_ST_SESSIONS if an audit, encrypt, or derypt
3228TPMI_ST_COMMAND_TAG tag session is present; otherwise,
3229 TPM_ST_NO_SESSIONS
3230UINT32 commandSize
3231TPM_CC commandCode TPM_CC_LoadExternal
3232
3233TPM2B_SENSITIVE inPrivate the sensitive portion of the object (optional)
3234TPM2B_PUBLIC+ inPublic the public portion of the object
3235TPMI_RH_HIERARCHY+ hierarchy hierarchy with which the object area is associated
3236
3237
3238 Table 24 — TPM2_LoadExternal Response
3239Type Name Description
3240
3241TPM_ST tag see clause 6
3242UINT32 responseSize
3243TPM_RC responseCode
3244
3245 handle of type TPM_HT_TRANSIENT for the loaded
3246TPM_HANDLE objectHandle
3247 object
3248
3249TPM2B_NAME name name of the loaded object
3250
3251
3252
3253
3254Page 60 TCG Published Family “2.0”
3255October 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
32621 #include "InternalRoutines.h"
32632 #include "LoadExternal_fp.h"
32643 #ifdef TPM_CC_LoadExternal // Conditional expansion of this file
32654 #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 )
329110 {
329211 TPM_RC result;
329312 TPMT_SENSITIVE *sensitive;
329413 BOOL skipChecks;
329514
329615 // Input Validation
329716
329817 // If the target hierarchy is turned off, the object can not be loaded.
329918 if(!HierarchyIsEnabled(in->hierarchy))
330019 return TPM_RC_HIERARCHY + RC_LoadExternal_hierarchy;
330120
330221 // the size of authPolicy is either 0 or the digest size of nameAlg
330322 if(in->inPublic.t.publicArea.authPolicy.t.size != 0
330423 && in->inPublic.t.publicArea.authPolicy.t.size !=
330524 CryptGetHashDigestSize(in->inPublic.t.publicArea.nameAlg))
330625 return TPM_RC_SIZE + RC_LoadExternal_inPublic;
330726
330827 // For loading an object with both public and sensitive
330928 if(in->inPrivate.t.size != 0)
331029 {
331130 // An external object can only be loaded at TPM_RH_NULL hierarchy
331231 if(in->hierarchy != TPM_RH_NULL)
331332 return TPM_RC_HIERARCHY + RC_LoadExternal_hierarchy;
331433 // An external object with a sensitive area must have fixedTPM == CLEAR
331534 // fixedParent == CLEAR, and must have restrict CLEAR so that it does not
331635 // 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
332236 if( in->inPublic.t.publicArea.objectAttributes.fixedTPM != CLEAR
332337 || in->inPublic.t.publicArea.objectAttributes.fixedParent != CLEAR
332438 || in->inPublic.t.publicArea.objectAttributes.restricted != CLEAR
332539 )
332640 return TPM_RC_ATTRIBUTES + RC_LoadExternal_inPublic;
332741 }
332842
332943 // Validate the scheme parameters
333044 result = SchemeChecks(TRUE, TPM_RH_NULL, &in->inPublic.t.publicArea);
333145 if(result != TPM_RC_SUCCESS)
333246 return RcSafeAddToResult(result, RC_LoadExternal_inPublic);
333347
333448 // Internal Data Update
333549 // Need the name to compute the qualified name
333650 ObjectComputeName(&in->inPublic.t.publicArea, &out->name);
333751 skipChecks = (in->inPublic.t.publicArea.nameAlg == TPM_ALG_NULL);
333852
333953 // If a sensitive area was provided, load it
334054 if(in->inPrivate.t.size != 0)
334155 sensitive = &in->inPrivate.t.sensitiveArea;
334256 else
334357 sensitive = NULL;
334458
334559 // Create external object. A TPM_RC_BINDING, TPM_RC_KEY, TPM_RC_OBJECT_MEMORY
334660 // or TPM_RC_TYPE error may be returned by ObjectLoad()
334761 result = ObjectLoad(in->hierarchy, &in->inPublic.t.publicArea,
334862 sensitive, &out->name, TPM_RH_NULL, skipChecks,
334963 &out->objectHandle);
335064 return result;
335165 }
335266 #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
336212.4 TPM2_ReadPublic
3363
336412.4.1 General Description
3365
3366This command allows access to the public area of a loaded object.
3367Use of the objectHandle does not require authorization.
3368
3369NOTE 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
3372If objectHandle references a sequence object, the TPM shall return TPM_RC_SEQUENCE.
3373
3374
3375
3376
3377Family “2.0” TCG Published Page 63
3378Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
3379 Part 3: Commands Trusted Platform Module Library
3380
3381
3382
338312.4.2 Command and Response
3384
3385 Table 25 — TPM2_ReadPublic Command
3386Type Name Description
3387
3388 TPM_ST_SESSIONS if an audit or encrypt session is
3389TPMI_ST_COMMAND_TAG tag
3390 present; otherwise, TPM_ST_NO_SESSIONS
3391UINT32 commandSize
3392TPM_CC commandCode TPM_CC_ReadPublic
3393
3394 TPM handle of an object
3395TPMI_DH_OBJECT objectHandle
3396 Auth Index: None
3397
3398
3399 Table 26 — TPM2_ReadPublic Response
3400Type Name Description
3401
3402TPM_ST tag see clause 6
3403UINT32 responseSize
3404TPM_RC responseCode
3405
3406TPM2B_PUBLIC outPublic structure containing the public area of an object
3407TPM2B_NAME name name of the object
3408TPM2B_NAME qualifiedName the Qualified Name of the object
3409
3410
3411
3412
3413Page 64 TCG Published Family “2.0”
3414October 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
34211 #include "InternalRoutines.h"
34222 #include "ReadPublic_fp.h"
34233 #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 {
343610 OBJECT *object;
343711
343812 // Input Validation
343913
344014 // Get loaded object pointer
344115 object = ObjectGet(in->objectHandle);
344216
344317 // Can not read public area of a sequence object
344418 if(ObjectIsSequence(object))
344519 return TPM_RC_SEQUENCE;
344620
344721 // Command Output
344822
344923 // Compute size of public area in canonical form
345024 out->outPublic.t.size = TPMT_PUBLIC_Marshal(&object->publicArea, NULL, NULL);
345125
345226 // Copy public area to output
345327 out->outPublic.t.publicArea = object->publicArea;
345428
345529 // Copy name to output
345630 out->name.t.size = ObjectGetName(in->objectHandle, &out->name.t.name);
345731
345832 // Copy qualified name to output
345933 ObjectGetQualifiedName(in->objectHandle, &out->qualifiedName);
346034
346135 return TPM_RC_SUCCESS;
346236 }
346337 #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
347312.5 TPM2_ActivateCredential
3474
347512.5.1 General Description
3476
3477This command enables the association of a credential with an object in a way that ensures that the TPM
3478has validated the parameters of the credentialed object.
3479If both the public and private portions of activateHandle and keyHandle are not loaded, then the TPM
3480shall return TPM_RC_AUTH_UNAVAILABLE.
3481If keyHandle is not a Storage Key, then the TPM shall return TPM_RC_TYPE.
3482Authorization for activateHandle requires the ADMIN role.
3483The key associated with keyHandle is used to recover a seed from secret, which is the encrypted seed.
3484The Name of the object associated with activateHandle and the recovered seed are used in a KDF to
3485recover the symmetric key. The recovered seed (but not the Name) is used in a KDF to recover the
3486HMAC key.
3487The HMAC is used to validate that the credentialBlob is associated with activateHandle and that the data
3488in credentialBlob has not been modified. The linkage to the object associated with activateHandle is
3489achieved by including the Name in the HMAC calculation.
3490If the integrity checks succeed, credentialBlob is decrypted and returned as certInfo.
3491
3492
3493
3494
3495Page 66 TCG Published Family “2.0”
3496October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
3497 Trusted Platform Module Library Part 3: Commands
3498
3499
3500
350112.5.2 Command and Response
3502
3503 Table 27 — TPM2_ActivateCredential Command
3504Type Name Description
3505
3506TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
3507UINT32 commandSize
3508TPM_CC commandCode TPM_CC_ActivateCredential
3509
3510 handle of the object associated with certificate in
3511 credentialBlob
3512TPMI_DH_OBJECT @activateHandle
3513 Auth Index: 1
3514 Auth Role: ADMIN
3515 loaded key used to decrypt the TPMS_SENSITIVE in
3516 credentialBlob
3517TPMI_DH_OBJECT @keyHandle
3518 Auth Index: 2
3519 Auth Role: USER
3520
3521TPM2B_ID_OBJECT credentialBlob the credential
3522 keyHandle algorithm-dependent encrypted seed that
3523TPM2B_ENCRYPTED_SECRET secret
3524 protects credentialBlob
3525
3526
3527 Table 28 — TPM2_ActivateCredential Response
3528Type Name Description
3529
3530TPM_ST tag see clause 6
3531UINT32 responseSize
3532TPM_RC responseCode
3533
3534 the decrypted certificate information
3535TPM2B_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
3541Family “2.0” TCG Published Page 67
3542Level 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
35491 #include "InternalRoutines.h"
35502 #include "ActivateCredential_fp.h"
35513 #ifdef TPM_CC_ActivateCredential // Conditional expansion of this file
35524 #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 )
357210 {
357311 TPM_RC result = TPM_RC_SUCCESS;
357412 OBJECT *object; // decrypt key
357513 OBJECT *activateObject;// key associated with
357614 // credential
357715 TPM2B_DATA data; // credential data
357816
357917 // Input Validation
358018
358119 // Get decrypt key pointer
358220 object = ObjectGet(in->keyHandle);
358321
358422 // Get certificated object pointer
358523 activateObject = ObjectGet(in->activateHandle);
358624
358725 // input decrypt key must be an asymmetric, restricted decryption key
358826 if( !CryptIsAsymAlgorithm(object->publicArea.type)
358927 || object->publicArea.objectAttributes.decrypt == CLEAR
359028 || object->publicArea.objectAttributes.restricted == CLEAR)
359129 return TPM_RC_TYPE + RC_ActivateCredential_keyHandle;
359230
359331 // Command output
359432
359533 // Decrypt input credential data via asymmetric decryption. A
359634 // TPM_RC_VALUE, TPM_RC_KEY or unmarshal errors may be returned at this
359735 // point
359836 result = CryptSecretDecrypt(in->keyHandle, NULL,
359937 "IDENTITY", &in->secret, &data);
360038 if(result != TPM_RC_SUCCESS)
360139 {
360240 if(result == TPM_RC_KEY)
360341 return TPM_RC_FAILURE;
360442 return RcSafeAddToResult(result, RC_ActivateCredential_secret);
360543 }
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
361144
361245 // Retrieve secret data. A TPM_RC_INTEGRITY error or unmarshal
361346 // errors may be returned at this point
361447 result = CredentialToSecret(&in->credentialBlob,
361548 &activateObject->name,
361649 (TPM2B_SEED *) &data,
361750 in->keyHandle,
361851 &out->certInfo);
361952 if(result != TPM_RC_SUCCESS)
362053 return RcSafeAddToResult(result,RC_ActivateCredential_credentialBlob);
362154
362255 return TPM_RC_SUCCESS;
362356 }
362457 #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
363412.6 TPM2_MakeCredential
3635
363612.6.1 General Description
3637
3638This command allows the TPM to perform the actions required of a Certificate Authority (CA) in creating a
3639TPM2B_ID_OBJECT containing an activation credential.
3640The TPM will produce a TPM_ID_OBJECT according to the methods in “Credential Protection” in TPM
36412.0 Part 1.
3642The loaded public area referenced by handle is required to be the public area of a Storage key,
3643otherwise, the credential cannot be properly sealed.
3644This command does not use any TPM secrets nor does it require authorization. It is a convenience
3645function, using the TPM to perform cryptographic calculations that could be done externally.
3646
3647
3648
3649
3650Page 70 TCG Published Family “2.0”
3651October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
3652 Trusted Platform Module Library Part 3: Commands
3653
3654
3655
365612.6.2 Command and Response
3657
3658 Table 29 — TPM2_MakeCredential Command
3659Type Name Description
3660
3661 TPM_ST_SESSIONS if an audit, encrypt, or decrypt
3662TPMI_ST_COMMAND_TAG tag session is present; otherwise,
3663 TPM_ST_NO_SESSIONS
3664UINT32 commandSize
3665TPM_CC commandCode TPM_CC_MakeCredential
3666
3667 loaded public area, used to encrypt the sensitive area
3668TPMI_DH_OBJECT handle containing the credential key
3669 Auth Index: None
3670
3671TPM2B_DIGEST credential the credential information
3672TPM2B_NAME objectName Name of the object to which the credential applies
3673
3674
3675 Table 30 — TPM2_MakeCredential Response
3676Type Name Description
3677
3678TPM_ST tag see clause 6
3679UINT32 responseSize
3680TPM_RC responseCode
3681
3682TPM2B_ID_OBJECT credentialBlob the credential
3683 handle algorithm-dependent data that wraps the key
3684TPM2B_ENCRYPTED_SECRET secret
3685 that encrypts credentialBlob
3686
3687
3688
3689
3690Family “2.0” TCG Published Page 71
3691Level 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
36981 #include "InternalRoutines.h"
36992 #include "MakeCredential_fp.h"
37003 #ifdef TPM_CC_MakeCredential // Conditional expansion of this file
37014 #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 )
371610 {
371711 TPM_RC result = TPM_RC_SUCCESS;
371812
371913 OBJECT *object;
372014 TPM2B_DATA data;
372115
372216 // Input Validation
372317
372418 // Get object pointer
372519 object = ObjectGet(in->handle);
372620
372721 // input key must be an asymmetric, restricted decryption key
372822 // NOTE: Needs to be restricted to have a symmetric value.
372923 if( !CryptIsAsymAlgorithm(object->publicArea.type)
373024 || object->publicArea.objectAttributes.decrypt == CLEAR
373125 || object->publicArea.objectAttributes.restricted == CLEAR
373226 )
373327 return TPM_RC_TYPE + RC_MakeCredential_handle;
373428
373529 // The credential information may not be larger than the digest size used for
373630 // the Name of the key associated with handle.
373731 if(in->credential.t.size > CryptGetHashDigestSize(object->publicArea.nameAlg))
373832 return TPM_RC_SIZE + RC_MakeCredential_credential;
373933
374034 // Command Output
374135
374236 // Make encrypt key and its associated secret structure.
374337 // Even though CrypeSecretEncrypt() may return
374438 out->secret.t.size = sizeof(out->secret.t.secret);
374539 result = CryptSecretEncrypt(in->handle, "IDENTITY", &data, &out->secret);
374640 if(result != TPM_RC_SUCCESS)
374741 return result;
374842
374943 // Prepare output credential data from secret
375044 SecretToCredential(&in->credential, &in->objectName, (TPM2B_SEED *) &data,
375145 in->handle, &out->credentialBlob);
375246
375347 return TPM_RC_SUCCESS;
375448 }
375549 #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
376512.7 TPM2_Unseal
3766
376712.7.1 General Description
3768
3769This command returns the data in a loaded Sealed Data Object.
3770
3771NOTE 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
3774The returned value may be encrypted using authorization session encryption.
3775If either restricted, decrypt, or sign is SET in the attributes of itemHandle, then the TPM shall return
3776TPM_RC_ATTRIBUTES. If the type of itemHandle is not TPM_ALG_KEYEDHASH, then the TPM shall
3777return TPM_RC_TYPE.
3778
3779
3780
3781
3782Family “2.0” TCG Published Page 73
3783Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
3784 Part 3: Commands Trusted Platform Module Library
3785
3786
3787
378812.7.2 Command and Response
3789
3790 Table 31 — TPM2_Unseal Command
3791Type Name Description
3792
3793TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
3794UINT32 commandSize
3795TPM_CC commandCode TPM_CC_Unseal
3796
3797 handle of a loaded data object
3798TPMI_DH_OBJECT @itemHandle Auth Index: 1
3799 Auth Role: USER
3800
3801
3802 Table 32 — TPM2_Unseal Response
3803Type Name Description
3804
3805TPM_ST tag see clause 6
3806UINT32 responseSize
3807TPM_RC responseCode
3808
3809 unsealed data
3810TPM2B_SENSITIVE_DATA outData
3811 Size of outData is limited to be no more than 128 octets.
3812
3813
3814
3815
3816Page 74 TCG Published Family “2.0”
3817October 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
38241 #include "InternalRoutines.h"
38252 #include "Unseal_fp.h"
38263 #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 {
384010 OBJECT *object;
384111
384212 // Input Validation
384313
384414 // Get pointer to loaded object
384515 object = ObjectGet(in->itemHandle);
384616
384717 // Input handle must be a data object
384818 if(object->publicArea.type != TPM_ALG_KEYEDHASH)
384919 return TPM_RC_TYPE + RC_Unseal_itemHandle;
385020 if( object->publicArea.objectAttributes.decrypt == SET
385121 || object->publicArea.objectAttributes.sign == SET
385222 || object->publicArea.objectAttributes.restricted == SET)
385323 return TPM_RC_ATTRIBUTES + RC_Unseal_itemHandle;
385424
385525 // Command Output
385626
385727 // Copy data
385828 MemoryCopy2B(&out->outData.b, &object->sensitive.sensitive.bits.b,
385929 sizeof(out->outData.t.buffer));
386030
386131 return TPM_RC_SUCCESS;
386232 }
386333 #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
387312.8 TPM2_ObjectChangeAuth
3874
387512.8.1 General Description
3876
3877This command is used to change the authorization secret for a TPM-resident object.
3878If successful, a new private area for the TPM-resident object associated with objectHandle is returned,
3879which includes the new authorization value.
3880This command does not change the authorization of the TPM-resident object on which it operates.
3881Therefore, the old authValue (of the TPM-resident object) is used when generating the response HMAC
3882key if required.
3883
3884NOTE 1 The returned outPrivate will need to be loaded before the new authorization will apply.
3885
3886NOTE 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
3890EXAMPLE 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
3894This command may not be used to change the authorization value for an NV Index or a Primary Object.
3895
3896NOTE 3 If an NV Index is to have a new authorization, it is done with TPM2_NV_ChangeAuth().
3897
3898NOTE 4 If a Primary Object is to have a new authorization, it needs to be recreated (TPM2_CreatePrimary()).
3899
3900
3901
3902
3903Page 76 TCG Published Family “2.0”
3904October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
3905 Trusted Platform Module Library Part 3: Commands
3906
3907
390812.8.2 Command and Response
3909
3910 Table 33 — TPM2_ObjectChangeAuth Command
3911Type Name Description
3912
3913TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
3914UINT32 commandSize
3915TPM_CC commandCode TPM_CC_ObjectChangeAuth
3916
3917 handle of the object
3918TPMI_DH_OBJECT @objectHandle Auth Index: 1
3919 Auth Role: ADMIN
3920 handle of the parent
3921TPMI_DH_OBJECT parentHandle
3922 Auth Index: None
3923
3924TPM2B_AUTH newAuth new authorization value
3925
3926
3927 Table 34 — TPM2_ObjectChangeAuth Response
3928Type Name Description
3929
3930TPM_ST tag see clause 6
3931UINT32 responseSize
3932TPM_RC responseCode
3933
3934TPM2B_PRIVATE outPrivate private area containing the new authorization value
3935
3936
3937
3938
3939Family “2.0” TCG Published Page 77
3940Level 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
39471 #include "InternalRoutines.h"
39482 #include "ObjectChangeAuth_fp.h"
39493 #ifdef TPM_CC_ObjectChangeAuth // Conditional expansion of this file
39504 #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 )
396510 {
396611 TPMT_SENSITIVE sensitive;
396712
396813 OBJECT *object;
396914 TPM2B_NAME objectQN, QNCompare;
397015 TPM2B_NAME parentQN;
397116
397217 // Input Validation
397318
397419 // Get object pointer
397520 object = ObjectGet(in->objectHandle);
397621
397722 // Can not change auth on sequence object
397823 if(ObjectIsSequence(object))
397924 return TPM_RC_TYPE + RC_ObjectChangeAuth_objectHandle;
398025
398126 // Make sure that the auth value is consistent with the nameAlg
398227 if( MemoryRemoveTrailingZeros(&in->newAuth)
398328 > CryptGetHashDigestSize(object->publicArea.nameAlg))
398429 return TPM_RC_SIZE + RC_ObjectChangeAuth_newAuth;
398530
398631 // Check parent for object
398732 // parent handle must be the parent of object handle. In this
398833 // implementation we verify this by checking the QN of object. Other
398934 // implementation may choose different method to verify this attribute.
399035 ObjectGetQualifiedName(in->parentHandle, &parentQN);
399136 ObjectComputeQualifiedName(&parentQN, object->publicArea.nameAlg,
399237 &object->name, &QNCompare);
399338
399439 ObjectGetQualifiedName(in->objectHandle, &objectQN);
399540 if(!Memory2BEqual(&objectQN.b, &QNCompare.b))
399641 return TPM_RC_TYPE + RC_ObjectChangeAuth_parentHandle;
399742
399843 // Command Output
399944
400045 // Copy internal sensitive area
400146 sensitive = object->sensitive;
400247 // Copy authValue
400348 sensitive.authValue = in->newAuth;
400449
400550 // Prepare output private data from sensitive
400651 SensitiveToPrivate(&sensitive, &object->name, in->parentHandle,
400752 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
401353 &out->outPrivate);
401454
401555 return TPM_RC_SUCCESS;
401656 }
401757 #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
402713 Duplication Commands
4028
402913.1 TPM2_Duplicate
4030
403113.1.1 General Description
4032
4033This command duplicates a loaded object so that it may be used in a different hierarchy. The new parent
4034key for the duplicate may be on the same or different TPM or TPM_RH_NULL. Only the public area of
4035newParentHandle is required to be loaded.
4036
4037NOTE 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
4040If encryptedDuplication is SET in the object being duplicated, then the TPM shall return
4041TPM_RC_SYMMETRIC if symmetricAlg is TPM_RH_NULL or TPM_RC_HIERARCHY if
4042newParentHandle is TPM_RH_NULL.
4043The authorization for this command shall be with a policy session.
4044If fixedParent of objectHandle→attributes is SET, the TPM shall return TPM_RC_ATTRIBUTES. If
4045objectHandle→nameAlg is TPM_ALG_NULL, the TPM shall return TPM_RC_TYPE.
4046The policySession→commandCode parameter in the policy session is required to be TPM_CC_Duplicate
4047to indicate that authorization for duplication has been provided. This indicates that the policy that is being
4048used is a policy that is for duplication, and not a policy that would approve another use. That is, authority
4049to use an object does not grant authority to duplicate the object.
4050The policy is likely to include cpHash in order to restrict where duplication can occur. If
4051TPM2_PolicyCpHash() has been executed as part of the policy, the policySession→cpHash is compared
4052to the cpHash of the command.
4053If TPM2_PolicyDuplicationSelect() has been executed as part of the policy, the
4054policySession→nameHash is compared to
4055 HpolicyAlg(objectHandle→Name || newParentHandle→Name) (2)
4056If the compared hashes are not the same, then the TPM shall return TPM_RC_POLICY_FAIL.
4057
4058NOTE 2 It is allowed that policySesion→nameHash and policySession→cpHash share the same memory
4059 space.
4060
4061NOTE 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
4065The TPM shall follow the process of encryption defined in the “Duplication” subclause of “Protected
4066Storage Hierarchy” in TPM 2.0 Part 1.
4067
4068
4069
4070
4071Page 80 TCG Published Family “2.0”
4072October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
4073 Trusted Platform Module Library Part 3: Commands
4074
4075
4076
407713.1.2 Command and Response
4078
4079 Table 35 — TPM2_Duplicate Command
4080Type Name Description
4081
4082TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
4083UINT32 commandSize
4084TPM_CC commandCode TPM_CC_Duplicate
4085
4086 loaded object to duplicate
4087TPMI_DH_OBJECT @objectHandle Auth Index: 1
4088 Auth Role: DUP
4089 shall reference the public area of an asymmetric key
4090TPMI_DH_OBJECT+ newParentHandle
4091 Auth Index: None
4092
4093 optional symmetric encryption key
4094TPM2B_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
4097TPMT_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
4102Type Name Description
4103
4104TPM_ST tag see clause 6
4105UINT32 responseSize
4106TPM_RC responseCode
4107
4108 If the caller provided an encryption key or if
4109 symmetricAlg was TPM_ALG_NULL, then this will be
4110TPM2B_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;
4114TPM2B_PRIVATE duplicate
4115 and may be doubly encrypted
4116 seed protected by the asymmetric algorithms of new
4117TPM2B_ENCRYPTED_SECRET outSymSeed
4118 parent (NP)
4119
4120
4121
4122
4123Family “2.0” TCG Published Page 81
4124Level 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
41311 #include "InternalRoutines.h"
41322 #include "Duplicate_fp.h"
41333 #ifdef TPM_CC_Duplicate // Conditional expansion of this file
41344 #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 )
415510 {
415611 TPM_RC result = TPM_RC_SUCCESS;
415712 TPMT_SENSITIVE sensitive;
415813
415914 UINT16 innerKeySize = 0; // encrypt key size for inner wrap
416015
416116 OBJECT *object;
416217 TPM2B_DATA data;
416318
416419 // Input Validation
416520
416621 // Get duplicate object pointer
416722 object = ObjectGet(in->objectHandle);
416823
416924 // duplicate key must have fixParent bit CLEAR.
417025 if(object->publicArea.objectAttributes.fixedParent == SET)
417126 return TPM_RC_ATTRIBUTES + RC_Duplicate_objectHandle;
417227
417328 // Do not duplicate object with NULL nameAlg
417429 if(object->publicArea.nameAlg == TPM_ALG_NULL)
417530 return TPM_RC_TYPE + RC_Duplicate_objectHandle;
417631
417732 // new parent key must be a storage object or TPM_RH_NULL
417833 if(in->newParentHandle != TPM_RH_NULL
417934 && !ObjectIsStorage(in->newParentHandle))
418035 return TPM_RC_TYPE + RC_Duplicate_newParentHandle;
418136
418237 // If the duplicates object has encryptedDuplication SET, then there must be
418338 // an inner wrapper and the new parent may not be TPM_RH_NULL
418439 if(object->publicArea.objectAttributes.encryptedDuplication == SET)
418540 {
418641 if(in->symmetricAlg.algorithm == TPM_ALG_NULL)
418742 return TPM_RC_SYMMETRIC + RC_Duplicate_symmetricAlg;
418843 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
419444 return TPM_RC_HIERARCHY + RC_Duplicate_newParentHandle;
419545 }
419646
419747 if(in->symmetricAlg.algorithm == TPM_ALG_NULL)
419848 {
419949 // if algorithm is TPM_ALG_NULL, input key size must be 0
420050 if(in->encryptionKeyIn.t.size != 0)
420151 return TPM_RC_SIZE + RC_Duplicate_encryptionKeyIn;
420252 }
420353 else
420454 {
420555 // Get inner wrap key size
420656 innerKeySize = in->symmetricAlg.keyBits.sym;
420757
420858 // If provided the input symmetric key must match the size of the algorithm
420959 if(in->encryptionKeyIn.t.size != 0
421060 && in->encryptionKeyIn.t.size != (innerKeySize + 7) / 8)
421161 return TPM_RC_SIZE + RC_Duplicate_encryptionKeyIn;
421262 }
421363
421464 // Command Output
421565
421666 if(in->newParentHandle != TPM_RH_NULL)
421767 {
421868
421969 // Make encrypt key and its associated secret structure. A TPM_RC_KEY
422070 // error may be returned at this point
422171 out->outSymSeed.t.size = sizeof(out->outSymSeed.t.secret);
422272 result = CryptSecretEncrypt(in->newParentHandle,
422373 "DUPLICATE", &data, &out->outSymSeed);
422474 pAssert(result != TPM_RC_VALUE);
422575 if(result != TPM_RC_SUCCESS)
422676 return result;
422777 }
422878 else
422979 {
423080 // Do not apply outer wrapper
423181 data.t.size = 0;
423282 out->outSymSeed.t.size = 0;
423383 }
423484
423585 // Copy sensitive area
423686 sensitive = object->sensitive;
423787
423888 // Prepare output private data from sensitive
423989 SensitiveToDuplicate(&sensitive, &object->name, in->newParentHandle,
424090 object->publicArea.nameAlg, (TPM2B_SEED *) &data,
424191 &in->symmetricAlg, &in->encryptionKeyIn,
424292 &out->duplicate);
424393
424494 out->encryptionKeyOut = in->encryptionKeyIn;
424595
424696 return TPM_RC_SUCCESS;
424797 }
424898 #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
425813.2 TPM2_Rewrap
4259
426013.2.1 General Description
4261
4262This command allows the TPM to serve in the role as a Duplication Authority. If proper authorization for
4263use of the oldParent is provided, then an HMAC key and a symmetric key are recovered from inSymSeed
4264and used to integrity check and decrypt inDuplicate. A new protection seed value is generated according
4265to the methods appropriate for newParent and the blob is re-encrypted and a new integrity value is
4266computed. The re-encrypted blob is returned in outDuplicate and the symmetric key returned in
4267outSymKey.
4268In the rewrap process, L is “DUPLICATE” (see “Terms and Definitions” in TPM 2.0 Part 1).
4269If inSymSeed has a zero length, then oldParent is required to be TPM_RH_NULL and no decryption of
4270inDuplicate takes place.
4271If newParent is TPM_RH_NULL, then no encryption is performed on outDuplicate. outSymSeed will have
4272a zero length. See TPM 2.0 Part 2 encryptedDuplication.
4273
4274
4275
4276
4277Page 84 TCG Published Family “2.0”
4278October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
4279 Trusted Platform Module Library Part 3: Commands
4280
4281
4282
428313.2.2 Command and Response
4284
4285 Table 37 — TPM2_Rewrap Command
4286Type Name Description
4287
4288TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
4289UINT32 commandSize
4290TPM_CC commandCode TPM_CC_Rewrap
4291
4292 parent of object
4293TPMI_DH_OBJECT+ @oldParent Auth Index: 1
4294 Auth Role: User
4295 new parent of the object
4296TPMI_DH_OBJECT+ newParent
4297 Auth Index: None
4298
4299 an object encrypted using symmetric key derived from
4300TPM2B_PRIVATE inDuplicate
4301 inSymSeed
4302TPM2B_NAME name the Name of the object being rewrapped
4303 seed for symmetric key
4304TPM2B_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
4309Type Name Description
4310
4311TPM_ST tag see clause 6
4312UINT32 responseSize
4313TPM_RC responseCode
4314
4315 an object encrypted using symmetric key derived from
4316TPM2B_PRIVATE outDuplicate
4317 outSymSeed
4318 seed for a symmetric key protected by newParent
4319TPM2B_ENCRYPTED_SECRET outSymSeed
4320 asymmetric key
4321
4322
4323
4324
4325Family “2.0” TCG Published Page 85
4326Level 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
43331 #include "InternalRoutines.h"
43342 #include "Rewrap_fp.h"
43353 #ifdef TPM_CC_Rewrap // Conditional expansion of this file
43364 #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 )
435810 {
435911 TPM_RC result = TPM_RC_SUCCESS;
436012 OBJECT *oldParent;
436113 TPM2B_DATA data; // symmetric key
436214 UINT16 hashSize = 0;
436315 TPM2B_PRIVATE privateBlob; // A temporary private blob
436416 // to transit between old
436517 // and new wrappers
436618
436719 // Input Validation
436820
436921 if((in->inSymSeed.t.size == 0 && in->oldParent != TPM_RH_NULL)
437022 || (in->inSymSeed.t.size != 0 && in->oldParent == TPM_RH_NULL))
437123 return TPM_RC_HANDLE + RC_Rewrap_oldParent;
437224
437325 if(in->oldParent != TPM_RH_NULL)
437426 {
437527 // Get old parent pointer
437628 oldParent = ObjectGet(in->oldParent);
437729
437830 // old parent key must be a storage object
437931 if(!ObjectIsStorage(in->oldParent))
438032 return TPM_RC_TYPE + RC_Rewrap_oldParent;
438133
438234 // Decrypt input secret data via asymmetric decryption. A
438335 // TPM_RC_VALUE, TPM_RC_KEY or unmarshal errors may be returned at this
438436 // point
438537 result = CryptSecretDecrypt(in->oldParent, NULL,
438638 "DUPLICATE", &in->inSymSeed, &data);
438739 if(result != TPM_RC_SUCCESS)
438840 return TPM_RC_VALUE + RC_Rewrap_inSymSeed;
438941
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;
4453100
4454101 // Copy privateBlob directly
4455102 out->outDuplicate = privateBlob;
4456103 }
4457104
4458105 return TPM_RC_SUCCESS;
4459106 }
4460107 #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
446713.3 TPM2_Import
4468
446913.3.1 General Description
4470
4471This command allows an object to be encrypted using the symmetric encryption values of a Storage Key.
4472After encryption, the object may be loaded and used in the new hierarchy. The imported object (duplicate)
4473may be singly encrypted, multiply encrypted, or unencrypted.
4474If fixedTPM or fixedParent is SET in objectPublic, the TPM shall return TPM_RC_ATTRIBUTES.
4475If encryptedDuplication is SET in the object referenced by parentHandle, then encryptedDuplication shall
4476be SET in objectPublic (TPM_RC_ATTRIBUTES).
4477If encryptedDuplication is SET in objectPublic, then inSymSeed and encryptionKey shall not be Empty
4478buffers (TPM_RC_ATTRIBUTES). Recovery of the sensitive data of the object occurs in the TPM in a
4479multi--step process in the following order:
4480a) 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
4497b) 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).
4501c) Unmarshal the sensitive area
4502
4503NOTE 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
4521After integrity checks and decryption, the TPM will create a new symmetrically encrypted private area
4522using the encryption key of the parent.
4523
4524Page 88 TCG Published Family “2.0”
4525October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
4526 Trusted Platform Module Library Part 3: Commands
4527
4528NOTE 5 The symmetric re-encryption is the normal integrity generation and symmetric encryption applied to
4529 a child object.
4530
4531
4532
4533
4534Family “2.0” TCG Published Page 89
4535Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
4536 Part 3: Commands Trusted Platform Module Library
4537
4538
453913.3.2 Command and Response
4540
4541 Table 39 — TPM2_Import Command
4542Type Name Description
4543
4544TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
4545UINT32 commandSize
4546TPM_CC commandCode TPM_CC_Import
4547
4548 the handle of the new parent for the object
4549TPMI_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
4554TPM2B_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
4559TPM2B_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
4565TPM2B_PRIVATE duplicate
4566 contain an inner symmetric wrapper
4567 symmetric key used to encrypt duplicate
4568TPM2B_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
4572TPMT_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
4578Type Name Description
4579
4580TPM_ST tag see clause 6
4581UINT32 responseSize
4582TPM_RC responseCode
4583
4584 the sensitive area encrypted with the symmetric key of
4585TPM2B_PRIVATE outPrivate
4586 parentHandle
4587
4588
4589
4590
4591Page 90 TCG Published Family “2.0”
4592October 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
45991 #include "InternalRoutines.h"
46002 #include "Import_fp.h"
46013 #ifdef TPM_CC_Import // Conditional expansion of this file
46024 #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 )
466910 {
467011
467112 TPM_RC result = TPM_RC_SUCCESS;
467213 OBJECT *parentObject;
467314 TPM2B_DATA data; // symmetric key
467415 TPMT_SENSITIVE sensitive;
467516 TPM2B_NAME name;
467617
467718 UINT16 innerKeySize = 0; // encrypt key size for inner
467819 // wrapper
467920
468021 // Input Validation
468122
468223 // FixedTPM and fixedParent must be CLEAR
468324 if( in->objectPublic.t.publicArea.objectAttributes.fixedTPM == SET
468425 || in->objectPublic.t.publicArea.objectAttributes.fixedParent == SET)
468526 return TPM_RC_ATTRIBUTES + RC_Import_objectPublic;
468627
468728 // Get parent pointer
468829 parentObject = ObjectGet(in->parentHandle);
468930
469031 if(!AreAttributesForParent(parentObject))
469132 return TPM_RC_TYPE + RC_Import_parentHandle;
469233
469334 if(in->symmetricAlg.algorithm != TPM_ALG_NULL)
469435 {
469536 // Get inner wrap key size
469637 innerKeySize = in->symmetricAlg.keyBits.sym;
469738 // Input symmetric key must match the size of algorithm.
469839 if(in->encryptionKey.t.size != (innerKeySize + 7) / 8)
469940 return TPM_RC_SIZE + RC_Import_encryptionKey;
470041 }
470142 else
470243 {
470344 // If input symmetric algorithm is NULL, input symmetric key size must
470445 // be 0 as well
470546 if(in->encryptionKey.t.size != 0)
470647 return TPM_RCS_SIZE + RC_Import_encryptionKey;
470748 // If encryptedDuplication is SET, then the object must have an inner
470849 // wrapper
470950 if(in->objectPublic.t.publicArea.objectAttributes.encryptedDuplication)
471051 return TPM_RCS_ATTRIBUTES + RC_Import_encryptionKey;
471152 }
471253
471354 // See if there is an outer wrapper
471455 if(in->inSymSeed.t.size != 0)
471556 {
471657 // Decrypt input secret data via asymmetric decryption. TPM_RC_ATTRIBUTES,
471758 // TPM_RC_ECC_POINT, TPM_RC_INSUFFICIENT, TPM_RC_KEY, TPM_RC_NO_RESULT,
471859 // TPM_RC_SIZE, TPM_RC_VALUE may be returned at this point
471960 result = CryptSecretDecrypt(in->parentHandle, NULL, "DUPLICATE",
472061 &in->inSymSeed, &data);
472162 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)
4765100 return RcSafeAddToResult(result, RC_Import_objectPublic);
4766101
4767102 // Create internal object. A TPM_RC_KEY_SIZE, TPM_RC_KEY or
4768103 // TPM_RC_OBJECT_MEMORY error may be returned at this point
4769104 result = ObjectLoad(TPM_RH_NULL, &in->objectPublic.t.publicArea,
4770105 &sensitive, NULL, in->parentHandle, FALSE,
4771106 &objectHandle);
4772107 if(result != TPM_RC_SUCCESS)
4773108 return result;
4774109
4775110 // Don't need the object, just needed the checks to be performed so
4776111 // flush the object
4777112 ObjectFlush(objectHandle);
4778113 }
4779114
4780115 // Command output
4781116
4782117 // Prepare output private data from sensitive
4783118 SensitiveToPrivate(&sensitive, &name, in->parentHandle,
4784119 in->objectPublic.t.publicArea.nameAlg,
4785120 &out->outPrivate);
4786121
4787122 return TPM_RC_SUCCESS;
4788123 }
4789124 #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
479914 Asymmetric Primitives
4800
480114.1 Introduction
4802
4803The commands in this clause provide low-level primitives for access to the asymmetric algorithms
4804implemented in the TPM. Many of these commands are only allowed if the asymmetric key is an
4805unrestricted key.
4806
480714.2 TPM2_RSA_Encrypt
4808
480914.2.1 General Description
4810
4811This command performs RSA encryption using the indicated padding scheme according to IETF RFC
48123447. If the scheme of keyHandle is TPM_ALG_NULL, then the caller may use inScheme to specify the
4813padding scheme. If scheme of keyHandle is not TPM_ALG_NULL, then inScheme shall either be
4814TPM_ALG_NULL or be the same as scheme (TPM_RC_SCHEME).
4815The key referenced by keyHandle is required to be an RSA key (TPM_RC_KEY) with the decrypt attribute
4816SET (TPM_RC_ATTRIBUTES).
4817
4818NOTE 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
4823The three types of allowed padding are:
48241) 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.
48262) TPM_ALG_RSAES – Data is padded as described in 7.2 of IETF RFC 3447 (PKCS#1).
48273) 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
4847After padding, the data is RSAEP encrypted according to 5.1.1 of IETF RFC 3447 (PKCS#1).
4848
4849
4850Page 94 TCG Published Family “2.0”
4851October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
4852 Trusted Platform Module Library Part 3: Commands
4853
4854NOTE 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
4857NOTE 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
4860If inScheme is used, and the scheme requires a hash algorithm it may not be TPM_ALG_NULL.
4861
4862NOTE 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
4867The 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
4871Scheme (mLen) in Octets Comments
4872
4873TPM_ALG_OAEP mLen  k – 2hLen – 2
4874TPM_ALG_RSAES mLen  k – 11
4875TPM_ALG_NULL mLen  k The numeric value of the message must be
4876 less than the numeric value of the public
4877 modulus (n).
4878NOTES
48791) k ≔ the number of byes in the public modulus
48802) hLen ≔ the number of octets in the digest produced by the hash algorithm used in the process
4881
4882The label parameter is optional. If provided (label.size != 0) then the TPM shall return TPM_RC_VALUE if
4883the last octet in label is not zero. If a zero octet occurs before label.buffer[label.size-1], the TPM shall
4884truncate the label at that point. The terminating octet of zero is included in the label used in the padding
4885scheme.
4886
4887NOTE 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
4890The function returns padded and encrypted value outData.
4891The message parameter in the command may be encrypted using parameter encryption.
4892
4893NOTE 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
4899Family “2.0” TCG Published Page 95
4900Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
4901 Part 3: Commands Trusted Platform Module Library
4902
4903
490414.2.2 Command and Response
4905
4906 Table 43 — TPM2_RSA_Encrypt Command
4907Type Name Description
4908
4909 TPM_ST_SESSIONS if an audit, encrypt, or decrypt
4910TPMI_ST_COMMAND_TAG tag session is present; otherwise,
4911 TPM_ST_NO_SESSIONS
4912UINT32 commandSize
4913TPM_CC commandCode TPM_CC_RSA_Encrypt
4914
4915 reference to public portion of RSA key to use for
4916TPMI_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
4921TPM2B_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
4926TPMT_RSA_DECRYPT+ inScheme
4927 keyHandle is TPM_ALG_NULL
4928 optional label L to be associated with the message
4929TPM2B_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
4934Type Name Description
4935
4936TPM_ST tag see clause 6
4937UINT32 responseSize
4938TPM_RC responseCode
4939
4940TPM2B_PUBLIC_KEY_RSA outData encrypted output
4941
4942
4943
4944
4945Page 96 TCG Published Family “2.0”
4946October 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
49531 #include "InternalRoutines.h"
49542 #include "RSA_Encrypt_fp.h"
49553 #ifdef TPM_CC_RSA_Encrypt // Conditional expansion of this file
49564 #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 )
497410 {
497511 TPM_RC result;
497612 OBJECT *rsaKey;
497713 TPMT_RSA_DECRYPT *scheme;
497814 char *label = NULL;
497915
498016 // Input Validation
498117
498218 rsaKey = ObjectGet(in->keyHandle);
498319
498420 // selected key must be an RSA key
498521 if(rsaKey->publicArea.type != TPM_ALG_RSA)
498622 return TPM_RC_KEY + RC_RSA_Encrypt_keyHandle;
498723
498824 // selected key must have the decryption attribute
498925 if(rsaKey->publicArea.objectAttributes.decrypt != SET)
499026 return TPM_RC_ATTRIBUTES + RC_RSA_Encrypt_keyHandle;
499127
499228 // Is there a label?
499329 if(in->label.t.size > 0)
499430 {
499531 // label is present, so make sure that is it NULL-terminated
499632 if(in->label.t.buffer[in->label.t.size - 1] != 0)
499733 return TPM_RC_VALUE + RC_RSA_Encrypt_label;
499834 label = (char *)in->label.t.buffer;
499935 }
500036
500137 // Command Output
500238
500339 // Select a scheme for encryption
500440 scheme = CryptSelectRSAScheme(in->keyHandle, &in->inScheme);
500541 if(scheme == NULL)
500642 return TPM_RC_SCHEME + RC_RSA_Encrypt_inScheme;
500743
500844 // Encryption. TPM_RC_VALUE, or TPM_RC_SCHEME errors my be returned buy
500945 // CryptEncyptRSA. Note: It can also return TPM_RC_ATTRIBUTES if the key does
501046 // not have the decrypt attribute but that was checked above.
501147 out->outData.t.size = sizeof(out->outData.t.buffer);
501248 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
501849 scheme, in->message.t.size, in->message.t.buffer,
501950 label);
502051 return result;
502152 }
502253 #endif
502354 #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
503314.3 TPM2_RSA_Decrypt
5034
503514.3.1 General Description
5036
5037This command performs RSA decryption using the indicated padding scheme according to IETF RFC
50383447 ((PKCS#1).
5039The scheme selection for this command is the same as for TPM2_RSA_Encrypt() and is shown in Table
504041.
5041The key referenced by keyHandle shall be an RSA key (TPM_RC_KEY) with restricted CLEAR and
5042decrypt SET (TPM_RC_ATTRIBUTES).
5043This command uses the private key of keyHandle for this operation and authorization is required.
5044The TPM will perform a modular exponentiation of ciphertext using the private exponent associated with
5045keyHandle (this is described in IETF RFC 3447 (PKCS#1), clause 5.1.2). It will then validate the padding
5046according to the selected scheme. If the padding checks fail, TPM_RC_VALUE is returned. Otherwise,
5047the data is returned with the padding removed. If no padding is used, the returned value is an unsigned
5048integer value that is the result of the modular exponentiation of cipherText using the private exponent of
5049keyHandle. The returned value may include leading octets zeros so that it is the same size as the public
5050modulus. For the other padding schemes, the returned value will be smaller than the public modulus but
5051will contain all the data remaining after padding is removed and this may include leading zeros if the
5052original encrypted value contained leading zeros.
5053If a label is used in the padding process of the scheme during encryption, the label parameter is required
5054to be present in the decryption process and label is required to be the same in both cases. If label is not
5055the same, the decrypt operation is very likely to fail ((TPM_RC_VALUE). If label is present (label.size !=
50560), it shall be a NULL-terminated string or the TPM will return TPM_RC_VALUE.
5057
5058NOTE 1 The size of label includes the terminating null.
5059
5060The message parameter in the response may be encrypted using parameter encryption.
5061If inScheme is used, and the scheme requires a hash algorithm it may not be TPM_ALG_NULL.
5062If the scheme does not require a label, the value in label is not used but the size of the label field is
5063checked for consistency with the indicated data type (TPM2B_DATA). That is, the field may not be larger
5064than allowed for a TPM2B_DATA.
5065
5066
5067
5068
5069Family “2.0” TCG Published Page 99
5070Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
5071 Part 3: Commands Trusted Platform Module Library
5072
5073
5074
507514.3.2 Command and Response
5076
5077 Table 45 — TPM2_RSA_Decrypt Command
5078Type Name Description
5079
5080TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
5081UINT32 commandSize
5082TPM_CC commandCode TPM_CC_RSA_Decrypt
5083
5084 RSA key to use for decryption
5085TPMI_DH_OBJECT @keyHandle Auth Index: 1
5086 Auth Role: USER
5087
5088 cipher text to be decrypted
5089TPM2B_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
5093TPMT_RSA_DECRYPT+ inScheme
5094 keyHandle is TPM_ALG_NULL
5095 label whose association with the message is to be
5096TPM2B_DATA label
5097 verified
5098
5099
5100 Table 46 — TPM2_RSA_Decrypt Response
5101Type Name Description
5102
5103TPM_ST tag see clause 6
5104UINT32 responseSize
5105TPM_RC responseCode
5106
5107TPM2B_PUBLIC_KEY_RSA message decrypted output
5108
5109
5110
5111
5112Page 100 TCG Published Family “2.0”
5113October 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
51201 #include "InternalRoutines.h"
51212 #include "RSA_Decrypt_fp.h"
51223 #ifdef TPM_CC_RSA_Decrypt // Conditional expansion of this file
51234 #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 )
514210 {
514311 TPM_RC result;
514412 OBJECT *rsaKey;
514513 TPMT_RSA_DECRYPT *scheme;
514614 char *label = NULL;
514715
514816 // Input Validation
514917
515018 rsaKey = ObjectGet(in->keyHandle);
515119
515220 // The selected key must be an RSA key
515321 if(rsaKey->publicArea.type != TPM_ALG_RSA)
515422 return TPM_RC_KEY + RC_RSA_Decrypt_keyHandle;
515523
515624 // The selected key must be an unrestricted decryption key
515725 if( rsaKey->publicArea.objectAttributes.restricted == SET
515826 || rsaKey->publicArea.objectAttributes.decrypt == CLEAR)
515927 return TPM_RC_ATTRIBUTES + RC_RSA_Decrypt_keyHandle;
516028
516129 // NOTE: Proper operation of this command requires that the sensitive area
516230 // of the key is loaded. This is assured because authorization is required
516331 // to use the sensitive area of the key. In order to check the authorization,
516432 // the sensitive area has to be loaded, even if authorization is with policy.
516533
516634 // If label is present, make sure that it is a NULL-terminated string
516735 if(in->label.t.size > 0)
516836 {
516937 // Present, so make sure that it is NULL-terminated
517038 if(in->label.t.buffer[in->label.t.size - 1] != 0)
517139 return TPM_RC_VALUE + RC_RSA_Decrypt_label;
517240 label = (char *)in->label.t.buffer;
517341 }
517442
517543 // Command Output
517644
517745 // Select a scheme for decrypt.
517846 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
518447 if(scheme == NULL)
518548 return TPM_RC_SCHEME + RC_RSA_Decrypt_inScheme;
518649
518750 // Decryption. TPM_RC_VALUE, TPM_RC_SIZE, and TPM_RC_KEY error may be
518851 // returned by CryptDecryptRSA.
518952 // NOTE: CryptDecryptRSA can also return TPM_RC_ATTRIBUTES or TPM_RC_BINDING
519053 // when the key is not a decryption key but that was checked above.
519154 out->message.t.size = sizeof(out->message.t.buffer);
519255 result = CryptDecryptRSA(&out->message.t.size, out->message.t.buffer, rsaKey,
519356 scheme, in->cipherText.t.size,
519457 in->cipherText.t.buffer,
519558 label);
519659
519760 return result;
519861 }
519962 #endif
520063 #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
521014.4 TPM2_ECDH_KeyGen
5211
521214.4.1 General Description
5213
5214This command uses the TPM to generate an ephemeral key pair ( de, Qe where Qe ≔ [de]G). It uses the
5215private ephemeral key and a loaded public key (QS) to compute the shared secret value (P ≔ [hde]QS).
5216keyHandle shall refer to a loaded ECC key. The sensitive portion of this key need not be loaded.
5217The curve parameters of the loaded ECC key are used to generate the ephemeral key.
5218
5219NOTE 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
5224The zPoint in the response may be encrypted using parameter encryption.
5225
5226
5227
5228
5229Family “2.0” TCG Published Page 103
5230Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
5231 Part 3: Commands Trusted Platform Module Library
5232
5233
5234
523514.4.2 Command and Response
5236
5237 Table 47 — TPM2_ECDH_KeyGen Command
5238Type Name Description
5239
5240 TPM_ST_SESSIONS if an audit or encrypt session is
5241TPMI_ST_COMMAND_TAG tag
5242 present; otherwise, TPM_ST_NO_SESSIONS
5243UINT32 commandSize
5244TPM_CC commandCode TPM_CC_ECDH_KeyGen
5245
5246 Handle of a loaded ECC key public area.
5247TPMI_DH_OBJECT keyHandle
5248 Auth Index: None
5249
5250
5251 Table 48 — TPM2_ECDH_KeyGen Response
5252Type Name Description
5253
5254TPM_ST tag see clause 6
5255UINT32 responseSize
5256TPM_RC responseCode
5257
5258TPM2B_ECC_POINT zPoint results of P ≔ h[de]Qs
5259
5260TPM2B_ECC_POINT pubPoint generated ephemeral public point (Qe)
5261
5262
5263
5264
5265Page 104 TCG Published Family “2.0”
5266October 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
52731 #include "InternalRoutines.h"
52742 #include "ECDH_KeyGen_fp.h"
52753 #ifdef TPM_CC_ECDH_KeyGen // Conditional expansion of this file
52764 #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 )
528810 {
528911 OBJECT *eccKey;
529012 TPM2B_ECC_PARAMETER sensitive;
529113 TPM_RC result;
529214
529315 // Input Validation
529416
529517 eccKey = ObjectGet(in->keyHandle);
529618
529719 // Input key must be a non-restricted, decrypt ECC key
529820 if( eccKey->publicArea.type != TPM_ALG_ECC)
529921 return TPM_RCS_KEY + RC_ECDH_KeyGen_keyHandle;
530022
530123 if( eccKey->publicArea.objectAttributes.restricted == SET
530224 || eccKey->publicArea.objectAttributes.decrypt != SET
530325 )
530426 return TPM_RC_KEY + RC_ECDH_KeyGen_keyHandle;
530527
530628 // Command Output
530729 do
530830 {
530931 // Create ephemeral ECC key
531032 CryptNewEccKey(eccKey->publicArea.parameters.eccDetail.curveID,
531133 &out->pubPoint.t.point, &sensitive);
531234
531335 out->pubPoint.t.size = TPMS_ECC_POINT_Marshal(&out->pubPoint.t.point,
531436 NULL, NULL);
531537
531638 // Compute Z
531739 result = CryptEccPointMultiply(&out->zPoint.t.point,
531840 eccKey->publicArea.parameters.eccDetail.curveID,
531941 &sensitive, &eccKey->publicArea.unique.ecc);
532042 // The point in the key is not on the curve. Indicate that the key is bad.
532143 if(result == TPM_RC_ECC_POINT)
532244 return TPM_RC_KEY + RC_ECDH_KeyGen_keyHandle;
532345 // The other possible error is TPM_RC_NO_RESULT indicating that the
532446 // multiplication resulted in the point at infinity, so get a new
532547 // random key and start over (hardly ever happens).
532648 }
532749 while(result == TPM_RC_NO_RESULT);
532850
532951 if(result == TPM_RC_SUCCESS)
533052 // Marshal the values to generate the point.
533153 out->zPoint.t.size = TPMS_ECC_POINT_Marshal(&out->zPoint.t.point,
533254 NULL, NULL);
533355
533456 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
534057 }
534158 #endif
534259 #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
535214.5 TPM2_ECDH_ZGen
5353
535414.5.1 General Description
5355
5356This command uses the TPM to recover the Z value from a public point (QB) and a private key (ds). It will
5357perform the multiplication of the provided inPoint (QB) with the private key (ds) and return the coordinates
5358of the resultant point (Z = (xZ , yZ) ≔ [hds]QB; where h is the cofactor of the curve).
5359keyHandle shall refer to a loaded, ECC key (TPM_RC_KEY) with the restricted attribute CLEAR and the
5360decrypt attribute SET (TPM_RC_ATTRIBUTES).
5361The scheme of the key referenced by keyHandle is required to be either TPM_ALG_ECDH or
5362TPM_ALG_NULL (TPM_RC_SCHEME).
5363inPoint is required to be on the curve of the key referenced by keyHandle (TPM_RC_ECC_POINT).
5364The parameters of the key referenced by keyHandle are used to perform the point multiplication.
5365
5366
5367
5368
5369Family “2.0” TCG Published Page 107
5370Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
5371 Part 3: Commands Trusted Platform Module Library
5372
5373
5374
537514.5.2 Command and Response
5376
5377 Table 49 — TPM2_ECDH_ZGen Command
5378Type Name Description
5379
5380TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
5381UINT32 commandSize
5382TPM_CC commandCode TPM_CC_ECDH_ZGen
5383
5384 handle of a loaded ECC key
5385TPMI_DH_OBJECT @keyHandle Auth Index: 1
5386 Auth Role: USER
5387
5388TPM2B_ECC_POINT inPoint a public key
5389
5390
5391 Table 50 — TPM2_ECDH_ZGen Response
5392Type Name Description
5393
5394TPM_ST tag see clause 6
5395UINT32 responseSize
5396TPM_RC responseCode
5397
5398 X and Y coordinates of the product of the multiplication
5399TPM2B_ECC_POINT outPoint
5400 Z = (xZ , yZ) ≔ [hdS]QB
5401
5402
5403
5404
5405Page 108 TCG Published Family “2.0”
5406October 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
54131 #include "InternalRoutines.h"
54142 #include "ECDH_ZGen_fp.h"
54153 #ifdef TPM_CC_ECDH_ZGen // Conditional expansion of this file
54164 #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 )
543210 {
543311 TPM_RC result;
543412 OBJECT *eccKey;
543513
543614 // Input Validation
543715
543816 eccKey = ObjectGet(in->keyHandle);
543917
544018 // Input key must be a non-restricted, decrypt ECC key
544119 if( eccKey->publicArea.type != TPM_ALG_ECC)
544220 return TPM_RCS_KEY + RC_ECDH_ZGen_keyHandle;
544321
544422 if( eccKey->publicArea.objectAttributes.restricted == SET
544523 || eccKey->publicArea.objectAttributes.decrypt != SET
544624 )
544725 return TPM_RC_KEY + RC_ECDH_ZGen_keyHandle;
544826
544927 // Make sure the scheme allows this use
545028 if( eccKey->publicArea.parameters.eccDetail.scheme.scheme != TPM_ALG_ECDH
545129 && eccKey->publicArea.parameters.eccDetail.scheme.scheme != TPM_ALG_NULL)
545230 return TPM_RC_SCHEME + RC_ECDH_ZGen_keyHandle;
545331
545432 // Command Output
545533
545634 // Compute Z. TPM_RC_ECC_POINT or TPM_RC_NO_RESULT may be returned here.
545735 result = CryptEccPointMultiply(&out->outPoint.t.point,
545836 eccKey->publicArea.parameters.eccDetail.curveID,
545937 &eccKey->sensitive.sensitive.ecc,
546038 &in->inPoint.t.point);
546139 if(result != TPM_RC_SUCCESS)
546240 return RcSafeAddToResult(result, RC_ECDH_ZGen_inPoint);
546341
546442 out->outPoint.t.size = TPMS_ECC_POINT_Marshal(&out->outPoint.t.point,
546543 NULL, NULL);
546644
546745 return TPM_RC_SUCCESS;
546846 }
546947 #endif
547048 #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
547914.6 TPM2_ECC_Parameters
5480
548114.6.1 General Description
5482
5483This command returns the parameters of an ECC curve identified by its TCG-assigned curveID.
5484
548514.6.2 Command and Response
5486
5487 Table 51 — TPM2_ECC_Parameters Command
5488Type Name Description
5489
5490 TPM_ST_SESSIONS if an audit session is
5491TPMI_ST_COMMAND_TAG tag
5492 present; otherwise, TPM_ST_NO_SESSIONS
5493UINT32 commandSize
5494TPM_CC commandCode TPM_CC_ECC_Parameters
5495
5496TPMI_ECC_CURVE curveID parameter set selector
5497
5498
5499 Table 52 — TPM2_ECC_Parameters Response
5500Type Name Description
5501
5502TPM_ST tag see clause 6
5503UINT32 responseSize
5504TPM_RC responseCode
5505
5506TPMS_ALGORITHM_DETAIL_ECC parameters ECC parameters for the selected curve
5507
5508
5509
5510
5511Page 110 TCG Published Family “2.0”
5512October 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
55191 #include "InternalRoutines.h"
55202 #include "ECC_Parameters_fp.h"
55213 #ifdef TPM_CC_ECC_Parameters // Conditional expansion of this file
55224 #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 )
553410 {
553511 // Command Output
553612
553713 // Get ECC curve parameters
553814 if(CryptEccGetParameters(in->curveID, &out->parameters))
553915 return TPM_RC_SUCCESS;
554016 else
554117 return TPM_RC_VALUE + RC_ECC_Parameters_curveID;
554218 }
554319 #endif
554420 #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
555614.7 TPM2_ZGen_2Phase
5557
555814.7.1 General Description
5559
5560This command supports two-phase key exchange protocols. The command is used in combination with
5561TPM2_EC_Ephemeral(). TPM2_EC_Ephemeral() generates an ephemeral key and returns the public
5562point of that ephemeral key along with a numeric value that allows the TPM to regenerate the associated
5563private key.
5564The input parameters for this command are a static public key (inQsU), an ephemeral key (inQeU) from
5565party B, and the commitCounter returned by TPM2_EC_Ephemeral(). The TPM uses the counter value to
5566regenerate the ephemeral private key (de,V) and the associated public key (Qe,V). keyA provides the static
5567ephemeral elements ds,V and Qs,V. This provides the two pairs of ephemeral and static keys that are
5568required for the schemes supported by this command.
5569The TPM will compute Z or Zs and Ze according to the selected scheme. If the scheme is not a two-phase
5570key exchange scheme or if the scheme is not supported, the TPM will return TPM_RC_SCHEME.
5571It is an error if inQsB or inQeB are not on the curve of keyA (TPM_RC_ECC_POINT).
5572
5573The two-phase key schemes that were assigned an algorithm ID as of the time of the publication of this
5574specification are TPM_ALG_ECDH, TPM_ALG_ECMQV, and TPM_ALG_SM2.
5575
5576If this command is supported, then support for TPM_ALG_ECDH is required. Support for
5577TPM_ALG_ECMQV or TPM_ALG_SM2 is optional.
5578
5579NOTE 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
5583For TPM_ALG_ECDH outZ1 will be Zs and outZ2 will Ze as defined in 6.1.1.2 of SP800-56A.
5584
5585NOTE 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
5590For TPM_ALG_ECMQV or TPM_ALG_SM2 outZ1 will be Z and outZ2 will be an Empty Point.
5591
5592NOTE 3 An Empty Point has two Empty Buffers as coordinates meaning the minimum size value for outZ2
5593 will be four.
5594
5595
5596If the input scheme is TPM_ALG_ECDH, then outZ1 will be Zs and outZ2 will be Ze. For schemes like
5597MQV (including SM2), outZ1 will contain the computed value and outZ2 will be an Empty Point.
5598
5599NOTE The Z values returned by the TPM are a full point and not just an x -coordinate.
5600
5601If a computation of either Z produces the point at infinity, then the corresponding Z value will be an Empty
5602Point.
5603
5604
5605
5606
5607Page 112 TCG Published Family “2.0”
5608October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
5609 Trusted Platform Module Library Part 3: Commands
5610
5611
5612
561314.7.2 Command and Response
5614
5615 Table 53 — TPM2_ZGen_2Phase Command
5616Type Name Description
5617
5618TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
5619UINT32 commandSize
5620TPM_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
5624TPMI_DH_OBJECT @keyA
5625 Auth Index: 1
5626 Auth Role: USER
5627
5628TPM2B_ECC_POINT inQsB other party’s static public key (Qs,B = (Xs,B, Ys,B))
5629
5630TPM2B_ECC_POINT inQeB other party's ephemeral public key (Qe,B = (Xe,B, Ye,B))
5631TPMI_ECC_KEY_EXCHANGE inScheme the key exchange scheme
5632UINT16 counter value returned by TPM2_EC_Ephemeral()
5633
5634
5635 Table 54 — TPM2_ZGen_2Phase Response
5636Type Name Description
5637
5638TPM_ST tag
5639UINT32 responseSize
5640TPM_RC responseCode
5641
5642 X and Y coordinates of the computed value (scheme
5643TPM2B_ECC_POINT outZ1
5644 dependent)
5645 X and Y coordinates of the second computed value
5646TPM2B_ECC_POINT outZ2
5647 (scheme dependent)
5648
5649
5650
5651
5652Family “2.0” TCG Published Page 113
5653Level 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
56601 #include "InternalRoutines.h"
56612 #include "ZGen_2Phase_fp.h"
56623 #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 {
568010 TPM_RC result;
568111 OBJECT *eccKey;
568212 TPM2B_ECC_PARAMETER r;
568313 TPM_ALG_ID scheme;
568414
568515 // Input Validation
568616
568717 eccKey = ObjectGet(in->keyA);
568818
568919 // keyA must be an ECC key
569020 if(eccKey->publicArea.type != TPM_ALG_ECC)
569121 return TPM_RC_KEY + RC_ZGen_2Phase_keyA;
569222
569323 // keyA must not be restricted and must be a decrypt key
569424 if( eccKey->publicArea.objectAttributes.restricted == SET
569525 || eccKey->publicArea.objectAttributes.decrypt != SET
569626 )
569727 return TPM_RC_ATTRIBUTES + RC_ZGen_2Phase_keyA;
569828
569929 // if the scheme of keyA is TPM_ALG_NULL, then use the input scheme; otherwise
570030 // the input scheme must be the same as the scheme of keyA
570131 scheme = eccKey->publicArea.parameters.asymDetail.scheme.scheme;
570232 if(scheme != TPM_ALG_NULL)
570333 {
570434 if(scheme != in->inScheme)
570535 return TPM_RC_SCHEME + RC_ZGen_2Phase_inScheme;
570636 }
570737 else
570838 scheme = in->inScheme;
570939 if(scheme == TPM_ALG_NULL)
571040 return TPM_RC_SCHEME + RC_ZGen_2Phase_inScheme;
571141
571242 // Input points must be on the curve of keyA
571343 if(!CryptEccIsPointOnCurve(eccKey->publicArea.parameters.eccDetail.curveID,
571444 &in->inQsB.t.point))
571545 return TPM_RC_ECC_POINT + RC_ZGen_2Phase_inQsB;
571646
571747 if(!CryptEccIsPointOnCurve(eccKey->publicArea.parameters.eccDetail.curveID,
571848 &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
572549 return TPM_RC_ECC_POINT + RC_ZGen_2Phase_inQeB;
572650
572751 if(!CryptGenerateR(&r, &in->counter,
572852 eccKey->publicArea.parameters.eccDetail.curveID,
572953 NULL))
573054 return TPM_RC_VALUE + RC_ZGen_2Phase_counter;
573155
573256 // Command Output
573357
573458 result = CryptEcc2PhaseKeyExchange(&out->outZ1.t.point,
573559 &out->outZ2.t.point,
573660 eccKey->publicArea.parameters.eccDetail.curveID,
573761 scheme,
573862 &eccKey->sensitive.sensitive.ecc,
573963 &r,
574064 &in->inQsB.t.point,
574165 &in->inQeB.t.point);
574266 if(result == TPM_RC_SCHEME)
574367 return TPM_RC_SCHEME + RC_ZGen_2Phase_inScheme;
574468
574569 if(result == TPM_RC_SUCCESS)
574670 CryptEndCommit(in->counter);
574771
574872 return result;
574973 }
575074 #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
576015 Symmetric Primitives
5761
576215.1 Introduction
5763
5764The commands in this clause provide low-level primitives for access to the symmetric algorithms
5765implemented in the TPM that operate on blocks of data. These include symmetric encryption and
5766decryption as well as hash and HMAC. All of the commands in this group are stateless. That is, they have
5767no persistent state that is retained in the TPM when the command is complete.
5768For hashing, HMAC, and Events that require large blocks of data with retained state, the sequence
5769commands are provided (see clause 1).
5770Some of the symmetric encryption/decryption modes use an IV. When an IV is used, it may be an
5771initiation value or a chained value from a previous stage. The chaining for each mode is:
5772
5773
5774
5775
5776Page 116 TCG Published Family “2.0”
5777October 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
5781Mode Chaining process
5782
5783TPM_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.
5795TPM_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.
5802TPM_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.
5812TPM_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.
5818TPM_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
5828Family “2.0” TCG Published Page 117
5829Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
5830 Part 3: Commands Trusted Platform Module Library
5831
5832
5833
583415.2 TPM2_EncryptDecrypt
5835
583615.2.1 General Description
5837
5838This command performs symmetric encryption or decryption.
5839keyHandle shall reference a symmetric cipher object (TPM_RC_KEY).
5840For 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
5842but both shall not be TPM_ALG_NULL (TPM_RC_VALUE). If different, mode overrides the mode of the
5843key.
5844If the TPM allows this command to be canceled before completion, then the TPM may produce
5845incremental results and return TPM_RC_SUCCESS rather than TPM_RC_CANCELED. In such case,
5846outData may be less than inData.
5847
5848
5849
5850
5851Page 118 TCG Published Family “2.0”
5852October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
5853 Trusted Platform Module Library Part 3: Commands
5854
5855
5856
585715.2.2 Command and Response
5858
5859 Table 56 — TPM2_EncryptDecrypt Command
5860Type Name Description
5861
5862TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
5863UINT32 commandSize
5864TPM_CC commandCode TPM_CC_EncryptDecrypt
5865
5866 the symmetric key used for the operation
5867TPMI_DH_OBJECT @keyHandle Auth Index: 1
5868 Auth Role: USER
5869
5870 if YES, then the operation is decryption; if NO, the
5871TPMI_YES_NO decrypt
5872 operation is encryption
5873 symmetric mode
5874TPMI_ALG_SYM_MODE+ mode For a restricted key, this field shall match the default
5875 mode of the key or be TPM_ALG_NULL.
5876TPM2B_IV ivIn an initial value as required by the algorithm
5877TPM2B_MAX_BUFFER inData the data to be encrypted/decrypted
5878
5879
5880 Table 57 — TPM2_EncryptDecrypt Response
5881Type Name Description
5882
5883TPM_ST tag see clause 6
5884UINT32 responseSize
5885TPM_RC responseCode
5886
5887TPM2B_MAX_BUFFER outData encrypted or decrypted output
5888TPM2B_IV ivOut chaining value to use for IV in next round
5889
5890
5891
5892
5893Family “2.0” TCG Published Page 119
5894Level 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
59011 #include "InternalRoutines.h"
59022 #include "EncryptDecrypt_fp.h"
59033 #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 {
592110 OBJECT *symKey;
592211 UINT16 keySize;
592312 UINT16 blockSize;
592413 BYTE *key;
592514 TPM_ALG_ID alg;
592615
592716 // Input Validation
592817 symKey = ObjectGet(in->keyHandle);
592918
593019 // The input key should be a symmetric decrypt key.
593120 if( symKey->publicArea.type != TPM_ALG_SYMCIPHER
593221 || symKey->attributes.publicOnly == SET)
593322 return TPM_RC_KEY + RC_EncryptDecrypt_keyHandle;
593423
593524 // If the input mode is TPM_ALG_NULL, use the key's mode
593625 if( in->mode == TPM_ALG_NULL)
593726 in->mode = symKey->publicArea.parameters.symDetail.sym.mode.sym;
593827
593928 // If the key is restricted, the input symmetric mode should match the key's
594029 // symmetric mode
594130 if( symKey->publicArea.objectAttributes.restricted == SET
594231 && symKey->publicArea.parameters.symDetail.sym.mode.sym != in->mode)
594332 return TPM_RC_VALUE + RC_EncryptDecrypt_mode;
594433
594534 // If the mode is null, then we have a problem.
594635 // Note: Construction of a TPMT_SYM_DEF does not allow the 'mode' to be
594736 // TPM_ALG_NULL so setting in->mode to the mode of the key should have
594837 // produced a valid mode. However, this is suspenders.
594938 if(in->mode == TPM_ALG_NULL)
595039 return TPM_RC_VALUE + RC_EncryptDecrypt_mode;
595140
595241 // The input iv for ECB mode should be null. All the other modes should
595342 // have an iv size same as encryption block size
595443
595544 keySize = symKey->publicArea.parameters.symDetail.sym.keyBits.sym;
595645 alg = symKey->publicArea.parameters.symDetail.sym.algorithm;
595746 blockSize = CryptGetSymmetricBlockSize(alg, keySize);
595847 if( (in->mode == TPM_ALG_ECB && in->ivIn.t.size != 0)
595948 || (in->mode != TPM_ALG_ECB && in->ivIn.t.size != blockSize))
596049 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
596650
596751 // The input data size of CBC mode or ECB mode must be an even multiple of
596852 // the symmetric algorithm's block size
596953 if( (in->mode == TPM_ALG_CBC || in->mode == TPM_ALG_ECB)
597054 && (in->inData.t.size % blockSize) != 0)
597155 return TPM_RC_SIZE + RC_EncryptDecrypt_inData;
597256
597357 // Copy IV
597458 // Note: This is copied here so that the calls to the encrypt/decrypt functions
597559 // will modify the output buffer, not the input buffer
597660 out->ivOut = in->ivIn;
597761
597862 // Command Output
597963
598064 key = symKey->sensitive.sensitive.sym.t.buffer;
598165 // For symmetric encryption, the cipher data size is the same as plain data
598266 // size.
598367 out->outData.t.size = in->inData.t.size;
598468 if(in->decrypt == YES)
598569 {
598670 // Decrypt data to output
598771 CryptSymmetricDecrypt(out->outData.t.buffer,
598872 alg,
598973 keySize, in->mode, key,
599074 &(out->ivOut),
599175 in->inData.t.size,
599276 in->inData.t.buffer);
599377 }
599478 else
599579 {
599680 // Encrypt data to output
599781 CryptSymmetricEncrypt(out->outData.t.buffer,
599882 alg,
599983 keySize,
600084 in->mode, key,
600185 &(out->ivOut),
600286 in->inData.t.size,
600387 in->inData.t.buffer);
600488 }
600589
600690 return TPM_RC_SUCCESS;
600791 }
600892 #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
601815.3 TPM2_Hash
6019
602015.3.1 General Description
6021
6022This command performs a hash operation on a data buffer and returns the results.
6023
6024NOTE 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
6027If the results of the hash will be used in a signing operation that uses a restricted signing key, then the
6028ticket returned by this command can indicate that the hash is safe to sign.
6029If the digest is not safe to sign, then the TPM will return a TPMT_TK_HASHCHECK with the hierarchy set
6030to TPM_RH_NULL and digest set to the Empty Buffer.
6031If hierarchy is TPM_RH_NULL, then digest in the ticket will be the Empty Buffer.
6032
6033
6034
6035
6036Page 122 TCG Published Family “2.0”
6037October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
6038 Trusted Platform Module Library Part 3: Commands
6039
6040
6041
604215.3.2 Command and Response
6043
6044 Table 58 — TPM2_Hash Command
6045Type Name Description
6046
6047 TPM_ST_SESSIONS if an audit, decrypt, or encrypt
6048TPMI_ST_COMMAND_TAG tag session is present; otherwise,
6049 TPM_ST_NO_SESSIONS
6050UINT32 commandSize
6051TPM_CC commandCode TPM_CC_Hash
6052
6053TPM2B_MAX_BUFFER data data to be hashed
6054 algorithm for the hash being computed – shall not be
6055TPMI_ALG_HASH hashAlg
6056 TPM_ALG_NULL
6057TPMI_RH_HIERARCHY+ hierarchy hierarchy to use for the ticket (TPM_RH_NULL allowed)
6058
6059
6060 Table 59 — TPM2_Hash Response
6061Type Name Description
6062
6063TPM_ST tag see clause 6
6064UINT32 responseSize
6065TPM_RC responseCode
6066
6067TPM2B_DIGEST outHash results
6068 ticket indicating that the sequence of octets used to
6069 compute outDigest did not start with
6070TPMT_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
6077Family “2.0” TCG Published Page 123
6078Level 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 {
609410 HASH_STATE hashState;
609511
609612 // Command Output
609713
609814 // Output hash
609915 // Start hash stack
610016 out->outHash.t.size = CryptStartHash(in->hashAlg, &hashState);
610117 // Adding hash data
610218 CryptUpdateDigest2B(&hashState, &in->data.b);
610319 // Complete hash
610420 CryptCompleteHash2B(&hashState, &out->outHash.b);
610521
610622 // Output ticket
610723 out->validation.tag = TPM_ST_HASHCHECK;
610824 out->validation.hierarchy = in->hierarchy;
610925
611026 if(in->hierarchy == TPM_RH_NULL)
611127 {
611228 // Ticket is not required
611329 out->validation.hierarchy = TPM_RH_NULL;
611430 out->validation.digest.t.size = 0;
611531 }
611632 else if( in->data.t.size >= sizeof(TPM_GENERATED)
611733 && !TicketIsSafe(&in->data.b))
611834 {
611935 // Ticket is not safe
612036 out->validation.hierarchy = TPM_RH_NULL;
612137 out->validation.digest.t.size = 0;
612238 }
612339 else
612440 {
612541 // Compute ticket
612642 TicketComputeHashCheck(in->hierarchy, in->hashAlg,
612743 &out->outHash, &out->validation);
612844 }
612945
613046 return TPM_RC_SUCCESS;
613147 }
613248 #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
614215.4 TPM2_HMAC
6143
614415.4.1 General Description
6145
6146This command performs an HMAC on the supplied data using the indicated hash algorithm.
6147The caller shall provide proper authorization for use of handle.
6148If the sign attribute is not SET in the key referenced by handle then the TPM shall return
6149TPM_RC_ATTRIBUTES. If the key type is not TPM_ALG_KEYEDHASH then the TPM shall return
6150TPM_RC_TYPE. If the key referenced by handle has the restricted attribute SET, the TPM shall return
6151TPM_RC_ATTRIBUTES.
6152If the default scheme of the key referenced by handle is not TPM_ALG_NULL, then the hashAlg
6153parameter is required to be either the same as the key’s default or TPM_ALG_NULL (TPM_RC_VALUE).
6154If the default scheme of the key is TPM_ALG_NULL, then hashAlg is required to be a valid hash and not
6155TPM_ALG_NULL (TPM_RC_VALUE). (See hash selection matrix in Table 66.)
6156
6157NOTE 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
6163Family “2.0” TCG Published Page 125
6164Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
6165 Part 3: Commands Trusted Platform Module Library
6166
6167
616815.4.2 Command and Response
6169
6170 Table 60 — TPM2_HMAC Command
6171Type Name Description
6172
6173TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
6174UINT32 commandSize
6175TPM_CC commandCode TPM_CC_HMAC
6176
6177 handle for the symmetric signing key providing the
6178 HMAC key
6179TPMI_DH_OBJECT @handle
6180 Auth Index: 1
6181 Auth Role: USER
6182
6183TPM2B_MAX_BUFFER buffer HMAC data
6184TPMI_ALG_HASH+ hashAlg algorithm to use for HMAC
6185
6186
6187 Table 61 — TPM2_HMAC Response
6188Type Name Description
6189
6190TPM_ST tag see clause 6
6191UINT32 responseSize
6192TPM_RC responseCode
6193
6194TPM2B_DIGEST outHMAC the returned HMAC in a sized buffer
6195
6196
6197
6198
6199Page 126 TCG Published Family “2.0”
6200October 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
62071 #include "InternalRoutines.h"
62082 #include "HMAC_fp.h"
62093 #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 {
622510 HMAC_STATE hmacState;
622611 OBJECT *hmacObject;
622712 TPMI_ALG_HASH hashAlg;
622813 TPMT_PUBLIC *publicArea;
622914
623015 // Input Validation
623116
623217 // Get HMAC key object and public area pointers
623318 hmacObject = ObjectGet(in->handle);
623419 publicArea = &hmacObject->publicArea;
623520
623621 // Make sure that the key is an HMAC key
623722 if(publicArea->type != TPM_ALG_KEYEDHASH)
623823 return TPM_RCS_TYPE + RC_HMAC_handle;
623924
624025 // and that it is unrestricted
624126 if(publicArea->objectAttributes.restricted == SET)
624227 return TPM_RCS_ATTRIBUTES + RC_HMAC_handle;
624328
624429 // and that it is a signing key
624530 if(publicArea->objectAttributes.sign != SET)
624631 return TPM_RCS_KEY + RC_HMAC_handle;
624732
624833 // See if the key has a default
624934 if(publicArea->parameters.keyedHashDetail.scheme.scheme == TPM_ALG_NULL)
625035 // it doesn't so use the input value
625136 hashAlg = in->hashAlg;
625237 else
625338 {
625439 // key has a default so use it
625540 hashAlg
625641 = publicArea->parameters.keyedHashDetail.scheme.details.hmac.hashAlg;
625742 // and verify that the input was either the TPM_ALG_NULL or the default
625843 if(in->hashAlg != TPM_ALG_NULL && in->hashAlg != hashAlg)
625944 hashAlg = TPM_ALG_NULL;
626045 }
626146 // if we ended up without a hash algorith then return an error
626247 if(hashAlg == TPM_ALG_NULL)
626348 return TPM_RCS_VALUE + RC_HMAC_hashAlg;
626449
626550 // Command Output
626651
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
627252 // Start HMAC stack
627353 out->outHMAC.t.size = CryptStartHMAC2B(hashAlg,
627454 &hmacObject->sensitive.sensitive.bits.b,
627555 &hmacState);
627656 // Adding HMAC data
627757 CryptUpdateDigest2B(&hmacState, &in->buffer.b);
627858
627959 // Complete HMAC
628060 CryptCompleteHMAC2B(&hmacState, &out->outHMAC.b);
628161
628262 return TPM_RC_SUCCESS;
628363 }
628464 #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
629416 Random Number Generator
6295
629616.1 TPM2_GetRandom
6297
629816.1.1 General Description
6299
6300This command returns the next bytesRequested octets from the random number generator (RNG).
6301
6302NOTE 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
6307If bytesRequested is more than will fit into a TPM2B_DIGEST on the TPM, no error is returned but the
6308TPM will only return as much data as will fit into a TPM2B_DIGEST buffer for the TPM.
6309
6310NOTE 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
6317Family “2.0” TCG Published Page 129
6318Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
6319 Part 3: Commands Trusted Platform Module Library
6320
6321
632216.1.2 Command and Response
6323
6324 Table 62 — TPM2_GetRandom Command
6325Type Name Description
6326
6327 TPM_ST_SESSIONS if an audit or encrypt session is
6328TPMI_ST_COMMAND_TAG tag
6329 present; otherwise, TPM_ST_NO_SESSIONS
6330UINT32 commandSize
6331TPM_CC commandCode TPM_CC_GetRandom
6332
6333UINT16 bytesRequested number of octets to return
6334
6335
6336 Table 63 — TPM2_GetRandom Response
6337Type Name Description
6338
6339TPM_ST tag see clause 6
6340UINT32 responseSize
6341TPM_RC responseCode
6342
6343TPM2B_DIGEST randomBytes the random octets
6344
6345
6346
6347
6348Page 130 TCG Published Family “2.0”
6349October 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 {
636510 // Command Output
636611
636712 // if the requested bytes exceed the output buffer size, generates the
636813 // maximum bytes that the output buffer allows
636914 if(in->bytesRequested > sizeof(TPMU_HA))
637015 out->randomBytes.t.size = sizeof(TPMU_HA);
637116 else
637217 out->randomBytes.t.size = in->bytesRequested;
637318
637419 CryptGenerateRandom(out->randomBytes.t.size, out->randomBytes.t.buffer);
637520
637621 return TPM_RC_SUCCESS;
637722 }
637823 #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
638816.2 TPM2_StirRandom
6389
639016.2.1 General Description
6391
6392This command is used to add "additional information" to the RNG state.
6393
6394NOTE The "additional information" is as defined in SP800 -90A.
6395
6396The inData parameter may not be larger than 128 octets.
6397
6398
6399
6400
6401Page 132 TCG Published Family “2.0”
6402October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
6403 Trusted Platform Module Library Part 3: Commands
6404
6405
6406
640716.2.2 Command and Response
6408
6409 Table 64 — TPM2_StirRandom Command
6410Type Name Description
6411
6412 TPM_ST_SESSIONS if an audit or decrypt session is
6413TPMI_ST_COMMAND_TAG tag
6414 present; otherwise, TPM_ST_NO_SESSIONS
6415UINT32 commandSize
6416TPM_CC commandCode TPM_CC_StirRandom {NV}
6417
6418TPM2B_SENSITIVE_DATA inData additional information
6419
6420
6421 Table 65 — TPM2_StirRandom Response
6422Type Name Description
6423
6424TPM_ST tag see clause 6
6425UINT32 responseSize
6426TPM_RC responseCode
6427
6428
6429
6430
6431Family “2.0” TCG Published Page 133
6432Level 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
644810 CryptStirRandom(in->inData.t.size, in->inData.t.buffer);
644911
645012 return TPM_RC_SUCCESS;
645113 }
645214 #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
646217 Hash/HMAC/Event Sequences
6463
646417.1 Introduction
6465
6466All of the commands in this group are to support sequences for which an intermediate state must be
6467maintained. For a description of sequences, see “Hash, HMAC, and Event Sequences” in TPM 2.0 Part 1.
6468
646917.2 TPM2_HMAC_Start
6470
647117.2.1 General Description
6472
6473This command starts an HMAC sequence. The TPM will create and initialize an HMAC sequence
6474structure, assign a handle to the sequence, and set the authValue of the sequence object to the value in
6475auth.
6476
6477NOTE The structure of a sequence object is vendor -dependent.
6478
6479The caller shall provide proper authorization for use of handle.
6480If the sign attribute is not SET in the key referenced by handle then the TPM shall return
6481TPM_RC_ATTRIBUTES. If the key type is not TPM_ALG_KEYEDHASH then the TPM shall return
6482TPM_RC_TYPE. If the key referenced by handle has the restricted attribute SET, the TPM shall return
6483TPM_RC_ATTRIBUTES.
6484If the default scheme of the key referenced by handle is not TPM_ALG_NULL, then the hashAlg
6485parameter is required to be either the same as the key’s default or TPM_ALG_NULL (TPM_RC_VALUE).
6486If the default scheme of the key is TPM_ALG_NULL, then hashAlg is required to be a valid hash and not
6487TPM_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
6505Family “2.0” TCG Published Page 135
6506Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
6507 Part 3: Commands Trusted Platform Module Library
6508
6509
6510
651117.2.2 Command and Response
6512
6513 Table 67 — TPM2_HMAC_Start Command
6514Type Name Description
6515
6516TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
6517UINT32 commandSize
6518TPM_CC commandCode TPM_CC_HMAC_Start
6519
6520 handle of an HMAC key
6521TPMI_DH_OBJECT @handle Auth Index: 1
6522 Auth Role: USER
6523
6524TPM2B_AUTH auth authorization value for subsequent use of the sequence
6525TPMI_ALG_HASH+ hashAlg the hash algorithm to use for the HMAC
6526
6527
6528 Table 68 — TPM2_HMAC_Start Response
6529Type Name Description
6530
6531TPM_ST tag see clause 6
6532UINT32 responseSize
6533TPM_RC responseCode
6534
6535TPMI_DH_OBJECT sequenceHandle a handle to reference the sequence
6536
6537
6538
6539
6540Page 136 TCG Published Family “2.0”
6541October 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
65481 #include "InternalRoutines.h"
65492 #include "HMAC_Start_fp.h"
65503 #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 {
656710 OBJECT *hmacObject;
656811 TPMT_PUBLIC *publicArea;
656912 TPM_ALG_ID hashAlg;
657013
657114 // Input Validation
657215
657316 // Get HMAC key object and public area pointers
657417 hmacObject = ObjectGet(in->handle);
657518 publicArea = &hmacObject->publicArea;
657619
657720 // Make sure that the key is an HMAC key
657821 if(publicArea->type != TPM_ALG_KEYEDHASH)
657922 return TPM_RCS_TYPE + RC_HMAC_Start_handle;
658023
658124 // and that it is unrestricted
658225 if(publicArea->objectAttributes.restricted == SET)
658326 return TPM_RCS_ATTRIBUTES + RC_HMAC_Start_handle;
658427
658528 // and that it is a signing key
658629 if(publicArea->objectAttributes.sign != SET)
658730 return TPM_RCS_KEY + RC_HMAC_Start_handle;
658831
658932 // See if the key has a default
659033 if(publicArea->parameters.keyedHashDetail.scheme.scheme == TPM_ALG_NULL)
659134 // it doesn't so use the input value
659235 hashAlg = in->hashAlg;
659336 else
659437 {
659538 // key has a default so use it
659639 hashAlg
659740 = publicArea->parameters.keyedHashDetail.scheme.details.hmac.hashAlg;
659841 // and verify that the input was either the TPM_ALG_NULL or the default
659942 if(in->hashAlg != TPM_ALG_NULL && in->hashAlg != hashAlg)
660043 hashAlg = TPM_ALG_NULL;
660144 }
660245 // if we ended up without a hash algorith then return an error
660346 if(hashAlg == TPM_ALG_NULL)
660447 return TPM_RCS_VALUE + RC_HMAC_Start_hashAlg;
660548
660649 // Internal Data Update
660750
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
661351 // Create a HMAC sequence object. A TPM_RC_OBJECT_MEMORY error may be
661452 // returned at this point
661553 return ObjectCreateHMACSequence(hashAlg,
661654 in->handle,
661755 &in->auth,
661856 &out->sequenceHandle);
661957 }
662058 #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
663017.3 TPM2_HashSequenceStart
6631
663217.3.1 General Description
6633
6634This command starts a hash or an Event Sequence. If hashAlg is an implemented hash, then a hash
6635sequence is started. If hashAlg is TPM_ALG_NULL, then an Event Sequence is started. If hashAlg is
6636neither an implemented algorithm nor TPM_ALG_NULL, then the TPM shall return TPM_RC_HASH.
6637Depending on hashAlg, the TPM will create and initialize a Hash Sequence context or an Event
6638Sequence context. Additionally, it will assign a handle to the context and set the authValue of the context
6639to the value in auth. A sequence context for an Event (hashAlg = TPM_ALG_NULL) contains a hash
6640context for each of the PCR banks implemented on the TPM.
6641
6642
6643
6644
6645Family “2.0” TCG Published Page 139
6646Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
6647 Part 3: Commands Trusted Platform Module Library
6648
6649
6650
665117.3.2 Command and Response
6652
6653 Table 69 — TPM2_HashSequenceStart Command
6654Type Name Description
6655
6656 TPM_ST_SESSIONS if an audit or decrypt session is
6657TPMI_ST_COMMAND_TAG tag
6658 present; otherwise, TPM_ST_NO_SESSIONS
6659UINT32 commandSize
6660TPM_CC commandCode TPM_CC_HashSequenceStart
6661
6662TPM2B_AUTH auth authorization value for subsequent use of the sequence
6663 the hash algorithm to use for the hash sequence
6664TPMI_ALG_HASH+ hashAlg
6665 An Event Sequence starts if this is TPM_ALG_NULL.
6666
6667
6668 Table 70 — TPM2_HashSequenceStart Response
6669Type Name Description
6670
6671TPM_ST tag see clause 6
6672UINT32 responseSize
6673TPM_RC responseCode
6674
6675TPMI_DH_OBJECT sequenceHandle a handle to reference the sequence
6676
6677
6678
6679
6680Page 140 TCG Published Family “2.0”
6681October 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
66881 #include "InternalRoutines.h"
66892 #include "HashSequenceStart_fp.h"
66903 #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 {
670310 // Internal Data Update
670411
670512 if(in->hashAlg == TPM_ALG_NULL)
670613 // Start a event sequence. A TPM_RC_OBJECT_MEMORY error may be
670714 // returned at this point
670815 return ObjectCreateEventSequence(&in->auth, &out->sequenceHandle);
670916
671017 // Start a hash sequence. A TPM_RC_OBJECT_MEMORY error may be
671118 // returned at this point
671219 return ObjectCreateHashSequence(in->hashAlg, &in->auth, &out->sequenceHandle);
671320 }
671421 #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
672417.4 TPM2_SequenceUpdate
6725
672617.4.1 General Description
6727
6728This command is used to add data to a hash or HMAC sequence. The amount of data in buffer may be
6729any size up to the limits of the TPM.
6730
6731NOTE 1 In all TPM, a buffer size of 1,024 octets is allowed.
6732
6733Proper authorization for the sequence object associated with sequenceHandle is required. If an
6734authorization or audit of this command requires computation of a cpHash and an rpHash, the Name
6735associated with sequenceHandle will be the Empty Buffer.
6736If the command does not return TPM_RC_SUCCESS, the state of the sequence is unmodified.
6737If the sequence is intended to produce a digest that will be signed by a restricted signing key, then the
6738first block of data shall contain sizeof(TPM_GENERATED) octets and the first octets shall not be
6739TPM_GENERATED_VALUE.
6740
6741NOTE 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
6747Page 142 TCG Published Family “2.0”
6748October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
6749 Trusted Platform Module Library Part 3: Commands
6750
6751
675217.4.2 Command and Response
6753
6754 Table 71 — TPM2_SequenceUpdate Command
6755Type Name Description
6756
6757TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
6758UINT32 commandSize
6759TPM_CC commandCode TPM_CC_SequenceUpdate
6760
6761 handle for the sequence object
6762TPMI_DH_OBJECT @sequenceHandle Auth Index: 1
6763 Auth Role: USER
6764
6765TPM2B_MAX_BUFFER buffer data to be added to hash
6766
6767
6768 Table 72 — TPM2_SequenceUpdate Response
6769Type Name Description
6770
6771TPM_ST tag see clause 6
6772UINT32 responseSize
6773TPM_RC responseCode
6774
6775
6776
6777
6778Family “2.0” TCG Published Page 143
6779Level 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
67861 #include "InternalRoutines.h"
67872 #include "SequenceUpdate_fp.h"
67883 #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;
680210
680311 // Input Validation
680412
680513 // Get sequence object pointer
680614 object = ObjectGet(in->sequenceHandle);
680715
680816 // Check that referenced object is a sequence object.
680917 if(!ObjectIsSequence(object))
681018 return TPM_RC_MODE + RC_SequenceUpdate_sequenceHandle;
681119
681220 // Internal Data Update
681321
681422 if(object->attributes.eventSeq == SET)
681523 {
681624 // Update event sequence object
681725 UINT32 i;
681826 HASH_OBJECT *hashObject = (HASH_OBJECT *)object;
681927 for(i = 0; i < HASH_COUNT; i++)
682028 {
682129 // Update sequence object
682230 CryptUpdateDigest2B(&hashObject->state.hashState[i], &in->buffer.b);
682331 }
682432 }
682533 else
682634 {
682735 HASH_OBJECT *hashObject = (HASH_OBJECT *)object;
682836
682937 // Update hash/HMAC sequence object
683038 if(hashObject->attributes.hashSeq == SET)
683139 {
683240 // Is this the first block of the sequence
683341 if(hashObject->attributes.firstBlock == CLEAR)
683442 {
683543 // If so, indicate that first block was received
683644 hashObject->attributes.firstBlock = SET;
683745
683846 // Check the first block to see if the first block can contain
683947 // the TPM_GENERATED_VALUE. If it does, it is not safe for
684048 // a ticket.
684149 if(TicketIsSafe(&in->buffer.b))
684250 hashObject->attributes.ticketSafe = SET;
684351 }
684452 // Update sequence object hash/HMAC stack
684553 CryptUpdateDigest2B(&hashObject->state.hashState[0], &in->buffer.b);
684654
684755 }
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
685356 else if(object->attributes.hmacSeq == SET)
685457 {
685558 HASH_OBJECT *hashObject = (HASH_OBJECT *)object;
685659
685760 // Update sequence object hash/HMAC stack
685861 CryptUpdateDigest2B(&hashObject->state.hmacState, &in->buffer.b);
685962 }
686063 }
686164
686265 return TPM_RC_SUCCESS;
686366 }
686467 #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
687417.5 TPM2_SequenceComplete
6875
687617.5.1 General Description
6877
6878This command adds the last part of data, if any, to a hash/HMAC sequence and returns the result.
6879
6880NOTE 1 This command is not used to complete an Event Sequence. TPM2_EventSequenceComplete() is
6881 used for that purpose.
6882
6883For a hash sequence, if the results of the hash will be used in a signing operation that uses a restricted
6884signing key, then the ticket returned by this command can indicate that the hash is safe to sign.
6885If the digest is not safe to sign, then validation will be a TPMT_TK_HASHCHECK with the hierarchy set to
6886TPM_RH_NULL and digest set to the Empty Buffer.
6887
6888NOTE 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
6892NOTE 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
6895If sequenceHandle references an Event Sequence, then the TPM shall return TPM_RC_MODE.
6896Proper authorization for the sequence object associated with sequenceHandle is required. If an
6897authorization or audit of this command requires computation of a cpHash and an rpHash, the Name
6898associated with sequenceHandle will be the Empty Buffer.
6899If this command completes successfully, the sequenceHandle object will be flushed.
6900
6901
6902
6903
6904Page 146 TCG Published Family “2.0”
6905October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
6906 Trusted Platform Module Library Part 3: Commands
6907
6908
6909
691017.5.2 Command and Response
6911
6912 Table 73 — TPM2_SequenceComplete Command
6913Type Name Description
6914
6915TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
6916UINT32 commandSize
6917TPM_CC commandCode TPM_CC_SequenceComplete {F}
6918
6919 authorization for the sequence
6920TPMI_DH_OBJECT @sequenceHandle Auth Index: 1
6921 Auth Role: USER
6922
6923TPM2B_MAX_BUFFER buffer data to be added to the hash/HMAC
6924TPMI_RH_HIERARCHY+ hierarchy hierarchy of the ticket for a hash
6925
6926
6927 Table 74 — TPM2_SequenceComplete Response
6928Type Name Description
6929
6930TPM_ST tag see clause 6
6931UINT32 responseSize
6932TPM_RC responseCode
6933
6934TPM2B_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
6937TPMT_TK_HASHCHECK validation TPM_GENERATED_VALUE
6938 This is a NULL Ticket when the sequence is HMAC.
6939
6940
6941
6942
6943Family “2.0” TCG Published Page 147
6944Level 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
69511 #include "InternalRoutines.h"
69522 #include "SequenceComplete_fp.h"
69533 #ifdef TPM_CC_SequenceComplete // Conditional expansion of this file
69544 #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 )
696710 {
696811 OBJECT *object;
696912
697013 // Input validation
697114
697215 // Get hash object pointer
697316 object = ObjectGet(in->sequenceHandle);
697417
697518 // input handle must be a hash or HMAC sequence object.
697619 if( object->attributes.hashSeq == CLEAR
697720 && object->attributes.hmacSeq == CLEAR)
697821 return TPM_RC_MODE + RC_SequenceComplete_sequenceHandle;
697922
698023 // Command Output
698124
698225 if(object->attributes.hashSeq == SET) // sequence object for hash
698326 {
698427 // Update last piece of data
698528 HASH_OBJECT *hashObject = (HASH_OBJECT *)object;
698629
698730 // Get the hash algorithm before the algorithm is lost in CryptCompleteHash
698831 TPM_ALG_ID hashAlg = hashObject->state.hashState[0].state.hashAlg;
698932
699033 CryptUpdateDigest2B(&hashObject->state.hashState[0], &in->buffer.b);
699134
699235 // Complete hash
699336 out->result.t.size
699437 = CryptGetHashDigestSize(
699538 CryptGetContextAlg(&hashObject->state.hashState[0]));
699639
699740 CryptCompleteHash2B(&hashObject->state.hashState[0], &out->result.b);
699841
699942 // Check if the first block of the sequence has been received
700043 if(hashObject->attributes.firstBlock == CLEAR)
700144 {
700245 // If not, then this is the first block so see if it is 'safe'
700346 // to sign.
700447 if(TicketIsSafe(&in->buffer.b))
700548 hashObject->attributes.ticketSafe = SET;
700649 }
700750
700851 // Output ticket
700952 out->validation.tag = TPM_ST_HASHCHECK;
701053 out->validation.hierarchy = in->hierarchy;
701154
701255 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
701856 {
701957 // Ticket is not required
702058 out->validation.digest.t.size = 0;
702159 }
702260 else if(object->attributes.ticketSafe == CLEAR)
702361 {
702462 // Ticket is not safe to generate
702563 out->validation.hierarchy = TPM_RH_NULL;
702664 out->validation.digest.t.size = 0;
702765 }
702866 else
702967 {
703068 // Compute ticket
703169 TicketComputeHashCheck(out->validation.hierarchy, hashAlg,
703270 &out->result, &out->validation);
703371 }
703472 }
703573 else
703674 {
703775 HASH_OBJECT *hashObject = (HASH_OBJECT *)object;
703876
703977 // Update last piece of data
704078 CryptUpdateDigest2B(&hashObject->state.hmacState, &in->buffer.b);
704179 // Complete hash/HMAC
704280 out->result.t.size =
704381 CryptGetHashDigestSize(
704482 CryptGetContextAlg(&hashObject->state.hmacState.hashState));
704583 CryptCompleteHMAC2B(&(hashObject->state.hmacState), &out->result.b);
704684
704785 // No ticket is generated for HMAC sequence
704886 out->validation.tag = TPM_ST_HASHCHECK;
704987 out->validation.hierarchy = TPM_RH_NULL;
705088 out->validation.digest.t.size = 0;
705189 }
705290
705391 // Internal Data Update
705492
705593 // mark sequence object as evict so it will be flushed on the way out
705694 object->attributes.evict = SET;
705795
705896 return TPM_RC_SUCCESS;
705997 }
706098 #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
707017.6 TPM2_EventSequenceComplete
7071
707217.6.1 General Description
7073
7074This command adds the last part of data, if any, to an Event Sequence and returns the result in a digest
7075list. If pcrHandle references a PCR and not TPM_RH_NULL, then the returned digest list is processed in
7076the same manner as the digest list input parameter to TPM2_PCR_Extend() with the pcrHandle in each
7077bank extended with the associated digest value.
7078If sequenceHandle references a hash or HMAC sequence, the TPM shall return TPM_RC_MODE.
7079Proper authorization for the sequence object associated with sequenceHandle is required. If an
7080authorization or audit of this command requires computation of a cpHash and an rpHash, the Name
7081associated with sequenceHandle will be the Empty Buffer.
7082If this command completes successfully, the sequenceHandle object will be flushed.
7083
7084
7085
7086
7087Page 150 TCG Published Family “2.0”
7088October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
7089 Trusted Platform Module Library Part 3: Commands
7090
7091
7092
709317.6.2 Command and Response
7094
7095 Table 75 — TPM2_EventSequenceComplete Command
7096Type Name Description
7097
7098TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
7099UINT32 commandSize
7100TPM_CC commandCode TPM_CC_EventSequenceComplete {NV F}
7101
7102 PCR to be extended with the Event data
7103TPMI_DH_PCR+ @ pcrHandle Auth Index: 1
7104 Auth Role: USER
7105 authorization for the sequence
7106TPMI_DH_OBJECT @sequenceHandle Auth Index: 2
7107 Auth Role: USER
7108
7109TPM2B_MAX_BUFFER buffer data to be added to the Event
7110
7111
7112 Table 76 — TPM2_EventSequenceComplete Response
7113Type Name Description
7114
7115TPM_ST tag see clause 6
7116UINT32 responseSize
7117TPM_RC responseCode
7118
7119TPML_DIGEST_VALUES results list of digests computed for the PCR
7120
7121
7122
7123
7124Family “2.0” TCG Published Page 151
7125Level 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
71321 #include "InternalRoutines.h"
71332 #include "EventSequenceComplete_fp.h"
71343 #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 {
714810 TPM_RC result;
714911 HASH_OBJECT *hashObject;
715012 UINT32 i;
715113 TPM_ALG_ID hashAlg;
715214
715315 // Input validation
715416
715517 // get the event sequence object pointer
715618 hashObject = (HASH_OBJECT *)ObjectGet(in->sequenceHandle);
715719
715820 // input handle must reference an event sequence object
715921 if(hashObject->attributes.eventSeq != SET)
716022 return TPM_RC_MODE + RC_EventSequenceComplete_sequenceHandle;
716123
716224 // see if a PCR extend is requested in call
716325 if(in->pcrHandle != TPM_RH_NULL)
716426 {
716527 // see if extend of the PCR is allowed at the locality of the command,
716628 if(!PCRIsExtendAllowed(in->pcrHandle))
716729 return TPM_RC_LOCALITY;
716830 // if an extend is going to take place, then check to see if there has
716931 // been an orderly shutdown. If so, and the selected PCR is one of the
717032 // state saved PCR, then the orderly state has to change. The orderly state
717133 // does not change for PCR that are not preserved.
717234 // NOTE: This doesn't just check for Shutdown(STATE) because the orderly
717335 // state will have to change if this is a state-saved PCR regardless
717436 // of the current state. This is because a subsequent Shutdown(STATE) will
717537 // check to see if there was an orderly shutdown and not do anything if
717638 // there was. So, this must indicate that a future Shutdown(STATE) has
717739 // something to do.
717840 if(gp.orderlyState != SHUTDOWN_NONE && PCRIsStateSaved(in->pcrHandle))
717941 {
718042 result = NvIsAvailable();
718143 if(result != TPM_RC_SUCCESS) return result;
718244 g_clearOrderly = TRUE;
718345 }
718446 }
718547
718648 // Command Output
718749
718850 out->results.count = 0;
718951
719052 for(i = 0; i < HASH_COUNT; i++)
719153 {
719254 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
719855 // Update last piece of data
719956 CryptUpdateDigest2B(&hashObject->state.hashState[i], &in->buffer.b);
720057 // Complete hash
720158 out->results.digests[out->results.count].hashAlg = hashAlg;
720259 CryptCompleteHash(&hashObject->state.hashState[i],
720360 CryptGetHashDigestSize(hashAlg),
720461 (BYTE *) &out->results.digests[out->results.count].digest);
720562
720663 // Extend PCR
720764 if(in->pcrHandle != TPM_RH_NULL)
720865 PCRExtend(in->pcrHandle, hashAlg,
720966 CryptGetHashDigestSize(hashAlg),
721067 (BYTE *) &out->results.digests[out->results.count].digest);
721168 out->results.count++;
721269 }
721370
721471 // Internal Data Update
721572
721673 // mark sequence object as evict so it will be flushed on the way out
721774 hashObject->attributes.evict = SET;
721875
721976 return TPM_RC_SUCCESS;
722077 }
722178 #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
723118 Attestation Commands
7232
723318.1 Introduction
7234
7235The attestation commands cause the TPM to sign an internally generated data structure. The contents of
7236the data structure vary according to the command.
7237All signing commands include a parameter (typically inScheme) for the caller to specify a scheme to be
7238used for the signing operation. This scheme will be applied only if the scheme of the key is
7239TPM_ALG_NULL or the key handle is TPM_RH_NULL. If the scheme for signHandle is not
7240TPM_ALG_NULL, then inScheme.scheme shall be TPM_ALG_NULL or the same as scheme in the
7241public area of the key. If the scheme for signHandle is TPM_ALG_NULL or the key handle is
7242TPM_RH_NULL, then inScheme will be used for the signing operation and may not be TPM_ALG_NULL.
7243The TPM shall return TPM_RC_SCHEME to indicate that the scheme is not appropriate.
7244For a signing key that is not restricted, the caller may specify the scheme to be used as long as the
7245scheme is compatible with the family of the key (for example, TPM_ALG_RSAPSS cannot be selected for
7246an ECC key). If the caller sets scheme to TPM_ALG_NULL, then the default scheme of the key is used.
7247For a restricted signing key, the key's scheme cannot be TPM_ALG_NULL and cannot be overridden.
7248If the handle for the signing key (signHandle) is TPM_RH_NULL, then all of the actions of the command
7249are performed and the attestation block is “signed” with the NULL Signature.
7250
7251NOTE 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
7254NOTE 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
7258TPM2_NV_Certify() is an attestation command that is documented in 1. The remaining attestation
7259commands are collected in the remainder of this clause.
7260Each of the attestation structures contains a TPMS_CLOCK_INFO structure and a firmware version
7261number. These values may be considered privacy-sensitive, because they would aid in the correlation of
7262attestations by different keys. To provide improved privacy, the resetCount, restartCount, and
7263firmwareVersion numbers are obfuscated when the signing key is not in the Endorsement or Platform
7264hierarchies.
7265The obfuscation value is computed by:
7266 obfuscation ≔ KDFa(signHandle→nameAlg, shProof, “OBFUSCATE”, signHandle→QN, 0, 128) (3)
7267Of the returned 128 bits, 64 bits are added to the versionNumber field of the attestation structure; 32 bits
7268are added to the clockInfo.resetCount and 32 bits are added to the clockInfo.restartCount. The order in
7269which the bits are added is implementation-dependent.
7270
7271NOTE 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
7274When the signing key is TPM_RH_NULL, the data structure is produced but not signed; and the values in
7275the signed data structure are obfuscated. When computing the obfuscation value for TPM_RH_NULL, the
7276hash used for context integrity is used.
7277
7278NOTE 4 The QN for TPM_RH_NULL is TPM_RH_NULL.
7279
7280If the signing scheme of signHandle is an anonymous scheme, then the attestation blocks will not contain
7281the Qualified Name of the signHandle.
7282Each of the attestation structures allows the caller to provide some qualifying data (qualifyingData). For
7283most signing schemes, this value will be placed in the TPMS_ATTEST.extraData parameter that is then
7284
7285Page 154 TCG Published Family “2.0”
7286October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
7287 Trusted Platform Module Library Part 3: Commands
7288
7289hashed and signed. However, for some schemes such as ECDAA, the qualifyingData is used in a
7290different manner (for details, see “ECDAA” in TPM 2.0 Part 1).
7291
7292
7293
7294
7295Family “2.0” TCG Published Page 155
7296Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
7297 Part 3: Commands Trusted Platform Module Library
7298
7299
7300
730118.2 TPM2_Certify
7302
730318.2.1 General Description
7304
7305The purpose of this command is to prove that an object with a specific Name is loaded in the TPM. By
7306certifying that the object is loaded, the TPM warrants that a public area with a given Name is self-
7307consistent and associated with a valid sensitive area. If a relying party has a public area that has the
7308same Name as a Name certified with this command, then the values in that public area are correct.
7309
7310NOTE 1 See 18.1 for description of how the signing scheme is selected.
7311
7312Authorization for objectHandle requires ADMIN role authorization. If performed with a policy session, the
7313session shall have a policySession→commandCode set to TPM_CC_Certify. This indicates that the
7314policy that is being used is a policy that is for certification, and not a policy that would approve another
7315use. That is, authority to use an object does not grant authority to certify the object.
7316The object may be any object that is loaded with TPM2_Load() or TPM2_CreatePrimary(). An object that
7317only has its public area loaded cannot be certified.
7318
7319NOTE 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
7323The certification includes the Name and Qualified Name of the certified object as well as the Name and
7324the Qualified Name of the certifying object.
7325
7326NOTE 2 If signHandle is TPM_RH_NULL, the TPMS_ATTEST structure is returned and signature is a NULL
7327 Signature.
7328
7329
7330
7331
7332Page 156 TCG Published Family “2.0”
7333October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
7334 Trusted Platform Module Library Part 3: Commands
7335
7336
7337
733818.2.2 Command and Response
7339
7340 Table 77 — TPM2_Certify Command
7341Type Name Description
7342
7343TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
7344UINT32 commandSize
7345TPM_CC commandCode TPM_CC_Certify
7346
7347 handle of the object to be certified
7348TPMI_DH_OBJECT @objectHandle Auth Index: 1
7349 Auth Role: ADMIN
7350 handle of the key used to sign the attestation structure
7351TPMI_DH_OBJECT+ @signHandle Auth Index: 2
7352 Auth Role: USER
7353
7354TPM2B_DATA qualifyingData user provided qualifying data
7355 signing scheme to use if the scheme for signHandle is
7356TPMT_SIG_SCHEME+ inScheme
7357 TPM_ALG_NULL
7358
7359
7360 Table 78 — TPM2_Certify Response
7361Type Name Description
7362
7363TPM_ST tag see clause 6
7364UINT32 responseSize
7365TPM_RC responseCode .
7366
7367TPM2B_ATTEST certifyInfo the structure that was signed
7368 the asymmetric signature over certifyInfo using the key
7369TPMT_SIGNATURE signature
7370 referenced by signHandle
7371
7372
7373
7374
7375Family “2.0” TCG Published Page 157
7376Level 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
73831 #include "InternalRoutines.h"
73842 #include "Attest_spt_fp.h"
73853 #include "Certify_fp.h"
73864 #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 )
740310 {
740411 TPM_RC result;
740512 TPMS_ATTEST certifyInfo;
740613
740714 // Command Output
740815
740916 // Filling in attest information
741017 // Common fields
741118 result = FillInAttestInfo(in->signHandle,
741219 &in->inScheme,
741320 &in->qualifyingData,
741421 &certifyInfo);
741522 if(result != TPM_RC_SUCCESS)
741623 {
741724 if(result == TPM_RC_KEY)
741825 return TPM_RC_KEY + RC_Certify_signHandle;
741926 else
742027 return RcSafeAddToResult(result, RC_Certify_inScheme);
742128 }
742229 // Certify specific fields
742330 // Attestation type
742431 certifyInfo.type = TPM_ST_ATTEST_CERTIFY;
742532 // Certified object name
742633 certifyInfo.attested.certify.name.t.size =
742734 ObjectGetName(in->objectHandle,
742835 &certifyInfo.attested.certify.name.t.name);
742936 // Certified object qualified name
743037 ObjectGetQualifiedName(in->objectHandle,
743138 &certifyInfo.attested.certify.qualifiedName);
743239
743340 // Sign attestation structure. A NULL signature will be returned if
743441 // signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE,
743542 // TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned
743643 // by SignAttestInfo()
743744 result = SignAttestInfo(in->signHandle,
743845 &in->inScheme,
743946 &certifyInfo,
744047 &in->qualifyingData,
744148 &out->certifyInfo,
744249 &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
744850
744951 // TPM_RC_ATTRIBUTES cannot be returned here as FillInAttestInfo would already
745052 // have returned TPM_RC_KEY
745153 pAssert(result != TPM_RC_ATTRIBUTES);
745254
745355 if(result != TPM_RC_SUCCESS)
745456 return result;
745557
745658 // orderly state should be cleared because of the reporting of clock info
745759 // if signing happens
745860 if(in->signHandle != TPM_RH_NULL)
745961 g_clearOrderly = TRUE;
746062
746163 return TPM_RC_SUCCESS;
746264 }
746365 #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
747318.3 TPM2_CertifyCreation
7474
747518.3.1 General Description
7476
7477This command is used to prove the association between an object and its creation data. The TPM will
7478validate that the ticket was produced by the TPM and that the ticket validates the association between a
7479loaded public area and the provided hash of the creation data (creationHash).
7480
7481NOTE 1 See 18.1 for description of how the signing scheme is selected.
7482
7483The 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)
7485This ticket is then compared to creation ticket. If the tickets are not the same, the TPM shall return
7486TPM_RC_TICKET.
7487If the ticket is valid, then the TPM will create a TPMS_ATTEST structure and place creationHash of the
7488command in the creationHash field of the structure. The Name associated with objectHandle will be
7489included in the attestation data that is then signed using the key associated with signHandle.
7490
7491NOTE 2 If signHandle is TPM_RH_NULL, the TPMS_ATTEST structure is returned and signature is a NULL
7492 Signature.
7493
7494ObjectHandle may be any object that is loaded with TPM2_Load() or TPM2_CreatePrimary().
7495
7496
7497
7498
7499Page 160 TCG Published Family “2.0”
7500October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
7501 Trusted Platform Module Library Part 3: Commands
7502
7503
7504
750518.3.2 Command and Response
7506
7507 Table 79 — TPM2_CertifyCreation Command
7508Type Name Description
7509
7510TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
7511UINT32 commandSize
7512TPM_CC commandCode TPM_CC_CertifyCreation
7513
7514 handle of the key that will sign the attestation block
7515TPMI_DH_OBJECT+ @signHandle Auth Index: 1
7516 Auth Role: USER
7517 the object associated with the creation data
7518TPMI_DH_OBJECT objectHandle
7519 Auth Index: None
7520
7521TPM2B_DATA qualifyingData user-provided qualifying data
7522 hash of the creation data produced by TPM2_Create()
7523TPM2B_DIGEST creationHash
7524 or TPM2_CreatePrimary()
7525 signing scheme to use if the scheme for signHandle is
7526TPMT_SIG_SCHEME+ inScheme
7527 TPM_ALG_NULL
7528 ticket produced by TPM2_Create() or
7529TPMT_TK_CREATION creationTicket
7530 TPM2_CreatePrimary()
7531
7532
7533 Table 80 — TPM2_CertifyCreation Response
7534Type Name Description
7535
7536TPM_ST tag see clause 6
7537UINT32 responseSize
7538TPM_RC responseCode
7539
7540TPM2B_ATTEST certifyInfo the structure that was signed
7541TPMT_SIGNATURE signature the signature over certifyInfo
7542
7543
7544
7545
7546Family “2.0” TCG Published Page 161
7547Level 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
75541 #include "InternalRoutines.h"
75552 #include "Attest_spt_fp.h"
75563 #include "CertifyCreation_fp.h"
75574 #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 )
757510 {
757611 TPM_RC result;
757712 TPM2B_NAME name;
757813 TPMT_TK_CREATION ticket;
757914 TPMS_ATTEST certifyInfo;
758015
758116 // Input Validation
758217
758318 // CertifyCreation specific input validation
758419 // Get certified object name
758520 name.t.size = ObjectGetName(in->objectHandle, &name.t.name);
758621 // Re-compute ticket
758722 TicketComputeCreation(in->creationTicket.hierarchy, &name,
758823 &in->creationHash, &ticket);
758924 // Compare ticket
759025 if(!Memory2BEqual(&ticket.digest.b, &in->creationTicket.digest.b))
759126 return TPM_RC_TICKET + RC_CertifyCreation_creationTicket;
759227
759328 // Command Output
759429 // Common fields
759530 result = FillInAttestInfo(in->signHandle, &in->inScheme, &in->qualifyingData,
759631 &certifyInfo);
759732 if(result != TPM_RC_SUCCESS)
759833 {
759934 if(result == TPM_RC_KEY)
760035 return TPM_RC_KEY + RC_CertifyCreation_signHandle;
760136 else
760237 return RcSafeAddToResult(result, RC_CertifyCreation_inScheme);
760338 }
760439
760540 // CertifyCreation specific fields
760641 // Attestation type
760742 certifyInfo.type = TPM_ST_ATTEST_CREATION;
760843 certifyInfo.attested.creation.objectName = name;
760944
761045 // Copy the creationHash
761146 certifyInfo.attested.creation.creationHash = in->creationHash;
761247
761348 // 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
761949 // signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE,
762050 // TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned at
762151 // this point
762252 result = SignAttestInfo(in->signHandle,
762353 &in->inScheme,
762454 &certifyInfo,
762555 &in->qualifyingData,
762656 &out->certifyInfo,
762757 &out->signature);
762858
762959 // TPM_RC_ATTRIBUTES cannot be returned here as FillInAttestInfo would already
763060 // have returned TPM_RC_KEY
763161 pAssert(result != TPM_RC_ATTRIBUTES);
763262
763363 if(result != TPM_RC_SUCCESS)
763464 return result;
763565
763666 // orderly state should be cleared because of the reporting of clock info
763767 // if signing happens
763868 if(in->signHandle != TPM_RH_NULL)
763969 g_clearOrderly = TRUE;
764070
764171 return TPM_RC_SUCCESS;
764272 }
764373 #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
765318.4 TPM2_Quote
7654
765518.4.1 General Description
7656
7657This command is used to quote PCR values.
7658
7659NOTE See 18.1 for description of how the signing scheme is selected.
7660
7661The TPM will hash the list of PCR selected by PCRselect using the hash algorithm associated with
7662signHandle (this is the hash algorithm of the signing scheme, not the nameAlg of signHandle).
7663The digest is computed as the hash of the concatenation of all of the digest values of the selected PCR.
7664The concatenation of PCR is described in TPM 2.0 Part 1, Selecting Multiple PCR.
7665
7666NOTE 2 If signHandle is TPM_RH_NULL, the TPMS_ATTEST structure is returned and signature is a NULL
7667 Signature.
7668
7669
7670
7671
7672Page 164 TCG Published Family “2.0”
7673October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
7674 Trusted Platform Module Library Part 3: Commands
7675
7676
7677
767818.4.2 Command and Response
7679
7680 Table 81 — TPM2_Quote Command
7681Type Name Description
7682
7683TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
7684UINT32 commandSize
7685TPM_CC commandCode TPM_CC_Quote
7686
7687 handle of key that will perform signature
7688TPMI_DH_OBJECT+ @signHandle Auth Index: 1
7689 Auth Role: USER
7690
7691TPM2B_DATA qualifyingData data supplied by the caller
7692 signing scheme to use if the scheme for signHandle is
7693TPMT_SIG_SCHEME+ inScheme
7694 TPM_ALG_NULL
7695TPML_PCR_SELECTION PCRselect PCR set to quote
7696
7697
7698 Table 82 — TPM2_Quote Response
7699Type Name Description
7700
7701TPM_ST tag see clause 6
7702UINT32 responseSize
7703TPM_RC responseCode
7704
7705TPM2B_ATTEST quoted the quoted information
7706TPMT_SIGNATURE signature the signature over quoted
7707
7708
7709
7710
7711Family “2.0” TCG Published Page 165
7712Level 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
77191 #include "InternalRoutines.h"
77202 #include "Attest_spt_fp.h"
77213 #include "Quote_fp.h"
77224 #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 )
773710 {
773811 TPM_RC result;
773912 TPMI_ALG_HASH hashAlg;
774013 TPMS_ATTEST quoted;
774114
774215 // Command Output
774316
774417 // Filling in attest information
774518 // Common fields
774619 // FillInAttestInfo may return TPM_RC_SCHEME or TPM_RC_KEY
774720 result = FillInAttestInfo(in->signHandle,
774821 &in->inScheme,
774922 &in->qualifyingData,
775023 &quoted);
775124 if(result != TPM_RC_SUCCESS)
775225 {
775326 if(result == TPM_RC_KEY)
775427 return TPM_RC_KEY + RC_Quote_signHandle;
775528 else
775629 return RcSafeAddToResult(result, RC_Quote_inScheme);
775730 }
775831
775932 // Quote specific fields
776033 // Attestation type
776134 quoted.type = TPM_ST_ATTEST_QUOTE;
776235
776336 // Get hash algorithm in sign scheme. This hash algorithm is used to
776437 // compute PCR digest. If there is no algorithm, then the PCR cannot
776538 // be digested and this command returns TPM_RC_SCHEME
776639 hashAlg = in->inScheme.details.any.hashAlg;
776740
776841 if(hashAlg == TPM_ALG_NULL)
776942 return TPM_RC_SCHEME + RC_Quote_inScheme;
777043
777144 // Compute PCR digest
777245 PCRComputeCurrentDigest(hashAlg,
777346 &in->PCRselect,
777447 &quoted.attested.quote.pcrDigest);
777548
777649 // Copy PCR select. "PCRselect" is modified in PCRComputeCurrentDigest
777750 // function
777851 quoted.attested.quote.pcrSelect = in->PCRselect;
777952
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
778553 // Sign attestation structure. A NULL signature will be returned if
778654 // signHandle is TPM_RH_NULL. TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES
778755 // error may be returned by SignAttestInfo.
778856 // NOTE: TPM_RC_ATTRIBUTES means that the key is not a signing key but that
778957 // was checked above and TPM_RC_KEY was returned. TPM_RC_VALUE means that the
779058 // value to sign is too large but that means that the digest is too big and
779159 // that can't happen.
779260 result = SignAttestInfo(in->signHandle,
779361 &in->inScheme,
779462 &quoted,
779563 &in->qualifyingData,
779664 &out->quoted,
779765 &out->signature);
779866 if(result != TPM_RC_SUCCESS)
779967 return result;
780068
780169 // orderly state should be cleared because of the reporting of clock info
780270 // if signing happens
780371 if(in->signHandle != TPM_RH_NULL)
780472 g_clearOrderly = TRUE;
780573
780674 return TPM_RC_SUCCESS;
780775 }
780876 #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
781818.5 TPM2_GetSessionAuditDigest
7819
782018.5.1 General Description
7821
7822This command returns a digital signature of the audit session digest.
7823
7824NOTE 1 See 18.1 for description of how the signing scheme is selected.
7825
7826If sessionHandle is not an audit session, the TPM shall return TPM_RC_TYPE.
7827
7828NOTE 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
7831This command requires authorization from the privacy administrator of the TPM (expressed with
7832Endorsement Authorization) as well as authorization to use the key associated with signHandle.
7833If this command is audited, then the audit digest that is signed will not include the digest of this command
7834because the audit digest is only updated when the command completes successfully.
7835This command does not cause the audit session to be closed and does not reset the digest value.
7836
7837NOTE 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
7840NOTE 4 If signHandle is TPM_RH_NULL, the TPMS_ATTEST structure is returned and signature is a NULL
7841 Signature.
7842
7843
7844
7845
7846Page 168 TCG Published Family “2.0”
7847October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
7848 Trusted Platform Module Library Part 3: Commands
7849
7850
7851
785218.5.2 Command and Response
7853
7854 Table 83 — TPM2_GetSessionAuditDigest Command
7855Type Name Description
7856
7857TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
7858UINT32 commandSize
7859TPM_CC commandCode TPM_CC_GetSessionAuditDigest
7860
7861 handle of the privacy administrator
7862 (TPM_RH_ENDORSEMENT)
7863TPMI_RH_ENDORSEMENT @privacyAdminHandle
7864 Auth Index: 1
7865 Auth Role: USER
7866 handle of the signing key
7867TPMI_DH_OBJECT+ @signHandle Auth Index: 2
7868 Auth Role: USER
7869 handle of the audit session
7870TPMI_SH_HMAC sessionHandle
7871 Auth Index: None
7872
7873TPM2B_DATA qualifyingData user-provided qualifying data – may be zero-length
7874 signing scheme to use if the scheme for signHandle is
7875TPMT_SIG_SCHEME+ inScheme
7876 TPM_ALG_NULL
7877
7878
7879 Table 84 — TPM2_GetSessionAuditDigest Response
7880Type Name Description
7881
7882TPM_ST tag see clause 6
7883UINT32 responseSize
7884TPM_RC responseCode
7885
7886TPM2B_ATTEST auditInfo the audit information that was signed
7887TPMT_SIGNATURE signature the signature over auditInfo
7888
7889
7890
7891
7892Family “2.0” TCG Published Page 169
7893Level 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
79001 #include "InternalRoutines.h"
79012 #include "Attest_spt_fp.h"
79023 #include "GetSessionAuditDigest_fp.h"
79034 #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 )
792310 {
792411 TPM_RC result;
792512 SESSION *session;
792613 TPMS_ATTEST auditInfo;
792714
792815 // Input Validation
792916
793017 // SessionAuditDigest specific input validation
793118 // Get session pointer
793219 session = SessionGet(in->sessionHandle);
793320
793421 // session must be an audit session
793522 if(session->attributes.isAudit == CLEAR)
793623 return TPM_RC_TYPE + RC_GetSessionAuditDigest_sessionHandle;
793724
793825 // Command Output
793926
794027 // Filling in attest information
794128 // Common fields
794229 result = FillInAttestInfo(in->signHandle,
794330 &in->inScheme,
794431 &in->qualifyingData,
794532 &auditInfo);
794633 if(result != TPM_RC_SUCCESS)
794734 {
794835 if(result == TPM_RC_KEY)
794936 return TPM_RC_KEY + RC_GetSessionAuditDigest_signHandle;
795037 else
795138 return RcSafeAddToResult(result, RC_GetSessionAuditDigest_inScheme);
795239 }
795340
795441 // SessionAuditDigest specific fields
795542 // Attestation type
795643 auditInfo.type = TPM_ST_ATTEST_SESSION_AUDIT;
795744
795845 // Copy digest
795946 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
796547
796648 // Exclusive audit session
796749 if(g_exclusiveAuditSession == in->sessionHandle)
796850 auditInfo.attested.sessionAudit.exclusiveSession = TRUE;
796951 else
797052 auditInfo.attested.sessionAudit.exclusiveSession = FALSE;
797153
797254 // Sign attestation structure. A NULL signature will be returned if
797355 // signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE,
797456 // TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned at
797557 // this point
797658 result = SignAttestInfo(in->signHandle,
797759 &in->inScheme,
797860 &auditInfo,
797961 &in->qualifyingData,
798062 &out->auditInfo,
798163 &out->signature);
798264 if(result != TPM_RC_SUCCESS)
798365 return result;
798466
798567 // orderly state should be cleared because of the reporting of clock info
798668 // if signing happens
798769 if(in->signHandle != TPM_RH_NULL)
798870 g_clearOrderly = TRUE;
798971
799072 return TPM_RC_SUCCESS;
799173 }
799274 #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
800218.6 TPM2_GetCommandAuditDigest
8003
800418.6.1 General Description
8005
8006This command returns the current value of the command audit digest, a digest of the commands being
8007audited, and the audit hash algorithm. These values are placed in an attestation structure and signed with
8008the key referenced by signHandle.
8009
8010NOTE 1 See 18.1 for description of how the signing scheme is selected.
8011
8012When this command completes successfully, and signHandle is not TPM_RH_NULL, the audit digest is
8013cleared. If signHandle is TPM_RH_NULL, signature is the Empty Buffer and the audit digest is not
8014cleared.
8015
8016NOTE 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
8019If this command is being audited, then the signed digest produced by the command will not include the
8020command. At the end of this command, the audit digest will be extended with cpHash and the rpHash of
8021the command which would change the command audit digest signed by the next invocation of this
8022command.
8023This command requires authorization from the privacy administrator of the TPM (expressed with
8024Endorsement Authorization) as well as authorization to use the key associated with signHandle.
8025
8026
8027
8028
8029Page 172 TCG Published Family “2.0”
8030October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
8031 Trusted Platform Module Library Part 3: Commands
8032
8033
8034
803518.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
8060Type Name Description
8061
8062TPM_ST tag see clause 6
8063UINT32 responseSize
8064TPM_RC responseCode
8065
8066TPM2B_ATTEST auditInfo the auditInfo that was signed
8067TPMT_SIGNATURE signature the signature over auditInfo
8068
8069
8070
8071
8072Family “2.0” TCG Published Page 173
8073Level 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
80801 #include "InternalRoutines.h"
80812 #include "Attest_spt_fp.h"
80823 #include "GetCommandAuditDigest_fp.h"
80834 #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 )
810210 {
810311 TPM_RC result;
810412 TPMS_ATTEST auditInfo;
810513
810614 // Command Output
810715
810816 // Filling in attest information
810917 // Common fields
811018 result = FillInAttestInfo(in->signHandle,
811119 &in->inScheme,
811220 &in->qualifyingData,
811321 &auditInfo);
811422 if(result != TPM_RC_SUCCESS)
811523 {
811624 if(result == TPM_RC_KEY)
811725 return TPM_RC_KEY + RC_GetCommandAuditDigest_signHandle;
811826 else
811927 return RcSafeAddToResult(result, RC_GetCommandAuditDigest_inScheme);
812028 }
812129
812230 // CommandAuditDigest specific fields
812331 // Attestation type
812432 auditInfo.type = TPM_ST_ATTEST_COMMAND_AUDIT;
812533
812634 // Copy audit hash algorithm
812735 auditInfo.attested.commandAudit.digestAlg = gp.auditHashAlg;
812836
812937 // Copy counter value
813038 auditInfo.attested.commandAudit.auditCounter = gp.auditCounter;
813139
813240 // Copy command audit log
813341 auditInfo.attested.commandAudit.auditDigest = gr.commandAuditDigest;
813442 CommandAuditGetDigest(&auditInfo.attested.commandAudit.commandDigest);
813543
813644 // Sign attestation structure. A NULL signature will be returned if
813745 // signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE,
813846 // TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned at
813947 // 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
814548 result = SignAttestInfo(in->signHandle,
814649 &in->inScheme,
814750 &auditInfo,
814851 &in->qualifyingData,
814952 &out->auditInfo,
815053 &out->signature);
815154
815255 if(result != TPM_RC_SUCCESS)
815356 return result;
815457
815558 // Internal Data Update
815659
815760 if(in->signHandle != TPM_RH_NULL)
815861 {
815962 // Reset log
816063 gr.commandAuditDigest.t.size = 0;
816164
816265 // orderly state should be cleared because of the update in
816366 // commandAuditDigest, as well as the reporting of clock info
816467 g_clearOrderly = TRUE;
816568 }
816669
816770 return TPM_RC_SUCCESS;
816871 }
816972 #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
817918.7 TPM2_GetTime
8180
818118.7.1 General Description
8182
8183This command returns the current values of Time and Clock.
8184
8185NOTE 1 See 18.1 for description of how the signing scheme is selected.
8186
8187The values of Clock, resetCount and restartCount appear in two places in timeInfo: once in
8188TPMS_ATTEST.clockInfo and again in TPMS_ATTEST.attested.time.clockInfo. The firmware version
8189number also appears in two places (TPMS_ATTEST.firmwareVersion and
8190TPMS_ATTEST.attested.time.firmwareVersion). If signHandle is in the endorsement or platform
8191hierarchies, both copies of the data will be the same. However, if signHandle is in the storage hierarchy or
8192is TPM_RH_NULL, the values in TPMS_ATTEST.clockInfo and TPMS_ATTEST.firmwareVersion are
8193obfuscated but the values in TPMS_ATTEST.attested.time are not.
8194
8195NOTE 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
8199NOTE 3 If signHandle is TPM_RH_NULL, the TPMS_ATTEST structure is returned and signature is a NULL
8200 Signature.
8201
8202
8203
8204
8205Page 176 TCG Published Family “2.0”
8206October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
8207 Trusted Platform Module Library Part 3: Commands
8208
8209
8210
821118.7.2 Command and Response
8212
8213 Table 87 — TPM2_GetTime Command
8214Type Name Description
8215
8216TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
8217UINT32 commandSize
8218TPM_CC commandCode TPM_CC_GetTime
8219
8220 handle of the privacy administrator
8221 (TPM_RH_ENDORSEMENT)
8222TPMI_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
8227TPMI_DH_OBJECT+ @signHandle
8228 Auth Index: 2
8229 Auth Role: USER
8230
8231TPM2B_DATA qualifyingData data to tick stamp
8232 signing scheme to use if the scheme for signHandle is
8233TPMT_SIG_SCHEME+ inScheme
8234 TPM_ALG_NULL
8235
8236
8237 Table 88 — TPM2_GetTime Response
8238Type Name Description
8239
8240TPM_ST tag see clause 6
8241UINT32 responseSize
8242TPM_RC responseCode .
8243
8244TPM2B_ATTEST timeInfo standard TPM-generated attestation block
8245TPMT_SIGNATURE signature the signature over timeInfo
8246
8247
8248
8249
8250Family “2.0” TCG Published Page 177
8251Level 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
82581 #include "InternalRoutines.h"
82592 #include "Attest_spt_fp.h"
82603 #include "GetTime_fp.h"
82614 #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 )
828010 {
828111 TPM_RC result;
828212 TPMS_ATTEST timeInfo;
828313
828414 // Command Output
828515
828616 // Filling in attest information
828717 // Common fields
828818 result = FillInAttestInfo(in->signHandle,
828919 &in->inScheme,
829020 &in->qualifyingData,
829121 &timeInfo);
829222 if(result != TPM_RC_SUCCESS)
829323 {
829424 if(result == TPM_RC_KEY)
829525 return TPM_RC_KEY + RC_GetTime_signHandle;
829626 else
829727 return RcSafeAddToResult(result, RC_GetTime_inScheme);
829828 }
829929
830030 // GetClock specific fields
830131 // Attestation type
830232 timeInfo.type = TPM_ST_ATTEST_TIME;
830333
830434 // current clock in plain text
830535 timeInfo.attested.time.time.time = g_time;
830636 TimeFillInfo(&timeInfo.attested.time.time.clockInfo);
830737
830838 // Firmware version in plain text
830939 timeInfo.attested.time.firmwareVersion
831040 = ((UINT64) gp.firmwareV1) << 32;
831141 timeInfo.attested.time.firmwareVersion += gp.firmwareV2;
831242
831343 // Sign attestation structure. A NULL signature will be returned if
831444 // signHandle is TPM_RH_NULL. A TPM_RC_NV_UNAVAILABLE, TPM_RC_NV_RATE,
831545 // TPM_RC_VALUE, TPM_RC_SCHEME or TPM_RC_ATTRIBUTES error may be returned at
831646 // this point
831747 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
832348 &in->inScheme,
832449 &timeInfo,
832550 &in->qualifyingData,
832651 &out->timeInfo,
832752 &out->signature);
832853 if(result != TPM_RC_SUCCESS)
832954 return result;
833055
833156 // orderly state should be cleared because of the reporting of clock info
833257 // if signing happens
833358 if(in->signHandle != TPM_RH_NULL)
833459 g_clearOrderly = TRUE;
833560
833661 return TPM_RC_SUCCESS;
833762 }
833863 #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
834819 Ephemeral EC Keys
8349
835019.1 Introduction
8351
8352The TPM generates keys that have different lifetimes. TPM keys in a hierarchy can be persistent for as
8353long as the seed of the hierarchy is unchanged and these keys may be used multiple times. Other TPM-
8354generated keys are only useful for a single operation. Some of these single-use keys are used in the
8355command in which they are created. Examples of this use are TPM2_Duplicate() where an ephemeral
8356key is created for a single pass key exchange with another TPM. However, there are other cases, such
8357as anonymous attestation, where the protocol requires two passes where the public part of the ephemeral
8358key is used outside of the TPM before the final command "consumes" the ephemeral key.
8359For these uses, TPM2_Commit() or TPM2_EC_Ephemeral() may be used to have the TPM create an
8360ephemeral EC key and return the public part of the key for external use. Then in a subsequent command,
8361the caller provides a reference to the ephemeral key so that the TPM can retrieve or recreate the
8362associated private key.
8363When an ephemeral EC key is created, it is assigned a number and that number is returned to the caller
8364as the identifier for the key. This number is not a handle. A handle is assigned to a key that may be
8365context saved but these ephemeral EC keys may not be saved and do not have a full key context. When
8366a subsequent command uses the ephemeral key, the caller provides the number of the ephemeral key.
8367The TPM uses that number to either look up or recompute the associated private key. After the key is
8368used, the TPM records the fact that the key has been used so that it cannot be used again.
8369As mentioned, the TPM can keep each assigned private ephemeral key in memory until it is used.
8370However, this could consume a large amount of memory. To limit the memory size, the TPM is allowed to
8371restrict the number of pending private keys – keys that have been allocated but not used.
8372
8373NOTE The minimum number of ephemeral keys is determined by a platform specific specification
8374
8375To further reduce the memory requirements for the ephemeral private keys, the TPM is allowed to use
8376pseudo-random values for the ephemeral keys. Instead of keeping the full value of the key in memory, the
8377TPM can use a counter as input to a KDF. Incrementing the counter will cause the TPM to generate a
8378new pseudo-random value.
8379Using the counter to generate pseudo-random private ephemeral keys greatly simplifies tracking of key
8380usage. When a counter value is used to create a key, a bit in an array may be set to indicate that the key
8381use is pending. When the ephemeral key is consumed, the bit is cleared. This prevents the key from
8382being used more than once.
8383Since the TPM is allowed to restrict the number of pending ephemeral keys, the array size can be limited.
8384For example, a 128 bit array would allow 128 keys to be "pending".
8385The management of the array is described in greater detail in the Split Operations clause in Annex C of
8386TPM 2.0 Part 1.
8387
8388
8389
8390
8391Page 180 TCG Published Family “2.0”
8392October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
8393 Trusted Platform Module Library Part 3: Commands
8394
8395
8396
839719.2 TPM2_Commit
8398
839919.2.1 General Description
8400
8401TPM2_Commit() performs the first part of an ECC anonymous signing operation. The TPM will perform
8402the point multiplications on the provided points and return intermediate signing values. The signHandle
8403parameter shall refer to an ECC key with the sign attribute (TPM_RC_ATTRIBUTES) and the signing
8404scheme must be anonymous (TPM_RC_SCHEME). Currently, TPM_ALG_ECDAA is the only defined
8405anonymous scheme.
8406
8407NOTE 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
8410For this command, p1, s2 and y2 are optional parameters. If s2 is an Empty Buffer, then the TPM shall
8411return TPM_RC_SIZE if y2 is not an Empty Buffer.
8412The algorithm is specified in the TPM 2.0 Part 1 Annex for ECC, TPM2_Commit().
8413
8414
8415
8416
8417Family “2.0” TCG Published Page 181
8418Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
8419 Part 3: Commands Trusted Platform Module Library
8420
8421
8422
842319.2.2 Command and Response
8424
8425 Table 89 — TPM2_Commit Command
8426Type Name Description
8427
8428TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
8429
8430UINT32 commandSize
8431
8432TPM_CC commandCode TPM_CC_Commit
8433
8434 handle of the key that will be used in the signing
8435 operation
8436TPMI_DH_OBJECT @signHandle
8437 Auth Index: 1
8438 Auth Role: USER
8439
8440TPM2B_ECC_POINT P1 a point (M) on the curve used by signHandle
8441
8442TPM2B_SENSITIVE_DATA s2 octet array used to derive x-coordinate of a base point
8443
8444TPM2B_ECC_PARAMETER y2 y coordinate of the point associated with s2
8445
8446
8447 Table 90 — TPM2_Commit Response
8448Type Name Description
8449
8450TPM_ST tag see 6
8451
8452UINT32 responseSize
8453
8454TPM_RC responseCode
8455
8456TPM2B_ECC_POINT K ECC point K ≔ [ds](x2, y2)
8457
8458TPM2B_ECC_POINT L ECC point L ≔ [r](x2, y2)
8459
8460TPM2B_ECC_POINT E ECC point E ≔ [r]P1
8461
8462UINT16 counter least-significant 16 bits of commitCount
8463
8464
8465
8466
8467Page 182 TCG Published Family “2.0”
8468October 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
84741 #include "InternalRoutines.h"
84752 #include "Commit_fp.h"
84763 #ifdef TPM_CC_Commit // Conditional expansion of this file
84774 #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 )
849610 {
849711 OBJECT *eccKey;
849812 TPMS_ECC_POINT P2;
849913 TPMS_ECC_POINT *pP2 = NULL;
850014 TPMS_ECC_POINT *pP1 = NULL;
850115 TPM2B_ECC_PARAMETER r;
850216 TPM2B *p;
850317 TPM_RC result;
850418 TPMS_ECC_PARMS *parms;
850519
850620 // Input Validation
850721
850822 eccKey = ObjectGet(in->signHandle);
850923 parms = & eccKey->publicArea.parameters.eccDetail;
851024
851125 // Input key must be an ECC key
851226 if(eccKey->publicArea.type != TPM_ALG_ECC)
851327 return TPM_RC_KEY + RC_Commit_signHandle;
851428
851529 // This command may only be used with a sign-only key using an anonymous
851630 // scheme.
851731 // NOTE: a sign + decrypt key has no scheme so it will not be an anonymous one
851832 // and an unrestricted sign key might no have a signing scheme but it can't
851933 // be use in Commit()
852034 if(!CryptIsSchemeAnonymous(parms->scheme.scheme))
852135 return TPM_RC_SCHEME + RC_Commit_signHandle;
852236
852337 // Make sure that both parts of P2 are present if either is present
852438 if((in->s2.t.size == 0) != (in->y2.t.size == 0))
852539 return TPM_RC_SIZE + RC_Commit_y2;
852640
852741 // Get prime modulus for the curve. This is needed later but getting this now
852842 // allows confirmation that the curve exists
852943 p = (TPM2B *)CryptEccGetParameter('p', parms->curveID);
853044
853145 // 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
8592100 // having to reload the curve parameters multiple times.
8593101 result = CryptCommitCompute(&out->K.t.point,
8594102 &out->L.t.point,
8595103 &out->E.t.point,
8596104 parms->curveID,
8597105 pP1,
8598106 pP2,
8599107 &eccKey->sensitive.sensitive.ecc,
8600108 &r);
8601109 if(result != TPM_RC_SUCCESS)
8602110 return result;
8603111
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
8609112 out->K.t.size = TPMS_ECC_POINT_Marshal(&out->K.t.point, NULL, NULL);
8610113 out->L.t.size = TPMS_ECC_POINT_Marshal(&out->L.t.point, NULL, NULL);
8611114 out->E.t.size = TPMS_ECC_POINT_Marshal(&out->E.t.point, NULL, NULL);
8612115
8613116 // The commit computation was successful so complete the commit by setting
8614117 // the bit
8615118 out->counter = CryptCommit();
8616119
8617120 return TPM_RC_SUCCESS;
8618121 }
8619122 #endif
8620123 #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
863119.3 TPM2_EC_Ephemeral
8632
863319.3.1 General Description
8634
8635TPM2_EC_Ephemeral() creates an ephemeral key for use in a two-phase key exchange protocol.
8636The 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
8642Page 186 TCG Published Family “2.0”
8643October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
8644 Trusted Platform Module Library Part 3: Commands
8645
8646
8647
864819.3.2 Command and Response
8649
8650 Table 91 — TPM2_EC_Ephemeral Command
8651Type Name Description
8652
8653 TPM_ST_SESSIONS if an audit or encrypt session is
8654TPMI_ST_COMMAND_TAG tag
8655 present; otherwise, TPM_ST_NO_SESSIONS
8656
8657UINT32 commandSize
8658
8659TPM_CC commandCode TPM_CC_EC_Ephemeral
8660
8661TPMI_ECC_CURVE curveID The curve for the computed ephemeral point
8662
8663
8664 Table 92 — TPM2_EC_Ephemeral Response
8665Type Name Description
8666
8667TPM_ST tag see 6
8668
8669UINT32 responseSize
8670
8671TPM_RC responseCode
8672
8673TPM2B_ECC_POINT Q ephemeral public key Q ≔ [r]G
8674
8675UINT16 counter least-significant 16 bits of commitCount
8676
8677
8678
8679
8680Family “2.0” TCG Published Page 187
8681Level 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
86871 #include "InternalRoutines.h"
86882 #include "EC_Ephemeral_fp.h"
86893 #ifdef TPM_CC_EC_Ephemeral // Conditional expansion of this file
86904 #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 )
870210 {
870311 TPM2B_ECC_PARAMETER r;
870412
870513 // Get the random value that will be used in the point multiplications
870614 // Note: this does not commit the count.
870715 if(!CryptGenerateR(&r,
870816 NULL,
870917 in->curveID,
871018 NULL))
871119 return TPM_RC_NO_RESULT;
871220
871321 CryptEccPointMultiply(&out->Q.t.point, in->curveID, &r, NULL);
871422
871523 // commit the count value
871624 out->counter = CryptCommit();
871725
871826 return TPM_RC_SUCCESS;
871927 }
872028 #endif
872129 #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
873120 Signing and Signature Verification
8732
873320.1 TPM2_VerifySignature
8734
873520.1.1 General Description
8736
8737This command uses loaded keys to validate a signature on a message with the message digest passed
8738to the TPM.
8739If the signature check succeeds, then the TPM will produce a TPMT_TK_VERIFIED. Otherwise, the TPM
8740shall return TPM_RC_SIGNATURE.
8741
8742NOTE 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
8745If keyHandle references an asymmetric key, only the public portion of the key needs to be loaded. If
8746keyHandle references a symmetric key, both the public and private portions need to be loaded.
8747
8748NOTE 2 The sensitive area of the symmetric object is required to allow verification of the symmetric
8749 signature (the HMAC).
8750
8751
8752
8753
8754Family “2.0” TCG Published Page 189
8755Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
8756 Part 3: Commands Trusted Platform Module Library
8757
8758
875920.1.2 Command and Response
8760
8761 Table 93 — TPM2_VerifySignature Command
8762Type Name Description
8763
8764 TPM_ST_SESSIONS if an audit or encrypt session is
8765TPMI_ST_COMMAND_TAG tag
8766 present; otherwise, TPM_ST_NO_SESSIONS
8767UINT32 commandSize
8768TPM_CC commandCode TPM_CC_VerifySignature
8769
8770 handle of public key that will be used in the validation
8771TPMI_DH_OBJECT keyHandle
8772 Auth Index: None
8773
8774TPM2B_DIGEST digest digest of the signed message
8775TPMT_SIGNATURE signature signature to be tested
8776
8777
8778 Table 94 — TPM2_VerifySignature Response
8779Type Name Description
8780
8781TPM_ST tag see clause 6
8782UINT32 responseSize
8783TPM_RC responseCode
8784
8785TPMT_TK_VERIFIED validation
8786
8787
8788
8789
8790Page 190 TCG Published Family “2.0”
8791October 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
87981 #include "InternalRoutines.h"
87992 #include "VerifySignature_fp.h"
88003 #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 {
881710 TPM_RC result;
881811 TPM2B_NAME name;
881912 OBJECT *signObject;
882013 TPMI_RH_HIERARCHY hierarchy;
882114
882215 // Input Validation
882316
882417 // Get sign object pointer
882518 signObject = ObjectGet(in->keyHandle);
882619
882720 // The object to validate the signature must be a signing key.
882821 if(signObject->publicArea.objectAttributes.sign != SET)
882922 return TPM_RC_ATTRIBUTES + RC_VerifySignature_keyHandle;
883023
883124 // Validate Signature. TPM_RC_SCHEME, TPM_RC_HANDLE or TPM_RC_SIGNATURE
883225 // error may be returned by CryptCVerifySignatrue()
883326 result = CryptVerifySignature(in->keyHandle, &in->digest, &in->signature);
883427 if(result != TPM_RC_SUCCESS)
883528 return RcSafeAddToResult(result, RC_VerifySignature_signature);
883629
883730 // Command Output
883831
883932 hierarchy = ObjectGetHierarchy(in->keyHandle);
884033 if( hierarchy == TPM_RH_NULL
884134 || signObject->publicArea.nameAlg == TPM_ALG_NULL)
884235 {
884336 // produce empty ticket if hierarchy is TPM_RH_NULL or nameAlg is
884437 // TPM_ALG_NULL
884538 out->validation.tag = TPM_ST_VERIFIED;
884639 out->validation.hierarchy = TPM_RH_NULL;
884740 out->validation.digest.t.size = 0;
884841 }
884942 else
885043 {
885144 // Get object name that verifies the signature
885245 name.t.size = ObjectGetName(in->keyHandle, &name.t.name);
885346 // Compute ticket
885447 TicketComputeVerified(hierarchy, &in->digest, &name, &out->validation);
885548 }
885649
885750 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
886351 }
886452 #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
887420.2 TPM2_Sign
8875
887620.2.1 General Description
8877
8878This command causes the TPM to sign an externally provided hash with the specified symmetric or
8879asymmetric signing key.
8880
8881NOTE 1 Symmetric “signing” is done with the TPM HMAC commands.
8882
8883If keyHandle references a restricted signing key, then validation shall be provided, indicating that the TPM
8884performed the hash of the data and validation shall indicate that hashed data did not start with
8885TPM_GENERATED_VALUE.
8886
8887NOTE 2 If the hashed data did start with TPM_GENERATED_VALUE, then the validation will be a NULL
8888 ticket.
8889
8890If the scheme of keyHandle is not TPM_ALG_NULL, then inScheme shall either be the same scheme as
8891keyHandle or TPM_ALG_NULL.
8892If the scheme of keyHandle is TPM_ALG_NULL, the TPM will sign using inScheme; otherwise, it will sign
8893using the scheme of keyHandle.
8894
8895NOTE 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
8899If inScheme is not a valid signing scheme for the type of keyHandle (or TPM_ALG_NULL), then the TPM
8900shall return TPM_RC_SCHEME.
8901If the scheme of keyHandle is an anonymous scheme, then inScheme shall have the same scheme
8902algorithm as keyHandle and inScheme will contain a counter value that will be used in the signing
8903process.
8904If validation is provided, then the hash algorithm used in computing the digest is required to be the hash
8905algorithm specified in the scheme of keyHandle (TPM_RC_TICKET).
8906If the validation parameter is not the Empty Buffer, then it will be checked even if the key referenced by
8907keyHandle is not a restricted signing key.
8908
8909NOTE 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
8915Family “2.0” TCG Published Page 193
8916Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
8917 Part 3: Commands Trusted Platform Module Library
8918
8919
892020.2.2 Command and Response
8921
8922 Table 95 — TPM2_Sign Command
8923Type Name Description
8924
8925TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
8926UINT32 commandSize
8927TPM_CC commandCode TPM_CC_Sign
8928
8929 Handle of key that will perform signing
8930TPMI_DH_OBJECT @keyHandle Auth Index: 1
8931 Auth Role: USER
8932
8933TPM2B_DIGEST digest digest to be signed
8934 signing scheme to use if the scheme for keyHandle is
8935TPMT_SIG_SCHEME+ inScheme
8936 TPM_ALG_NULL
8937 proof that digest was created by the TPM
8938TPMT_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
8944Type Name Description
8945
8946TPM_ST tag see clause 6
8947UINT32 responseSize
8948TPM_RC responseCode
8949
8950TPMT_SIGNATURE signature the signature
8951
8952
8953
8954
8955Page 194 TCG Published Family “2.0”
8956October 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
89631 #include "InternalRoutines.h"
89642 #include "Sign_fp.h"
89653 #ifdef TPM_CC_Sign // Conditional expansion of this file
89664 #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 )
898410 {
898511 TPM_RC result;
898612 TPMT_TK_HASHCHECK ticket;
898713 OBJECT *signKey;
898814
898915 // Input Validation
899016 // Get sign key pointer
899117 signKey = ObjectGet(in->keyHandle);
899218
899319 // pick a scheme for sign. If the input sign scheme is not compatible with
899420 // the default scheme, return an error.
899521 result = CryptSelectSignScheme(in->keyHandle, &in->inScheme);
899622 if(result != TPM_RC_SUCCESS)
899723 {
899824 if(result == TPM_RC_KEY)
899925 return TPM_RC_KEY + RC_Sign_keyHandle;
900026 else
900127 return RcSafeAddToResult(result, RC_Sign_inScheme);
900228 }
900329
900430 // If validation is provided, or the key is restricted, check the ticket
900531 if( in->validation.digest.t.size != 0
900632 || signKey->publicArea.objectAttributes.restricted == SET)
900733 {
900834 // Compute and compare ticket
900935 TicketComputeHashCheck(in->validation.hierarchy,
901036 in->inScheme.details.any.hashAlg,
901137 &in->digest, &ticket);
901238
901339 if(!Memory2BEqual(&in->validation.digest.b, &ticket.digest.b))
901440 return TPM_RC_TICKET + RC_Sign_validation;
901541 }
901642 else
901743 // If we don't have a ticket, at least verify that the provided 'digest'
901844 // is the size of the scheme hashAlg digest.
901945 // NOTE: this does not guarantee that the 'digest' is actually produced using
902046 // the indicated hash algorithm, but at least it might be.
902147 {
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
902748 if( in->digest.t.size
902849 != CryptGetHashDigestSize(in->inScheme.details.any.hashAlg))
902950 return TPM_RCS_SIZE + RC_Sign_digest;
903051 }
903152
903253 // Command Output
903354 // Sign the hash. A TPM_RC_VALUE or TPM_RC_SCHEME
903455 // error may be returned at this point
903556 result = CryptSign(in->keyHandle, &in->inScheme, &in->digest, &out->signature);
903657
903758 return result;
903859 }
903960 #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
904921 Command Audit
9050
905121.1 Introduction
9052
9053If a command has been selected for command audit, the command audit status will be updated when that
9054command completes successfully. The digest is updated as:
9055 commandAuditDigestnew ≔ HauditAlg(commandAuditDigestold || cpHash || rpHash) (5)
9056where
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
9062auditAlg, the hash algorithm, is set using TPM2_SetCommandCodeAuditStatus.
9063
9064
9065TPM2_Shutdown() cannot be audited but TPM2_Startup() can be audited. If the cpHash of the
9066TPM2_Startup() is TPM_SU_STATE, that would indicate that a TPM2_Shutdown() had been successfully
9067executed.
9068TPM2_SetCommandCodeAuditStatus() is always audited.
9069If the TPM is in Failure mode, command audit is not functional.
9070
9071
9072
9073
9074Family “2.0” TCG Published Page 197
9075Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
9076 Part 3: Commands Trusted Platform Module Library
9077
9078
9079
908021.2 TPM2_SetCommandCodeAuditStatus
9081
908221.2.1 General Description
9083
9084This command may be used by the Privacy Administrator or platform to change the audit status of a
9085command or to set the hash algorithm used for the audit digest, but not both at the same time.
9086If the auditAlg parameter is a supported hash algorithm and not the same as the current algorithm, then
9087the TPM will check both setList and clearList are empty (zero length). If so, then the algorithm is changed,
9088and the audit digest is cleared. If auditAlg is TPM_ALG_NULL or the same as the current algorithm, then
9089the algorithm and audit digest are unchanged and the setList and clearList will be processed.
9090
9091NOTE 1 Because the audit digest is cleared, the audit counter will increment the next time that an audited
9092 command is executed.
9093
9094Use of TPM2_SetCommandCodeAuditStatus() to change the list of audited commands is an audited
9095event. If TPM_CC_SetCommandCodeAuditStatus is in clearList, the fact that it is in clearList is ignored.
9096
9097NOTE 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
9101The commands in setList indicate the commands to be added to the list of audited commands and the
9102commands in clearList indicate the commands that will no longer be audited. It is not an error if a
9103command in setList is already audited or is not implemented. It is not an error if a command in clearList is
9104not currently being audited or is not implemented.
9105If a command code is in both setList and clearList, then it will not be audited (that is, setList shall be
9106processed first).
9107
9108
9109
9110
9111Page 198 TCG Published Family “2.0”
9112October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
9113 Trusted Platform Module Library Part 3: Commands
9114
9115
9116
911721.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
9149Family “2.0” TCG Published Page 199
9150Level 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;
916610 UINT32 i;
916711 BOOL changed = FALSE;
916812
916913 // The command needs NV update. Check if NV is available.
917014 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
917115 // this point
917216 result = NvIsAvailable();
917317 if(result != TPM_RC_SUCCESS)
917418 return result;
917519
917620 // Internal Data Update
917721
917822 // Update hash algorithm
917923 if( in->auditAlg != TPM_ALG_NULL
918024 && in->auditAlg != gp.auditHashAlg)
918125 {
918226 // Can't change the algorithm and command list at the same time
918327 if(in->setList.count != 0 || in->clearList.count != 0)
918428 return TPM_RC_VALUE + RC_SetCommandCodeAuditStatus_auditAlg;
918529
918630 // Change the hash algorithm for audit
918731 gp.auditHashAlg = in->auditAlg;
918832
918933 // Set the digest size to a unique value that indicates that the digest
919034 // algorithm has been changed. The size will be cleared to zero in the
919135 // command audit processing on exit.
919236 gr.commandAuditDigest.t.size = 1;
919337
919438 // Save the change of command audit data (this sets g_updateNV so that NV
919539 // will be updated on exit.)
919640 NvWriteReserved(NV_AUDIT_HASH_ALG, &gp.auditHashAlg);
919741
919842 } else {
919943
920044 // Process set list
920145 for(i = 0; i < in->setList.count; i++)
920246
920347 // If change is made in CommandAuditSet, set changed flag
920448 if(CommandAuditSet(in->setList.commandCodes[i]))
920549 changed = TRUE;
920650
920751 // Process clear list
920852 for(i = 0; i < in->clearList.count; i++)
920953 // If change is made in CommandAuditClear, set changed flag
921054 if(CommandAuditClear(in->clearList.commandCodes[i]))
921155 changed = TRUE;
921256
921357 // if change was made to command list, update NV
921458 if(changed)
921559 // this sets g_updateNV so that NV will be updated on exit.
921660 NvWriteReserved(NV_AUDIT_COMMANDS, &gp.auditComands);
921761 }
921862
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
922463 return TPM_RC_SUCCESS;
922564 }
922665 #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
923622 Integrity Collection (PCR)
9237
923822.1 Introduction
9239
9240In TPM 1.2, an Event was hashed using SHA-1 and then the 20-octet digest was extended to a PCR
9241using TPM_Extend(). This specification allows the use of multiple PCR at a given Index, each using a
9242different hash algorithm. Rather than require that the external software generate multiple hashes of the
9243Event with each being extended to a different PCR, the Event data may be sent to the TPM for hashing.
9244This ensures that the resulting digests will properly reflect the algorithms chosen for the PCR even if the
9245calling software is unable to implement the hash algorithm.
9246
9247NOTE 1 There is continued support for software hashing of events with TPM2_PCR_Extend().
9248
9249To support recording of an Event that is larger than the TPM input buffer, the caller may use the
9250command sequence described in clause 1.
9251Change to a PCR requires authorization. The authorization may be with either an authorization value or
9252an authorization policy. The platform-specific specifications determine which PCR may be controlled by
9253policy. All other PCR are controlled by authorization.
9254If a PCR may be associated with a policy, then the algorithm ID of that policy determines whether the
9255policy is to be applied. If the algorithm ID is not TPM_ALG_NULL, then the policy digest associated with
9256the PCR must match the policySession→policyDigest in a policy session. If the algorithm ID is
9257TPM_ALG_NULL, then no policy is present and the authorization requires an EmptyAuth.
9258If a platform-specific specification indicates that PCR are grouped, then all the PCR in the group use the
9259same authorization policy or authorization value.
9260PcrUpdateCounter counter will be incremented on the successful completion of any command that
9261modifies (Extends or resets) a PCR unless the platform-specific specification explicitly excludes the PCR
9262from being counted.
9263
9264NOTE 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
9267A platform-specific specification may designate a set of PCR that are under control of the TCB. These
9268PCR may not be modified without the proper authorization. Updates of these PCR shall not cause the
9269PCR Update Counter to increment.
9270
9271EXAMPLE 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
9277Page 202 TCG Published Family “2.0”
9278October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
9279 Trusted Platform Module Library Part 3: Commands
9280
9281
928222.2 TPM2_PCR_Extend
9283
928422.2.1 General Description
9285
9286This command is used to cause an update to the indicated PCR. The digests parameter contains one or
9287more tagged digest values identified by an algorithm ID. For each digest, the PCR associated with
9288pcrHandle is Extended into the bank identified by the tag (hashAlg).
9289
9290EXAMPLE A SHA1 digest would be Extended i nto the SHA1 bank and a SHA256 digest would be Extended into
9291 the SHA256 bank.
9292
9293For each list entry, the TPM will check to see if pcrNum is implemented for that algorithm. If so, the TPM
9294shall perform the following operation:
9295 PCR.digestnew [pcrNum][alg] ≔ Halg(PCR.digestold [pcrNum][alg] || data[alg].buffer)) (6)
9296where
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
9305If no digest value is specified for a bank, then the PCR in that bank is not modified.
9306
9307NOTE 1 This allows consistent operation of the digests list for all of the Event recording commands.
9308
9309If a digest is present and the PCR in that bank is not implemented, the digest value is not used.
9310
9311NOTE 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
9316If the TPM unmarshals the hashAlg of a list entry and the unmarshaled value is not a hash algorithm
9317implemented on the TPM, the TPM shall return TPM_RC_HASH.
9318The pcrHandle parameter is allowed to reference TPM_RH_NULL. If so, the input parameters are
9319processed but no action is taken by the TPM. This permits the caller to probe for implemented hash
9320algorithms as an alternative to TPM2_GetCapability.
9321
9322NOTE 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
9330Family “2.0” TCG Published Page 203
9331Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
9332 Part 3: Commands Trusted Platform Module Library
9333
9334
933522.2.2 Command and Response
9336
9337 Table 99 — TPM2_PCR_Extend Command
9338Type Name Description
9339
9340TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
9341UINT32 commandSize
9342TPM_CC commandCode TPM_CC_PCR_Extend {NV}
9343
9344 handle of the PCR
9345TPMI_DH_PCR+ @pcrHandle Auth Handle: 1
9346 Auth Role: USER
9347
9348TPML_DIGEST_VALUES digests list of tagged digest values to be extended
9349
9350
9351 Table 100 — TPM2_PCR_Extend Response
9352Type Name Description
9353
9354TPM_ST tag see clause 6
9355UINT32 responseSize
9356TPM_RC responseCode .
9357
9358
9359
9360
9361Page 204 TCG Published Family “2.0”
9362October 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
93691 #include "InternalRoutines.h"
93702 #include "PCR_Extend_fp.h"
93713 #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;
938510 UINT32 i;
938611
938712 // Input Validation
938813
938914 // NOTE: This function assumes that the unmarshaling function for 'digests' will
939015 // have validated that all of the indicated hash algorithms are valid. If the
939116 // hash algorithms are correct, the unmarshaling code will unmarshal a digest
939217 // of the size indicated by the hash algorithm. If the overall size is not
939318 // consistent, the unmarshaling code will run out of input data or have input
939419 // data left over. In either case, it will cause an unmarshaling error and this
939520 // function will not be called.
939621
939722 // For NULL handle, do nothing and return success
939823 if(in->pcrHandle == TPM_RH_NULL)
939924 return TPM_RC_SUCCESS;
940025
940126 // Check if the extend operation is allowed by the current command locality
940227 if(!PCRIsExtendAllowed(in->pcrHandle))
940328 return TPM_RC_LOCALITY;
940429
940530 // If PCR is state saved and we need to update orderlyState, check NV
940631 // availability
940732 if(PCRIsStateSaved(in->pcrHandle) && gp.orderlyState != SHUTDOWN_NONE)
940833 {
940934 result = NvIsAvailable();
941035 if(result != TPM_RC_SUCCESS) return result;
941136 g_clearOrderly = TRUE;
941237 }
941338
941439 // Internal Data Update
941540
941641 // Iterate input digest list to extend
941742 for(i = 0; i < in->digests.count; i++)
941843 {
941944 PCRExtend(in->pcrHandle, in->digests.digests[i].hashAlg,
942045 CryptGetHashDigestSize(in->digests.digests[i].hashAlg),
942146 (BYTE *) &in->digests.digests[i].digest);
942247 }
942348
942449 return TPM_RC_SUCCESS;
942550 }
942651 #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
943622.3 TPM2_PCR_Event
9437
943822.3.1 General Description
9439
9440This command is used to cause an update to the indicated PCR.
9441The data in eventData is hashed using the hash algorithm associated with each bank in which the
9442indicated PCR has been allocated. After the data is hashed, the digests list is returned. If the pcrHandle
9443references an implemented PCR and not TPM_ALG_NULL, the digests list is processed as in
9444TPM2_PCR_Extend().
9445A TPM shall support an Event.size of zero through 1,024 inclusive (Event.size is an octet count). An
9446Event.size of zero indicates that there is no data but the indicated operations will still occur,
9447
9448EXAMPLE 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
9453On successful command completion, digests will contain the list of tagged digests of eventData that was
9454computed in preparation for extending the data into the PCR. At the option of the TPM, the list may
9455contain a digest for each bank, or it may only contain a digest for each bank in which pcrHandle is extant.
9456If pcrHandle is TPM_RH_NULL, the TPM may return either an empty list or a digest for each bank.
9457
9458EXAMPLE 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
9465Page 206 TCG Published Family “2.0”
9466October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
9467 Trusted Platform Module Library Part 3: Commands
9468
9469
947022.3.2 Command and Response
9471
9472 Table 101 — TPM2_PCR_Event Command
9473Type Name Description
9474
9475TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
9476UINT32 commandSize
9477TPM_CC commandCode TPM_CC_PCR_Event {NV}
9478
9479 Handle of the PCR
9480TPMI_DH_PCR+ @pcrHandle Auth Handle: 1
9481 Auth Role: USER
9482
9483TPM2B_EVENT eventData Event data in sized buffer
9484
9485
9486 Table 102 — TPM2_PCR_Event Response
9487Type Name Description
9488
9489TPM_ST tag see clause 6
9490UINT32 responseSize
9491TPM_RC responseCode .
9492
9493TPML_DIGEST_VALUES digests
9494
9495
9496
9497
9498Family “2.0” TCG Published Page 207
9499Level 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
95061 #include "InternalRoutines.h"
95072 #include "PCR_Event_fp.h"
95083 #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 {
952210 TPM_RC result;
952311 HASH_STATE hashState;
952412 UINT32 i;
952513 UINT16 size;
952614
952715 // Input Validation
952816
952917 // If a PCR extend is required
953018 if(in->pcrHandle != TPM_RH_NULL)
953119 {
953220 // If the PCR is not allow to extend, return error
953321 if(!PCRIsExtendAllowed(in->pcrHandle))
953422 return TPM_RC_LOCALITY;
953523
953624 // If PCR is state saved and we need to update orderlyState, check NV
953725 // availability
953826 if(PCRIsStateSaved(in->pcrHandle) && gp.orderlyState != SHUTDOWN_NONE)
953927 {
954028 result = NvIsAvailable();
954129 if(result != TPM_RC_SUCCESS) return result;
954230 g_clearOrderly = TRUE;
954331 }
954432 }
954533
954634 // Internal Data Update
954735
954836 out->digests.count = HASH_COUNT;
954937
955038 // Iterate supported PCR bank algorithms to extend
955139 for(i = 0; i < HASH_COUNT; i++)
955240 {
955341 TPM_ALG_ID hash = CryptGetHashAlgByIndex(i);
955442 out->digests.digests[i].hashAlg = hash;
955543 size = CryptStartHash(hash, &hashState);
955644 CryptUpdateDigest2B(&hashState, &in->eventData.b);
955745 CryptCompleteHash(&hashState, size,
955846 (BYTE *) &out->digests.digests[i].digest);
955947 if(in->pcrHandle != TPM_RH_NULL)
956048 PCRExtend(in->pcrHandle, hash, size,
956149 (BYTE *) &out->digests.digests[i].digest);
956250 }
956351
956452 return TPM_RC_SUCCESS;
956553 }
956654 #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
957422.4 TPM2_PCR_Read
9575
957622.4.1 General Description
9577
9578This command returns the values of all PCR specified in pcrSelectionIn.
9579The TPM will process the list of TPMS_PCR_SELECTION in pcrSelectionIn in order. Within each
9580TPMS_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,
9582then the TPM will add the digest of the PCR to the list of values to be returned in pcrValues.
9583The TPM will continue processing bits until all have been processed or until pcrValues would be too large
9584to fit into the output buffer if additional values were added.
9585The returned pcrSelectionOut will have a bit SET in its pcrSelect structures for each value present in
9586pcrValues.
9587The current value of the PCR Update Counter is returned in pcrUpdateCounter.
9588The returned list may be empty if none of the selected PCR are implemented.
9589
9590NOTE If no PCR are returned from a bank, the selector for the bank will be present in pcrSelectionOut.
9591
9592No authorization is required to read a PCR and any implemented PCR may be read from any locality.
9593
9594
9595
9596
9597Family “2.0” TCG Published Page 209
9598Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
9599 Part 3: Commands Trusted Platform Module Library
9600
9601
9602
960322.4.2 Command and Response
9604
9605 Table 103 — TPM2_PCR_Read Command
9606Type Name Description
9607
9608 TPM_ST_SESSIONS if an audit session is present;
9609TPMI_ST_COMMAND_TAG tag
9610 otherwise, TPM_ST_NO_SESSIONS
9611UINT32 commandSize
9612TPM_CC commandCode TPM_CC_PCR_Read
9613
9614TPML_PCR_SELECTION pcrSelectionIn The selection of PCR to read
9615
9616
9617 Table 104 — TPM2_PCR_Read Response
9618Type Name Description
9619
9620TPM_ST tag see clause 6
9621UINT32 responseSize
9622TPM_RC responseCode
9623
9624UINT32 pcrUpdateCounter the current value of the PCR update counter
9625TPML_PCR_SELECTION pcrSelectionOut the PCR in the returned list
9626 the contents of the PCR indicated in pcrSelect as
9627TPML_DIGEST pcrValues
9628 tagged digests
9629
9630
9631
9632
9633Page 210 TCG Published Family “2.0”
9634October 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 {
965010 // Command Output
965111
965212 // Call PCR read function. input pcrSelectionIn parameter could be changed
965313 // to reflect the actual PCR being returned
965414 PCRRead(&in->pcrSelectionIn, &out->pcrValues, &out->pcrUpdateCounter);
965515
965616 out->pcrSelectionOut = in->pcrSelectionIn;
965717
965818 return TPM_RC_SUCCESS;
965919 }
966020 #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
967022.5 TPM2_PCR_Allocate
9671
967222.5.1 General Description
9673
9674This command is used to set the desired PCR allocation of PCR and algorithms. This command requires
9675Platform Authorization.
9676The TPM will evaluate the request and, if sufficient memory is available for the requested allocation, the
9677TPM will store the allocation request for use during the next TPM2_Startup(TPM_SU_CLEAR) operation.
9678The PCR allocation in place when this command is executed will be retained until the next
9679TPM2_Startup(TPM_SU_CLEAR). If this command is received multiple times before a
9680TPM2_Startup(TPM_SU_CLEAR), each one overwrites the previous stored allocation.
9681This command will only change the allocations of banks that are listed in pcrAllocation.
9682EXAMPLE 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
9690If a bank is listed more than once, then the last selection in the pcrAllocation list is the one that the TPM
9691will attempt to allocate.
9692This command shall not allocate more PCR in any bank than there are PCR attribute definitions. The
9693PCR attribute definitions indicate how a PCR is to be managed – if it is resettable, the locality for update,
9694etc. In the response to this command, the TPM returns the maximum number of PCR allowed for any
9695bank.
9696When PCR are allocated, if DRTM_PCR is defined, the resulting allocation must have at least one bank
9697with the D-RTM PCR allocated. If HCRTM_PCR is defined, the resulting allocation must have at least
9698one bank with the HCRTM_PCR allocated. If not, the TPM returns TPM_RC_PCR.
9699The TPM may return TPM_RC_SUCCESS even though the request fails. This is to allow the TPM to
9700return information about the size needed for the requested allocation and the size available. If the
9701sizeNeeded parameter in the return is less than or equal to the sizeAvailable parameter, then the
9702allocationSuccess parameter will be YES. Alternatively, if the request fails, The TPM may return
9703TPM_RC_NO_RESULT.
9704
9705NOTE 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
9708After this command, TPM2_Shutdown() is only allowed to have a startupType equal to TPM_SU_CLEAR.
9709
9710NOTE 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
9718Page 212 TCG Published Family “2.0”
9719October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
9720 Trusted Platform Module Library Part 3: Commands
9721
9722
972322.5.2 Command and Response
9724
9725 Table 105 — TPM2_PCR_Allocate Command
9726Type Name Description
9727
9728TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
9729UINT32 commandSize
9730TPM_CC commandCode TPM_CC_PCR_Allocate {NV}
9731
9732 TPM_RH_PLATFORM+{PP}
9733TPMI_RH_PLATFORM @authHandle Auth Index: 1
9734 Auth Role: USER
9735
9736TPML_PCR_SELECTION pcrAllocation the requested allocation
9737
9738
9739 Table 106 — TPM2_PCR_Allocate Response
9740Type Name Description
9741
9742TPM_ST tag see clause 6
9743UINT32 responseSize
9744TPM_RC responseCode
9745
9746TPMI_YES_NO allocationSuccess YES if the allocation succeeded
9747UINT32 maxPCR maximum number of PCR that may be in a bank
9748UINT32 sizeNeeded number of octets required to satisfy the request
9749 Number of octets available. Computed before the
9750UINT32 sizeAvailable
9751 allocation.
9752
9753
9754
9755
9756Family “2.0” TCG Published Page 213
9757Level 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
97641 #include "InternalRoutines.h"
97652 #include "PCR_Allocate_fp.h"
97663 #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 {
978110 TPM_RC result;
978211
978312 // The command needs NV update. Check if NV is available.
978413 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
978514 // this point.
978615 // Note: These codes are not listed in the return values above because it is
978716 // an implementation choice to check in this routine rather than in a common
978817 // function that is called before these actions are called. These return values
978918 // are described in the Response Code section of Part 3.
979019 result = NvIsAvailable();
979120 if(result != TPM_RC_SUCCESS)
979221 return result;
979322
979423 // Command Output
979524
979625 // Call PCR Allocation function.
979726 result = PCRAllocate(&in->pcrAllocation, &out->maxPCR,
979827 &out->sizeNeeded, &out->sizeAvailable);
979928 if(result == TPM_RC_PCR)
980029 return result;
980130
980231 //
980332 out->allocationSuccess = (result == TPM_RC_SUCCESS);
980433
980534 // if re-configuration succeeds, set the flag to indicate PCR configuration is
980635 // going to be changed in next boot
980736 if(out->allocationSuccess == YES)
980837 g_pcrReConfig = TRUE;
980938
981039 return TPM_RC_SUCCESS;
981140 }
981241 #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
982222.6 TPM2_PCR_SetAuthPolicy
9823
982422.6.1 General Description
9825
9826This command is used to associate a policy with a PCR or group of PCR. The policy determines the
9827conditions under which a PCR may be extended or reset.
9828A policy may only be associated with a PCR that has been defined by a platform-specific specification as
9829allowing a policy. If the TPM implementation does not allow a policy for pcrNum, the TPM shall return
9830TPM_RC_VALUE.
9831A platform-specific specification may group PCR so that they share a common policy. In such case, a
9832pcrNum that selects any of the PCR in the group will change the policy for all PCR in the group.
9833The policy setting is persistent and may only be changed by TPM2_PCR_SetAuthPolicy() or by
9834TPM2_ChangePPS().
9835Before this command is first executed on a TPM or after TPM2_ChangePPS(), the access control on the
9836PCR will be set to the default value defined in the platform-specific specification.
9837
9838NOTE 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
9842If the size of the data buffer in authPolicy is not the size of a digest produced by hashAlg, the TPM shall
9843return TPM_RC_SIZE.
9844
9845NOTE 2 If hashAlg is TPM_ALG_NULL, then the size is required to be zero.
9846
9847This command requires platformAuth/platformPolicy.
9848
9849NOTE 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
9855Family “2.0” TCG Published Page 215
9856Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
9857 Part 3: Commands Trusted Platform Module Library
9858
9859
986022.6.2 Command and Response
9861
9862 Table 107 — TPM2_PCR_SetAuthPolicy Command
9863Type Name Description
9864
9865TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
9866UINT32 commandSize
9867TPM_CC commandCode TPM_CC_PCR_SetAuthPolicy {NV}
9868
9869 TPM_RH_PLATFORM+{PP}
9870TPMI_RH_PLATFORM @authHandle Auth Index: 1
9871 Auth Role: USER
9872
9873TPM2B_DIGEST authPolicy the desired authPolicy
9874TPMI_ALG_HASH+ hashAlg the hash algorithm of the policy
9875TPMI_DH_PCR pcrNum the PCR for which the policy is to be set
9876
9877
9878 Table 108 — TPM2_PCR_SetAuthPolicy Response
9879Type Name Description
9880
9881TPM_ST tag see clause 6
9882UINT32 responseSize
9883TPM_RC responseCode
9884
9885
9886
9887
9888Page 216 TCG Published Family “2.0”
9889October 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
98961 #include "InternalRoutines.h"
98972 #include "PCR_SetAuthPolicy_fp.h"
98983 #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;
991210
991311 TPM_RC result;
991412
991513 // The command needs NV update. Check if NV is available.
991614 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
991715 // this point
991816 result = NvIsAvailable();
991917 if(result != TPM_RC_SUCCESS) return result;
992018
992119 // Input Validation:
992220
992321 // Check the authPolicy consistent with hash algorithm
992422 if(in->authPolicy.t.size != CryptGetHashDigestSize(in->hashAlg))
992523 return TPM_RC_SIZE + RC_PCR_SetAuthPolicy_authPolicy;
992624
992725 // If PCR does not belong to a policy group, return TPM_RC_VALUE
992826 if(!PCRBelongsPolicyGroup(in->pcrNum, &groupIndex))
992927 return TPM_RC_VALUE + RC_PCR_SetAuthPolicy_pcrNum;
993028
993129 // Internal Data Update
993230
993331 // Set PCR policy
993432 gp.pcrPolicies.hashAlg[groupIndex] = in->hashAlg;
993533 gp.pcrPolicies.policy[groupIndex] = in->authPolicy;
993634
993735 // Save new policy to NV
993836 NvWriteReserved(NV_PCR_POLICIES, &gp.pcrPolicies);
993937
994038 return TPM_RC_SUCCESS;
994139 }
994240 #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
995222.7 TPM2_PCR_SetAuthValue
9953
995422.7.1 General Description
9955
9956This command changes the authValue of a PCR or group of PCR.
9957An authValue may only be associated with a PCR that has been defined by a platform-specific
9958specification as allowing an authorization value. If the TPM implementation does not allow an
9959authorization for pcrNum, the TPM shall return TPM_RC_VALUE. A platform-specific specification may
9960group PCR so that they share a common authorization value. In such case, a pcrNum that selects any of
9961the PCR in the group will change the authValue value for all PCR in the group.
9962The authorization setting is set to EmptyAuth on each STARTUP(CLEAR) or by TPM2_Clear(). The
9963authorization setting is preserved by SHUTDOWN(STATE).
9964
9965
9966
9967
9968Page 218 TCG Published Family “2.0”
9969October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
9970 Trusted Platform Module Library Part 3: Commands
9971
9972
9973
997422.7.2 Command and Response
9975
9976 Table 109 — TPM2_PCR_SetAuthValue Command
9977Type Name Description
9978
9979TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
9980UINT32 commandSize
9981TPM_CC commandCode TPM_CC_PCR_SetAuthValue
9982
9983 handle for a PCR that may have an authorization value
9984 set
9985TPMI_DH_PCR @pcrHandle
9986 Auth Index: 1
9987 Auth Role: USER
9988
9989TPM2B_DIGEST auth the desired authorization value
9990
9991
9992 Table 110 — TPM2_PCR_SetAuthValue Response
9993Type Name Description
9994
9995TPM_ST tag see clause 6
9996UINT32 responseSize
9997TPM_RC responseCode
9998
9999
10000
10001
10002Family “2.0” TCG Published Page 219
10003Level 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
100101 #include "InternalRoutines.h"
100112 #include "PCR_SetAuthValue_fp.h"
100123 #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;
1002610 TPM_RC result;
1002711
1002812 // Input Validation:
1002913
1003014 // If PCR does not belong to an auth group, return TPM_RC_VALUE
1003115 if(!PCRBelongsAuthGroup(in->pcrHandle, &groupIndex))
1003216 return TPM_RC_VALUE;
1003317
1003418 // The command may cause the orderlyState to be cleared due to the update of
1003519 // state clear data. If this is the case, Check if NV is available.
1003620 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
1003721 // this point
1003822 if(gp.orderlyState != SHUTDOWN_NONE)
1003923 {
1004024 result = NvIsAvailable();
1004125 if(result != TPM_RC_SUCCESS) return result;
1004226 g_clearOrderly = TRUE;
1004327 }
1004428
1004529 // Internal Data Update
1004630
1004731 // Set PCR authValue
1004832 gc.pcrAuthValues.auth[groupIndex] = in->auth;
1004933
1005034 return TPM_RC_SUCCESS;
1005135 }
1005236 #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
1006222.8 TPM2_PCR_Reset
10063
1006422.8.1 General Description
10065
10066If the attribute of a PCR allows the PCR to be reset and proper authorization is provided, then this
10067command may be used to set the PCR to zero. The attributes of the PCR may restrict the locality that can
10068perform the reset operation.
10069
10070NOTE 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
10073If pcrHandle references a PCR that cannot be reset, the TPM shall return TPM_RC_LOCALITY.
10074
10075NOTE 2 TPM_RC_LOCALITY is returned because the reset attributes are defined on a per -locality basis.
10076
10077
10078
10079
10080Family “2.0” TCG Published Page 221
10081Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
10082 Part 3: Commands Trusted Platform Module Library
10083
10084
1008522.8.2 Command and Response
10086
10087 Table 111 — TPM2_PCR_Reset Command
10088Type Name Description
10089
10090TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
10091UINT32 commandSize
10092TPM_CC commandCode TPM_CC_PCR_Reset {NV}
10093
10094 the PCR to reset
10095TPMI_DH_PCR @pcrHandle Auth Index: 1
10096 Auth Role: USER
10097
10098
10099 Table 112 — TPM2_PCR_Reset Response
10100Type Name Description
10101
10102TPM_ST tag see clause 6
10103UINT32 responseSize
10104TPM_RC responseCode
10105
10106
10107
10108
10109Page 222 TCG Published Family “2.0”
10110October 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
101171 #include "InternalRoutines.h"
101182 #include "PCR_Reset_fp.h"
101193 #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;
1013310
1013411 // Input Validation
1013512
1013613 // Check if the reset operation is allowed by the current command locality
1013714 if(!PCRIsResetAllowed(in->pcrHandle))
1013815 return TPM_RC_LOCALITY;
1013916
1014017 // If PCR is state saved and we need to update orderlyState, check NV
1014118 // availability
1014219 if(PCRIsStateSaved(in->pcrHandle) && gp.orderlyState != SHUTDOWN_NONE)
1014320 {
1014421 result = NvIsAvailable();
1014522 if(result != TPM_RC_SUCCESS)
1014623 return result;
1014724 g_clearOrderly = TRUE;
1014825 }
1014926
1015027 // Internal Data Update
1015128
1015229 // Reset selected PCR in all banks to 0
1015330 PCRSetValue(in->pcrHandle, 0);
1015431
1015532 // Indicate that the PCR changed so that pcrCounter will be incremented if
1015633 // necessary.
1015734 PCRChanged(in->pcrHandle);
1015835
1015936 return TPM_RC_SUCCESS;
1016037 }
1016138 #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
1017122.9 _TPM_Hash_Start
10172
1017322.9.1 Description
10174
10175This indication from the TPM interface indicates the start of an H-CRTM measurement sequence. On
10176receipt of this indication, the TPM will initialize an H-CRTM Event Sequence context.
10177If no object memory is available for creation of the sequence context, the TPM will flush the context of an
10178object so that creation of the sequence context will always succeed.
10179A platform-specific specification may allow this indication before TPM2_Startup().
10180
10181NOTE 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
10189Page 224 TCG Published Family “2.0”
10190October 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
101961 #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
1020810 // If a DRTM sequence object exists, free it up
1020911 if(g_DRTMHandle != TPM_RH_UNASSIGNED)
1021012 {
1021113 ObjectFlush(g_DRTMHandle);
1021214 g_DRTMHandle = TPM_RH_UNASSIGNED;
1021315 }
1021416
1021517 // Create an event sequence object and store the handle in global
1021618 // g_DRTMHandle. A TPM_RC_OBJECT_MEMORY error may be returned at this point
1021719 // The null value for the 'auth' parameter will cause the sequence structure to
1021820 // be allocated without being set as present. This keeps the sequence from
1021921 // being left behind if the sequence is terminated early.
1022022 result = ObjectCreateEventSequence(NULL, &g_DRTMHandle);
1022123
1022224 // If a free slot was not available, then free up a slot.
1022325 if(result != TPM_RC_SUCCESS)
1022426 {
1022527 // An implementation does not need to have a fixed relationship between
1022628 // slot numbers and handle numbers. To handle the general case, scan for
1022729 // a handle that is assigned and free it for the DRTM sequence.
1022830 // In the reference implementation, the relationship between handles and
1022931 // slots is fixed. So, if the call to ObjectCreateEvenSequence()
1023032 // failed indicating that all slots are occupied, then the first handle we
1023133 // are going to check (TRANSIENT_FIRST) will be occupied. It will be freed
1023234 // so that it can be assigned for use as the DRTM sequence object.
1023335 for(handle = TRANSIENT_FIRST; handle < TRANSIENT_LAST; handle++)
1023436 {
1023537 // try to flush the first object
1023638 if(ObjectIsPresent(handle))
1023739 break;
1023840 }
1023941 // If the first call to find a slot fails but none of the slots is occupied
1024042 // then there's a big problem
1024143 pAssert(handle < TRANSIENT_LAST);
1024244
1024345 // Free the slot
1024446 ObjectFlush(handle);
1024547
1024648 // Try to create an event sequence object again. This time, we must
1024749 // succeed.
1024850 result = ObjectCreateEventSequence(NULL, &g_DRTMHandle);
1024951 pAssert(result == TPM_RC_SUCCESS);
1025052 }
1025153
1025254 return;
1025355 }
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
1026322.10 _TPM_Hash_Data
10264
1026522.10.1 Description
10266
10267This indication from the TPM interface indicates arrival of one or more octets of data that are to be
10268included in the H-CRTM Event Sequence sequence context created by the _TPM_Hash_Start indication.
10269The context holds data for each hash algorithm for each PCR bank implemented on the TPM.
10270If no H-CRTM Event Sequence context exists, this indication is discarded and no other action is
10271performed.
10272
10273
10274
10275
10276Page 226 TCG Published Family “2.0”
10277October 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
102841 #include "InternalRoutines.h"
102852 #include "Platform.h"
102863 #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 {
1029610 UINT32 i;
1029711 HASH_OBJECT *hashObject;
1029812 TPMI_DH_PCR pcrHandle = TPMIsStarted()
1029913 ? PCR_FIRST + DRTM_PCR : PCR_FIRST + HCRTM_PCR;
1030014
1030115 // If there is no DRTM sequence object, then _TPM_Hash_Start
1030216 // was not called so this function returns without doing
1030317 // anything.
1030418 if(g_DRTMHandle == TPM_RH_UNASSIGNED)
1030519 return;
1030620
1030721 hashObject = (HASH_OBJECT *)ObjectGet(g_DRTMHandle);
1030822 pAssert(hashObject->attributes.eventSeq);
1030923
1031024 // For each of the implemented hash algorithms, update the digest with the
1031125 // data provided.
1031226 for(i = 0; i < HASH_COUNT; i++)
1031327 {
1031428 // make sure that the PCR is implemented for this algorithm
1031529 if(PcrIsAllocated(pcrHandle,
1031630 hashObject->state.hashState[i].state.hashAlg))
1031731 // Update sequence object
1031832 CryptUpdateDigest(&hashObject->state.hashState[i], dataSize, data);
1031933 }
1032034
1032135 return;
1032236 }
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
1033222.11 _TPM_Hash_End
10333
1033422.11.1 Description
10335
10336This indication from the TPM interface indicates the end of the H-CRTM measurement. This indication is
10337discarded and no other action performed if the TPM does not contain an H-CRTM Event Sequence
10338context.
10339
10340NOTE 1 An H-CRTM Event Sequence context is created by _TPM_Hash_Start().
10341
10342If the H-CRTM Event Sequence occurs after TPM2_Startup(), the TPM will set all of the PCR designated
10343in the platform-specific specifications as resettable by this event to the value indicated in the platform
10344specific specification, and increment restartCount. The TPM will then Extend the Event Sequence
10345digest/digests into the designated D-RTM PCR (PCR[17]).
10346 PCR[17][hashAlg] ≔ HhashAlg (initial_value || HhashAlg (hash_data)) (7)
10347where
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
10352A _TPM_Hash_End indication that occurs after TPM2_Startup() will increment pcrUpdateCounter unless
10353a platform-specific specification excludes modifications of PCR[DRTM] from causing an increment.
10354A 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
10356the H-CRTM Event Sequence data into PCR[0].
10357 PCR[0][hashAlg] ≔ HhashAlg (0…04 || HhashAlg (hash_data)) (8)
10358
10359NOTE 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
10362NOTE 3 PCR[0] does not need to be updated according to (8) until the end of TPM2_Startup().
10363
10364
10365
10366
10367Page 228 TCG Published Family “2.0”
10368October 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
103741 #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;
1038610 HASH_OBJECT *hashObject;
1038711 TPMI_DH_PCR pcrHandle;
1038812
1038913 // If the DRTM handle is not being used, then either _TPM_Hash_Start has not
1039014 // been called, _TPM_Hash_End was previously called, or some other command
1039115 // was executed and the sequence was aborted.
1039216 if(g_DRTMHandle == TPM_RH_UNASSIGNED)
1039317 return;
1039418
1039519 // Get DRTM sequence object
1039620 hashObject = (HASH_OBJECT *)ObjectGet(g_DRTMHandle);
1039721
1039822 // Is this _TPM_Hash_End after Startup or before
1039923 if(TPMIsStarted())
1040024 {
1040125 // After
1040226
1040327 // Reset the DRTM PCR
1040428 PCRResetDynamics();
1040529
1040630 // Extend the DRTM_PCR.
1040731 pcrHandle = PCR_FIRST + DRTM_PCR;
1040832
1040933 // DRTM sequence increments restartCount
1041034 gr.restartCount++;
1041135 }
1041236 else
1041337 {
1041438 pcrHandle = PCR_FIRST + HCRTM_PCR;
1041539 }
1041640
1041741 // Complete hash and extend PCR, or if this is an HCRTM, complete
1041842 // the hash, reset the H-CRTM register (PCR[0]) to 0...04, and then
1041943 // extend the H-CRTM data
1042044 for(i = 0; i < HASH_COUNT; i++)
1042145 {
1042246 TPMI_ALG_HASH hash = CryptGetHashAlgByIndex(i);
1042347 // make sure that the PCR is implemented for this algorithm
1042448 if(PcrIsAllocated(pcrHandle,
1042549 hashObject->state.hashState[i].state.hashAlg))
1042650 {
1042751 // Complete hash
1042852 digest.t.size = CryptGetHashDigestSize(hash);
1042953 CryptCompleteHash2B(&hashObject->state.hashState[i], &digest.b);
1043054
1043155 PcrDrtm(pcrHandle, hash, &digest);
1043256 }
1043357 }
1043458
1043559 // 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
1044260 ObjectFlush(g_DRTMHandle);
1044361
1044462 g_DRTMHandle = TPM_RH_UNASSIGNED;
1044563
1044664 g_DrtmPreStartup = TRUE;
1044765
1044866 return;
1044967 }
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
1045923 Enhanced Authorization (EA) Commands
10460
1046123.1 Introduction
10462
10463The commands in this clause 1 are used for policy evaluation. When successful, each command will
10464update the policySession→policyDigest in a policy session context in order to establish that the
10465authorizations required to use an object have been provided. Many of the commands will also modify
10466other parts of a policy context so that the caller may constrain the scope of the authorization that is
10467provided.
10468
10469NOTE 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
10472The policySession parameter of the command is the handle of the policy session context to be modified
10473by the command.
10474If the policySession parameter indicates a trial policy session, then the policySession→policyDigest will
10475be updated and the indicated validations are not performed.
10476
10477NOTE 2 A policy session is set to a trial policy by TPM2_StartAuthSession(sessionType = TPM_SE_TRIAL).
10478
10479NOTE 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
10482NOTE 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
10488Family “2.0” TCG Published Page 231
10489Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
10490 Part 3: Commands Trusted Platform Module Library
10491
10492
1049323.2 Signed Authorization Actions
10494
1049523.2.1 Introduction
10496
10497The TPM2_PolicySigned, TPM_PolicySecret, and TPM2_PolicyTicket commands use many of the same
10498functions. This clause consolidates those functions to simplify the document and to ensure uniformity of
10499the operations.
10500
1050123.2.2 Policy Parameter Checks
10502
10503These parameter checks will be performed when indicated in the description of each of the commands:
10504a) 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).
10507b) 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.
10514c) 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
10520d) 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
10540Page 232 TCG Published Family “2.0”
10541October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
10542 Trusted Platform Module Library Part 3: Commands
10543
10544
1054523.2.3 Policy Digest Update Function (PolicyUpdate())
10546
10547This is the update process for policySession→policyDigest used by TPM2_PolicySigned(),
10548TPM2_PolicySecret(), TPM2_PolicyTicket(), and TPM2_PolicyAuthorize(). The function prototype for the
10549update function is:
10550 PolicyUpdate(commandCode, arg2, arg3) (9)
10551where
10552 arg2 a TPM2B_NAME
10553 arg3 a TPM2B
10554These parameters are used to update policySession→policyDigest by
10555 policyDigestnew ≔ HpolicyAlg(policyDigestold || commandCode || arg2.name) (10)
10556followed by
10557 policyDigestnew+1 ≔ HpolicyAlg(policyDigestnew || arg3.buffer) (11)
10558where
10559 HpolicyAlg() the hash algorithm chosen when the policy session was started
10560
10561NOTE 1 If arg3 is a TPM2B_NAME, then arg3.buffer will actually be an arg3.name.
10562
10563NOTE 2 The arg2.size and arg3.size fields are not included in the hashes.
10564
10565NOTE 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
10575Family “2.0” TCG Published Page 233
10576Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
10577 Part 3: Commands Trusted Platform Module Library
10578
10579
10580
1058123.2.4 Policy Context Updates
10582
10583When a policy command modifies some part of the policy session context other than the
10584policySession→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
10616NOTE 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
10624Page 234 TCG Published Family “2.0”
10625October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
10626 Trusted Platform Module Library Part 3: Commands
10627
10628
1062923.2.5 Policy Ticket Creation
10630
10631If, for TPM2_PolicySigned() or TPM2_PolicySecret(), the caller specified a negative value for expiration,
10632and the nonceTPM matches policySession->nonceTPM, then the TPM will return a ticket that includes a
10633value indicating when the authorization expires. If expiration is non-negative, then the TPM will return a
10634NULL ticket.
10635The required computation for the digest in the authorization ticket is:
10636 HMAC(proof, HpolicyAlg(ticketType || timeout || cpHashA || policyRef || authObject→Name)) (12)
10637where
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
10669Family “2.0” TCG Published Page 235
10670Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
10671 Part 3: Commands Trusted Platform Module Library
10672
1067323.3 TPM2_PolicySigned
10674
1067523.3.1 General Description
10676
10677This command includes a signed authorization in a policy. The command ties the policy to a signing key
10678by including the Name of the signing key in the policyDigest
10679If policySession is a trial session, the TPM will not check the signature and will update
10680policySession→policyDigest as described in 23.2.3 as if a properly signed authorization was received, but
10681no ticket will be produced.
10682If policySession is not a trial session, the TPM will validate auth and only perform the update if it is a valid
10683signature over the fields of the command.
10684The authorizing entity will sign a digest of the authorization qualifiers: nonceTPM, expiration, cpHashA,
10685and policyRef. The digest is computed as:
10686 aHash ≔ HauthAlg(nonceTPM || expiration || cpHashA || policyRef) (13)
10687where
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
10714EXAMPLE 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
10720The aHash is signed by the key associated with a key whose handle is authObject. The signature and
10721signing parameters are combined to create the auth parameter.
10722The TPM will perform the parameter checks listed in 23.2.2
10723If the parameter checks succeed, the TPM will construct a test digest (tHash) over the provided
10724parameters using the same formulation as shown in equation (13) above.
10725If tHash does not match the digest of the signed aHash, then the authorization fails and the TPM shall
10726return TPM_RC_POLICY_FAIL and make no change to policySession→policyDigest.
10727
10728
10729Page 236 TCG Published Family “2.0”
10730October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
10731 Trusted Platform Module Library Part 3: Commands
10732
10733When all validations have succeeded, policySession→policyDigest is updated by PolicyUpdate() (see
1073423.2.3).
10735 PolicyUpdate(TPM_CC_PolicySigned, authObject→Name, policyRef) (14)
10736policySession is updated as described in 23.2.4. The TPM will optionally produce a ticket as described in
1073723.2.5.
10738Authorization to use authObject is not required.
10739
10740
10741
10742
10743Family “2.0” TCG Published Page 237
10744Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
10745 Part 3: Commands Trusted Platform Module Library
10746
10747
10748
1074923.3.2 Command and Response
10750
10751 Table 113 — TPM2_PolicySigned Command
10752Type Name Description
10753
10754 TPM_ST_SESSIONS if an audit, encrypt, or decrypt
10755TPMI_ST_COMMAND_TAG tag session is present; otherwise,
10756 TPM_ST_NO_SESSIONS
10757UINT32 commandSize
10758TPM_CC commandCode TPM_CC_PolicySigned
10759
10760 handle for a key that will validate the signature
10761TPMI_DH_OBJECT authObject
10762 Auth Index: None
10763 handle for the policy session being extended
10764TPMI_SH_POLICY policySession
10765 Auth Index: None
10766
10767 the policy nonce for the session
10768TPM2B_NONCE nonceTPM
10769 This can be the Empty Buffer.
10770 digest of the command parameters to which this
10771 authorization is limited
10772TPM2B_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
10778TPM2B_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
10783INT32 expiration
10784 If expiration is non-negative, a NULL Ticket is returned.
10785 See 23.2.5.
10786TPMT_SIGNATURE auth signed authorization (not optional)
10787
10788
10789 Table 114 — TPM2_PolicySigned Response
10790Type Name Description
10791
10792TPM_ST tag see clause 6
10793UINT32 responseSize
10794TPM_RC responseCode
10795
10796 implementation-specific time value, used to indicate to
10797 the TPM when the ticket expires
10798TPM2B_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
10803TPMT_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
10809Page 238 TCG Published Family “2.0”
10810October 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
108171 #include "InternalRoutines.h"
108182 #include "Policy_spt_fp.h"
108193 #include "PolicySigned_fp.h"
108204 #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 )
1084210 {
1084311 TPM_RC result = TPM_RC_SUCCESS;
1084412 SESSION *session;
1084513 TPM2B_NAME entityName;
1084614 TPM2B_DIGEST authHash;
1084715 HASH_STATE hashState;
1084816 UINT32 expiration = (in->expiration < 0)
1084917 ? -(in->expiration) : in->expiration;
1085018 UINT64 authTimeout = 0;
1085119
1085220 // Input Validation
1085321
1085422 // Set up local pointers
1085523 session = SessionGet(in->policySession); // the session structure
1085624
1085725 // Only do input validation if this is not a trial policy session
1085826 if(session->attributes.isTrialPolicy == CLEAR)
1085927 {
1086028 if(expiration != 0)
1086129 authTimeout = expiration * 1000 + session->startTime;
1086230
1086331 result = PolicyParameterChecks(session, authTimeout,
1086432 &in->cpHashA, &in->nonceTPM,
1086533 RC_PolicySigned_nonceTPM,
1086634 RC_PolicySigned_cpHashA,
1086735 RC_PolicySigned_expiration);
1086836 if(result != TPM_RC_SUCCESS)
1086937 return result;
1087038
1087139 // Re-compute the digest being signed
1087240 /*(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
10937100 )
10938101 {
10939102 // Generate timeout buffer. The format of output timeout buffer is
10940103 // TPM-specific.
10941104 // Note: can't do a direct copy because the output buffer is a byte
10942105 // array and it may not be aligned to accept a 64-bit value. The method
10943106 // 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
10949107 // 64-bit value that is byte aligned.
10950108 out->timeout.t.size = sizeof(UINT64);
10951109 UINT64_TO_BYTE_ARRAY(authTimeout, out->timeout.t.buffer);
10952110
10953111 // Compute policy ticket
10954112 TicketComputeAuth(TPM_ST_AUTH_SIGNED, EntityGetHierarchy(in->authObject),
10955113 authTimeout, &in->cpHashA, &in->policyRef, &entityName,
10956114 &out->policyTicket);
10957115 }
10958116 else
10959117 {
10960118 // Generate a null ticket.
10961119 // timeout buffer is null
10962120 out->timeout.t.size = 0;
10963121
10964122 // auth ticket is null
10965123 out->policyTicket.tag = TPM_ST_AUTH_SIGNED;
10966124 out->policyTicket.hierarchy = TPM_RH_NULL;
10967125 out->policyTicket.digest.t.size = 0;
10968126 }
10969127
10970128 return TPM_RC_SUCCESS;
10971129 }
10972130 #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
1098223.4 TPM2_PolicySecret
10983
1098423.4.1 General Description
10985
10986This command includes a secret-based authorization to a policy. The caller proves knowledge of the
10987secret value using an authorization session using the authValue associated with authHandle. A password
10988session, an HMAC session, or a policy session containing TPM2_PolicyAuthValue() or
10989TPM2_PolicyPassword() will satisfy this requirement.
10990If a policy session is used and use of the authValue of authHandle is not required, the TPM will return
10991TPM_RC_MODE.
10992The secret is the authValue of the entity whose handle is authHandle, which may be any TPM entity with
10993a handle and an associated authValue. This includes the reserved handles (for example, Platform,
10994Storage, and Endorsement), NV Indexes, and loaded objects.
10995
10996NOTE 1 The authorization value for a hierarchy cannot be used in this command if the hierarchy is disabled.
10997
10998If the authorization check fails, then the normal dictionary attack logic is invoked.
10999If the authorization provided by the authorization session is valid, the command parameters are checked
11000as described in 23.2.2.
11001nonceTPM must be present if expiration is non-zero.
11002When all validations have succeeded, policySession→policyDigest is updated by PolicyUpdate() (see
1100323.2.3).
11004 PolicyUpdate(TPM_CC_PolicySecret, authObject→Name, policyRef) (15)
11005policySession is updated as described in 23.2.4. The TPM will optionally produce a ticket as described in
1100623.2.5.
11007If the session is a trial session, policySession→policyDigest is updated as if the authorization is valid but
11008no check is performed.
11009
11010NOTE 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
11018Page 242 TCG Published Family “2.0”
11019October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
11020 Trusted Platform Module Library Part 3: Commands
11021
11022
1102323.4.2 Command and Response
11024
11025 Table 115 — TPM2_PolicySecret Command
11026Type Name Description
11027
11028TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
11029UINT32 commandSize
11030TPM_CC commandCode TPM_CC_PolicySecret
11031
11032 handle for an entity providing the authorization
11033TPMI_DH_ENTITY @authHandle Auth Index: 1
11034 Auth Role: USER
11035 handle for the policy session being extended
11036TPMI_SH_POLICY policySession
11037 Auth Index: None
11038
11039 the policy nonce for the session
11040TPM2B_NONCE nonceTPM
11041 This can be the Empty Buffer.
11042 digest of the command parameters to which this
11043 authorization is limited
11044TPM2B_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
11050TPM2B_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
11055INT32 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
11061Type Name Description
11062
11063TPM_ST tag see clause 6
11064UINT32 responseSize
11065TPM_RC responseCode
11066
11067 implementation-specific time value used to indicate to
11068TPM2B_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
11071TPMT_TK_AUTH policyTicket
11072 the command was non-zero. See 23.2.5
11073
11074
11075
11076
11077Family “2.0” TCG Published Page 243
11078Level 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
110851 #include "InternalRoutines.h"
110862 #include "PolicySecret_fp.h"
110873 #ifdef TPM_CC_PolicySecret // Conditional expansion of this file
110884 #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 )
1110710 {
1110811 TPM_RC result;
1110912 SESSION *session;
1111013 TPM2B_NAME entityName;
1111114 UINT32 expiration = (in->expiration < 0)
1111215 ? -(in->expiration) : in->expiration;
1111316 UINT64 authTimeout = 0;
1111417
1111518 // Input Validation
1111619
1111720 // Get pointer to the session structure
1111821 session = SessionGet(in->policySession);
1111922
1112023 //Only do input validation if this is not a trial policy session
1112124 if(session->attributes.isTrialPolicy == CLEAR)
1112225 {
1112326
1112427 if(expiration != 0)
1112528 authTimeout = expiration * 1000 + session->startTime;
1112629
1112730 result = PolicyParameterChecks(session, authTimeout,
1112831 &in->cpHashA, &in->nonceTPM,
1112932 RC_PolicySecret_nonceTPM,
1113033 RC_PolicySecret_cpHashA,
1113134 RC_PolicySecret_expiration);
1113235 if(result != TPM_RC_SUCCESS)
1113336 return result;
1113437 }
1113538
1113639 // Internal Data Update
1113740 // Need the name of the authorizing entity
1113841 entityName.t.size = EntityGetName(in->authHandle, &entityName.t.name);
1113942
1114043 // Update policy context with input policyRef and name of auth key
1114144 // This value is computed even for trial sessions. Possibly update the cpHash
1114245 PolicyContextUpdate(TPM_CC_PolicySecret, &entityName, &in->policyRef,
1114346 &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
1114947
1115048 // Command Output
1115149
1115250 // Create ticket and timeout buffer if in->expiration < 0 and this is not
1115351 // a trial session.
1115452 // NOTE: PolicyParameterChecks() makes sure that nonceTPM is present
1115553 // when expiration is non-zero.
1115654 if( in->expiration < 0
1115755 && session->attributes.isTrialPolicy == CLEAR
1115856 )
1115957 {
1116058 // Generate timeout buffer. The format of output timeout buffer is
1116159 // TPM-specific.
1116260 // Note: can't do a direct copy because the output buffer is a byte
1116361 // array and it may not be aligned to accept a 64-bit value. The method
1116462 // used has the side-effect of making the returned value a big-endian,
1116563 // 64-bit value that is byte aligned.
1116664 out->timeout.t.size = sizeof(UINT64);
1116765 UINT64_TO_BYTE_ARRAY(authTimeout, out->timeout.t.buffer);
1116866
1116967 // Compute policy ticket
1117068 TicketComputeAuth(TPM_ST_AUTH_SECRET, EntityGetHierarchy(in->authHandle),
1117169 authTimeout, &in->cpHashA, &in->policyRef,
1117270 &entityName, &out->policyTicket);
1117371 }
1117472 else
1117573 {
1117674 // timeout buffer is null
1117775 out->timeout.t.size = 0;
1117876
1117977 // auth ticket is null
1118078 out->policyTicket.tag = TPM_ST_AUTH_SECRET;
1118179 out->policyTicket.hierarchy = TPM_RH_NULL;
1118280 out->policyTicket.digest.t.size = 0;
1118381 }
1118482
1118583 return TPM_RC_SUCCESS;
1118684 }
1118785 #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
1119723.5 TPM2_PolicyTicket
11198
1119923.5.1 General Description
11200
11201This command is similar to TPM2_PolicySigned() except that it takes a ticket instead of a signed
11202authorization. The ticket represents a validated authorization that had an expiration time associated with
11203it.
11204The parameters of this command are checked as described in 23.2.2.
11205If the checks succeed, the TPM uses the timeout, cpHashA, policyRef, and authName to construct a
11206ticket 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)
11209If the structure tag of ticket is TPM_ST_AUTH_SECRET, then commandCode will be
11210TPM_CC_PolicySecret. If the structure tag of ticket is TPM_ST_AUTH_SIGNED, then commandCode will
11211be TPM_CC_PolicySIgned.
11212policySession is updated as described in 23.2.4.
11213
11214
11215
11216
11217Page 246 TCG Published Family “2.0”
11218October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
11219 Trusted Platform Module Library Part 3: Commands
11220
11221
11222
1122323.5.2 Command and Response
11224
11225 Table 117 — TPM2_PolicyTicket Command
11226Type Name Description
11227
11228 TPM_ST_SESSIONS if an audit or decrypt session is
11229TPMI_ST_COMMAND_TAG tag
11230 present; otherwise, TPM_ST_NO_SESSIONS
11231UINT32 commandSize
11232TPM_CC commandCode TPM_CC_PolicyTicket
11233
11234 handle for the policy session being extended
11235TPMI_SH_POLICY policySession
11236 Auth Index: None
11237
11238 time when authorization will expire
11239TPM2B_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
11243TPM2B_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
11247TPM2B_NONCE policyRef
11248 Empty Buffer
11249TPM2B_NAME authName name of the object that provided the authorization
11250 an authorization ticket returned by the TPM in response
11251TPMT_TK_AUTH ticket
11252 to a TPM2_PolicySigned() or TPM2_PolicySecret()
11253
11254
11255 Table 118 — TPM2_PolicyTicket Response
11256Type Name Description
11257
11258TPM_ST tag see clause 6
11259UINT32 responseSize
11260TPM_RC responseCode
11261
11262
11263
11264
11265Family “2.0” TCG Published Page 247
11266Level 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
112731 #include "InternalRoutines.h"
112742 #include "PolicyTicket_fp.h"
112753 #ifdef TPM_CC_PolicyTicket // Conditional expansion of this file
112764 #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 {
1129110 TPM_RC result;
1129211 SESSION *session;
1129312 UINT64 timeout;
1129413 TPMT_TK_AUTH ticketToCompare;
1129514 TPM_CC commandCode = TPM_CC_PolicySecret;
1129615
1129716 // Input Validation
1129817
1129918 // Get pointer to the session structure
1130019 session = SessionGet(in->policySession);
1130120
1130221 // NOTE: A trial policy session is not allowed to use this command.
1130322 // A ticket is used in place of a previously given authorization. Since
1130423 // a trial policy doesn't actually authenticate, the validated
1130524 // ticket is not necessary and, in place of using a ticket, one
1130625 // should use the intended authorization for which the ticket
1130726 // would be a substitute.
1130827 if(session->attributes.isTrialPolicy)
1130928 return TPM_RCS_ATTRIBUTES + RC_PolicyTicket_policySession;
1131029
1131130 // Restore timeout data. The format of timeout buffer is TPM-specific.
1131231 // In this implementation, we simply copy the value of timeout to the
1131332 // buffer.
1131433 if(in->timeout.t.size != sizeof(UINT64))
1131534 return TPM_RC_SIZE + RC_PolicyTicket_timeout;
1131635 timeout = BYTE_ARRAY_TO_UINT64(in->timeout.t.buffer);
1131736
1131837 // Do the normal checks on the cpHashA and timeout values
1131938 result = PolicyParameterChecks(session, timeout,
1132039 &in->cpHashA, NULL,
1132140 0, // no bad nonce return
1132241 RC_PolicyTicket_cpHashA,
1132342 RC_PolicyTicket_timeout);
1132443 if(result != TPM_RC_SUCCESS)
1132544 return result;
1132645
1132746 // Validate Ticket
1132847 // Re-generate policy ticket by input parameters
1132948 TicketComputeAuth(in->ticket.tag, in->ticket.hierarchy, timeout, &in->cpHashA,
1133049 &in->policyRef, &in->authName, &ticketToCompare);
1133150
1133251 // 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
1133852 if(!Memory2BEqual(&in->ticket.digest.b, &ticketToCompare.digest.b))
1133953 return TPM_RC_TICKET + RC_PolicyTicket_ticket;
1134054
1134155 // Internal Data Update
1134256
1134357 // Is this ticket to take the place of a TPM2_PolicySigned() or
1134458 // a TPM2_PolicySecret()?
1134559 if(in->ticket.tag == TPM_ST_AUTH_SIGNED)
1134660 commandCode = TPM_CC_PolicySigned;
1134761 else if(in->ticket.tag == TPM_ST_AUTH_SECRET)
1134862 commandCode = TPM_CC_PolicySecret;
1134963 else
1135064 // There could only be two possible tag values. Any other value should
1135165 // be caught by the ticket validation process.
1135266 pAssert(FALSE);
1135367
1135468 // Update policy context
1135569 PolicyContextUpdate(commandCode, &in->authName, &in->policyRef,
1135670 &in->cpHashA, timeout, session);
1135771
1135872 return TPM_RC_SUCCESS;
1135973 }
1136074 #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
1137023.6 TPM2_PolicyOR
11371
1137223.6.1 General Description
11373
11374This command allows options in authorizations without requiring that the TPM evaluate all of the options.
11375If a policy may be satisfied by different sets of conditions, the TPM need only evaluate one set that
11376satisfies the policy. This command will indicate that one of the required sets of conditions has been
11377satisfied.
11378PolicySession→policyDigest is compared against the list of provided values. If the current
11379policySession→policyDigest does not match any value in the list, the TPM shall return TPM_RC_VALUE.
11380Otherwise, it will replace policySession→policyDigest with the digest of the concatenation of all of the
11381digests and return TPM_RC_SUCCESS.
11382If policySession is a trial session, the TPM will assume that policySession→policyDigest matches one of
11383the list entries and compute the new value of policyDigest.
11384The algorithm for computing the new value for policyDigest of policySession is:
11385a) 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
11391b) Reset policyDigest to a Zero Digest.
11392c) 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
11398A TPM shall support a list with at least eight tagged digest values.
11399
11400NOTE 3 If policies are to be portable between TPMs, then they should not use more than eight values.
11401
11402
11403
11404
11405Page 250 TCG Published Family “2.0”
11406October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
11407 Trusted Platform Module Library Part 3: Commands
11408
11409
1141023.6.2 Command and Response
11411
11412 Table 119 — TPM2_PolicyOR Command
11413Type Name Description
11414
11415 TPM_ST_SESSIONS if an audit session is present;
11416TPMI_ST_COMMAND_TAG tag
11417 otherwise, TPM_ST_NO_SESSIONS
11418UINT32 commandSize
11419TPM_CC commandCode TPM_CC_PolicyOR.
11420
11421 handle for the policy session being extended
11422TPMI_SH_POLICY policySession
11423 Auth Index: None
11424
11425TPML_DIGEST pHashList the list of hashes to check for a match
11426
11427
11428 Table 120 — TPM2_PolicyOR Response
11429Type Name Description
11430
11431TPM_ST tag see clause 6
11432UINT32 responseSize
11433TPM_RC responseCode
11434
11435
11436
11437
11438Family “2.0” TCG Published Page 251
11439Level 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
114461 #include "InternalRoutines.h"
114472 #include "PolicyOR_fp.h"
114483 #ifdef TPM_CC_PolicyOR // Conditional expansion of this file
114494 #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 {
1146210 SESSION *session;
1146311 UINT32 i;
1146412
1146513 // Input Validation and Update
1146614
1146715 // Get pointer to the session structure
1146816 session = SessionGet(in->policySession);
1146917
1147018 // Compare and Update Internal Session policy if match
1147119 for(i = 0; i < in->pHashList.count; i++)
1147220 {
1147321 if( session->attributes.isTrialPolicy == SET
1147422 || (Memory2BEqual(&session->u2.policyDigest.b,
1147523 &in->pHashList.digests[i].b))
1147624 )
1147725 {
1147826 // Found a match
1147927 HASH_STATE hashState;
1148028 TPM_CC commandCode = TPM_CC_PolicyOR;
1148129
1148230 // Start hash
1148331 session->u2.policyDigest.t.size = CryptStartHash(session->authHashAlg,
1148432 &hashState);
1148533 // Set policyDigest to 0 string and add it to hash
1148634 MemorySet(session->u2.policyDigest.t.buffer, 0,
1148735 session->u2.policyDigest.t.size);
1148836 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b);
1148937
1149038 // add command code
1149139 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode);
1149240
1149341 // Add each of the hashes in the list
1149442 for(i = 0; i < in->pHashList.count; i++)
1149543 {
1149644 // Extend policyDigest
1149745 CryptUpdateDigest2B(&hashState, &in->pHashList.digests[i].b);
1149846 }
1149947 // Complete digest
1150048 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b);
1150149
1150250 return TPM_RC_SUCCESS;
1150351 }
1150452 }
1150553 // None of the values in the list matched the current policyDigest
1150654 return TPM_RC_VALUE + RC_PolicyOR_pHashList;
1150755 }
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
1151356 #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
1152323.7 TPM2_PolicyPCR
11524
1152523.7.1 General Description
11526
11527This command is used to cause conditional gating of a policy based on PCR. This command together
11528with TPM2_PolicyOR() allows one group of authorizations to occur when PCR are in one state and a
11529different set of authorizations when the PCR are in a different state. If this command is used for a trial
11530policySession, policySession→policyDigest will be updated using the values from the command rather
11531than the values from digest of the TPM PCR.
11532The TPM will modify the pcrs parameter so that bits that correspond to unimplemented PCR are CLEAR.
11533If policySession is not a trial policy session, the TPM will use the modified value of pcrs to select PCR
11534values to hash according to TPM 2.0 Part 1, Selecting Multiple PCR. The hash algorithm of the policy
11535session is used to compute a digest (digestTPM) of the selected PCR. If pcrDigest does not have a length
11536of zero, then it is compared to digestTPM; and if the values do not match, the TPM shall return
11537TPM_RC_VALUE and make no change to policySession→policyDigest. If the values match, or if the
11538length of pcrDigest is zero, then policySession→policyDigest is extended by:
11539 policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyPCR || pcrs || digestTPM) (19)
11540where
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
11546NOTE 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
11553After this command completes successfully, the TPM shall return TPM_RC_PCR_CHANGED if the policy
11554session is used for authorization and the PCR are not known to be correct.
11555The TPM uses a “generation” number (pcrUpdateCounter) that is incremented each time PCR are
11556updated (unless the PCR being changed is specified not to cause a change to this counter). The value of
11557this counter is stored in the policy session context (policySession→pcrUpdateCounter) when this
11558command is executed. When the policy is used for authorization, the current value of the counter is
11559compared to the value in the policy session context and the authorization will fail if the values are not the
11560same.
11561When this command is executed, policySession→pcrUpdateCounter is checked to see if it has been
11562previously set (in the reference implementation, it has a value of zero if not previously set). If it has been
11563set, it will be compared with the current value of pcrUpdateCounter to determine if any PCR changes
11564have occurred. If the values are different, the TPM shall return TPM_RC_PCR_CHANGED.
11565
11566NOTE 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
11572If policySession→pcrUpdateCounter has not been set, then it is set to the current value of
11573pcrUpdateCounter.
11574
11575
11576
11577
11578Page 254 TCG Published Family “2.0”
11579October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
11580 Trusted Platform Module Library Part 3: Commands
11581
11582If 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)
11584In this computation, pcrs is the input parameter without modification.
11585
11586NOTE 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
11589NOTE 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
11596Family “2.0” TCG Published Page 255
11597Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
11598 Part 3: Commands Trusted Platform Module Library
11599
11600
1160123.7.2 Command and Response
11602
11603 Table 121 — TPM2_PolicyPCR Command
11604Type Name Description
11605
11606 TPM_ST_SESSIONS if an audit or decrypt session is
11607TPMI_ST_COMMAND_TAG tag
11608 present; otherwise, TPM_ST_NO_SESSIONS
11609UINT32 commandSize
11610TPM_CC commandCode TPM_CC_PolicyPCR
11611
11612 handle for the policy session being extended
11613TPMI_SH_POLICY policySession
11614 Auth Index: None
11615
11616 expected digest value of the selected PCR using the
11617TPM2B_DIGEST pcrDigest
11618 hash algorithm of the session; may be zero length
11619TPML_PCR_SELECTION pcrs the PCR to include in the check digest
11620
11621
11622 Table 122 — TPM2_PolicyPCR Response
11623Type Name Description
11624
11625TPM_ST tag see clause 6
11626UINT32 responseSize
11627TPM_RC responseCode
11628
11629
11630
11631
11632Page 256 TCG Published Family “2.0”
11633October 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
116401 #include "InternalRoutines.h"
116412 #include "PolicyPCR_fp.h"
116423 #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;
1165610 TPM2B_DIGEST pcrDigest;
1165711 BYTE pcrs[sizeof(TPML_PCR_SELECTION)];
1165812 UINT32 pcrSize;
1165913 BYTE *buffer;
1166014 TPM_CC commandCode = TPM_CC_PolicyPCR;
1166115 HASH_STATE hashState;
1166216
1166317 // Input Validation
1166418
1166519 // Get pointer to the session structure
1166620 session = SessionGet(in->policySession);
1166721
1166822 // Do validation for non trial session
1166923 if(session->attributes.isTrialPolicy == CLEAR)
1167024 {
1167125 // Make sure that this is not going to invalidate a previous PCR check
1167226 if(session->pcrCounter != 0 && session->pcrCounter != gr.pcrCounter)
1167327 return TPM_RC_PCR_CHANGED;
1167428
1167529 // Compute current PCR digest
1167630 PCRComputeCurrentDigest(session->authHashAlg, &in->pcrs, &pcrDigest);
1167731
1167832 // If the caller specified the PCR digest and it does not
1167933 // match the current PCR settings, return an error..
1168034 if(in->pcrDigest.t.size != 0)
1168135 {
1168236 if(!Memory2BEqual(&in->pcrDigest.b, &pcrDigest.b))
1168337 return TPM_RC_VALUE + RC_PolicyPCR_pcrDigest;
1168438 }
1168539 }
1168640 else
1168741 {
1168842 // For trial session, just use the input PCR digest
1168943 pcrDigest = in->pcrDigest;
1169044 }
1169145 // Internal Data Update
1169246
1169347 // Update policy hash
1169448 // policyDigestnew = hash( policyDigestold || TPM_CC_PolicyPCR
1169549 // || pcrs || pcrDigest)
1169650 // Start hash
1169751 CryptStartHash(session->authHashAlg, &hashState);
1169852
1169953 // add old digest
1170054 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
1170655
1170756 // add commandCode
1170857 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode);
1170958
1171059 // add PCRS
1171160 buffer = pcrs;
1171261 pcrSize = TPML_PCR_SELECTION_Marshal(&in->pcrs, &buffer, NULL);
1171362 CryptUpdateDigest(&hashState, pcrSize, pcrs);
1171463
1171564 // add PCR digest
1171665 CryptUpdateDigest2B(&hashState, &pcrDigest.b);
1171766
1171867 // complete the hash and get the results
1171968 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b);
1172069
1172170 // update pcrCounter in session context for non trial session
1172271 if(session->attributes.isTrialPolicy == CLEAR)
1172372 {
1172473 session->pcrCounter = gr.pcrCounter;
1172574 }
1172675
1172776 return TPM_RC_SUCCESS;
1172877 }
1172978 #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
1173923.8 TPM2_PolicyLocality
11740
1174123.8.1 General Description
11742
11743This command indicates that the authorization will be limited to a specific locality.
11744policySession→commandLocality is a parameter kept in the session context. When the policy session is
11745started, this parameter is initialized to a value that allows the policy to apply to any locality.
11746If locality has a value greater than 31, then an extended locality is indicated. For an extended locality, the
11747TPM will validate that policySession→commandLocality has not previously been set or that the current
11748value of policySession→commandLocality is the same as locality (TPM_RC_RANGE).
11749When locality is not an extended locality, the TPM will validate that the policySession→commandLocality
11750is not set to an extended locality value (TPM_RC_RANGE). If not the TPM will disable any locality not
11751SET in the locality parameter. If the result of disabling localities results in no locality being enabled, the
11752TPM will return TPM_RC_RANGE.
11753If no error occurred in the validation of locality, policySession→policyDigest is extended with
11754 policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyLocality || locality) (21)
11755Then policySession→commandLocality is updated to indicate which localities are still allowed after
11756execution of TPM2_PolicyLocality().
11757When the policy session is used to authorize a command, the authorization will fail if the locality used for
11758the command is not one of the enabled localities in policySession→commandLocality.
11759
11760
11761
11762
11763Family “2.0” TCG Published Page 259
11764Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
11765 Part 3: Commands Trusted Platform Module Library
11766
11767
11768
1176923.8.2 Command and Response
11770
11771 Table 123 — TPM2_PolicyLocality Command
11772Type Name Description
11773
11774 TPM_ST_SESSIONS if an audit session is present;
11775TPMI_ST_COMMAND_TAG tag
11776 otherwise, TPM_ST_NO_SESSIONS
11777UINT32 commandSize
11778TPM_CC commandCode TPM_CC_PolicyLocality
11779
11780 handle for the policy session being extended
11781TPMI_SH_POLICY policySession
11782 Auth Index: None
11783
11784TPMA_LOCALITY locality the allowed localities for the policy
11785
11786
11787 Table 124 — TPM2_PolicyLocality Response
11788Type Name Description
11789
11790TPM_ST tag see clause 6
11791UINT32 responseSize
11792TPM_RC responseCode
11793
11794
11795
11796
11797Page 260 TCG Published Family “2.0”
11798October 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
118051 #include "InternalRoutines.h"
118062 #include "PolicyLocality_fp.h"
118073 #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;
1182210 BYTE marshalBuffer[sizeof(TPMA_LOCALITY)];
1182311 BYTE prevSetting[sizeof(TPMA_LOCALITY)];
1182412 UINT32 marshalSize;
1182513 BYTE *buffer;
1182614 TPM_CC commandCode = TPM_CC_PolicyLocality;
1182715 HASH_STATE hashState;
1182816
1182917 // Input Validation
1183018
1183119 // Get pointer to the session structure
1183220 session = SessionGet(in->policySession);
1183321
1183422 // Get new locality setting in canonical form
1183523 buffer = marshalBuffer;
1183624 marshalSize = TPMA_LOCALITY_Marshal(&in->locality, &buffer, NULL);
1183725
1183826 // Its an error if the locality parameter is zero
1183927 if(marshalBuffer[0] == 0)
1184028 return TPM_RC_RANGE + RC_PolicyLocality_locality;
1184129
1184230 // Get existing locality setting in canonical form
1184331 buffer = prevSetting;
1184432 TPMA_LOCALITY_Marshal(&session->commandLocality, &buffer, NULL);
1184533
1184634 // If the locality has previously been set
1184735 if( prevSetting[0] != 0
1184836 // then the current locality setting and the requested have to be the same
1184937 // type (that is, either both normal or both extended
1185038 && ((prevSetting[0] < 32) != (marshalBuffer[0] < 32)))
1185139 return TPM_RC_RANGE + RC_PolicyLocality_locality;
1185240
1185341 // See if the input is a regular or extended locality
1185442 if(marshalBuffer[0] < 32)
1185543 {
1185644 // if there was no previous setting, start with all normal localities
1185745 // enabled
1185846 if(prevSetting[0] == 0)
1185947 prevSetting[0] = 0x1F;
1186048
1186149 // AND the new setting with the previous setting and store it in prevSetting
1186250 prevSetting[0] &= marshalBuffer[0];
1186351
1186452 // The result setting can not be 0
1186553 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
1187154 return TPM_RC_RANGE + RC_PolicyLocality_locality;
1187255 }
1187356 else
1187457 {
1187558 // for extended locality
1187659 // if the locality has already been set, then it must match the
1187760 if(prevSetting[0] != 0 && prevSetting[0] != marshalBuffer[0])
1187861 return TPM_RC_RANGE + RC_PolicyLocality_locality;
1187962
1188063 // Setting is OK
1188164 prevSetting[0] = marshalBuffer[0];
1188265
1188366 }
1188467
1188568 // Internal Data Update
1188669
1188770 // Update policy hash
1188871 // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyLocality || locality)
1188972 // Start hash
1189073 CryptStartHash(session->authHashAlg, &hashState);
1189174
1189275 // add old digest
1189376 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b);
1189477
1189578 // add commandCode
1189679 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode);
1189780
1189881 // add input locality
1189982 CryptUpdateDigest(&hashState, marshalSize, marshalBuffer);
1190083
1190184 // complete the digest
1190285 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b);
1190386
1190487 // update session locality by unmarshal function. The function must succeed
1190588 // because both input and existing locality setting have been validated.
1190689 buffer = prevSetting;
1190790 TPMA_LOCALITY_Unmarshal(&session->commandLocality, &buffer,
1190891 (INT32 *) &marshalSize);
1190992
1191093 return TPM_RC_SUCCESS;
1191194 }
1191295 #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
1192223.9 TPM2_PolicyNV
11923
1192423.9.1 General Description
11925
11926This command is used to cause conditional gating of a policy based on the contents of an NV Index.
11927If policySession is a trial policy session, the TPM will update policySession→policyDigest as shown in
11928equations (22) and (23) below and return TPM_RC_SUCCESS. It will not perform any validation. The
11929remainder of this general description would apply only if policySession is not a trial policy session.
11930An authorization session providing authorization to read the NV Index shall be provided.
11931
11932NOTE If read access is controlled by policy, the policy should include a branch that authorizes a
11933 TPM2_PolicyNV().
11934
11935If TPMA_NV_WRITTEN is not SET in the NV Index, the TPM shall return TPM_RC_NV_UNINITIALIZED.
11936The TPM will validate that the size of operandB plus offset is not greater than the size of the NV Index. If
11937it is, the TPM shall return TPM_RC_SIZE.
11938operandA begins at offest into the NV index contents and has a size equal to the size of operandB. The
11939TPM will perform the indicated arithmetic check using operandA and operandB. . If the check fails, the
11940TPM shall return TPM_RC_POLICY and not change policySession→policyDigest. If the check succeeds,
11941the TPM will hash the arguments:
11942 args ≔ HpolicyAlg(operandB.buffer || offset || operation) (22)
11943where
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
11951The 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)
11953where
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
11959The signed arithmetic operations are performed using twos-compliment.
11960Magnitude comparisons assume that the octet at offset zero in the referenced NV location and in
11961operandB contain the most significant octet of the data.
11962
11963
11964
11965
11966Family “2.0” TCG Published Page 263
11967Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
11968 Part 3: Commands Trusted Platform Module Library
11969
11970
11971
1197223.9.2 Command and Response
11973
11974 Table 125 — TPM2_PolicyNV Command
11975Type Name Description
11976
11977TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
11978UINT32 commandSize
11979TPM_CC commandCode TPM_CC_PolicyNV
11980
11981 handle indicating the source of the authorization value
11982TPMI_RH_NV_AUTH @authHandle Auth Index: 1
11983 Auth Role: USER
11984 the NV Index of the area to read
11985TPMI_RH_NV_INDEX nvIndex
11986 Auth Index: None
11987 handle for the policy session being extended
11988TPMI_SH_POLICY policySession
11989 Auth Index: None
11990
11991TPM2B_OPERAND operandB the second operand
11992UINT16 offset the offset in the NV Index for the start of operand A
11993TPM_EO operation the comparison to make
11994
11995
11996 Table 126 — TPM2_PolicyNV Response
11997Type Name Description
11998
11999TPM_ST tag see clause 6
12000UINT32 responseSize
12001TPM_RC responseCode
12002
12003
12004
12005
12006Page 264 TCG Published Family “2.0”
12007October 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
120141 #include "InternalRoutines.h"
120152 #include "PolicyNV_fp.h"
120163 #ifdef TPM_CC_PolicyNV // Conditional expansion of this file
120174 #include "Policy_spt_fp.h"
120185 #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 )
1203410 {
1203511 TPM_RC result;
1203612 SESSION *session;
1203713 NV_INDEX nvIndex;
1203814 BYTE nvBuffer[sizeof(in->operandB.t.buffer)];
1203915 TPM2B_NAME nvName;
1204016 TPM_CC commandCode = TPM_CC_PolicyNV;
1204117 HASH_STATE hashState;
1204218 TPM2B_DIGEST argHash;
1204319
1204420 // Input Validation
1204521
1204622 // Get NV index information
1204723 NvGetIndexInfo(in->nvIndex, &nvIndex);
1204824
1204925 // Get pointer to the session structure
1205026 session = SessionGet(in->policySession);
1205127
1205228 //If this is a trial policy, skip all validations and the operation
1205329 if(session->attributes.isTrialPolicy == CLEAR)
1205430 {
1205531 // NV Read access check. NV index should be allowed for read. A
1205632 // TPM_RC_AUTH_TYPE or TPM_RC_NV_LOCKED error may be return at this
1205733 // point
1205834 result = NvReadAccessChecks(in->authHandle, in->nvIndex);
1205935 if(result != TPM_RC_SUCCESS) return result;
1206036
1206137 // Valid NV data size should not be smaller than input operandB size
1206238 if((nvIndex.publicArea.dataSize - in->offset) < in->operandB.t.size)
1206339 return TPM_RC_SIZE + RC_PolicyNV_operandB;
1206440
1206541 // Arithmetic Comparison
1206642
1206743 // Get NV data. The size of NV data equals the input operand B size
1206844 NvGetIndexData(in->nvIndex, &nvIndex, in->offset,
1206945 in->operandB.t.size, nvBuffer);
1207046
1207147 switch(in->operation)
1207248 {
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,
12129100 in->operandB.t.size, in->operandB.t.buffer) > 0)
12130101 return TPM_RC_POLICY;
12131102 break;
12132103 case TPM_EO_UNSIGNED_LE:
12133104 // compare A <= B unsigned
12134105 if(CryptCompare(in->operandB.t.size, nvBuffer,
12135106 in->operandB.t.size, in->operandB.t.buffer) > 0)
12136107 return TPM_RC_POLICY;
12137108 break;
12138109 case TPM_EO_BITSET:
12139110 // All bits SET in B are SET in A. ((A&B)=B)
12140111 {
12141112 UINT32 i;
12142113 for (i = 0; i < in->operandB.t.size; i++)
12143114 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
12149115 != in->operandB.t.buffer[i])
12150116 return TPM_RC_POLICY;
12151117 }
12152118 break;
12153119 case TPM_EO_BITCLEAR:
12154120 // All bits SET in B are CLEAR in A. ((A&B)=0)
12155121 {
12156122 UINT32 i;
12157123 for (i = 0; i < in->operandB.t.size; i++)
12158124 if((nvBuffer[i] & in->operandB.t.buffer[i]) != 0)
12159125 return TPM_RC_POLICY;
12160126 }
12161127 break;
12162128 default:
12163129 pAssert(FALSE);
12164130 break;
12165131 }
12166132 }
12167133
12168134 // Internal Data Update
12169135
12170136 // Start argument hash
12171137 argHash.t.size = CryptStartHash(session->authHashAlg, &hashState);
12172138
12173139 // add operandB
12174140 CryptUpdateDigest2B(&hashState, &in->operandB.b);
12175141
12176142 // add offset
12177143 CryptUpdateDigestInt(&hashState, sizeof(UINT16), &in->offset);
12178144
12179145 // add operation
12180146 CryptUpdateDigestInt(&hashState, sizeof(TPM_EO), &in->operation);
12181147
12182148 // complete argument digest
12183149 CryptCompleteHash2B(&hashState, &argHash.b);
12184150
12185151 // Update policyDigest
12186152 // Start digest
12187153 CryptStartHash(session->authHashAlg, &hashState);
12188154
12189155 // add old digest
12190156 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b);
12191157
12192158 // add commandCode
12193159 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode);
12194160
12195161 // add argument digest
12196162 CryptUpdateDigest2B(&hashState, &argHash.b);
12197163
12198164 // Adding nvName
12199165 nvName.t.size = EntityGetName(in->nvIndex, &nvName.t.name);
12200166 CryptUpdateDigest2B(&hashState, &nvName.b);
12201167
12202168 // complete the digest
12203169 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b);
12204170
12205171 return TPM_RC_SUCCESS;
12206172 }
12207173 #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
1221723.10 TPM2_PolicyCounterTimer
12218
1221923.10.1 General Description
12220
12221This command is used to cause conditional gating of a policy based on the contents of the
12222TPMS_TIME_INFO structure.
12223If policySession is a trial policy session, the TPM will update policySession→policyDigest as shown in
12224equations (24) and (25) below and return TPM_RC_SUCCESS. It will not perform any validation. The
12225remainder of this general description would apply only if policySession is not a trial policy session.
12226The TPM will perform the indicated arithmetic check on the indicated portion of the TPMS_TIME_INFO
12227structure. If the check fails, the TPM shall return TPM_RC_POLICY and not change
12228policySession→policyDigest. If the check succeeds, the TPM will hash the arguments:
12229 args ≔ HpolicyAlg(operandB.buffer || offset || operation) (24)
12230where
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
12239The value of args is extended to policySession→policyDigest by
12240 policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyCounterTimer || args) (25)
12241where
12242 HpolicyAlg() hash function using the algorithm of the policy session
12243 args value computed in equation (24)
12244
12245
12246The signed arithmetic operations are performed using twos-compliment. The indicated portion of the
12247TPMS_TIME_INFO structure begins at offset and has a length of operandB.size. If the octets to be
12248compared overflows the TPMS_TIME_INFO structure, the TPM returns TPM_RC_RANGE. The structure
12249is marshaled into its canonical form with no padding. The TPM does not check for alignment of the offset
12250with a TPMS_TIME_INFO structure member.
12251Magnitude comparisons assume that the octet at offset zero in the referenced location and in operandB
12252contain the most significant octet of the data.
12253
12254
12255
12256
12257Page 268 TCG Published Family “2.0”
12258October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
12259 Trusted Platform Module Library Part 3: Commands
12260
12261
12262
1226323.10.2 Command and Response
12264
12265 Table 127 — TPM2_PolicyCounterTimer Command
12266Type Name Description
12267
12268 TPM_ST_SESSIONS if an audit or decrypt session is
12269TPMI_ST_COMMAND_TAG tag
12270 present; otherwise, TPM_ST_NO_SESSIONS
12271UINT32 commandSize
12272TPM_CC commandCode TPM_CC_PolicyCounterTimer
12273
12274 handle for the policy session being extended
12275TPMI_SH_POLICY policySession
12276 Auth Index: None
12277
12278TPM2B_OPERAND operandB the second operand
12279 the offset in TPMS_TIME_INFO structure for the start of
12280UINT16 offset
12281 operand A
12282TPM_EO operation the comparison to make
12283
12284
12285 Table 128 — TPM2_PolicyCounterTimer Response
12286Type Name Description
12287
12288TPM_ST tag see clause 6
12289UINT32 responseSize
12290TPM_RC responseCode
12291
12292
12293
12294
12295Family “2.0” TCG Published Page 269
12296Level 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
123031 #include "InternalRoutines.h"
123042 #include "PolicyCounterTimer_fp.h"
123053 #ifdef TPM_CC_PolicyCounterTimer // Conditional expansion of this file
123064 #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 {
1232010 TPM_RC result;
1232111 SESSION *session;
1232212 TIME_INFO infoData; // data buffer of TPMS_TIME_INFO
1232313 TPM_CC commandCode = TPM_CC_PolicyCounterTimer;
1232414 HASH_STATE hashState;
1232515 TPM2B_DIGEST argHash;
1232616
1232717 // Input Validation
1232818
1232919 // If the command is going to use any part of the counter or timer, need
1233020 // to verify that time is advancing.
1233121 // The time and clock vales are the first two 64-bit values in the clock
1233222 if(in->offset < sizeof(UINT64) + sizeof(UINT64))
1233323 {
1233424 // Using Clock or Time so see if clock is running. Clock doesn't run while
1233525 // NV is unavailable.
1233626 // TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned here.
1233727 result = NvIsAvailable();
1233828 if(result != TPM_RC_SUCCESS)
1233929 return result;
1234030 }
1234131 // Get pointer to the session structure
1234232 session = SessionGet(in->policySession);
1234333
1234434 //If this is a trial policy, skip all validations and the operation
1234535 if(session->attributes.isTrialPolicy == CLEAR)
1234636 {
1234737 // Get time data info. The size of time info data equals the input
1234838 // operand B size. A TPM_RC_RANGE error may be returned at this point
1234939 result = TimeGetRange(in->offset, in->operandB.t.size, &infoData);
1235040 if(result != TPM_RC_SUCCESS) return result;
1235141
1235242 // Arithmetic Comparison
1235343 switch(in->operation)
1235444 {
1235545 case TPM_EO_EQ:
1235646 // compare A = B
1235747 if(CryptCompare(in->operandB.t.size, infoData,
1235848 in->operandB.t.size, in->operandB.t.buffer) != 0)
1235949 return TPM_RC_POLICY;
1236050 break;
1236151 case TPM_EO_NEQ:
1236252 // compare A != B
1236353 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:
12415100 // compare A <= B unsigned
12416101 if(CryptCompare(in->operandB.t.size, infoData,
12417102 in->operandB.t.size, in->operandB.t.buffer) > 0)
12418103 return TPM_RC_POLICY;
12419104 break;
12420105 case TPM_EO_BITSET:
12421106 // All bits SET in B are SET in A. ((A&B)=B)
12422107 {
12423108 UINT32 i;
12424109 for (i = 0; i < in->operandB.t.size; i++)
12425110 if( (infoData[i] & in->operandB.t.buffer[i])
12426111 != in->operandB.t.buffer[i])
12427112 return TPM_RC_POLICY;
12428113 }
12429114 break;
12430115 case TPM_EO_BITCLEAR:
12431116 // All bits SET in B are CLEAR in A. ((A&B)=0)
12432117 {
12433118 UINT32 i;
12434119 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
12440120 if((infoData[i] & in->operandB.t.buffer[i]) != 0)
12441121 return TPM_RC_POLICY;
12442122 }
12443123 break;
12444124 default:
12445125 pAssert(FALSE);
12446126 break;
12447127 }
12448128 }
12449129
12450130 // Internal Data Update
12451131
12452132 // Start argument list hash
12453133 argHash.t.size = CryptStartHash(session->authHashAlg, &hashState);
12454134 // add operandB
12455135 CryptUpdateDigest2B(&hashState, &in->operandB.b);
12456136 // add offset
12457137 CryptUpdateDigestInt(&hashState, sizeof(UINT16), &in->offset);
12458138 // add operation
12459139 CryptUpdateDigestInt(&hashState, sizeof(TPM_EO), &in->operation);
12460140 // complete argument hash
12461141 CryptCompleteHash2B(&hashState, &argHash.b);
12462142
12463143 // update policyDigest
12464144 // start hash
12465145 CryptStartHash(session->authHashAlg, &hashState);
12466146
12467147 // add old digest
12468148 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b);
12469149
12470150 // add commandCode
12471151 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode);
12472152
12473153 // add argument digest
12474154 CryptUpdateDigest2B(&hashState, &argHash.b);
12475155
12476156 // complete the digest
12477157 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b);
12478158
12479159 return TPM_RC_SUCCESS;
12480160 }
12481161 #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
1249123.11 TPM2_PolicyCommandCode
12492
1249323.11.1 General Description
12494
12495This command indicates that the authorization will be limited to a specific command code.
12496If policySession→commandCode has its default value, then it will be set to code. If
12497policySession→commandCode does not have its default value, then the TPM will return
12498TPM_RC_VALUE if the two values are not the same.
12499If code is not implemented, the TPM will return TPM_RC_POLICY_CC.
12500If the TPM does not return an error, it will update policySession→policyDigest by
12501 policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyCommandCode || code) (26)
12502
12503NOTE 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
12506NOTE 2 A TPM2_PolicyOR() would be used to allow an authorization to be used for multiple commands.
12507
12508When the policy session is used to authorize a command, the TPM will fail the command if the
12509commandCode of that command does not match policySession→commandCode.
12510This command, or TPM2_PolicyDuplicationSelect(), is required to enable the policy to be used for ADMIN
12511role authorization.
12512
12513EXAMPLE Before TPM2_Certify() can be executed, TPM2_PolicyCommandCode() with code set to
12514 TPM_CC_Certify is required.
12515
12516
12517
12518
12519Family “2.0” TCG Published Page 273
12520Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
12521 Part 3: Commands Trusted Platform Module Library
12522
12523
1252423.11.2 Command and Response
12525
12526 Table 129 — TPM2_PolicyCommandCode Command
12527Type Name Description
12528
12529 TPM_ST_SESSIONS if an audit session is present;
12530TPMI_ST_COMMAND_TAG tag
12531 otherwise, TPM_ST_NO_SESSIONS
12532UINT32 commandSize
12533TPM_CC commandCode TPM_CC_PolicyCommandCode
12534
12535 handle for the policy session being extended
12536TPMI_SH_POLICY policySession
12537 Auth Index: None
12538
12539TPM_CC code the allowed commandCode
12540
12541
12542 Table 130 — TPM2_PolicyCommandCode Response
12543Type Name Description
12544
12545TPM_ST tag see clause 6
12546UINT32 responseSize
12547TPM_RC responseCode
12548
12549
12550
12551
12552Page 274 TCG Published Family “2.0”
12553October 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
125601 #include "InternalRoutines.h"
125612 #include "PolicyCommandCode_fp.h"
125623 #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;
1257510 TPM_CC commandCode = TPM_CC_PolicyCommandCode;
1257611 HASH_STATE hashState;
1257712
1257813 // Input validation
1257914
1258015 // Get pointer to the session structure
1258116 session = SessionGet(in->policySession);
1258217
1258318 if(session->commandCode != 0 && session->commandCode != in->code)
1258419 return TPM_RC_VALUE + RC_PolicyCommandCode_code;
1258520 if(!CommandIsImplemented(in->code))
1258621 return TPM_RC_POLICY_CC + RC_PolicyCommandCode_code;
1258722
1258823 // Internal Data Update
1258924 // Update policy hash
1259025 // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyCommandCode || code)
1259126 // Start hash
1259227 CryptStartHash(session->authHashAlg, &hashState);
1259328
1259429 // add old digest
1259530 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b);
1259631
1259732 // add commandCode
1259833 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode);
1259934
1260035 // add input commandCode
1260136 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &in->code);
1260237
1260338 // complete the hash and get the results
1260439 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b);
1260540
1260641 // update commandCode value in session context
1260742 session->commandCode = in->code;
1260843
1260944 return TPM_RC_SUCCESS;
1261045 }
1261146 #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
1262123.12 TPM2_PolicyPhysicalPresence
12622
1262323.12.1 General Description
12624
12625This command indicates that physical presence will need to be asserted at the time the authorization is
12626performed.
12627If this command is successful, policySession→isPPRequired will be SET to indicate that this check is
12628required when the policy is used for authorization. Additionally, policySession→policyDigest is extended
12629with
12630 policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyPhysicalPresence) (27)
12631
12632
12633
12634
12635Page 276 TCG Published Family “2.0”
12636October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
12637 Trusted Platform Module Library Part 3: Commands
12638
12639
12640
1264123.12.2 Command and Response
12642
12643 Table 131 — TPM2_PolicyPhysicalPresence Command
12644Type Name Description
12645
12646 TPM_ST_SESSIONS if an audit session is present;
12647TPMI_ST_COMMAND_TAG tag
12648 otherwise, TPM_ST_NO_SESSIONS
12649UINT32 commandSize
12650TPM_CC commandCode TPM_CC_PolicyPhysicalPresence
12651
12652 handle for the policy session being extended
12653TPMI_SH_POLICY policySession
12654 Auth Index: None
12655
12656
12657 Table 132 — TPM2_PolicyPhysicalPresence Response
12658Type Name Description
12659
12660TPM_ST tag see clause 6
12661UINT32 responseSize
12662TPM_RC responseCode
12663
12664
12665
12666
12667Family “2.0” TCG Published Page 277
12668Level 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;
1268410 TPM_CC commandCode = TPM_CC_PolicyPhysicalPresence;
1268511 HASH_STATE hashState;
1268612
1268713 // Internal Data Update
1268814
1268915 // Get pointer to the session structure
1269016 session = SessionGet(in->policySession);
1269117
1269218 // Update policy hash
1269319 // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyPhysicalPresence)
1269420 // Start hash
1269521 CryptStartHash(session->authHashAlg, &hashState);
1269622
1269723 // add old digest
1269824 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b);
1269925
1270026 // add commandCode
1270127 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode);
1270228
1270329 // complete the digest
1270430 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b);
1270531
1270632 // update session attribute
1270733 session->attributes.isPPRequired = SET;
1270834
1270935 return TPM_RC_SUCCESS;
1271036 }
1271137 #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
1272123.13 TPM2_PolicyCpHash
12722
1272323.13.1 General Description
12724
12725This command is used to allow a policy to be bound to a specific command and command parameters.
12726TPM2_PolicySigned(), TPM2_PolicySecret(), and TPM2_PolicyTIcket() are designed to allow an
12727authorizing entity to execute an arbitrary command as the cpHashA parameter of those commands is not
12728included in policySession→policyDigest. TPM2_PolicyCommandCode() allows the policy to be bound to a
12729specific Command Code so that only certain entities may authorize specific command codes. This
12730command allows the policy to be restricted such that an entity may only authorize a command with a
12731specific set of parameters.
12732If policySession→cpHash is already set and not the same as cpHashA, then the TPM shall return
12733TPM_RC_VALUE. If cpHashA does not have the size of the policySession→policyDigest, the TPM shall
12734return TPM_RC_SIZE.
12735If the cpHashA checks succeed, policySession→cpHash is set to cpHashA and
12736policySession→policyDigest is updated with
12737 policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyCpHash || cpHashA) (28)
12738
12739
12740
12741
12742Family “2.0” TCG Published Page 279
12743Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
12744 Part 3: Commands Trusted Platform Module Library
12745
12746
12747
1274823.13.2 Command and Response
12749
12750 Table 133 — TPM2_PolicyCpHash Command
12751Type Name Description
12752
12753 TPM_ST_SESSIONS if an audit or decrypt session is
12754TPMI_ST_COMMAND_TAG tag
12755 present; otherwise, TPM_ST_NO_SESSIONS
12756UINT32 commandSize
12757TPM_CC commandCode TPM_CC_PolicyCpHash
12758
12759 handle for the policy session being extended
12760TPMI_SH_POLICY policySession
12761 Auth Index: None
12762
12763TPM2B_DIGEST cpHashA the cpHash added to the policy
12764
12765
12766 Table 134 — TPM2_PolicyCpHash Response
12767Type Name Description
12768
12769TPM_ST tag see clause 6
12770UINT32 responseSize
12771TPM_RC responseCode
12772
12773
12774
12775
12776Page 280 TCG Published Family “2.0”
12777October 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
127841 #include "InternalRoutines.h"
127852 #include "PolicyCpHash_fp.h"
127863 #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;
1280110 TPM_CC commandCode = TPM_CC_PolicyCpHash;
1280211 HASH_STATE hashState;
1280312
1280413 // Input Validation
1280514
1280615 // Get pointer to the session structure
1280716 session = SessionGet(in->policySession);
1280817
1280918 // A new cpHash is given in input parameter, but cpHash in session context
1281019 // is not empty, or is not the same as the new cpHash
1281120 if( in->cpHashA.t.size != 0
1281221 && session->u1.cpHash.t.size != 0
1281322 && !Memory2BEqual(&in->cpHashA.b, &session->u1.cpHash.b)
1281423 )
1281524 return TPM_RC_CPHASH;
1281625
1281726 // A valid cpHash must have the same size as session hash digest
1281827 if(in->cpHashA.t.size != CryptGetHashDigestSize(session->authHashAlg))
1281928 return TPM_RC_SIZE + RC_PolicyCpHash_cpHashA;
1282029
1282130 // Internal Data Update
1282231
1282332 // Update policy hash
1282433 // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyCpHash || cpHashA)
1282534 // Start hash
1282635 CryptStartHash(session->authHashAlg, &hashState);
1282736
1282837 // add old digest
1282938 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b);
1283039
1283140 // add commandCode
1283241 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode);
1283342
1283443 // add cpHashA
1283544 CryptUpdateDigest2B(&hashState, &in->cpHashA.b);
1283645
1283746 // complete the digest and get the results
1283847 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b);
1283948
1284049 // update cpHash in session context
1284150 session->u1.cpHash = in->cpHashA;
1284251 session->attributes.iscpHashDefined = SET;
1284352
1284453 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
1285054 }
1285155 #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
1286123.14 TPM2_PolicyNameHash
12862
1286323.14.1 General Description
12864
12865This command allows a policy to be bound to a specific set of TPM entities without being bound to the
12866parameters of the command. This is most useful for commands such as TPM2_Duplicate() and for
12867TPM2_PCR_Event() when the referenced PCR requires a policy.
12868The nameHash parameter should contain the digest of the Names associated with the handles to be used
12869in the authorized command.
12870
12871EXAMPLE 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
12876If policySession→cpHash is already set, the TPM shall return TPM_RC_VALUE. If the size of nameHash
12877is not the size of policySession→policyDigest, the TPM shall return TPM_RC_SIZE. Otherwise,
12878policySession→cpHash is set to nameHash.
12879If this command completes successfully, the cpHash of the authorized command will not be used for
12880validation. Only the digest of the Names associated with the handles in the command will be used.
12881
12882NOTE 1 This allows the space normally used to hold policySession→cpHash to be used for
12883 policySession→nameHash instead.
12884
12885The policySession→policyDigest will be updated with
12886 policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyNameHash || nameHash) (29)
12887
12888NOTE 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
12894Family “2.0” TCG Published Page 283
12895Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
12896 Part 3: Commands Trusted Platform Module Library
12897
12898
1289923.14.2 Command and Response
12900
12901 Table 135 — TPM2_PolicyNameHash Command
12902Type Name Description
12903
12904 TPM_ST_SESSIONS if an audit or decrypt session is
12905TPMI_ST_COMMAND_TAG tag
12906 present; otherwise, TPM_ST_NO_SESSIONS
12907UINT32 commandSize
12908TPM_CC commandCode TPM_CC_PolicyNameHash
12909
12910 handle for the policy session being extended
12911TPMI_SH_POLICY policySession
12912 Auth Index: None
12913
12914TPM2B_DIGEST nameHash the digest to be added to the policy
12915
12916
12917 Table 136 — TPM2_PolicyNameHash Response
12918Type Name Description
12919
12920TPM_ST tag see clause 6
12921UINT32 responseSize
12922TPM_RC responseCode
12923
12924
12925
12926
12927Page 284 TCG Published Family “2.0”
12928October 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
129351 #include "InternalRoutines.h"
129362 #include "PolicyNameHash_fp.h"
129373 #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;
1295210 TPM_CC commandCode = TPM_CC_PolicyNameHash;
1295311 HASH_STATE hashState;
1295412
1295513 // Input Validation
1295614
1295715 // Get pointer to the session structure
1295816 session = SessionGet(in->policySession);
1295917
1296018 // A new nameHash is given in input parameter, but cpHash in session context
1296119 // is not empty
1296220 if(in->nameHash.t.size != 0 && session->u1.cpHash.t.size != 0)
1296321 return TPM_RC_CPHASH;
1296422
1296523 // A valid nameHash must have the same size as session hash digest
1296624 if(in->nameHash.t.size != CryptGetHashDigestSize(session->authHashAlg))
1296725 return TPM_RC_SIZE + RC_PolicyNameHash_nameHash;
1296826
1296927 // Internal Data Update
1297028
1297129 // Update policy hash
1297230 // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyNameHash || nameHash)
1297331 // Start hash
1297432 CryptStartHash(session->authHashAlg, &hashState);
1297533
1297634 // add old digest
1297735 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b);
1297836
1297937 // add commandCode
1298038 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode);
1298139
1298240 // add nameHash
1298341 CryptUpdateDigest2B(&hashState, &in->nameHash.b);
1298442
1298543 // complete the digest
1298644 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b);
1298745
1298846 // clear iscpHashDefined bit to indicate now this field contains a nameHash
1298947 session->attributes.iscpHashDefined = CLEAR;
1299048
1299149 // update nameHash in session context
1299250 session->u1.cpHash = in->nameHash;
1299351
1299452 return TPM_RC_SUCCESS;
1299553 }
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
1300154 #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
1301123.15 TPM2_PolicyDuplicationSelect
13012
1301323.15.1 General Description
13014
13015This command allows qualification of duplication to allow duplication to a selected new parent.
13016If this command not used in conjunction with TPM2_PolicyAuthorize(), then only the new parent is
13017selected.
13018
13019EXAMPLE When an object is created when the list of allowed duplication targets is known, the policy would be
13020 created with includeObject CLEAR.
13021
13022NOTE 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
13026If used in conjunction with TPM2_PolicyAuthorize(), then the authorizer of the new policy has the option
13027of selecting just the new parent or of selecting both the new parent and the duplication Object..
13028
13029NOTE 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
13034If either policySession→cpHash or policySession→nameHash has been previously set, the TPM shall
13035return TPM_RC_CPHASH. Otherwise, policySession→nameHash will be set to:
13036 nameHash ≔ HpolicyAlg(objectName || newParentName) (30)
13037
13038NOTE 3 It is allowed that policySesion→nameHash and policySession→cpHash share the same memory
13039 space.
13040
13041The policySession→policyDigest will be updated according to the setting of includeObject. If equal to
13042YES, policySession→policyDigest is updated by:
13043 policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyDuplicationSelect ||
13044 objectName || newParentName || includeObject) (31)
13045If includeObject is NO, policySession→policyDigest is updated by:
13046 policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyDuplicationSelect ||
13047 newParentName || includeObject) (32)
13048
13049NOTE 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
13054If the command succeeds, policySession→commandCode is set to TPM_CC_Duplicate.
13055
13056NOTE 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
13064Family “2.0” TCG Published Page 287
13065Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
13066 Part 3: Commands Trusted Platform Module Library
13067
13068
1306923.15.2 Command and Response
13070
13071 Table 137 — TPM2_PolicyDuplicationSelect Command
13072Type Name Description
13073
13074 TPM_ST_SESSIONS if an audit or decrypt session is
13075TPMI_ST_COMMAND_TAG tag
13076 present; otherwise, TPM_ST_NO_SESSIONS
13077UINT32 commandSize
13078TPM_CC commandCode TPM_CC_PolicyDuplicationSelect
13079
13080 handle for the policy session being extended
13081TPMI_SH_POLICY policySession
13082 Auth Index: None
13083
13084TPM2B_NAME objectName the Name of the object to be duplicated
13085TPM2B_NAME newParentName the Name of the new parent
13086 if YES, the objectName will be included in the value in
13087TPMI_YES_NO includeObject
13088 policySession→policyDigest
13089
13090
13091 Table 138 — TPM2_PolicyDuplicationSelect Response
13092Type Name Description
13093
13094TPM_ST tag see clause 6
13095UINT32 responseSize
13096TPM_RC responseCode
13097
13098
13099
13100
13101Page 288 TCG Published Family “2.0”
13102October 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
131091 #include "InternalRoutines.h"
131102 #include "PolicyDuplicationSelect_fp.h"
131113 #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;
1312510 HASH_STATE hashState;
1312611 TPM_CC commandCode = TPM_CC_PolicyDuplicationSelect;
1312712
1312813 // Input Validation
1312914
1313015 // Get pointer to the session structure
1313116 session = SessionGet(in->policySession);
1313217
1313318 // cpHash in session context must be empty
1313419 if(session->u1.cpHash.t.size != 0)
1313520 return TPM_RC_CPHASH;
1313621
1313722 // commandCode in session context must be empty
1313823 if(session->commandCode != 0)
1313924 return TPM_RC_COMMAND_CODE;
1314025
1314126 // Internal Data Update
1314227
1314328 // Update name hash
1314429 session->u1.cpHash.t.size = CryptStartHash(session->authHashAlg, &hashState);
1314530
1314631 // add objectName
1314732 CryptUpdateDigest2B(&hashState, &in->objectName.b);
1314833
1314934 // add new parent name
1315035 CryptUpdateDigest2B(&hashState, &in->newParentName.b);
1315136
1315237 // complete hash
1315338 CryptCompleteHash2B(&hashState, &session->u1.cpHash.b);
1315439
1315540 // update policy hash
1315641 // Old policyDigest size should be the same as the new policyDigest size since
1315742 // they are using the same hash algorithm
1315843 session->u2.policyDigest.t.size
1315944 = CryptStartHash(session->authHashAlg, &hashState);
1316045
1316146 // add old policy
1316247 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b);
1316348
1316449 // add command code
1316550 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode);
1316651
1316752 // add objectName
1316853 if(in->includeObject == YES)
1316954 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
1317555
1317656 // add new parent name
1317757 CryptUpdateDigest2B(&hashState, &in->newParentName.b);
1317858
1317959 // add includeObject
1318060 CryptUpdateDigestInt(&hashState, sizeof(TPMI_YES_NO), &in->includeObject);
1318161
1318262 // complete digest
1318363 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b);
1318464
1318565 // clear iscpHashDefined bit to indicate now this field contains a nameHash
1318666 session->attributes.iscpHashDefined = CLEAR;
1318767
1318868 // set commandCode in session context
1318969 session->commandCode = TPM_CC_Duplicate;
1319070
1319171 return TPM_RC_SUCCESS;
1319272 }
1319373 #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
1320323.16 TPM2_PolicyAuthorize
13204
1320523.16.1 General Description
13206
13207This command allows policies to change. If a policy were static, then it would be difficult to add users to a
13208policy. This command lets a policy authority sign a new policy so that it may be used in an existing policy.
13209The authorizing entity signs a structure that contains
13210 aHash ≔ HaHashAlg(approvedPolicy || policyRef) (33)
13211The aHashAlg is required to be the nameAlg of the key used to sign the aHash. The aHash value is then
13212signed (symmetric or asymmetric) by keySign. That signature is then checked by the TPM in
13213TPM2_VerifySignature() which produces a ticket by
13214 HMAC(proof, (TPM_ST_VERIFIED || aHash || keySign→Name)) (34)
13215
13216NOTE 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
13219The ticket is then used in TPM2_PolicyAuthorize() to validate the parameters.
13220The keySign parameter is required to be a valid object name using nameAlg other than TPM_ALG_NULL.
13221If the first two octets of keySign are not a valid hash algorithm, the TPM shall return TPM_RC_HASH. If
13222the remainder of the Name is not the size of the indicated digest, the TPM shall return TPM_RC_SIZE.
13223The TPM validates that the approvedPolicy matches the current value of policySession→policyDigest and
13224if not, shall return TPM_RC_VALUE.
13225The TPM then validates that the parameters to TPM2_PolicyAuthorize() match the values used to
13226generate the ticket. If so, the TPM will reset policySession→policyDigest to a Zero Digest. Then it will
13227update policySession→policyDigest with PolicyUpdate() (see 23.2.3).
13228 PolicyUpdate(TPM_CC_PolicyAuthorize, keySign, policyRef) (35)
13229If the ticket is not valid, the TPM shall return TPM_RC_POLICY.
13230If policySession is a trial session, policySession→policyDigest is extended as if the ticket is valid without
13231actual verification.
13232
13233NOTE 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
13240Family “2.0” TCG Published Page 291
13241Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
13242 Part 3: Commands Trusted Platform Module Library
13243
13244
1324523.16.2 Command and Response
13246
13247 Table 139 — TPM2_PolicyAuthorize Command
13248Type Name Description
13249
13250 TPM_ST_SESSIONS if an audit or decrypt session is
13251TPMI_ST_COMMAND_TAG tag
13252 present; otherwise, TPM_ST_NO_SESSIONS
13253UINT32 commandSize
13254TPM_CC commandCode TPM_CC_PolicyAuthorize
13255
13256 handle for the policy session being extended
13257TPMI_SH_POLICY policySession
13258 Auth Index: None
13259
13260TPM2B_DIGEST approvedPolicy digest of the policy being approved
13261TPM2B_NONCE policyRef a policy qualifier
13262TPM2B_NAME keySign Name of a key that can sign a policy addition
13263 ticket validating that approvedPolicy and policyRef were
13264TPMT_TK_VERIFIED checkTicket
13265 signed by keySign
13266
13267
13268 Table 140 — TPM2_PolicyAuthorize Response
13269Type Name Description
13270
13271TPM_ST tag see clause 6
13272UINT32 responseSize
13273TPM_RC responseCode
13274
13275
13276
13277
13278Page 292 TCG Published Family “2.0”
13279October 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
132861 #include "InternalRoutines.h"
132872 #include "PolicyAuthorize_fp.h"
132883 #ifdef TPM_CC_PolicyAuthorize // Conditional expansion of this file
132894 #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 {
1330410 SESSION *session;
1330511 TPM2B_DIGEST authHash;
1330612 HASH_STATE hashState;
1330713 TPMT_TK_VERIFIED ticket;
1330814 TPM_ALG_ID hashAlg;
1330915 UINT16 digestSize;
1331016
1331117 // Input Validation
1331218
1331319 // Get pointer to the session structure
1331420 session = SessionGet(in->policySession);
1331521
1331622 // Extract from the Name of the key, the algorithm used to compute it's Name
1331723 hashAlg = BYTE_ARRAY_TO_UINT16(in->keySign.t.name);
1331824
1331925 // 'keySign' parameter needs to use a supported hash algorithm, otherwise
1332026 // can't tell how large the digest should be
1332127 digestSize = CryptGetHashDigestSize(hashAlg);
1332228 if(digestSize == 0)
1332329 return TPM_RC_HASH + RC_PolicyAuthorize_keySign;
1332430
1332531 if(digestSize != (in->keySign.t.size - 2))
1332632 return TPM_RC_SIZE + RC_PolicyAuthorize_keySign;
1332733
1332834 //If this is a trial policy, skip all validations
1332935 if(session->attributes.isTrialPolicy == CLEAR)
1333036 {
1333137 // Check that "approvedPolicy" matches the current value of the
1333238 // policyDigest in policy session
1333339 if(!Memory2BEqual(&session->u2.policyDigest.b,
1333440 &in->approvedPolicy.b))
1333541 return TPM_RC_VALUE + RC_PolicyAuthorize_approvedPolicy;
1333642
1333743 // Validate ticket TPMT_TK_VERIFIED
1333844 // Compute aHash. The authorizing object sign a digest
1333945 // aHash := hash(approvedPolicy || policyRef).
1334046 // Start hash
1334147 authHash.t.size = CryptStartHash(hashAlg, &hashState);
1334248
1334349 // add approvedPolicy
1334450 CryptUpdateDigest2B(&hashState, &in->approvedPolicy.b);
1334551
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
1335152 // add policyRef
1335253 CryptUpdateDigest2B(&hashState, &in->policyRef.b);
1335354
1335455 // complete hash
1335556 CryptCompleteHash2B(&hashState, &authHash.b);
1335657
1335758 // re-compute TPMT_TK_VERIFIED
1335859 TicketComputeVerified(in->checkTicket.hierarchy, &authHash,
1335960 &in->keySign, &ticket);
1336061
1336162 // Compare ticket digest. If not match, return error
1336263 if(!Memory2BEqual(&in->checkTicket.digest.b, &ticket.digest.b))
1336364 return TPM_RC_VALUE+ RC_PolicyAuthorize_checkTicket;
1336465 }
1336566
1336667 // Internal Data Update
1336768
1336869 // Set policyDigest to zero digest
1336970 MemorySet(session->u2.policyDigest.t.buffer, 0,
1337071 session->u2.policyDigest.t.size);
1337172
1337273 // Update policyDigest
1337374 PolicyContextUpdate(TPM_CC_PolicyAuthorize, &in->keySign, &in->policyRef,
1337475 NULL, 0, session);
1337576
1337677 return TPM_RC_SUCCESS;
1337778
1337879 }
1337980 #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
1338923.17 TPM2_PolicyAuthValue
13390
1339123.17.1 General Description
13392
13393This command allows a policy to be bound to the authorization value of the authorized object.
13394When this command completes successfully, policySession→isAuthValueNeeded is SET to indicate that
13395the authValue will be included in hmacKey when the authorization HMAC is computed for the command
13396being authorized using this session. Additionally, policySession→isPasswordNeeded will be CLEAR.
13397
13398NOTE 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
13402If successful, policySession→policyDigest will be updated with
13403 policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyAuthValue) (36)
13404
13405
13406
13407
13408Family “2.0” TCG Published Page 295
13409Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
13410 Part 3: Commands Trusted Platform Module Library
13411
13412
13413
1341423.17.2 Command and Response
13415
13416 Table 141 — TPM2_PolicyAuthValue Command
13417Type Name Description
13418
13419 TPM_ST_SESSIONS if an audit session is present;
13420TPMI_ST_COMMAND_TAG tag
13421 otherwise, TPM_ST_NO_SESSIONS
13422UINT32 commandSize
13423TPM_CC commandCode TPM_CC_PolicyAuthValue
13424
13425 handle for the policy session being extended
13426TPMI_SH_POLICY policySession
13427 Auth Index: None
13428
13429
13430 Table 142 — TPM2_PolicyAuthValue Response
13431Type Name Description
13432
13433TPM_ST tag see clause 6
13434UINT32 responseSize
13435TPM_RC responseCode
13436
13437
13438
13439
13440Page 296 TCG Published Family “2.0”
13441October 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 {
1345710 SESSION *session;
1345811 TPM_CC commandCode = TPM_CC_PolicyAuthValue;
1345912 HASH_STATE hashState;
1346013
1346114 // Internal Data Update
1346215
1346316 // Get pointer to the session structure
1346417 session = SessionGet(in->policySession);
1346518
1346619 // Update policy hash
1346720 // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyAuthValue)
1346821 // Start hash
1346922 CryptStartHash(session->authHashAlg, &hashState);
1347023
1347124 // add old digest
1347225 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b);
1347326
1347427 // add commandCode
1347528 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode);
1347629
1347730 // complete the hash and get the results
1347831 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b);
1347932
1348033 // update isAuthValueNeeded bit in the session context
1348134 session->attributes.isAuthValueNeeded = SET;
1348235 session->attributes.isPasswordNeeded = CLEAR;
1348336
1348437 return TPM_RC_SUCCESS;
1348538 }
1348639 #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
1349623.18 TPM2_PolicyPassword
13497
1349823.18.1 General Description
13499
13500This command allows a policy to be bound to the authorization value of the authorized object.
13501When this command completes successfully, policySession→isPasswordNeeded is SET to indicate that
13502authValue of the authorized object will be checked when the session is used for authorization. The caller
13503will provide the authValue in clear text in the hmac parameter of the authorization. The comparison of
13504hmac to authValue is performed as if the authorization is a password.
13505
13506NOTE 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
13510If successful, policySession→policyDigest will be updated with
13511 policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyAuthValue) (37)
13512
13513NOTE 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
13518When this command is successful, policySession→isAuthValueNeeded will be CLEAR.
13519
13520
13521
13522
13523Page 298 TCG Published Family “2.0”
13524October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
13525 Trusted Platform Module Library Part 3: Commands
13526
13527
13528
1352923.18.2 Command and Response
13530
13531 Table 143 — TPM2_PolicyPassword Command
13532Type Name Description
13533
13534 TPM_ST_SESSIONS if an audit session is present;
13535TPMI_ST_COMMAND_TAG tag
13536 otherwise, TPM_ST_NO_SESSIONS
13537UINT32 commandSize
13538TPM_CC commandCode TPM_CC_PolicyPassword
13539
13540 handle for the policy session being extended
13541TPMI_SH_POLICY policySession
13542 Auth Index: None
13543
13544
13545 Table 144 — TPM2_PolicyPassword Response
13546Type Name Description
13547
13548TPM_ST tag see clause 6
13549UINT32 responseSize
13550TPM_RC responseCode
13551
13552
13553
13554
13555Family “2.0” TCG Published Page 299
13556Level 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 {
1357210 SESSION *session;
1357311 TPM_CC commandCode = TPM_CC_PolicyAuthValue;
1357412 HASH_STATE hashState;
1357513
1357614 // Internal Data Update
1357715
1357816 // Get pointer to the session structure
1357917 session = SessionGet(in->policySession);
1358018
1358119 // Update policy hash
1358220 // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyAuthValue)
1358321 // Start hash
1358422 CryptStartHash(session->authHashAlg, &hashState);
1358523
1358624 // add old digest
1358725 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b);
1358826
1358927 // add commandCode
1359028 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode);
1359129
1359230 // complete the digest
1359331 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b);
1359432
1359533 // Update isPasswordNeeded bit
1359634 session->attributes.isPasswordNeeded = SET;
1359735 session->attributes.isAuthValueNeeded = CLEAR;
1359836
1359937 return TPM_RC_SUCCESS;
1360038 }
1360139 #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
1361123.19 TPM2_PolicyGetDigest
13612
1361323.19.1 General Description
13614
13615This command returns the current policyDigest of the session. This command allows the TPM to be used
13616to perform the actions required to pre-compute the authPolicy for an object.
13617
13618
13619
13620
13621Family “2.0” TCG Published Page 301
13622Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
13623 Part 3: Commands Trusted Platform Module Library
13624
13625
13626
1362723.19.2 Command and Response
13628
13629 Table 145 — TPM2_PolicyGetDigest Command
13630Type Name Description
13631
13632 TPM_ST_SESSIONS if an audit or encrypt session is
13633TPMI_ST_COMMAND_TAG tag
13634 present; otherwise, TPM_ST_NO_SESSIONS
13635UINT32 commandSize
13636TPM_CC commandCode TPM_CC_PolicyGetDigest
13637
13638 handle for the policy session
13639TPMI_SH_POLICY policySession
13640 Auth Index: None
13641
13642
13643 Table 146 — TPM2_PolicyGetDigest Response
13644Type Name Description
13645
13646TPM_ST tag see clause 6
13647UINT32 responseSize
13648TPM_RC responseCode
13649
13650TPM2B_DIGEST policyDigest the current value of the policySession→policyDigest
13651
13652
13653
13654
13655Page 302 TCG Published Family “2.0”
13656October 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 {
1367210 SESSION *session;
1367311
1367412 // Command Output
1367513
1367614 // Get pointer to the session structure
1367715 session = SessionGet(in->policySession);
1367816
1367917 out->policyDigest = session->u2.policyDigest;
1368018
1368119 return TPM_RC_SUCCESS;
1368220 }
1368321 #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
1369323.20 TPM2_PolicyNvWritten
13694
1369523.20.1 General Description
13696
13697This command allows a policy to be bound to the TPMA_NV_WRITTEN attributes. This is a deferred
13698assertion. Values are stored in the policy session context and checked when the policy is used for
13699authorization.
13700If policySession→checkNVWritten is CLEAR, it is SET and policySession→nvWrittenState is set to
13701writtenSet. If policySession→checkNVWritten is SET, the TPM will return TPM_RC_VALUE if
13702policySession→nvWrittenState and writtenSet are not the same.
13703If the TPM does not return an error, it will update policySession→policyDigest by
13704 policyDigestnew ≔ HpolicyAlg(policyDigestold || TPM_CC_PolicyNvWritten || writtenSet) (38)
13705When the policy session is used to authorize a command, the TPM will fail the command if
13706policySession→checkNVWritten is SET and nvIndex→attributes→TPMA_NV_WRITTEN does not match
13707policySession→nvWrittenState.
13708
13709NOTE 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
13713NOTE 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
13719Page 304 TCG Published Family “2.0”
13720October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
13721 Trusted Platform Module Library Part 3: Commands
13722
13723
1372423.20.2 Command and Response
13725
13726 Table 147 — TPM2_PolicyNvWritten Command
13727Type Name Description
13728
13729 TPM_ST_SESSIONS if an audit session is present;
13730TPMI_ST_COMMAND_TAG tag
13731 otherwise, TPM_ST_NO_SESSIONS
13732UINT32 commandSize
13733TPM_CC commandCode TPM_CC_PolicyNVWritten
13734
13735 handle for the policy session being extended
13736TPMI_SH_POLICY policySession
13737 Auth Index: None
13738
13739 YES if NV Index is required to have been written
13740TPMI_YES_NO writtenSet
13741 NO if NV Index is required not to have been written
13742
13743
13744 Table 148 — TPM2_PolicyNvWritten Response
13745Type Name Description
13746
13747TPM_ST tag see clause 6
13748UINT32 responseSize
13749TPM_RC responseCode
13750
13751
13752
13753
13754Family “2.0” TCG Published Page 305
13755Level 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
137621 #include "InternalRoutines.h"
137632 #include "PolicyNvWritten_fp.h"
137643 #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;
1377810 TPM_CC commandCode = TPM_CC_PolicyNvWritten;
1377911 HASH_STATE hashState;
1378012
1378113 // Input Validation
1378214
1378315 // Get pointer to the session structure
1378416 session = SessionGet(in->policySession);
1378517
1378618 // If already set is this a duplicate (the same setting)? If it
1378719 // is a conflicting setting, it is an error
1378820 if(session->attributes.checkNvWritten == SET)
1378921 {
1379022 if(( (session->attributes.nvWrittenState == SET)
1379123 != (in->writtenSet == YES)))
1379224 return TPM_RC_VALUE + RC_PolicyNvWritten_writtenSet;
1379325 }
1379426
1379527 // Internal Data Update
1379628
1379729 // Set session attributes so that the NV Index needs to be checked
1379830 session->attributes.checkNvWritten = SET;
1379931 session->attributes.nvWrittenState = (in->writtenSet == YES);
1380032
1380133 // Update policy hash
1380234 // policyDigestnew = hash(policyDigestold || TPM_CC_PolicyNvWritten
1380335 // || writtenSet)
1380436 // Start hash
1380537 CryptStartHash(session->authHashAlg, &hashState);
1380638
1380739 // add old digest
1380840 CryptUpdateDigest2B(&hashState, &session->u2.policyDigest.b);
1380941
1381042 // add commandCode
1381143 CryptUpdateDigestInt(&hashState, sizeof(TPM_CC), &commandCode);
1381244
1381345 // add the byte of writtenState
1381446 CryptUpdateDigestInt(&hashState, sizeof(TPMI_YES_NO), &in->writtenSet);
1381547
1381648 // complete the digest
1381749 CryptCompleteHash2B(&hashState, &session->u2.policyDigest.b);
1381850
1381951 return TPM_RC_SUCCESS;
1382052 }
1382153 #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
13831Family “2.0” TCG Published Page 307
13832Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
13833 Part 3: Commands Trusted Platform Module Library
13834
13835
13836
1383724 Hierarchy Commands
13838
1383924.1 TPM2_CreatePrimary
13840
1384124.1.1 General Description
13842
13843This command is used to create a Primary Object under one of the Primary Seeds or a Temporary Object
13844under TPM_RH_NULL. The command uses a TPM2B_PUBLIC as a template for the object to be created.
13845The command will create and load a Primary Object. The sensitive area is not returned.
13846
13847NOTE 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
13850Any type of object and attributes combination that is allowed by TPM2_Create() may be created by this
13851command. The constraints on templates and parameters are the same as TPM2_Create() except that a
13852Primary Storage Key and a Temporary Storage Key are not constrained to use the algorithms of their
13853parents.
13854For setting of the attributes of the created object, fixedParent, fixedTPM, decrypt, and restricted are
13855implied to be SET in the parent (a Permanent Handle). The remaining attributes are implied to be CLEAR.
13856The TPM will derive the object from the Primary Seed indicated in primaryHandle using an approved
13857KDF. All of the bits of the template are used in the creation of the Primary Key. Methods for creating a
13858Primary Object from a Primary Seed are described in TPM 2.0 Part 1 and implemented in TPM 2.0 Part 4.
13859If this command is called multiple times with the same inPublic parameter, inSensitive.data, and Primary
13860Seed, the TPM shall produce the same Primary Object.
13861
13862NOTE 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
13865This command requires authorization. Authorization for a Primary Object attached to the Platform Primary
13866Seed (PPS) shall be provided by platformAuth or platformPolicy. Authorization for a Primary Object
13867attached to the Storage Primary Seed (SPS) shall be provided by ownerAuth or ownerPolicy.
13868Authorization for a Primary Key attached to the Endorsement Primary Seed (EPS) shall be provided by
13869endorsementAuth or endorsementPolicy.
13870
13871
13872
13873
13874Page 308 TCG Published Family “2.0”
13875October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
13876 Trusted Platform Module Library Part 3: Commands
13877
13878
13879
1388024.1.2 Command and Response
13881
13882 Table 149 — TPM2_CreatePrimary Command
13883Type Name Description
13884
13885TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
13886UINT32 commandSize
13887TPM_CC commandCode TPM_CC_CreatePrimary
13888
13889 TPM_RH_ENDORSEMENT, TPM_RH_OWNER,
13890 TPM_RH_PLATFORM+{PP}, or TPM_RH_NULL
13891TPMI_RH_HIERARCHY+ @primaryHandle
13892 Auth Index: 1
13893 Auth Role: USER
13894
13895TPM2B_SENSITIVE_CREATE inSensitive the sensitive data, see TPM 2.0 Part 1 Sensitive Values
13896TPM2B_PUBLIC inPublic the public template
13897 data that will be included in the creation data for this
13898TPM2B_DATA outsideInfo object to provide permanent, verifiable linkage between
13899 this object and some object owner data
13900TPML_PCR_SELECTION creationPCR PCR that will be used in creation data
13901
13902
13903 Table 150 — TPM2_CreatePrimary Response
13904Type Name Description
13905
13906TPM_ST tag see clause 6
13907UINT32 responseSize
13908TPM_RC responseCode
13909
13910 handle of type TPM_HT_TRANSIENT for created
13911TPM_HANDLE objectHandle
13912 Primary Object
13913
13914TPM2B_PUBLIC outPublic the public portion of the created object
13915TPM2B_CREATION_DATA creationData contains a TPMT_CREATION_DATA
13916TPM2B_DIGEST creationHash digest of creationData using nameAlg of outPublic
13917 ticket used by TPM2_CertifyCreation() to validate that
13918TPMT_TK_CREATION creationTicket
13919 the creation data was produced by the TPM
13920TPM2B_NAME name the name of the created object
13921
13922
13923
13924
13925Family “2.0” TCG Published Page 309
13926Level 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
139331 #include "InternalRoutines.h"
139342 #include "CreatePrimary_fp.h"
139353 #ifdef TPM_CC_CreatePrimary // Conditional expansion of this file
139364 #include "Object_spt_fp.h"
139375 #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
1396510 )
1396611 {
1396712 // Local variables
1396813 TPM_RC result = TPM_RC_SUCCESS;
1396914 TPMT_SENSITIVE sensitive;
1397015
1397116 // Input Validation
1397217 // The sensitiveDataOrigin attribute must be consistent with the setting of
1397318 // the size of the data object in inSensitive.
1397419 if( (in->inPublic.t.publicArea.objectAttributes.sensitiveDataOrigin == SET)
1397520 != (in->inSensitive.t.sensitive.data.t.size == 0 ))
1397621 // Mismatch between the object attributes and the parameter.
1397722 return TPM_RC_ATTRIBUTES + RC_CreatePrimary_inSensitive;
1397823
1397924 // Check attributes in input public area. TPM_RC_ATTRIBUTES, TPM_RC_KDF,
1398025 // TPM_RC_SCHEME, TPM_RC_SIZE, TPM_RC_SYMMETRIC, or TPM_RC_TYPE error may
1398126 // be returned at this point.
1398227 result = PublicAttributesValidation(FALSE, in->primaryHandle,
1398328 &in->inPublic.t.publicArea);
1398429 if(result != TPM_RC_SUCCESS)
1398530 return RcSafeAddToResult(result, RC_CreatePrimary_inPublic);
1398631
1398732 // Validate the sensitive area values
1398833 if( MemoryRemoveTrailingZeros(&in->inSensitive.t.sensitive.userAuth)
1398934 > 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
1399635 return TPM_RC_SIZE + RC_CreatePrimary_inSensitive;
1399736
1399837 // Command output
1399938
1400039 // Generate Primary Object
1400140 // The primary key generation process uses the Name of the input public
1400241 // template to compute the key. The keys are generated from the template
1400342 // before anything in the template is allowed to be changed.
1400443 // A TPM_RC_KDF, TPM_RC_SIZE error may be returned at this point
1400544 result = CryptCreateObject(in->primaryHandle, &in->inPublic.t.publicArea,
1400645 &in->inSensitive.t.sensitive,&sensitive);
1400746 if(result != TPM_RC_SUCCESS)
1400847 return result;
1400948
1401049 // Fill in creation data
1401150 FillInCreationData(in->primaryHandle, in->inPublic.t.publicArea.nameAlg,
1401251 &in->creationPCR, &in->outsideInfo, &out->creationData,
1401352 &out->creationHash);
1401453
1401554 // Copy public area
1401655 out->outPublic = in->inPublic;
1401756
1401857 // Fill in private area for output
1401958 ObjectComputeName(&(out->outPublic.t.publicArea), &out->name);
1402059
1402160 // Compute creation ticket
1402261 TicketComputeCreation(EntityGetHierarchy(in->primaryHandle), &out->name,
1402362 &out->creationHash, &out->creationTicket);
1402463
1402564 // Create a internal object. A TPM_RC_OBJECT_MEMORY error may be returned
1402665 // at this point.
1402766 result = ObjectLoad(in->primaryHandle, &in->inPublic.t.publicArea, &sensitive,
1402867 &out->name, in->primaryHandle, TRUE, &out->objectHandle);
1402968
1403069 return result;
1403170 }
1403271 #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
1404224.2 TPM2_HierarchyControl
14043
1404424.2.1 General Description
14045
14046This command enables and disables use of a hierarchy and its associated NV storage. The command
14047allows phEnable, phEnableNV, shEnable, and ehEnable to be changed when the proper authorization is
14048provided.
14049This command may be used to CLEAR phEnable and phEnableNV if platformAuth/platformPolicy is
14050provided. phEnable may not be SET using this command.
14051This command may be used to CLEAR shEnable if either platformAuth/platformPolicy or
14052ownerAuth/ownerPolicy is provided. shEnable may be SET if platformAuth/platformPolicy is provided.
14053This command may be used to CLEAR ehEnable if either platformAuth/platformPolicy or
14054endorsementAuth/endorsementPolicy is provided. ehEnable may be SET if platformAuth/platformPolicy is
14055provided.
14056When this command is used to CLEAR phEnable, shEnable, or ehEnable, the TPM will disable use of
14057any persistent entity associated with the disabled hierarchy and will flush any transient objects associated
14058with the disabled hierarchy.
14059When this command is used to CLEAR shEnable, the TPM will disable access to any NV index that has
14060TPMA_NV_PLATFORMCREATE CLEAR (indicating that the NV Index was defined using Owner
14061Authorization). As long as shEnable is CLEAR, the TPM will return an error in response to any command
14062that attempts to operate upon an NV index that has TPMA_NV_PLATFORMCREATE CLEAR.
14063When this command is used to CLEAR phEnableNV, the TPM will disable access to any NV index that
14064has TPMA_NV_PLATFORMCREATE SET (indicating that the NV Index was defined using Platform
14065Authorization). As long as phEnableNV is CLEAR, the TPM will return an error in response to any
14066command that attempts to operate upon an NV index that has TPMA_NV_PLATFORMCREATE SET.
14067
14068
14069
14070
14071Page 312 TCG Published Family “2.0”
14072October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
14073 Trusted Platform Module Library Part 3: Commands
14074
14075
14076
1407724.2.2 Command and Response
14078
14079 Table 151 — TPM2_HierarchyControl Command
14080Type Name Description
14081
14082TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
14083
14084UINT32 commandSize
14085
14086TPM_CC commandCode TPM_CC_HierarchyControl {NV E}
14087
14088 TPM_RH_ENDORSEMENT, TPM_RH_OWNER or
14089 TPM_RH_PLATFORM+{PP}
14090TPMI_RH_HIERARCHY @authHandle
14091 Auth Index: 1
14092 Auth Role: USER
14093
14094 the enable being modified
14095TPMI_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
14098TPMI_YES_NO state
14099 should be CLEAR
14100
14101
14102 Table 152 — TPM2_HierarchyControl Response
14103Type Name Description
14104
14105TPM_ST tag see clause 6
14106
14107UINT32 responseSize
14108
14109TPM_RC responseCode
14110
14111
14112
14113
14114Family “2.0” TCG Published Page 313
14115Level 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
141221 #include "InternalRoutines.h"
141232 #include "HierarchyControl_fp.h"
141243 #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;
1413710 BOOL select = (in->state == YES);
1413811 BOOL *selected = NULL;
1413912
1414013 // Input Validation
1414114 switch(in->enable)
1414215 {
1414316 // Platform hierarchy has to be disabled by platform auth
1414417 // If the platform hierarchy has already been disabled, only a reboot
1414518 // can enable it again
1414619 case TPM_RH_PLATFORM:
1414720 case TPM_RH_PLATFORM_NV:
1414821 if(in->authHandle != TPM_RH_PLATFORM)
1414922 return TPM_RC_AUTH_TYPE;
1415023 break;
1415124
1415225 // ShEnable may be disabled if PlatformAuth/PlatformPolicy or
1415326 // OwnerAuth/OwnerPolicy is provided. If ShEnable is disabled, then it
1415427 // may only be enabled if PlatformAuth/PlatformPolicy is provided.
1415528 case TPM_RH_OWNER:
1415629 if( in->authHandle != TPM_RH_PLATFORM
1415730 && in->authHandle != TPM_RH_OWNER)
1415831 return TPM_RC_AUTH_TYPE;
1415932 if( gc.shEnable == FALSE && in->state == YES
1416033 && in->authHandle != TPM_RH_PLATFORM)
1416134 return TPM_RC_AUTH_TYPE;
1416235 break;
1416336
1416437 // EhEnable may be disabled if either PlatformAuth/PlatformPolicy or
1416538 // EndosementAuth/EndorsementPolicy is provided. If EhEnable is disabled,
1416639 // then it may only be enabled if PlatformAuth/PlatformPolicy is
1416740 // provided.
1416841 case TPM_RH_ENDORSEMENT:
1416942 if( in->authHandle != TPM_RH_PLATFORM
1417043 && in->authHandle != TPM_RH_ENDORSEMENT)
1417144 return TPM_RC_AUTH_TYPE;
1417245 if( gc.ehEnable == FALSE && in->state == YES
1417346 && in->authHandle != TPM_RH_PLATFORM)
1417447 return TPM_RC_AUTH_TYPE;
1417548 break;
1417649 default:
1417750 pAssert(FALSE);
1417851 break;
1417952 }
1418053
1418154 // Internal Data Update
1418255
1418356 // 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)
14232100 // Flush hierarchy
14233101 ObjectFlushHierarchy(in->enable);
14234102
14235103 // orderly state should be cleared because of the update to state clear data
14236104 // This gets processed in ExecuteCommand() on the way out.
14237105 g_clearOrderly = TRUE;
14238106 }
14239107 return TPM_RC_SUCCESS;
14240108 }
14241109 #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
1425124.3 TPM2_SetPrimaryPolicy
14252
1425324.3.1 General Description
14254
14255This command allows setting of the authorization policy for the lockout (lockoutPolicy), the platform
14256hierarchy (platformPolicy), the storage hierarchy (ownerPolicy), and the endorsement hierarchy
14257(endorsementPolicy).
14258The command requires an authorization session. The session shall use the current authValue or satisfy
14259the current authPolicy for the referenced hierarchy.
14260The policy that is changed is the policy associated with authHandle.
14261If the enable associated with authHandle is not SET, then the associated authorization values (authValue
14262or authPolicy) may not be used.
14263
14264
14265
14266
14267Page 316 TCG Published Family “2.0”
14268October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
14269 Trusted Platform Module Library Part 3: Commands
14270
14271
14272
1427324.3.2 Command and Response
14274
14275 Table 153 — TPM2_SetPrimaryPolicy Command
14276Type Name Description
14277
14278TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
14279
14280UINT32 commandSize
14281
14282TPM_CC commandCode TPM_CC_SetPrimaryPolicy {NV}
14283
14284 TPM_RH_LOCKOUT, TPM_RH_ENDORSEMENT,
14285 TPM_RH_OWNER or TPM_RH_PLATFORM+{PP}
14286TPMI_RH_HIERARCHY_AUTH @authHandle
14287 Auth Index: 1
14288 Auth Role: USER
14289
14290 an authorization policy digest; may be the Empty Buffer
14291TPM2B_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
14294TPMI_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
14299Type Name Description
14300
14301TPM_ST tag see clause 6
14302
14303UINT32 responseSize
14304
14305TPM_RC responseCode
14306
14307
14308
14309
14310Family “2.0” TCG Published Page 317
14311Level 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
143181 #include "InternalRoutines.h"
143192 #include "SetPrimaryPolicy_fp.h"
143203 #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;
1433310
1433411 // Input Validation
1433512
1433613 // Check the authPolicy consistent with hash algorithm. If the policy size is
1433714 // zero, then the algorithm is required to be TPM_ALG_NULL
1433815 if(in->authPolicy.t.size != CryptGetHashDigestSize(in->hashAlg))
1433916 return TPM_RC_SIZE + RC_SetPrimaryPolicy_authPolicy;
1434017
1434118 // The command need NV update for OWNER and ENDORSEMENT hierarchy, and
1434219 // might need orderlyState update for PLATFROM hierarchy.
1434320 // Check if NV is available. A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE
1434421 // error may be returned at this point
1434522 result = NvIsAvailable();
1434623 if(result != TPM_RC_SUCCESS)
1434724 return result;
1434825
1434926 // Internal Data Update
1435027
1435128 // Set hierarchy policy
1435229 switch(in->authHandle)
1435330 {
1435431 case TPM_RH_OWNER:
1435532 gp.ownerAlg = in->hashAlg;
1435633 gp.ownerPolicy = in->authPolicy;
1435734 NvWriteReserved(NV_OWNER_ALG, &gp.ownerAlg);
1435835 NvWriteReserved(NV_OWNER_POLICY, &gp.ownerPolicy);
1435936 break;
1436037 case TPM_RH_ENDORSEMENT:
1436138 gp.endorsementAlg = in->hashAlg;
1436239 gp.endorsementPolicy = in->authPolicy;
1436340 NvWriteReserved(NV_ENDORSEMENT_ALG, &gp.endorsementAlg);
1436441 NvWriteReserved(NV_ENDORSEMENT_POLICY, &gp.endorsementPolicy);
1436542 break;
1436643 case TPM_RH_PLATFORM:
1436744 gc.platformAlg = in->hashAlg;
1436845 gc.platformPolicy = in->authPolicy;
1436946 // need to update orderly state
1437047 g_clearOrderly = TRUE;
1437148 break;
1437249 case TPM_RH_LOCKOUT:
1437350 gp.lockoutAlg = in->hashAlg;
1437451 gp.lockoutPolicy = in->authPolicy;
1437552 NvWriteReserved(NV_LOCKOUT_ALG, &gp.lockoutAlg);
1437653 NvWriteReserved(NV_LOCKOUT_POLICY, &gp.lockoutPolicy);
1437754 break;
1437855
1437956 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
1438557 pAssert(FALSE);
1438658 break;
1438759 }
1438860
1438961 return TPM_RC_SUCCESS;
1439062 }
1439163 #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
1440124.4 TPM2_ChangePPS
14402
1440324.4.1 General Description
14404
14405This replaces the current PPS with a value from the RNG and sets platformPolicy to the default
14406initialization value (the Empty Buffer).
14407
14408NOTE 1 A policy that is the Empty Buffer can match no policy.
14409
14410NOTE 2 Platform Authorization is not changed.
14411
14412All resident transient and persistent objects in the Platform hierarchy are flushed.
14413Saved contexts in the Platform hierarchy that were created under the old PPS will no longer be able to be
14414loaded.
14415The policy hash algorithm for PCR is reset to TPM_ALG_NULL.
14416This command does not clear any NV Index values.
14417
14418NOTE 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
14422This command requires Platform Authorization.
14423
14424
14425
14426
14427Page 320 TCG Published Family “2.0”
14428October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
14429 Trusted Platform Module Library Part 3: Commands
14430
14431
14432
1443324.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
14456Family “2.0” TCG Published Page 321
14457Level 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;
1447310 TPM_RC result;
1447411
1447512 // Check if NV is available. A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE
1447613 // error may be returned at this point
1447714 result = NvIsAvailable();
1447815 if(result != TPM_RC_SUCCESS) return result;
1447916
1448017 // Input parameter is not reference in command action
1448118 in = NULL;
1448219
1448320 // Internal Data Update
1448421
1448522 // Reset platform hierarchy seed from RNG
1448623 CryptGenerateRandom(PRIMARY_SEED_SIZE, gp.PPSeed.t.buffer);
1448724
1448825 // Create a new phProof value from RNG to prevent the saved platform
1448926 // hierarchy contexts being loaded
1449027 CryptGenerateRandom(PROOF_SIZE, gp.phProof.t.buffer);
1449128
1449229 // Set platform authPolicy to null
1449330 gc.platformAlg = TPM_ALG_NULL;
1449431 gc.platformPolicy.t.size = 0;
1449532
1449633 // Flush loaded object in platform hierarchy
1449734 ObjectFlushHierarchy(TPM_RH_PLATFORM);
1449835
1449936 // Flush platform evict object and index in NV
1450037 NvFlushHierarchy(TPM_RH_PLATFORM);
1450138
1450239 // Save hierarchy changes to NV
1450340 NvWriteReserved(NV_PP_SEED, &gp.PPSeed);
1450441 NvWriteReserved(NV_PH_PROOF, &gp.phProof);
1450542
1450643 // Re-initialize PCR policies
1450744 for(i = 0; i < NUM_POLICY_PCR_GROUP; i++)
1450845 {
1450946 gp.pcrPolicies.hashAlg[i] = TPM_ALG_NULL;
1451047 gp.pcrPolicies.policy[i].t.size = 0;
1451148 }
1451249 NvWriteReserved(NV_PCR_POLICIES, &gp.pcrPolicies);
1451350
1451451 // orderly state should be cleared because of the update to state clear data
1451552 g_clearOrderly = TRUE;
1451653
1451754 return TPM_RC_SUCCESS;
1451855 }
1451956 #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
1452924.5 TPM2_ChangeEPS
14530
1453124.5.1 General Description
14532
14533This replaces the current EPS with a value from the RNG and sets the Endorsement hierarchy controls to
14534their default initialization values: ehEnable is SET, endorsementAuth and endorsementPolicy both equal
14535to the Empty Buffer. It will flush any resident objects (transient or persistent) in the EPS hierarchy and not
14536allow objects in the hierarchy associated with the previous EPS to be loaded.
14537
14538NOTE 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
14542This command requires Platform Authorization.
14543
14544
14545
14546
14547Family “2.0” TCG Published Page 323
14548Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
14549 Part 3: Commands Trusted Platform Module Library
14550
14551
14552
1455324.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
14576Page 324 TCG Published Family “2.0”
14577October 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;
1459310
1459411 // The command needs NV update. Check if NV is available.
1459512 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
1459613 // this point
1459714 result = NvIsAvailable();
1459815 if(result != TPM_RC_SUCCESS) return result;
1459916
1460017 // Input parameter is not reference in command action
1460118 in = NULL;
1460219
1460320 // Internal Data Update
1460421
1460522 // Reset endorsement hierarchy seed from RNG
1460623 CryptGenerateRandom(PRIMARY_SEED_SIZE, gp.EPSeed.t.buffer);
1460724
1460825 // Create new ehProof value from RNG
1460926 CryptGenerateRandom(PROOF_SIZE, gp.ehProof.t.buffer);
1461027
1461128 // Enable endorsement hierarchy
1461229 gc.ehEnable = TRUE;
1461330
1461431 // set authValue buffer to zeros
1461532 MemorySet(gp.endorsementAuth.t.buffer, 0, gp.endorsementAuth.t.size);
1461633 // Set endorsement authValue to null
1461734 gp.endorsementAuth.t.size = 0;
1461835
1461936 // Set endorsement authPolicy to null
1462037 gp.endorsementAlg = TPM_ALG_NULL;
1462138 gp.endorsementPolicy.t.size = 0;
1462239
1462340 // Flush loaded object in endorsement hierarchy
1462441 ObjectFlushHierarchy(TPM_RH_ENDORSEMENT);
1462542
1462643 // Flush evict object of endorsement hierarchy stored in NV
1462744 NvFlushHierarchy(TPM_RH_ENDORSEMENT);
1462845
1462946 // Save hierarchy changes to NV
1463047 NvWriteReserved(NV_EP_SEED, &gp.EPSeed);
1463148 NvWriteReserved(NV_EH_PROOF, &gp.ehProof);
1463249 NvWriteReserved(NV_ENDORSEMENT_AUTH, &gp.endorsementAuth);
1463350 NvWriteReserved(NV_ENDORSEMENT_ALG, &gp.endorsementAlg);
1463451 NvWriteReserved(NV_ENDORSEMENT_POLICY, &gp.endorsementPolicy);
1463552
1463653 // orderly state should be cleared because of the update to state clear data
1463754 g_clearOrderly = TRUE;
1463855
1463956 return TPM_RC_SUCCESS;
1464057 }
1464158 #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
1465124.6 TPM2_Clear
14652
1465324.6.1 General Description
14654
14655This command removes all TPM context associated with a specific Owner.
14656The 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.
14675This command requires Platform Authorization or Lockout Authorization. If TPM2_ClearControl() has
14676disabled this command, the TPM shall return TPM_RC_DISABLED.
14677If this command is authorized using lockoutAuth, the HMAC in the response shall use the new
14678lockoutAuth value (that is, the Empty Buffer) when computing response HMAC.
14679
14680
14681
14682
14683Page 326 TCG Published Family “2.0”
14684October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
14685 Trusted Platform Module Library Part 3: Commands
14686
14687
14688
1468924.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
14712Family “2.0” TCG Published Page 327
14713Level 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
147201 #include "InternalRoutines.h"
147212 #include "Clear_fp.h"
147223 #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;
1473510
1473611 // Input parameter is not reference in command action
1473712 in = NULL;
1473813
1473914 // The command needs NV update. Check if NV is available.
1474015 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
1474116 // this point
1474217 result = NvIsAvailable();
1474318 if(result != TPM_RC_SUCCESS) return result;
1474419
1474520 // Input Validation
1474621
1474722 // If Clear command is disabled, return an error
1474823 if(gp.disableClear)
1474924 return TPM_RC_DISABLED;
1475025
1475126 // Internal Data Update
1475227
1475328 // Reset storage hierarchy seed from RNG
1475429 CryptGenerateRandom(PRIMARY_SEED_SIZE, gp.SPSeed.t.buffer);
1475530
1475631 // Create new shProof and ehProof value from RNG
1475732 CryptGenerateRandom(PROOF_SIZE, gp.shProof.t.buffer);
1475833 CryptGenerateRandom(PROOF_SIZE, gp.ehProof.t.buffer);
1475934
1476035 // Enable storage and endorsement hierarchy
1476136 gc.shEnable = gc.ehEnable = TRUE;
1476237
1476338 // set the authValue buffers to zero
1476439 MemorySet(gp.ownerAuth.t.buffer, 0, gp.ownerAuth.t.size);
1476540 MemorySet(gp.endorsementAuth.t.buffer, 0, gp.endorsementAuth.t.size);
1476641 MemorySet(gp.lockoutAuth.t.buffer, 0, gp.lockoutAuth.t.size);
1476742 // Set storage, endorsement and lockout authValue to null
1476843 gp.ownerAuth.t.size = gp.endorsementAuth.t.size = gp.lockoutAuth.t.size = 0;
1476944
1477045 // Set storage, endorsement, and lockout authPolicy to null
1477146 gp.ownerAlg = gp.endorsementAlg = gp.lockoutAlg = TPM_ALG_NULL;
1477247 gp.ownerPolicy.t.size = 0;
1477348 gp.endorsementPolicy.t.size = 0;
1477449 gp.lockoutPolicy.t.size = 0;
1477550
1477651 // Flush loaded object in storage and endorsement hierarchy
1477752 ObjectFlushHierarchy(TPM_RH_OWNER);
1477853 ObjectFlushHierarchy(TPM_RH_ENDORSEMENT);
1477954
1478055 // Flush owner and endorsement object and owner index in NV
1478156 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
1478757 NvFlushHierarchy(TPM_RH_ENDORSEMENT);
1478858
1478959 // Save hierarchy changes to NV
1479060 NvWriteReserved(NV_SP_SEED, &gp.SPSeed);
1479161 NvWriteReserved(NV_SH_PROOF, &gp.shProof);
1479262 NvWriteReserved(NV_EH_PROOF, &gp.ehProof);
1479363 NvWriteReserved(NV_OWNER_AUTH, &gp.ownerAuth);
1479464 NvWriteReserved(NV_ENDORSEMENT_AUTH, &gp.endorsementAuth);
1479565 NvWriteReserved(NV_LOCKOUT_AUTH, &gp.lockoutAuth);
1479666 NvWriteReserved(NV_OWNER_ALG, &gp.ownerAlg);
1479767 NvWriteReserved(NV_ENDORSEMENT_ALG, &gp.endorsementAlg);
1479868 NvWriteReserved(NV_LOCKOUT_ALG, &gp.lockoutAlg);
1479969 NvWriteReserved(NV_OWNER_POLICY, &gp.ownerPolicy);
1480070 NvWriteReserved(NV_ENDORSEMENT_POLICY, &gp.endorsementPolicy);
1480171 NvWriteReserved(NV_LOCKOUT_POLICY, &gp.lockoutPolicy);
1480272
1480373 // Initialize dictionary attack parameters
1480474 DAPreInstall_Init();
1480575
1480676 // Reset clock
1480777 go.clock = 0;
1480878 go.clockSafe = YES;
1480979 // Update the DRBG state whenever writing orderly state to NV
1481080 CryptDrbgGetPutState(GET_STATE);
1481181 NvWriteReserved(NV_ORDERLY_DATA, &go);
1481282
1481383 // Reset counters
1481484 gp.resetCount = gr.restartCount = gr.clearCount = 0;
1481585 gp.auditCounter = 0;
1481686 NvWriteReserved(NV_RESET_COUNT, &gp.resetCount);
1481787 NvWriteReserved(NV_AUDIT_COUNTER, &gp.auditCounter);
1481888
1481989 // orderly state should be cleared because of the update to state clear data
1482090 g_clearOrderly = TRUE;
1482191
1482292 return TPM_RC_SUCCESS;
1482393 }
1482494 #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
1483424.7 TPM2_ClearControl
14835
1483624.7.1 General Description
14837
14838TPM2_ClearControl() disables and enables the execution of TPM2_Clear().
14839The TPM will SET the TPM’s TPMA_PERMANENT.disableClear attribute if disable is YES and will
14840CLEAR the attribute if disable is NO. When the attribute is SET, TPM2_Clear() may not be executed.
14841
14842NOTE 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
14845Lockout Authorization may be used to SET disableClear but not to CLEAR it.
14846Platform Authorization may be used to SET or CLEAR disableClear.
14847
14848
14849
14850
14851Page 330 TCG Published Family “2.0”
14852October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
14853 Trusted Platform Module Library Part 3: Commands
14854
14855
14856
1485724.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
14885Family “2.0” TCG Published Page 331
14886Level 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
148931 #include "InternalRoutines.h"
148942 #include "ClearControl_fp.h"
148953 #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;
1490810
1490911 // The command needs NV update. Check if NV is available.
1491012 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
1491113 // this point
1491214 result = NvIsAvailable();
1491315 if(result != TPM_RC_SUCCESS) return result;
1491416
1491517 // Input Validation
1491618
1491719 // LockoutAuth may be used to set disableLockoutClear to TRUE but not to FALSE
1491820 if(in->auth == TPM_RH_LOCKOUT && in->disable == NO)
1491921 return TPM_RC_AUTH_FAIL;
1492022
1492123 // Internal Data Update
1492224
1492325 if(in->disable == YES)
1492426 gp.disableClear = TRUE;
1492527 else
1492628 gp.disableClear = FALSE;
1492729
1492830 // Record the change to NV
1492931 NvWriteReserved(NV_DISABLE_CLEAR, &gp.disableClear);
1493032
1493133 return TPM_RC_SUCCESS;
1493234 }
1493335 #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
1494324.8 TPM2_HierarchyChangeAuth
14944
1494524.8.1 General Description
14946
14947This command allows the authorization secret for a hierarchy or lockout to be changed using the current
14948authorization value as the command authorization.
14949If authHandle is TPM_RH_PLATFORM, then platformAuth is changed. If authHandle is
14950TPM_RH_OWNER, then ownerAuth is changed. If authHandle is TPM_RH_ENDORSEMENT, then
14951endorsementAuth is changed. If authHandle is TPM_RH_LOCKOUT, then lockoutAuth is changed.
14952If authHandle is TPM_RH_PLATFORM, then Physical Presence may need to be asserted for this
14953command to succeed (see 26.2, “TPM2_PP_Commands”).
14954The authorization value may be no larger than the digest produced by the hash algorithm used for context
14955integrity.
14956
14957EXAMPLE 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
14963Family “2.0” TCG Published Page 333
14964Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
14965 Part 3: Commands Trusted Platform Module Library
14966
14967
1496824.8.2 Command and Response
14969
14970 Table 163 — TPM2_HierarchyChangeAuth Command
14971Type Name Description
14972
14973TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
14974UINT32 commandSize
14975TPM_CC commandCode TPM_CC_HierarchyChangeAuth {NV}
14976
14977 TPM_RH_LOCKOUT, TPM_RH_ENDORSEMENT,
14978 TPM_RH_OWNER or TPM_RH_PLATFORM+{PP}
14979TPMI_RH_HIERARCHY_AUTH @authHandle
14980 Auth Index: 1
14981 Auth Role: USER
14982
14983TPM2B_AUTH newAuth new authorization value
14984
14985
14986 Table 164 — TPM2_HierarchyChangeAuth Response
14987Type Name Description
14988
14989TPM_ST tag see clause 6
14990UINT32 responseSize
14991TPM_RC responseCode
14992
14993
14994
14995
14996Page 334 TCG Published Family “2.0”
14997October 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
150041 #include "InternalRoutines.h"
150052 #include "HierarchyChangeAuth_fp.h"
150063 #ifdef TPM_CC_HierarchyChangeAuth // Conditional expansion of this file
150074 #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 {
1501910 TPM_RC result;
1502011
1502112 // The command needs NV update. Check if NV is available.
1502213 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
1502314 // this point
1502415 result = NvIsAvailable();
1502516 if(result != TPM_RC_SUCCESS) return result;
1502617
1502718 // Make sure the the auth value is a reasonable size (not larger than
1502819 // the size of the digest produced by the integrity hash. The integrity
1502920 // hash is assumed to produce the longest digest of any hash implemented
1503021 // on the TPM.
1503122 if( MemoryRemoveTrailingZeros(&in->newAuth)
1503223 > CryptGetHashDigestSize(CONTEXT_INTEGRITY_HASH_ALG))
1503324 return TPM_RC_SIZE + RC_HierarchyChangeAuth_newAuth;
1503425
1503526 // Set hierarchy authValue
1503627 switch(in->authHandle)
1503728 {
1503829 case TPM_RH_OWNER:
1503930 gp.ownerAuth = in->newAuth;
1504031 NvWriteReserved(NV_OWNER_AUTH, &gp.ownerAuth);
1504132 break;
1504233 case TPM_RH_ENDORSEMENT:
1504334 gp.endorsementAuth = in->newAuth;
1504435 NvWriteReserved(NV_ENDORSEMENT_AUTH, &gp.endorsementAuth);
1504536 break;
1504637 case TPM_RH_PLATFORM:
1504738 gc.platformAuth = in->newAuth;
1504839 // orderly state should be cleared
1504940 g_clearOrderly = TRUE;
1505041 break;
1505142 case TPM_RH_LOCKOUT:
1505243 gp.lockoutAuth = in->newAuth;
1505344 NvWriteReserved(NV_LOCKOUT_AUTH, &gp.lockoutAuth);
1505445 break;
1505546 default:
1505647 pAssert(FALSE);
1505748 break;
1505849 }
1505950
1506051 return TPM_RC_SUCCESS;
1506152 }
1506253 #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
1507225 Dictionary Attack Functions
15073
1507425.1 Introduction
15075
15076A TPM is required to have support for logic that will help prevent a dictionary attack on an authorization
15077value. The protection is provided by a counter that increments when a password authorization or an
15078HMAC authorization fails. When the counter reaches a predefined value, the TPM will not accept, for
15079some time interval, further requests that require authorization and the TPM is in Lockout mode. While the
15080TPM is in Lockout mode, the TPM will return TPM_RC_LOCKED if the command requires use of an
15081object’s or Index’s authValue unless the authorization applies to an entry in the Platform hierarchy.
15082
15083NOTE 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
15088If the TPM is continuously powered for the duration of newRecoveryTime and no authorization failures
15089occur, the authorization failure counter will be decremented by one. This property is called “self-healing.”
15090Self-healing shall not cause the count of failed attempts to decrement below zero.
15091The count of failed attempts, the lockout interval, and self-healing interval are settable using
15092TPM2_DictionaryAttackParameters(). The lockout parameters and the current value of the lockout
15093counter can be read with TPM2_GetCapability().
15094Dictionary attack protection does not apply to an entity associated with a permanent handle (handle type
15095== TPM_HT_PERMANENT).
15096
1509725.2 TPM2_DictionaryAttackLockReset
15098
1509925.2.1 General Description
15100
15101This command cancels the effect of a TPM lockout due to a number of successive authorization failures.
15102If this command is properly authorized, the lockout counter is set to zero.
15103Only one lockoutAuth authorization failure is allowed for this command during a lockoutRecovery interval
15104(set using TPM2_DictionaryAttackParameters().
15105
15106
15107
15108
15109Page 336 TCG Published Family “2.0”
15110October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
15111 Trusted Platform Module Library Part 3: Commands
15112
15113
15114
1511525.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
15138Family “2.0” TCG Published Page 337
15139Level 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;
1515510
1515611 // Input parameter is not reference in command action
1515712 in = NULL;
1515813
1515914 // The command needs NV update. Check if NV is available.
1516015 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
1516116 // this point
1516217 result = NvIsAvailable();
1516318 if(result != TPM_RC_SUCCESS) return result;
1516419
1516520 // Internal Data Update
1516621
1516722 // Set failed tries to 0
1516823 gp.failedTries = 0;
1516924
1517025 // Record the changes to NV
1517126 NvWriteReserved(NV_FAILED_TRIES, &gp.failedTries);
1517227
1517328 return TPM_RC_SUCCESS;
1517429 }
1517530 #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
1518525.3 TPM2_DictionaryAttackParameters
15186
1518725.3.1 General Description
15188
15189This command changes the lockout parameters.
15190The command requires Lockout Authorization.
15191The timeout parameters (newRecoveryTime and lockoutRecovery) indicate values that are measured with
15192respect to the Time and not Clock.
15193
15194NOTE Use of Time means that the TPM shall be continuously powered for the duration of a timeout.
15195
15196If newRecoveryTime is zero, then DA protection is disabled. Authorizations are checked but authorization
15197failures will not cause the TPM to enter lockout.
15198If newMaxTries is zero, the TPM will be in lockout and use of DA protected entities will be disabled.
15199If lockoutRecovery is zero, then the recovery interval is a boot cycle (_TPM_Init followed by
15200Startup(CLEAR).
15201This command will set the authorization failure count (failedTries) to zero.
15202Only one lockoutAuth authorization failure is allowed for this command during a lockoutRecovery interval.
15203
15204
15205
15206
15207Family “2.0” TCG Published Page 339
15208Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
15209 Part 3: Commands Trusted Platform Module Library
15210
15211
15212
1521325.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
15249Page 340 TCG Published Family “2.0”
15250October 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;
1526610
1526711 // The command needs NV update. Check if NV is available.
1526812 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
1526913 // this point
1527014 result = NvIsAvailable();
1527115 if(result != TPM_RC_SUCCESS) return result;
1527216
1527317 // Internal Data Update
1527418
1527519 // Set dictionary attack parameters
1527620 gp.maxTries = in->newMaxTries;
1527721 gp.recoveryTime = in->newRecoveryTime;
1527822 gp.lockoutRecovery = in->lockoutRecovery;
1527923
1528024 // Set failed tries to 0
1528125 gp.failedTries = 0;
1528226
1528327 // Record the changes to NV
1528428 NvWriteReserved(NV_FAILED_TRIES, &gp.failedTries);
1528529 NvWriteReserved(NV_MAX_TRIES, &gp.maxTries);
1528630 NvWriteReserved(NV_RECOVERY_TIME, &gp.recoveryTime);
1528731 NvWriteReserved(NV_LOCKOUT_RECOVERY, &gp.lockoutRecovery);
1528832
1528933 return TPM_RC_SUCCESS;
1529034 }
1529135 #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
1530126 Miscellaneous Management Functions
15302
1530326.1 Introduction
15304
15305This clause contains commands that do not logically group with any other commands.
15306
1530726.2 TPM2_PP_Commands
15308
1530926.2.1 General Description
15310
15311This command is used to determine which commands require assertion of Physical Presence (PP) in
15312addition to platformAuth/platformPolicy.
15313This command requires that auth is TPM_RH_PLATFORM and that Physical Presence be asserted.
15314After this command executes successfully, the commands listed in setList will be added to the list of
15315commands that require that Physical Presence be asserted when the handle associated with the
15316authorization is TPM_RH_PLATFORM. The commands in clearList will no longer require assertion of
15317Physical Presence in order to authorize a command.
15318If a command is not in either list, its state is not changed. If a command is in both lists, then it will no
15319longer require Physical Presence (for example, setList is processed first).
15320Only commands with handle types of TPMI_RH_PLATFORM, TPMI_RH_PROVISION,
15321TPMI_RH_CLEAR, or TPMI_RH_HIERARCHY can be gated with Physical Presence. If any other
15322command is in either list, it is discarded.
15323When a command requires that Physical Presence be provided, then Physical Presence shall be
15324asserted for either an HMAC or a Policy authorization.
15325
15326NOTE Physical Presence may be made a requirement of any policy.
15327
15328TPM2_PP_Commands() always requires assertion of Physical Presence.
15329
15330
15331
15332
15333Page 342 TCG Published Family “2.0”
15334October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
15335 Trusted Platform Module Library Part 3: Commands
15336
15337
15338
1533926.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
15370Family “2.0” TCG Published Page 343
15371Level 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;
1538710
1538811 TPM_RC result;
1538912
1539013 // The command needs NV update. Check if NV is available.
1539114 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
1539215 // this point
1539316 result = NvIsAvailable();
1539417 if(result != TPM_RC_SUCCESS) return result;
1539518
1539619 // Internal Data Update
1539720
1539821 // Process set list
1539922 for(i = 0; i < in->setList.count; i++)
1540023 // If command is implemented, set it as PP required. If the input
1540124 // command is not a PP command, it will be ignored at
1540225 // PhysicalPresenceCommandSet().
1540326 if(CommandIsImplemented(in->setList.commandCodes[i]))
1540427 PhysicalPresenceCommandSet(in->setList.commandCodes[i]);
1540528
1540629 // Process clear list
1540730 for(i = 0; i < in->clearList.count; i++)
1540831 // If command is implemented, clear it as PP required. If the input
1540932 // command is not a PP command, it will be ignored at
1541033 // PhysicalPresenceCommandClear(). If the input command is
1541134 // TPM2_PP_Commands, it will be ignored as well
1541235 if(CommandIsImplemented(in->clearList.commandCodes[i]))
1541336 PhysicalPresenceCommandClear(in->clearList.commandCodes[i]);
1541437
1541538 // Save the change of PP list
1541639 NvWriteReserved(NV_PP_LIST, &gp.ppList);
1541740
1541841 return TPM_RC_SUCCESS;
1541942 }
1542043 #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
1543026.3 TPM2_SetAlgorithmSet
15431
1543226.3.1 General Description
15433
15434This command allows the platform to change the set of algorithms that are used by the TPM. The
15435algorithmSet setting is a vendor-dependent value.
15436If the changing of the algorithm set results in a change of the algorithms of PCR banks, then the TPM will
15437need to be reset (_TPM_Init and TPM2_Startup(TPM_SU_CLEAR)) before the new PCR settings take
15438effect. After this command executes successfully, if startupType in the next TPM2_Startup() is not
15439TPM_SU_CLEAR, the TPM shall return TPM_RC_VALUE and enter Failure mode.
15440This command does not change the algorithms available to the platform.
15441
15442NOTE 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
15450Family “2.0” TCG Published Page 345
15451Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
15452 Part 3: Commands Trusted Platform Module Library
15453
15454
1545526.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
15483Page 346 TCG Published Family “2.0”
15484October 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;
1550010
1550111 // The command needs NV update. Check if NV is available.
1550212 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
1550313 // this point
1550414 result = NvIsAvailable();
1550515 if(result != TPM_RC_SUCCESS) return result;
1550616
1550717 // Internal Data Update
1550818 gp.algorithmSet = in->algorithmSet;
1550919
1551020 // Write the algorithm set changes to NV
1551121 NvWriteReserved(NV_ALGORITHM_SET, &gp.algorithmSet);
1551222
1551323 return TPM_RC_SUCCESS;
1551424 }
1551525 #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
1552527 Field Upgrade
15526
1552727.1 Introduction
15528
15529This clause contains the commands for managing field upgrade of the firmware in the TPM. The field
15530upgrade scheme may be used for replacement or augmentation of the firmware installed in the TPM.
15531
15532EXAMPLE 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
15536EXAMPLE 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
15539The field upgrade process uses two commands (TPM2_FieldUpgradeStart() and
15540TPM2_FieldUpgradeData()). TPM2_FieldUpgradeStart() validates that a signature on the provided digest
15541is from the TPM manufacturer and that proper authorization is provided using platformPolicy.
15542
15543NOTE 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
15547If the proper authorization is given, the TPM will retain the signed digest and enter the Field Upgrade
15548mode (FUM). While in FUM, the TPM will accept TPM2_FieldUpgradeData() commands. It may accept
15549other commands if it is able to complete them using the previously installed firmware. Otherwise, it will
15550return TPM_RC_UPGRADE.
15551Each block of the field upgrade shall contain the digest of the next block of the field upgrade data. That
15552digest shall be included in the digest of the previous block. The digest of the first block is signed by the
15553TPM manufacturer. That signature and first block digest are the parameters for
15554TPM2_FieldUpgradeStart(). The digest is saved in the TPM as the required digest for the next field
15555upgrade data block and as the identifier of the field upgrade sequence.
15556For each field upgrade data block that is sent to the TPM by TPM2_FieldUpgradeData(), the TPM shall
15557validate that the digest matches the required digest and if not, shall return TPM_RC_VALUE. The TPM
15558shall extract the digest of the next expected block and return that value to the caller, along with the digest
15559of the first data block of the update sequence.
15560The system may attempt to abandon the firmware upgrade by using a zero-length buffer in
15561TPM2_FieldUpdateData(). If the TPM is able to resume operation using the firmware present when the
15562upgrade started, then the TPM will indicate that it has abandon the update by setting the digest of the
15563next block to the Empty Buffer. If the TPM cannot abandon the update, it will return the expected next
15564digest.
15565The system may also attempt to abandon the update because of a power interruption. If the TPM is able
15566to resume normal operations, then it will respond normally to TPM2_Startup(). If the TPM is not able to
15567resume normal operations, then it will respond to any command but TPM2_FieldUpgradeData() with
15568TPM_RC_FIELDUPGRADE.
15569After a _TPM_Init, system software may not be able to resume the field upgrade that was in process
15570when the power interruption occurred. In such case, the TPM firmware may be reset to one of two other
15571values:
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”).
15574The TPM retains the digest of the first block for these firmware images and checks to see if the first block
15575after _TPM_Init matches either of those digests. If so, the firmware update process restarts and the
15576original firmware may be loaded.
15577
15578
15579Page 348 TCG Published Family “2.0”
15580October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
15581 Trusted Platform Module Library Part 3: Commands
15582
15583NOTE 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
15586When the last block of the firmware upgrade is loaded into the TPM (indicated to the TPM by data in the
15587data block in a TPM vendor-specific manner), the TPM will complete the upgrade process. If the TPM is
15588able to resume normal operations without a reboot, it will set the hash algorithm of the next block to
15589TPM_ALG_NULL and return TPM_RC_SUCCESS. If a reboot is required, the TPM shall return
15590TPM_RC_REBOOT in response to the last TPM2_FieldUpgradeData() and all subsequent TPM
15591commands until a _TPM_Init is received.
15592
15593NOTE 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
15600During the field upgrade process, either the one specified in this clause or a vendor proprietary field
15601upgrade 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
15610NOTE 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
15616Family “2.0” TCG Published Page 349
15617Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
15618 Part 3: Commands Trusted Platform Module Library
15619
15620
1562127.2 TPM2_FieldUpgradeStart
15622
1562327.2.1 General Description
15624
15625This command uses platformPolicy and a TPM Vendor Authorization Key to authorize a Field Upgrade
15626Manifest.
15627If the signature checks succeed, the authorization is valid and the TPM will accept
15628TPM2_FieldUpgradeData().
15629This signature is checked against the loaded key referenced by keyHandle. This key will have a Name
15630that is the same as a value that is part of the TPM firmware data. If the signature is not valid, the TPM
15631shall return TPM_RC_SIGNATURE.
15632
15633NOTE 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
15639Page 350 TCG Published Family “2.0”
15640October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
15641 Trusted Platform Module Library Part 3: Commands
15642
15643
1564427.2.2 Command and Response
15645
15646 Table 173 — TPM2_FieldUpgradeStart Command
15647Type Name Description
15648
15649TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
15650UINT32 commandSize
15651TPM_CC commandCode TPM_CC_FieldUpgradeStart
15652
15653 TPM_RH_PLATFORM+{PP}
15654TPMI_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
15658TPMI_DH_OBJECT keyHandle manifestSignature
15659 Auth Index: None
15660
15661TPM2B_DIGEST fuDigest digest of the first block in the field upgrade sequence
15662 signature over fuDigest using the key associated with
15663TPMT_SIGNATURE manifestSignature
15664 keyHandle (not optional)
15665
15666
15667 Table 174 — TPM2_FieldUpgradeStart Response
15668Type Name Description
15669
15670TPM_ST tag see clause 6
15671UINT32 responseSize
15672TPM_RC responseCode
15673
15674
15675
15676
15677Family “2.0” TCG Published Page 351
15678Level 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
1569410 UNUSED_PARAMETER(in);
1569511 return TPM_RC_SUCCESS;
1569612 }
1569713 #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
1570727.3 TPM2_FieldUpgradeData
15708
1570927.3.1 General Description
15710
15711This command will take the actual field upgrade image to be installed on the TPM. The exact format of
15712fuData is vendor-specific. This command is only possible following a successful
15713TPM2_FieldUpgradeStart(). If the TPM has not received a properly authorized
15714TPM2_FieldUpgradeStart(), then the TPM shall return TPM_RC_FIELDUPGRADE.
15715The TPM will validate that the digest of fuData matches an expected value. If so, the TPM may buffer or
15716immediately apply the update. If the digest of fuData does not match an expected value, the TPM shall
15717return TPM_RC_VALUE.
15718
15719
15720
15721
15722Family “2.0” TCG Published Page 353
15723Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
15724 Part 3: Commands Trusted Platform Module Library
15725
15726
15727
1572827.3.2 Command and Response
15729
15730 Table 175 — TPM2_FieldUpgradeData Command
15731Type Name Description
15732
15733 TPM_ST_SESSIONS if an audit or decrypt session is
15734TPMI_ST_COMMAND_TAG tag
15735 present; otherwise, TPM_ST_NO_SESSIONS
15736UINT32 commandSize
15737TPM_CC commandCode TPM_CC_FieldUpgradeData {NV}
15738
15739TPM2B_MAX_BUFFER fuData field upgrade image data
15740
15741
15742 Table 176 — TPM2_FieldUpgradeData Response
15743Type Name Description
15744
15745TPM_ST tag see clause 6
15746UINT32 responseSize
15747TPM_RC responseCode
15748
15749 tagged digest of the next block
15750TPMT_HA+ nextDigest
15751 TPM_ALG_NULL if field update is complete
15752TPMT_HA firstDigest tagged digest of the first block of the sequence
15753
15754
15755
15756
15757Page 354 TCG Published Family “2.0”
15758October 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 {
1577410 // Not implemented
1577511 UNUSED_PARAMETER(in);
1577612 UNUSED_PARAMETER(out);
1577713 return TPM_RC_SUCCESS;
1577814 }
1577915 #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
1578927.4 TPM2_FirmwareRead
15790
1579127.4.1 General Description
15792
15793This command is used to read a copy of the current firmware installed in the TPM.
15794The presumption is that the data will be returned in reverse order so that the last block in the sequence
15795would be the first block given to the TPM in case of a failure recovery. If the TPM2_FirmwareRead
15796sequence completes successfully, then the data provided from the TPM will be sufficient to allow the TPM
15797to recover from an abandoned upgrade of this firmware.
15798To start the sequence of retrieving the data, the caller sets sequenceNumber to zero. When the TPM has
15799returned all the firmware data, the TPM will return the Empty Buffer as fuData.
15800The contents of fuData are opaque to the caller.
15801
15802NOTE 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
15805NOTE 2 Support for this command is optional even if the TPM implements TPM2_FieldUpgradeStart() a nd
15806 TPM2_FieldUpgradeData().
15807
15808
15809
15810
15811Page 356 TCG Published Family “2.0”
15812October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
15813 Trusted Platform Module Library Part 3: Commands
15814
15815
1581627.4.2 Command and Response
15817
15818 Table 177 — TPM2_FirmwareRead Command
15819Type Name Description
15820
15821 TPM_ST_SESSIONS if an audit or encrypt session is
15822TPMI_ST_COMMAND_TAG tag
15823 present; otherwise, TPM_ST_NO_SESSIONS
15824UINT32 commandSize
15825TPM_CC commandCode TPM_CC_FirmwareRead
15826
15827 the number of previous calls to this command in this
15828UINT32 sequenceNumber sequence
15829 set to 0 on the first call
15830
15831
15832 Table 178 — TPM2_FirmwareRead Response
15833Type Name Description
15834
15835TPM_ST tag see clause 6
15836UINT32 responseSize
15837TPM_RC responseCode
15838
15839TPM2B_MAX_BUFFER fuData field upgrade image data
15840
15841
15842
15843
15844Family “2.0” TCG Published Page 357
15845Level 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 {
1586110 // Not implemented
1586211 UNUSED_PARAMETER(in);
1586312 UNUSED_PARAMETER(out);
1586413 return TPM_RC_SUCCESS;
1586514 }
1586615 #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
1587628 Context Management
15877
1587828.1 Introduction
15879
15880Three of the commands in this clause (TPM2_ContextSave(), TPM2_ContextLoad(), and
15881TPM2_FlushContext()) implement the resource management described in the "Context Management"
15882clause in TPM 2.0 Part 1.
15883The fourth command in this clause (TPM2_EvictControl()) is used to control the persistence of loadable
15884objects in TPM memory. Background for this command may be found in the "Owner and Platform Evict
15885Objects" clause in TPM 2.0 Part 1.
15886
1588728.2 TPM2_ContextSave
15888
1588928.2.1 General Description
15890
15891This command saves a session context, object context, or sequence object context outside the TPM.
15892No authorization sessions of any type are allowed with this command and tag is required to be
15893TPM_ST_NO_SESSIONS.
15894
15895NOTE 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
15900The TPM shall encrypt and integrity protect the TPM2B_CONTEXT_SENSITIVE context as described in
15901the "Context Protection" clause in TPM 2.0 Part 1.
15902See the “Context Data” clause in TPM 2.0 Part 2 for a description of the context structure in the response.
15903
15904
15905
15906
15907Family “2.0” TCG Published Page 359
15908Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
15909 Part 3: Commands Trusted Platform Module Library
15910
15911
15912
1591328.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
15939Page 360 TCG Published Family “2.0”
15940October 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
159471 #include "InternalRoutines.h"
159482 #include "ContextSave_fp.h"
159493 #ifdef TPM_CC_ContextSave // Conditional expansion of this file
159504 #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 )
1596310 {
1596411 TPM_RC result;
1596512 UINT16 fingerprintSize; // The size of fingerprint in context
1596613 // blob.
1596714 UINT64 contextID = 0; // session context ID
1596815 TPM2B_SYM_KEY symKey;
1596916 TPM2B_IV iv;
1597017
1597118 TPM2B_DIGEST integrity;
1597219 UINT16 integritySize;
1597320 BYTE *buffer;
1597421
1597522 // This command may cause the orderlyState to be cleared due to
1597623 // the update of state reset data. If this is the case, check if NV is
1597724 // available first
1597825 if(gp.orderlyState != SHUTDOWN_NONE)
1597926 {
1598027 // The command needs NV update. Check if NV is available.
1598128 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
1598229 // this point
1598330 result = NvIsAvailable();
1598431 if(result != TPM_RC_SUCCESS) return result;
1598532 }
1598633
1598734 // Internal Data Update
1598835
1598936 // Initialize output handle. At the end of command action, the output
1599037 // handle of an object will be replaced, while the output handle
1599138 // for a session will be the same as input
1599239 out->context.savedHandle = in->saveHandle;
1599340
1599441 // Get the size of fingerprint in context blob. The sequence value in
1599542 // TPMS_CONTEXT structure is used as the fingerprint
1599643 fingerprintSize = sizeof(out->context.sequence);
1599744
1599845 // Compute the integrity size at the beginning of context blob
1599946 integritySize = sizeof(integrity.t.size)
1600047 + CryptGetHashDigestSize(CONTEXT_INTEGRITY_HASH_ALG);
1600148
1600249 // Perform object or session specific context save
1600350 switch(HandleGetType(in->saveHandle))
1600451 {
1600552 case TPM_HT_TRANSIENT:
1600653 {
1600754 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
16058100 break;
16059101 }
16060102 case TPM_HT_HMAC_SESSION:
16061103 case TPM_HT_POLICY_SESSION:
16062104 {
16063105 SESSION *session = SessionGet(in->saveHandle);
16064106
16065107 // Set size of the context data. The contents of context blob is vendor
16066108 // defined. In this implementation, the size of context blob is the
16067109 // size of a internal session structure plus the size of
16068110 // fingerprint plus the size of integrity
16069111 out->context.contextBlob.t.size = integritySize +
16070112 fingerprintSize + sizeof(*session);
16071113
16072114 // Make sure things fit
16073115 pAssert(out->context.contextBlob.t.size
16074116 < sizeof(out->context.contextBlob.t.buffer));
16075117
16076118 // Copy the whole internal SESSION structure to context blob.
16077119 // Save space for fingerprint at the beginning of the buffer
16078120 // 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
16084121 // can be reclaimed after this call
16085122 MemoryCopy(out->context.contextBlob.t.buffer
16086123 + integritySize + fingerprintSize,
16087124 session, sizeof(*session),
16088125 sizeof(out->context.contextBlob.t.buffer)
16089126 - integritySize - fingerprintSize);
16090127
16091128 // Fill in the other return parameters for a session
16092129 // Get a context ID and set the session tracking values appropriately
16093130 // TPM_RC_CONTEXT_GAP is a possible error.
16094131 // SessionContextSave() will flush the in-memory context
16095132 // so no additional errors may occur after this call.
16096133 result = SessionContextSave(out->context.savedHandle, &contextID);
16097134 if(result != TPM_RC_SUCCESS) return result;
16098135
16099136 // sequence number is the current session contextID
16100137 out->context.sequence = contextID;
16101138
16102139 // use TPM_RH_NULL as hierarchy for session context
16103140 out->context.hierarchy = TPM_RH_NULL;
16104141
16105142 break;
16106143 }
16107144 default:
16108145 // SaveContext may only take an object handle or a session handle.
16109146 // All the other handle type should be filtered out at unmarshal
16110147 pAssert(FALSE);
16111148 break;
16112149 }
16113150
16114151 // Save fingerprint at the beginning of encrypted area of context blob.
16115152 // Reserve the integrity space
16116153 MemoryCopy(out->context.contextBlob.t.buffer + integritySize,
16117154 &out->context.sequence, sizeof(out->context.sequence),
16118155 sizeof(out->context.contextBlob.t.buffer) - integritySize);
16119156
16120157 // Compute context encryption key
16121158 ComputeContextProtectionKey(&out->context, &symKey, &iv);
16122159
16123160 // Encrypt context blob
16124161 CryptSymmetricEncrypt(out->context.contextBlob.t.buffer + integritySize,
16125162 CONTEXT_ENCRYPT_ALG, CONTEXT_ENCRYPT_KEY_BITS,
16126163 TPM_ALG_CFB, symKey.t.buffer, &iv,
16127164 out->context.contextBlob.t.size - integritySize,
16128165 out->context.contextBlob.t.buffer + integritySize);
16129166
16130167 // Compute integrity hash for the object
16131168 // In this implementation, the same routine is used for both sessions
16132169 // and objects.
16133170 ComputeContextIntegrity(&out->context, &integrity);
16134171
16135172 // add integrity at the beginning of context blob
16136173 buffer = out->context.contextBlob.t.buffer;
16137174 TPM2B_DIGEST_Marshal(&integrity, &buffer, NULL);
16138175
16139176 // orderly state should be cleared because of the update of state reset and
16140177 // state clear data
16141178 g_clearOrderly = TRUE;
16142179
16143180 return TPM_RC_SUCCESS;
16144181 }
16145182 #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
1615528.3 TPM2_ContextLoad
16156
1615728.3.1 General Description
16158
16159This command is used to reload a context that has been saved by TPM2_ContextSave().
16160No authorization sessions of any type are allowed with this command and tag is required to be
16161TPM_ST_NO_SESSIONS (see note in 28.2.1).
16162The TPM will return TPM_RC_HIERARCHY if the context is associated with a hierarchy that is disabled.
16163
16164NOTE Contexts for authorization sessions and for sequence objects belong to the NULL hierarchy which is
16165 never disabled.
16166
16167See the “Context Data” clause in TPM 2.0 Part 2 for a description of the values in the context parameter.
16168If the integrity HMAC of the saved context is not valid, the TPM shall return TPM_RC_INTEGRITY.
16169The TPM shall perform a check on the decrypted context as described in the "Context Confidentiality
16170Protections" clause of TPM 2.0 Part 1 and enter failure mode if the check fails.
16171
16172
16173
16174
16175Page 364 TCG Published Family “2.0”
16176October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
16177 Trusted Platform Module Library Part 3: Commands
16178
16179
16180
1618128.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
16207Family “2.0” TCG Published Page 365
16208Level 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
162151 #include "InternalRoutines.h"
162162 #include "ContextLoad_fp.h"
162173 #ifdef TPM_CC_ContextLoad // Conditional expansion of this file
162184 #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 )
1623710 {
1623811 // Local Variables
1623912 TPM_RC result = TPM_RC_SUCCESS;
1624013
1624114 TPM2B_DIGEST integrityToCompare;
1624215 TPM2B_DIGEST integrity;
1624316 UINT16 integritySize;
1624417 UINT64 fingerprint;
1624518 BYTE *buffer;
1624619 INT32 size;
1624720
1624821 TPM_HT handleType;
1624922 TPM2B_SYM_KEY symKey;
1625023 TPM2B_IV iv;
1625124
1625225 // Input Validation
1625326
1625427 // Check context blob size
1625528 handleType = HandleGetType(in->context.savedHandle);
1625629
1625730 // Check integrity
1625831 // In this implementation, the same routine is used for both sessions
1625932 // and objects.
1626033 integritySize = CryptGetHashDigestSize(CONTEXT_INTEGRITY_HASH_ALG);
1626134
1626235 // Get integrity from context blob
1626336 buffer = in->context.contextBlob.t.buffer;
1626437 size = (INT32) in->context.contextBlob.t.size;
1626538 result = TPM2B_DIGEST_Unmarshal(&integrity, &buffer, &size);
1626639 if(result != TPM_RC_SUCCESS)
1626740 return result;
1626841 if(integrity.t.size != integritySize)
1626942 return TPM_RC_SIZE;
1627043
1627144 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;
16333100 }
16334101 case TPM_HT_POLICY_SESSION:
16335102 case TPM_HT_HMAC_SESSION:
16336103 {
16337104
16338105 SESSION *session = (SESSION *)(in->context.contextBlob.t.buffer
16339106 + integritySize + sizeof(fingerprint));
16340107
16341108 // This command may cause the orderlyState to be cleared due to
16342109 // the update of state reset data. If this is the case, check if NV is
16343110 // 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
16349111 if(gp.orderlyState != SHUTDOWN_NONE)
16350112 {
16351113 // The command needs NV update. Check if NV is available.
16352114 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned
16353115 // at this point
16354116 result = NvIsAvailable();
16355117 if(result != TPM_RC_SUCCESS)
16356118 return result;
16357119 }
16358120
16359121 // Check if input handle points to a valid saved session
16360122 if(!SessionIsSaved(in->context.savedHandle))
16361123 return TPM_RC_HANDLE + RC_ContextLoad_context;
16362124
16363125 // Restore session. A TPM_RC_SESSION_MEMORY, TPM_RC_CONTEXT_GAP error
16364126 // may be returned at this point
16365127 result = SessionContextLoad(session, &in->context.savedHandle);
16366128 if(result != TPM_RC_SUCCESS)
16367129 return result;
16368130
16369131 out->loadedHandle = in->context.savedHandle;
16370132
16371133 // orderly state should be cleared because of the update of state
16372134 // reset and state clear data
16373135 g_clearOrderly = TRUE;
16374136
16375137 break;
16376138 }
16377139 default:
16378140 // Context blob may only have an object handle or a session handle.
16379141 // All the other handle type should be filtered out at unmarshal
16380142 pAssert(FALSE);
16381143 break;
16382144 }
16383145
16384146 return TPM_RC_SUCCESS;
16385147 }
16386148 #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
1639628.4 TPM2_FlushContext
16397
1639828.4.1 General Description
16399
16400This command causes all context associated with a loaded object or session to be removed from TPM
16401memory.
16402This command may not be used to remove a persistent object from the TPM.
16403A session does not have to be loaded in TPM memory to have its context flushed. The saved session
16404context associated with the indicated handle is invalidated.
16405No sessions of any type are allowed with this command and tag is required to be
16406TPM_ST_NO_SESSIONS (see note in 28.2.1).
16407If the handle is for a transient object and the handle is not associated with a loaded object, then the TPM
16408shall return TPM_RC_HANDLE.
16409If the handle is for an authorization session and the handle does not reference a loaded or active session,
16410then the TPM shall return TPM_RC_HANDLE.
16411NOTE flushHandle is a parameter and not a handle. If it were in the handle area, the TPM would
16412validate that the context for the referenced entity is in the TPM. When a TPM2_FlushContext references a
16413saved session context, it is not necessary for the context to be in the TPM. When the flushHandle is in
16414the parameter area, the TPM does not validate that associated context is actually in the TPM.
16415
16416
16417
16418
16419Family “2.0” TCG Published Page 369
16420Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
16421 Part 3: Commands Trusted Platform Module Library
16422
16423
16424
1642528.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
16449Page 370 TCG Published Family “2.0”
16450October 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
164571 #include "InternalRoutines.h"
164582 #include "FlushContext_fp.h"
164593 #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
1647210
1647311 // Call object or session specific routine to flush
1647412 switch(HandleGetType(in->flushHandle))
1647513 {
1647614 case TPM_HT_TRANSIENT:
1647715 if(!ObjectIsPresent(in->flushHandle))
1647816 return TPM_RC_HANDLE;
1647917 // Flush object
1648018 ObjectFlush(in->flushHandle);
1648119 break;
1648220 case TPM_HT_HMAC_SESSION:
1648321 case TPM_HT_POLICY_SESSION:
1648422 if( !SessionIsLoaded(in->flushHandle)
1648523 && !SessionIsSaved(in->flushHandle)
1648624 )
1648725 return TPM_RC_HANDLE;
1648826
1648927 // If the session to be flushed is the exclusive audit session, then
1649028 // indicate that there is no exclusive audit session any longer.
1649129 if(in->flushHandle == g_exclusiveAuditSession)
1649230 g_exclusiveAuditSession = TPM_RH_UNASSIGNED;
1649331
1649432 // Flush session
1649533 SessionFlush(in->flushHandle);
1649634 break;
1649735 default:
1649836 // This command only take object or session handle. Other handles
1649937 // should be filtered out at handle unmarshal
1650038 pAssert(FALSE);
1650139 break;
1650240 }
1650341
1650442 return TPM_RC_SUCCESS;
1650543 }
1650644 #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
1651628.5 TPM2_EvictControl
16517
1651828.5.1 General Description
16519
16520This command allows a transient object to be made persistent or a persistent object to be evicted.
16521
16522NOTE 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
16526If objectHandle is a transient object, then the call is to make the object persistent and assign
16527persistentHandle to the persistent version of the object. If objectHandle is a persistent object, then the call
16528is to evict the persistent object.
16529Before execution of TPM2_EvictControl code below, the TPM verifies that objectHandle references an
16530object that is resident on the TPM and that persistentHandle is a valid handle for a persistent object.
16531
16532NOTE 2 This requirement simplifies the unmarshaling code so that it only need check that persistentHandle
16533 is always a persistent object.
16534
16535If objectHandle references a transient object:
16536a) 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.
16540b) 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.
16545c) 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.
16551d) The TPM shall return TPM_RC_NV_DEFINED if a persistent object exists with the same handle as
16552 persistentHandle.
16553e) The TPM shall return TPM_RC_NV_SPACE if insufficient space is available to make the object
16554 persistent.
16555f) 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
16564g) 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
16567Page 372 TCG Published Family “2.0”
16568October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
16569 Trusted Platform Module Library Part 3: Commands
16570
16571If objectHandle references a persistent object:
16572a) 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.
16576b) If the TPM returns TPM_RC_SUCCESS, objectHandle will be removed from persistent memory and
16577 no longer be accessible.
16578
16579NOTE 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
16585Family “2.0” TCG Published Page 373
16586Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
16587 Part 3: Commands Trusted Platform Module Library
16588
16589
1659028.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
16623Page 374 TCG Published Family “2.0”
16624October 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
166311 #include "InternalRoutines.h"
166322 #include "EvictControl_fp.h"
166333 #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;
1665410 OBJECT *evictObject;
1665511
1665612 // The command needs NV update. Check if NV is available.
1665713 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
1665814 // this point
1665915 result = NvIsAvailable();
1666016 if(result != TPM_RC_SUCCESS) return result;
1666117
1666218 // Input Validation
1666319
1666420 // Get internal object pointer
1666521 evictObject = ObjectGet(in->objectHandle);
1666622
1666723 // Temporary, stClear or public only objects can not be made persistent
1666824 if( evictObject->attributes.temporary == SET
1666925 || evictObject->attributes.stClear == SET
1667026 || evictObject->attributes.publicOnly == SET
1667127 )
1667228 return TPM_RC_ATTRIBUTES + RC_EvictControl_objectHandle;
1667329
1667430 // If objectHandle refers to a persistent object, it should be the same as
1667531 // input persistentHandle
1667632 if( evictObject->attributes.evict == SET
1667733 && evictObject->evictHandle != in->persistentHandle
1667834 )
1667935 return TPM_RC_HANDLE + RC_EvictControl_objectHandle;
1668036
1668137 // Additional auth validation
1668238 if(in->auth == TPM_RH_PLATFORM)
1668339 {
1668440 // To make persistent
1668541 if(evictObject->attributes.evict == CLEAR)
1668642 {
1668743 // Platform auth can not set evict object in storage or endorsement
1668844 // 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
1669445 if(evictObject->attributes.ppsHierarchy == CLEAR)
1669546 return TPM_RC_HIERARCHY + RC_EvictControl_objectHandle;
1669647
1669748 // Platform cannot use a handle outside of platform persistent range.
1669849 if(!NvIsPlatformPersistentHandle(in->persistentHandle))
1669950 return TPM_RC_RANGE + RC_EvictControl_persistentHandle;
1670051 }
1670152 // Platform auth can delete any persistent object
1670253 }
1670354 else if(in->auth == TPM_RH_OWNER)
1670455 {
1670556 // Owner auth can not set or clear evict object in platform hierarchy
1670657 if(evictObject->attributes.ppsHierarchy == SET)
1670758 return TPM_RC_HIERARCHY + RC_EvictControl_objectHandle;
1670859
1670960 // Owner cannot use a handle outside of owner persistent range.
1671061 if( evictObject->attributes.evict == CLEAR
1671162 && !NvIsOwnerPersistentHandle(in->persistentHandle)
1671263 )
1671364 return TPM_RC_RANGE + RC_EvictControl_persistentHandle;
1671465 }
1671566 else
1671667 {
1671768 // Other auth is not allowed in this command and should be filtered out
1671869 // at unmarshal process
1671970 pAssert(FALSE);
1672071 }
1672172
1672273 // Internal Data Update
1672374
1672475 // Change evict state
1672576 if(evictObject->attributes.evict == CLEAR)
1672677 {
1672778 // Make object persistent
1672879 // A TPM_RC_NV_HANDLE or TPM_RC_NV_SPACE error may be returned at this
1672980 // point
1673081 result = NvAddEvictObject(in->persistentHandle, evictObject);
1673182 if(result != TPM_RC_SUCCESS) return result;
1673283 }
1673384 else
1673485 {
1673586 // Delete the persistent object in NV
1673687 NvDeleteEntity(evictObject->evictHandle);
1673788 }
1673889
1673990 return TPM_RC_SUCCESS;
1674091
1674192 }
1674293 #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
1675229 Clocks and Timers
16753
1675429.1 TPM2_ReadClock
16755
1675629.1.1 General Description
16757
16758This command reads the current TPMS_TIME_INFO structure that contains the current setting of Time,
16759Clock, resetCount, and restartCount.
16760No authorization sessions of any type are allowed with this command and tag is required to be
16761TPM_ST_NO_SESSIONS.
16762
16763NOTE 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
16772Family “2.0” TCG Published Page 377
16773Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
16774 Part 3: Commands Trusted Platform Module Library
16775
16776
1677729.1.2 Command and Response
16778
16779 Table 187 — TPM2_ReadClock Command
16780Type Name Description
16781
16782TPMI_ST_COMMAND_TAG tag TPM_ST_NO_SESSIONS
16783UINT32 commandSize
16784TPM_CC commandCode TPM_CC_ReadClock
16785
16786
16787 Table 188 — TPM2_ReadClock Response
16788Type Name Description
16789
16790TPM_ST tag see clause 6
16791UINT32 responseSize
16792TPM_RC responseCode
16793
16794TPMS_TIME_INFO currentTime
16795
16796
16797
16798
16799Page 378 TCG Published Family “2.0”
16800October 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
1681610
1681711 out->currentTime.time = g_time;
1681812 TimeFillInfo(&out->currentTime.clockInfo);
1681913
1682014 return TPM_RC_SUCCESS;
1682115 }
1682216 #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
1683229.2 TPM2_ClockSet
16833
1683429.2.1 General Description
16835
16836This command is used to advance the value of the TPM’s Clock. The command will fail if newTime is less
16837than the current value of Clock or if the new time is greater than FF FF 00 00 00 00 00 0016. If both of
16838these checks succeed, Clock is set to newTime. If either of these checks fails, the TPM shall return
16839TPM_RC_VALUE and make no change to Clock.
16840
16841NOTE 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
16847If the value of Clock after the update makes the volatile and non-volatile versions of
16848TPMS_CLOCK_INFO.clock differ by more than the reported update interval, then the TPM shall update
16849the non-volatile version of TPMS_CLOCK_INFO.clock before returning.
16850This command requires Platform Authorization or Owner Authorization.
16851
16852
16853
16854
16855Page 380 TCG Published Family “2.0”
16856October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
16857 Trusted Platform Module Library Part 3: Commands
16858
16859
16860
1686129.2.2 Command and Response
16862
16863 Table 189 — TPM2_ClockSet Command
16864Type Name Description
16865
16866TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
16867UINT32 commandSize
16868TPM_CC commandCode TPM_CC_ClockSet {NV}
16869
16870 TPM_RH_OWNER or TPM_RH_PLATFORM+{PP}
16871TPMI_RH_PROVISION @auth Auth Handle: 1
16872 Auth Role: USER
16873
16874UINT64 newTime new Clock setting in milliseconds
16875
16876
16877 Table 190 — TPM2_ClockSet Response
16878Type Name Description
16879
16880TPM_ST tag see clause 6
16881UINT32 responseSize
16882TPM_RC responseCode
16883
16884
16885
16886
16887Family “2.0” TCG Published Page 381
16888Level 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
168951 #include "InternalRoutines.h"
168962 #include "ClockSet_fp.h"
168973 #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)
1691110 UINT64 clockNow;
1691211
1691312 // Input Validation
1691413
1691514 // new time can not be bigger than 0xFFFF000000000000 or smaller than
1691615 // current clock
1691716 if(in->newTime > 0xFFFF000000000000ULL
1691817 || in->newTime < go.clock)
1691918 return TPM_RC_VALUE + RC_ClockSet_newTime;
1692019
1692120 // Internal Data Update
1692221
1692322 // Internal Data Update
1692423 clockNow = go.clock; // grab the old value
1692524 go.clock = in->newTime; // set the new value
1692625 // Check to see if the update has caused a need for an nvClock update
1692726 if((in->newTime & CLOCK_UPDATE_MASK) > (clockNow & CLOCK_UPDATE_MASK))
1692827 {
1692928 CryptDrbgGetPutState(GET_STATE);
1693029 NvWriteReserved(NV_ORDERLY_DATA, &go);
1693130
1693231 // Now the time state is safe
1693332 go.clockSafe = YES;
1693433 }
1693534
1693635 return TPM_RC_SUCCESS;
1693736 }
1693837 #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
1694829.3 TPM2_ClockRateAdjust
16949
1695029.3.1 General Description
16951
16952This command adjusts the rate of advance of Clock and Time to provide a better approximation to real
16953time.
16954The rateAdjust value is relative to the current rate and not the nominal rate of advance.
16955
16956EXAMPLE 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
16960The range of adjustment shall be sufficient to allow Clock and Time to advance at real time but no more.
16961If the requested adjustment would make the rate advance faster or slower than the nominal accuracy of
16962the input frequency, the TPM shall return TPM_RC_VALUE.
16963
16964EXAMPLE 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
16970The interpretation of “fine” and “coarse” adjustments is implementation-specific.
16971The nominal rate of advance for Clock and Time shall be accurate to within 15 percent. That is, with no
16972adjustment applied, Clock and Time shall be advanced at a rate within 15 percent of actual time.
16973
16974NOTE 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
16977Changes to the current Clock update rate adjustment need not be persisted across TPM power cycles.
16978
16979
16980
16981
16982Family “2.0” TCG Published Page 383
16983Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
16984 Part 3: Commands Trusted Platform Module Library
16985
16986
16987
1698829.3.2 Command and Response
16989
16990 Table 191 — TPM2_ClockRateAdjust Command
16991Type Name Description
16992
16993TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
16994UINT32 commandSize
16995TPM_CC commandCode TPM_CC_ClockRateAdjust
16996
16997 TPM_RH_OWNER or TPM_RH_PLATFORM+{PP}
16998TPMI_RH_PROVISION @auth Auth Handle: 1
16999 Auth Role: USER
17000
17001TPM_CLOCK_ADJUST rateAdjust Adjustment to current Clock update rate
17002
17003
17004 Table 192 — TPM2_ClockRateAdjust Response
17005Type Name Description
17006
17007TPM_ST tag see clause 6
17008UINT32 responseSize
17009TPM_RC responseCode
17010
17011
17012
17013
17014Page 384 TCG Published Family “2.0”
17015October 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
1703110 TimeSetAdjustRate(in->rateAdjust);
1703211
1703312 return TPM_RC_SUCCESS;
1703413 }
1703514 #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
1704530 Capability Commands
17046
1704730.1 Introduction
17048
17049The TPM has numerous values that indicate the state, capabilities, and properties of the TPM. These
17050values are needed for proper management of the TPM. The TPM2_GetCapability() command is used to
17051access these values.
17052TPM2_GetCapability() allows reporting of multiple values in a single call. The values are grouped
17053according to type.
17054
17055NOTE TPM2_TestParms()is used to determine if a TPM supports a particular combination of algorith m
17056 parameters
17057
17058
1705930.2 TPM2_GetCapability
17060
1706130.2.1 General Description
17062
17063This command returns various information regarding the TPM and its current state.
17064The capability parameter determines the category of data returned. The property parameter selects the
17065first value of the selected category to be returned. If there is no property that corresponds to the value of
17066property, the next higher value is returned, if it exists.
17067
17068EXAMPLE 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
17074The propertyCount parameter indicates the number of capabilities in the indicated group that are
17075requested. The TPM will return the number of requested values (propertyCount) or until the last property
17076of the requested type has been returned.
17077
17078NOTE 1 The type of the capability is determined by a combination of capability and property.
17079
17080NOTE 2 If the propertyCount selects an unimplemented property, the next higher implemented property is
17081 returned.
17082
17083When all of the properties of the requested type have been returned, the moreData parameter in the
17084response will be set to NO. Otherwise, it will be set to YES.
17085
17086NOTE 3 The moreData parameter will be YES if there are more properties even if the requested number of
17087 capabilities has been returned.
17088
17089The TPM is not required to return more than one value at a time. It is not required to provide the same
17090number of values in response to subsequent requests.
17091
17092EXAMPLE 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
17097When the TPM is in Failure mode, a TPM is required to allow use of this command for access of the
17098following capabilities:
17099
17100
17101
17102
17103Page 386 TCG Published Family “2.0”
17104October 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
17123NOTE 4 If the vendor string does not require one of these values, the property type does not need to exist.
17124
17125A vendor may optionally allow the TPM to return other values.
17126If in Failure mode and a capability is requested that is not available in Failure mode, the TPM shall return
17127no value.
17128
17129EXAMPLE 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
17136In Failure mode, tag is required to be TPM_ST_NO_SESSIONS or the TPM shall return
17137TPM_RC_FAILURE.
17138The 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
17159Family “2.0” TCG Published Page 387
17160Level 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
17219Page 388 TCG Published Family “2.0”
17220October 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.
17226The moreData parameter will have a value of YES if there are more values of the requested type that
17227were not returned.
17228If no next capability exists, the TPM will return a zero-length list and moreData will have a value of NO.
17229
17230
17231
17232
17233Family “2.0” TCG Published Page 389
17234Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
17235 Part 3: Commands Trusted Platform Module Library
17236
17237
17238
1723930.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
17268Page 390 TCG Published Family “2.0”
17269October 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
172761 #include "InternalRoutines.h"
172772 #include "GetCapability_fp.h"
172783 #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 {
1729410 // Command Output
1729511
1729612 // Set output capability type the same as input type
1729713 out->capabilityData.capability = in->capability;
1729814
1729915 switch(in->capability)
1730016 {
1730117 case TPM_CAP_ALGS:
1730218 out->moreData = AlgorithmCapGetImplemented((TPM_ALG_ID) in->property,
1730319 in->propertyCount, &out->capabilityData.data.algorithms);
1730420 break;
1730521 case TPM_CAP_HANDLES:
1730622 switch(HandleGetType((TPM_HANDLE) in->property))
1730723 {
1730824 case TPM_HT_TRANSIENT:
1730925 // Get list of handles of loaded transient objects
1731026 out->moreData = ObjectCapGetLoaded((TPM_HANDLE) in->property,
1731127 in->propertyCount,
1731228 &out->capabilityData.data.handles);
1731329 break;
1731430 case TPM_HT_PERSISTENT:
1731531 // Get list of handles of persistent objects
1731632 out->moreData = NvCapGetPersistent((TPM_HANDLE) in->property,
1731733 in->propertyCount,
1731834 &out->capabilityData.data.handles);
1731935 break;
1732036 case TPM_HT_NV_INDEX:
1732137 // Get list of defined NV index
1732238 out->moreData = NvCapGetIndex((TPM_HANDLE) in->property,
1732339 in->propertyCount,
1732440 &out->capabilityData.data.handles);
1732541 break;
1732642 case TPM_HT_LOADED_SESSION:
1732743 // Get list of handles of loaded sessions
1732844 out->moreData = SessionCapGetLoaded((TPM_HANDLE) in->property,
1732945 in->propertyCount,
1733046 &out->capabilityData.data.handles);
1733147 break;
1733248 case TPM_HT_ACTIVE_SESSION:
1733349 // Get list of handles of
1733450 out->moreData = SessionCapGetSaved((TPM_HANDLE) in->property,
1733551 in->propertyCount,
1733652 &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:
17389100 out->moreData = TPMCapGetProperties((TPM_PT) in->property,
17390101 in->propertyCount,
17391102 &out->capabilityData.data.tpmProperties);
17392103 break;
17393104 #ifdef TPM_ALG_ECC
17394105 case TPM_CAP_ECC_CURVES:
17395106 out->moreData = CryptCapGetECCCurve((TPM_ECC_CURVE ) in->property,
17396107 in->propertyCount,
17397108 &out->capabilityData.data.eccCurves);
17398109 break;
17399110 #endif // TPM_ALG_ECC
17400111 case TPM_CAP_VENDOR_PROPERTY:
17401112 // vendor property is not implemented
17402113 default:
17403114 // Unexpected TPM_CAP value
17404115 return TPM_RC_VALUE;
17405116 break;
17406117 }
17407118
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
17413119 return TPM_RC_SUCCESS;
17414120 }
17415121 #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
1742530.3 TPM2_TestParms
17426
1742730.3.1 General Description
17428
17429This command is used to check to see if specific combinations of algorithm parameters are supported.
17430The TPM will unmarshal the provided TPMT_PUBLIC_PARMS. If the parameters unmarshal correctly,
17431then the TPM will return TPM_RC_SUCCESS, indicating that the parameters are valid for the TPM. The
17432TPM will return the appropriate unmarshaling error if a parameter is not valid.
17433
17434
17435
17436
17437Page 394 TCG Published Family “2.0”
17438October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
17439 Trusted Platform Module Library Part 3: Commands
17440
17441
17442
1744330.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
17467Family “2.0” TCG Published Page 395
17468Level 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
1748410 in = NULL;
1748511
1748612 // The parameters are tested at unmarshal process. We do nothing in command
1748713 // action
1748814 return TPM_RC_SUCCESS;
1748915 }
1749016 #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
1750031 Non-volatile Storage
17501
1750231.1 Introduction
17503
17504The NV commands are used to create, update, read, and delete allocations of space in NV memory.
17505Before an Index may be used, it must be defined (TPM2_NV_DefineSpace()).
17506An Index may be modified if the proper write authorization is provided or read if the proper read
17507authorization is provided. Different controls are available for reading and writing.
17508An Index may have an Index-specific authValue and authPolicy. The authValue may be used to authorize
17509reading if TPMA_NV_AUTHREAD is SET and writing if TPMA_NV_AUTHREAD is SET. The authPolicy
17510may be used to authorize reading if TPMA_NV_POLICYREAD is SET and writing if
17511TPMA_NV_POLICYWRITE is SET.
17512For commands that have both authHandle and nvIndex parameters, authHandle can be an NV Index,
17513Platform Authorization, or Owner Authorization. If authHandle is an NV Index, it must be the same as
17514nvIndex (TPM_RC_NV_AUTHORIZATION).
17515TPMA_NV_PPREAD and TPMA_NV_PPWRITE indicate if reading or writing of the NV Index may be
17516authorized by platformAuth or platformPolicy.
17517TPMA_NV_OWNERREAD and TPMA_NV_OWNERWRITE indicate if reading or writing of the NV Index
17518may be authorized by ownerAuth or ownerPolicy.
17519If an operation on an NV index requires authorization, and the authHandle parameter is the handle of an
17520NV Index, then the nvIndex parameter must have the same value or the TPM will return
17521TPM_RC_NV_AUTHORIZATION.
17522
17523NOTE 1 This check ensures that the authorization that was provided is associated with the NV Index being
17524 authorized.
17525
17526For creating an Index, Owner Authorization may not be used if shEnable is CLEAR and Platform
17527Authorization may not be used if phEnableNV is CLEAR.
17528If an Index was defined using Platform Authorization, then that Index is not accessible when phEnableNV
17529is CLEAR. If an Index was defined using Owner Authorization, then that Index is not accessible when
17530shEnable is CLEAR.
17531For read access control, any combination of TPMA_NV_PPREAD, TPMA_NV_OWNERREAD,
17532TPMA_NV_AUTHREAD, or TPMA_NV_POLICYREAD is allowed as long as at least one is SET.
17533For write access control, any combination of TPMA_NV_PPWRITE, TPMA_NV_OWNERWRITE,
17534TPMA_NV_AUTHWRITE, or TPMA_NV_POLICYWRITE is allowed as long as at least one is SET.
17535If an Index has been defined and not written, then any operation on the NV Index that requires read
17536authorization will fail (TPM_RC_NV_INITIALIZED). This check may be made before or after other
17537authorization checks but shall be performed before checking the NV Index authValue. An authorization
17538failure due to the NV Index not having been written shall not be logged by the dictionary attack logic.
17539If TPMA_NV_CLEAR_STCLEAR is SET, then the TPMA_NV_WRITTEN will be CLEAR on each
17540TPM2_Startup(TPM_SU_CLEAR). TPMA_NV_CLEAR_STCLEAR shall not be SET if
17541TPMA_NV_COUNTER is SET.
17542The code in the “Detailed Actions” clause of each command is written to interface with an implementation-
17543dependent library that allows access to NV memory. The actions assume no specific layout of the
17544structure of the NV data.
17545Only one NV Index may be directly referenced in a command.
17546
17547NOTE 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
17551Family “2.0” TCG Published Page 397
17552Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
17553 Part 3: Commands Trusted Platform Module Library
17554
17555
1755631.2 NV Counters
17557
17558When an Index has the TPMA_NV_COUNTER attribute set, it behaves as a monotonic counter and may
17559only be updated using TPM2_NV_Increment().
17560When an NV counter is created, the TPM shall initialize the 8-octet counter value with a number that is
17561greater than any count value for any NV counter on the TPM since the time of TPM manufacture.
17562An NV counter may be defined with the TPMA_NV_ORDERLY attribute to indicate that the NV Index is
17563expected to be modified at a high frequency and that the data is only required to persist when the TPM
17564goes through an orderly shutdown process. The TPM may update the counter value in RAM and
17565occasionally update the non-volatile version of the counter. An orderly shutdown is one occasion to
17566update the non-volatile count. If the difference between the volatile and non-volatile version of the counter
17567becomes as large as MAX_ORDERLY_COUNT, this shall be another occasion for updating the non-
17568volatile count.
17569Before an NV counter can be used, the TPM shall validate that the count is not less than a previously
17570reported value. If the TPMA_NV_ORDERLY attribute is not SET, or if the TPM experienced an orderly
17571shutdown, then the count is assumed to be correct. If the TPMA_NV_ORDERLY attribute is SET, and the
17572TPM shutdown was not orderly, then the TPM shall OR MAX_ORDERLY_COUNT to the contents of the
17573non-volatile counter and set that as the current count.
17574
17575NOTE 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
17579NOTE 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
17583NOTE 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
17591Page 398 TCG Published Family “2.0”
17592October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
17593 Trusted Platform Module Library Part 3: Commands
17594
17595
1759631.3 TPM2_NV_DefineSpace
17597
1759831.3.1 General Description
17599
17600This command defines the attributes of an NV Index and causes the TPM to reserve space to hold the
17601data associated with the NV Index. If a definition already exists at the NV Index, the TPM will return
17602TPM_RC_NV_DEFINED.
17603The TPM will return TPM_RC_ATTRIBUTES if more than one of TPMA_NV_COUNTER,
17604TPMA_NV_BITS, or TPMA_NV_EXTEND is SET in publicInfo.
17605
17606NOTE 1 It is not required that any of these three attributes be set.
17607
17608The TPM shall return TPM_RC_ATTRIBUTES if TPMA_NV_WRITTEN, TPM_NV_READLOCKED, or
17609TPMA_NV_WRITELOCKED is SET.
17610If TPMA_NV_COUNTER or TPMA_NV_BITS is SET, then publicInfo→dataSize shall be set to eight (8) or
17611the TPM shall return TPM_RC_SIZE.
17612If TPMA_NV_EXTEND is SET, then publicInfo→dataSize shall match the digest size of the
17613publicInfo.nameAlg or the TPM shall return TPM_RC_SIZE.
17614If the NV Index is an ordinary Index and publicInfo→dataSize is larger than supported by the TPM
17615implementation then the TPM shall return TPM_RC_SIZE.
17616
17617NOTE 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
17621At least one of TPMA_NV_PPREAD, TPMA_NV_OWNERREAD, TPMA_NV_AUTHREAD, or
17622TPMA_NV_POLICYREAD shall be SET or the TPM shall return TPM_RC_ATTRIBUTES.
17623At least one of TPMA_NV_PPWRITE, TPMA_NV_OWNERWRITE, TPMA_NV_AUTHWRITE, or
17624TPMA_NV_POLICYWRITE shall be SET or the TPM shall return TPM_RC_ATTRIBUTES.
17625If TPMA_NV_CLEAR_STCLEAR is SET, then TPMA_NV_COUNTER shall be CLEAR or the TPM shall
17626return TPM_RC_ATTRIBUTES.
17627If platformAuth/platformPolicy is used for authorization, then TPMA_NV_PLATFORMCREATE shall be
17628SET in publicInfo. If ownerAuth/ownerPolicy is used for authorization, TPMA_NV_PLATFORMCREATE
17629shall be CLEAR in publicInfo. If TPMA_NV_PLATFORMCREATE is not set correctly for the authorization,
17630the TPM shall return TPM_RC_ATTRIBUTES.
17631If TPMA_NV_POLICY_DELETE is SET, then the authorization shall be with Platform Authorization or the
17632TPM shall return TPM_RC_ATTRIBUTES.
17633If the implementation does not support TPM2_NV_Increment(), the TPM shall return
17634TPM_RC_ATTRIBUTES if TPMA_NV_COUNTER is SET.
17635If the implementation does not support TPM2_NV_SetBits(), the TPM shall return
17636TPM_RC_ATTRIBUTES if TPMA_NV_BITS is SET.
17637If the implementation does not support TPM2_NV_Extend(), the TPM shall return
17638TPM_RC_ATTRIBUTES if TPMA_NV_EXTEND is SET.
17639If the implementation does not support TPM2_NV_UndefineSpaceSpecial(), the TPM shall return
17640TPM_RC_ATTRIBUTES if TPMA_NV_POLICY_DELETE is SET.
17641After the successful completion of this command, the NV Index exists but TPMA_NV_WRITTEN will be
17642CLEAR. Any access of the NV data will return TPM_RC_NV_UINITIALIZED.
17643
17644
17645
17646
17647Family “2.0” TCG Published Page 399
17648Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
17649 Part 3: Commands Trusted Platform Module Library
17650
17651In some implementations, an NV Index with the TPMA_NV_COUNTER attribute may require special TPM
17652resources that provide higher endurance than regular NV. For those implementations, if this command
17653fails because of lack of resources, the TPM will return TPM_RC_NV_SPACE.
17654The value of auth is saved in the created structure. The size of auth is limited to be no larger than the size
17655of the digest produced by the NV Index's nameAlg (TPM_RC_SIZE).
17656
17657
17658
17659
17660Page 400 TCG Published Family “2.0”
17661October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
17662 Trusted Platform Module Library Part 3: Commands
17663
17664
17665
1766631.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
17693Family “2.0” TCG Published Page 401
17694Level 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
177011 #include "InternalRoutines.h"
177022 #include "NV_DefineSpace_fp.h"
177033 #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;
1772310 TPMA_NV attributes;
1772411 UINT16 nameSize;
1772512
1772613 nameSize = CryptGetHashDigestSize(in->publicInfo.t.nvPublic.nameAlg);
1772714
1772815 // Check if NV is available. NvIsAvailable may return TPM_RC_NV_UNAVAILABLE
1772916 // TPM_RC_NV_RATE or TPM_RC_SUCCESS.
1773017 result = NvIsAvailable();
1773118 if(result != TPM_RC_SUCCESS)
1773219 return result;
1773320
1773421 // Input Validation
1773522 // If an index is being created by the owner and shEnable is
1773623 // clear, then we would not reach this point because ownerAuth
1773724 // can't be given when shEnable is CLEAR. However, if phEnable
1773825 // is SET but phEnableNV is CLEAR, we have to check here
1773926 if(in->authHandle == TPM_RH_PLATFORM && gc.phEnableNV == CLEAR)
1774027 return TPM_RC_HIERARCHY + RC_NV_DefineSpace_authHandle;
1774128
1774229 attributes = in->publicInfo.t.nvPublic.attributes;
1774330
1774431 //TPMS_NV_PUBLIC validation.
1774532 // Counters and bit fields must have a size of 8
1774633 if ( (attributes.TPMA_NV_COUNTER == SET || attributes.TPMA_NV_BITS == SET)
1774734 && (in->publicInfo.t.nvPublic.dataSize != 8))
1774835 return TPM_RC_SIZE + RC_NV_DefineSpace_publicInfo;
1774936
1775037 // check that the authPolicy consistent with hash algorithm
1775138 if( in->publicInfo.t.nvPublic.authPolicy.t.size != 0
1775239 && in->publicInfo.t.nvPublic.authPolicy.t.size != nameSize)
1775340 return TPM_RC_SIZE + RC_NV_DefineSpace_publicInfo;
1775441
1775542 // make sure that the authValue is not too large
1775643 MemoryRemoveTrailingZeros(&in->auth);
1775744 if(in->auth.t.size > nameSize)
1775845 return TPM_RC_SIZE + RC_NV_DefineSpace_auth;
1775946
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
17818100 if( attributes.TPMA_NV_CLEAR_STCLEAR == SET
17819101 && ( attributes.TPMA_NV_COUNTER == SET
17820102 || attributes.TPMA_NV_WRITEDEFINE == SET)
17821103 )
17822104 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo;
17823105
17824106 // Make sure that the creator of the index can delete the index
17825107 if( ( in->publicInfo.t.nvPublic.attributes.TPMA_NV_PLATFORMCREATE == SET
17826108 && in->authHandle == TPM_RH_OWNER
17827109 )
17828110 || ( in->publicInfo.t.nvPublic.attributes.TPMA_NV_PLATFORMCREATE == CLEAR
17829111 && in->authHandle == TPM_RH_PLATFORM
17830112 )
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
17836113 )
17837114 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_authHandle;
17838115
17839116 // If TPMA_NV_POLICY_DELETE is SET, then the index must be defined by
17840117 // the platform
17841118 if( in->publicInfo.t.nvPublic.attributes.TPMA_NV_POLICY_DELETE == SET
17842119 && TPM_RH_PLATFORM != in->authHandle
17843120 )
17844121 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo;
17845122
17846123 // If the NV index is used as a PCR, the data size must match the digest
17847124 // size
17848125 if( in->publicInfo.t.nvPublic.attributes.TPMA_NV_EXTEND == SET
17849126 && in->publicInfo.t.nvPublic.dataSize != nameSize
17850127 )
17851128 return TPM_RC_ATTRIBUTES + RC_NV_DefineSpace_publicInfo;
17852129
17853130 // See if the index is already defined.
17854131 if(NvIsUndefinedIndex(in->publicInfo.t.nvPublic.nvIndex))
17855132 return TPM_RC_NV_DEFINED;
17856133
17857134 // Internal Data Update
17858135 // define the space. A TPM_RC_NV_SPACE error may be returned at this point
17859136 result = NvDefineIndex(&in->publicInfo.t.nvPublic, &in->auth);
17860137 if(result != TPM_RC_SUCCESS)
17861138 return result;
17862139
17863140 return TPM_RC_SUCCESS;
17864141
17865142 }
17866143 #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
1787631.4 TPM2_NV_UndefineSpace
17877
1787831.4.1 General Description
17879
17880This command removes an Index from the TPM.
17881If nvIndex is not defined, the TPM shall return TPM_RC_HANDLE.
17882If nvIndex references an Index that has its TPMA_NV_PLATFORMCREATE attribute SET, the TPM shall
17883return TPM_RC_NV_AUTHORIZATION unless Platform Authorization is provided.
17884If nvIndex references an Index that has its TPMA_NV_POLICY_DELETE attribute SET, the TPM shall
17885return TPM_RC_ATTRIBUTES.
17886
17887NOTE 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
17894Family “2.0” TCG Published Page 405
17895Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
17896 Part 3: Commands Trusted Platform Module Library
17897
17898
1789931.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
17926Page 406 TCG Published Family “2.0”
17927October 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
179341 #include "InternalRoutines.h"
179352 #include "NV_UndefineSpace_fp.h"
179363 #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;
1795210 NV_INDEX nvIndex;
1795311
1795412 // The command needs NV update. Check if NV is available.
1795513 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
1795614 // this point
1795715 result = NvIsAvailable();
1795816 if(result != TPM_RC_SUCCESS) return result;
1795917
1796018 // Input Validation
1796119
1796220 // Get NV index info
1796321 NvGetIndexInfo(in->nvIndex, &nvIndex);
1796422
1796523 // This command can't be used to delete an index with TPMA_NV_POLICY_DELETE SET
1796624 if(SET == nvIndex.publicArea.attributes.TPMA_NV_POLICY_DELETE)
1796725 return TPM_RC_ATTRIBUTES + RC_NV_UndefineSpace_nvIndex;
1796826
1796927 // The owner may only delete an index that was defined with ownerAuth. The
1797028 // platform may delete an index that was created with either auth.
1797129 if( in->authHandle == TPM_RH_OWNER
1797230 && nvIndex.publicArea.attributes.TPMA_NV_PLATFORMCREATE == SET)
1797331 return TPM_RC_NV_AUTHORIZATION;
1797432
1797533 // Internal Data Update
1797634
1797735 // Call implementation dependent internal routine to delete NV index
1797836 NvDeleteEntity(in->nvIndex);
1797937
1798038 return TPM_RC_SUCCESS;
1798139 }
1798240 #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
1799231.5 TPM2_NV_UndefineSpaceSpecial
17993
1799431.5.1 General Description
17995
17996This command allows removal of a platform-created NV Index that has TPMA_NV_POLICY_DELETE
17997SET.
17998This command requires that the policy of the NV Index be satisfied before the NV Index may be deleted.
17999Because administrative role is required, the policy must contain a command that sets the policy command
18000code to TPM_CC_NV_UndefineSpaceSpecial. This indicates that the policy that is being used is a policy
18001that is for this command, and not a policy that would approve another use. That is, authority to use an
18002object does not grant authority to undefine the object.
18003If nvIndex is not defined, the TPM shall return TPM_RC_HANDLE.
18004If nvIndex references an Index that has its TPMA_NV_PLATFORMCREATE or
18005TPMA_NV_POLICY_DELETE attribute CLEAR, the TPM shall return TPM_RC_ATTRIBUTES.
18006
18007NOTE 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
18014Page 408 TCG Published Family “2.0”
18015October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
18016 Trusted Platform Module Library Part 3: Commands
18017
18018
1801931.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
18046Family “2.0” TCG Published Page 409
18047Level 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
180541 #include "InternalRoutines.h"
180552 #include "NV_UndefineSpaceSpecial_fp.h"
180563 #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;
1807010 NV_INDEX nvIndex;
1807111
1807212 // The command needs NV update. Check if NV is available.
1807313 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
1807414 // this point
1807515 result = NvIsAvailable();
1807616 if(result != TPM_RC_SUCCESS)
1807717 return result;
1807818
1807919 // Input Validation
1808020
1808121 // Get NV index info
1808222 NvGetIndexInfo(in->nvIndex, &nvIndex);
1808323
1808424 // This operation only applies when the TPMA_NV_POLICY_DELETE attribute is SET
1808525 if(CLEAR == nvIndex.publicArea.attributes.TPMA_NV_POLICY_DELETE)
1808626 return TPM_RC_ATTRIBUTES + RC_NV_UndefineSpaceSpecial_nvIndex;
1808727
1808828 // Internal Data Update
1808929
1809030 // Call implementation dependent internal routine to delete NV index
1809131 NvDeleteEntity(in->nvIndex);
1809232
1809333 return TPM_RC_SUCCESS;
1809434 }
1809535 #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
1810531.6 TPM2_NV_ReadPublic
18106
1810731.6.1 General Description
18108
18109This command is used to read the public area and Name of an NV Index. The public area of an Index is
18110not privacy-sensitive and no authorization is required to read this data.
18111
18112
18113
18114
18115Family “2.0” TCG Published Page 411
18116Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
18117 Part 3: Commands Trusted Platform Module Library
18118
18119
18120
1812131.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
18149Page 412 TCG Published Family “2.0”
18150October 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 {
1816610 NV_INDEX nvIndex;
1816711
1816812 // Command Output
1816913
1817014 // Get NV index info
1817115 NvGetIndexInfo(in->nvIndex, &nvIndex);
1817216
1817317 // Copy data to output
1817418 out->nvPublic.t.nvPublic = nvIndex.publicArea;
1817519
1817620 // Compute NV name
1817721 out->nvName.t.size = NvGetName(in->nvIndex, &out->nvName.t.name);
1817822
1817923 return TPM_RC_SUCCESS;
1818024 }
1818125 #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
1819131.7 TPM2_NV_Write
18192
1819331.7.1 General Description
18194
18195This command writes a value to an area in NV memory that was previously defined by
18196TPM2_NV_DefineSpace().
18197Proper authorizations are required for this command as determined by TPMA_NV_PPWRITE;
18198TPMA_NV_OWNERWRITE; TPMA_NV_AUTHWRITE; and, if TPMA_NV_POLICY_WRITE is SET, the
18199authPolicy of the NV Index.
18200If the TPMA_NV_WRITELOCKED attribute of the NV Index is SET, then the TPM shall return
18201TPM_RC_NV_LOCKED.
18202
18203NOTE 1 If authorization sessions are present, they are checked before checks to see if writes to the NV
18204 Index are locked.
18205
18206If TPMA_NV_COUNTER, TPMA_NV_BITS or TPMA_NV_EXTEND of the NV Index is SET, then the
18207TPM shall return TPM_RC_ATTRIBUTES.
18208If the size of the data parameter plus the offset parameter adds to a value that is greater than the size of
18209the NV Index data, the TPM shall return TPM_RC_NV_RANGE and not write any data to the NV Index.
18210If the TPMA_NV_WRITEALL attribute of the NV Index is SET, then the TPM shall return
18211TPM_RC_NV_RANGE if the size of the data parameter of the command is not the same as the data field
18212of the NV Index.
18213If all checks succeed, the TPM will merge the data.size octets of data.buffer value into the nvIndex→data
18214starting at nvIndex→data[offset]. If the NV memory is implemented with a technology that has endurance
18215limitations, the TPM shall check that the merged data is different from the current contents of the NV
18216Index and only perform a write to NV memory if they differ.
18217After successful completion of this command, TPMA_NV_WRITTEN for the NV Index will be SET.
18218
18219NOTE 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
18225Page 414 TCG Published Family “2.0”
18226October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
18227 Trusted Platform Module Library Part 3: Commands
18228
18229
1823031.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
18260Family “2.0” TCG Published Page 415
18261Level 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
182681 #include "InternalRoutines.h"
182692 #include "NV_Write_fp.h"
182703 #ifdef TPM_CC_NV_Write // Conditional expansion of this file
182714 #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 {
1829010 NV_INDEX nvIndex;
1829111 TPM_RC result;
1829212
1829313 // Input Validation
1829414
1829515 // Get NV index info
1829616 NvGetIndexInfo(in->nvIndex, &nvIndex);
1829717
1829818 // common access checks. NvWrtieAccessChecks() may return
1829919 // TPM_RC_NV_AUTHORIZATION or TPM_RC_NV_LOCKED
1830020 result = NvWriteAccessChecks(in->authHandle, in->nvIndex);
1830121 if(result != TPM_RC_SUCCESS)
1830222 return result;
1830323
1830424 // Bits index, extend index or counter index may not be updated by
1830525 // TPM2_NV_Write
1830626 if( nvIndex.publicArea.attributes.TPMA_NV_COUNTER == SET
1830727 || nvIndex.publicArea.attributes.TPMA_NV_BITS == SET
1830828 || nvIndex.publicArea.attributes.TPMA_NV_EXTEND == SET)
1830929 return TPM_RC_ATTRIBUTES;
1831030
1831131 // Too much data
1831232 if((in->data.t.size + in->offset) > nvIndex.publicArea.dataSize)
1831333 return TPM_RC_NV_RANGE;
1831434
1831535 // If this index requires a full sized write, make sure that input range is
1831636 // full sized
1831737 if( nvIndex.publicArea.attributes.TPMA_NV_WRITEALL == SET
1831838 && in->data.t.size < nvIndex.publicArea.dataSize)
1831939 return TPM_RC_NV_RANGE;
1832040
1832141 // Internal Data Update
1832242
1832343 // Perform the write. This called routine will SET the TPMA_NV_WRITTEN
1832444 // attribute if it has not already been SET. If NV isn't available, an error
1832545 // will be returned.
1832646 return NvWriteIndexData(in->nvIndex, &nvIndex, in->offset,
1832747 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
1833348
1833449 }
1833550 #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
1834531.8 TPM2_NV_Increment
18346
1834731.8.1 General Description
18348
18349This command is used to increment the value in an NV Index that has TPMA_NV_COUNTER SET. The
18350data value of the NV Index is incremented by one.
18351
18352NOTE 1 The NV Index counter is an unsigned value.
18353
18354If TPMA_NV_COUNTER is not SET in the indicated NV Index, the TPM shall return
18355TPM_RC_ATTRIBUTES.
18356If TPMA_NV_WRITELOCKED is SET, the TPM shall return TPM_RC_NV_LOCKED.
18357If TPMA_NV_WRITTEN is CLEAR, it will be SET.
18358If TPMA_NV_ORDERLY is SET, and the difference between the volatile and non-volatile versions of this
18359field is greater than MAX_ORDERLY_COUNT, then the non-volatile version of the counter is updated.
18360
18361NOTE 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
18365NOTE 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
18373Page 418 TCG Published Family “2.0”
18374October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
18375 Trusted Platform Module Library Part 3: Commands
18376
18377
1837831.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
18405Family “2.0” TCG Published Page 419
18406Level 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
184131 #include "InternalRoutines.h"
184142 #include "NV_Increment_fp.h"
184153 #ifdef TPM_CC_NV_Increment // Conditional expansion of this file
184164 #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 {
1843010 TPM_RC result;
1843111 NV_INDEX nvIndex;
1843212 UINT64 countValue;
1843313
1843414 // Input Validation
1843515
1843616 // Common access checks, a TPM_RC_NV_AUTHORIZATION or TPM_RC_NV_LOCKED
1843717 // error may be returned at this point
1843818 result = NvWriteAccessChecks(in->authHandle, in->nvIndex);
1843919 if(result != TPM_RC_SUCCESS)
1844020 return result;
1844121
1844222 // Get NV index info
1844323 NvGetIndexInfo(in->nvIndex, &nvIndex);
1844424
1844525 // Make sure that this is a counter
1844626 if(nvIndex.publicArea.attributes.TPMA_NV_COUNTER != SET)
1844727 return TPM_RC_ATTRIBUTES + RC_NV_Increment_nvIndex;
1844828
1844929 // Internal Data Update
1845030
1845131 // If counter index is not been written, initialize it
1845232 if(nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == CLEAR)
1845333 countValue = NvInitialCounter();
1845434 else
1845535 // Read NV data in native format for TPM CPU.
1845636 NvGetIntIndexData(in->nvIndex, &nvIndex, &countValue);
1845737
1845838 // Do the increment
1845939 countValue++;
1846040
1846141 // If this is an orderly counter that just rolled over, need to be able to
1846242 // write to NV to proceed. This check is done here, because NvWriteIndexData()
1846343 // does not see if the update is for counter rollover.
1846444 if( nvIndex.publicArea.attributes.TPMA_NV_ORDERLY == SET
1846545 && (countValue & MAX_ORDERLY_COUNT) == 0)
1846646 {
1846747 result = NvIsAvailable();
1846848 if(result != TPM_RC_SUCCESS)
1846949 return result;
1847050
1847151 // Need to force an NV update
1847252 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
1847953 }
1848054
1848155 // Write NV data back. A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may
1848256 // be returned at this point. If necessary, this function will set the
1848357 // TPMA_NV_WRITTEN attribute
1848458 return NvWriteIndexData(in->nvIndex, &nvIndex, 0, 8, &countValue);
1848559
1848660 }
1848761 #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
1849731.9 TPM2_NV_Extend
18498
1849931.9.1 General Description
18500
18501This command extends a value to an area in NV memory that was previously defined by
18502TPM2_NV_DefineSpace.
18503If TPMA_NV_EXTEND is not SET, then the TPM shall return TPM_RC_ATTRIBUTES.
18504Proper write authorizations are required for this command as determined by TPMA_NV_PPWRITE,
18505TPMA_NV_OWNERWRITE, TPMA_NV_AUTHWRITE, and the authPolicy of the NV Index.
18506After successful completion of this command, TPMA_NV_WRITTEN for the NV Index will be SET.
18507
18508NOTE 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
18511If the TPMA_NV_WRITELOCKED attribute of the NV Index is SET, then the TPM shall return
18512TPM_RC_NV_LOCKED.
18513
18514NOTE 2 If authorization sessions are present, they are checked before checks to see if writes to the NV
18515 Index are locked.
18516
18517The data.buffer parameter may be larger than the defined size of the NV Index.
18518The Index will be updated by:
18519 nvIndex→datanew ≔ HnameAkg(nvIndex→dataold || data.buffer) (39)
18520where
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
18525NOTE 3 If TPMA_NV_WRITTEN is CLEAR, then nvIndex→data is a Zero Digest.
18526
18527
18528
18529
18530Page 422 TCG Published Family “2.0”
18531October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
18532 Trusted Platform Module Library Part 3: Commands
18533
18534
1853531.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
18564Family “2.0” TCG Published Page 423
18565Level 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
185721 #include "InternalRoutines.h"
185732 #include "NV_Extend_fp.h"
185743 #ifdef TPM_CC_NV_Extend // Conditional expansion of this file
185754 #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 {
1859110 TPM_RC result;
1859211 NV_INDEX nvIndex;
1859312
1859413 TPM2B_DIGEST oldDigest;
1859514 TPM2B_DIGEST newDigest;
1859615 HASH_STATE hashState;
1859716
1859817 // Input Validation
1859918
1860019 // Common access checks, NvWriteAccessCheck() may return TPM_RC_NV_AUTHORIZATION
1860120 // or TPM_RC_NV_LOCKED
1860221 result = NvWriteAccessChecks(in->authHandle, in->nvIndex);
1860322 if(result != TPM_RC_SUCCESS)
1860423 return result;
1860524
1860625 // Get NV index info
1860726 NvGetIndexInfo(in->nvIndex, &nvIndex);
1860827
1860928 // Make sure that this is an extend index
1861029 if(nvIndex.publicArea.attributes.TPMA_NV_EXTEND != SET)
1861130 return TPM_RC_ATTRIBUTES + RC_NV_Extend_nvIndex;
1861231
1861332 // If the Index is not-orderly, or if this is the first write, NV will
1861433 // need to be updated.
1861534 if( nvIndex.publicArea.attributes.TPMA_NV_ORDERLY == CLEAR
1861635 || nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == CLEAR)
1861736 {
1861837 // Check if NV is available. NvIsAvailable may return TPM_RC_NV_UNAVAILABLE
1861938 // TPM_RC_NV_RATE or TPM_RC_SUCCESS.
1862039 result = NvIsAvailable();
1862140 if(result != TPM_RC_SUCCESS)
1862241 return result;
1862342 }
1862443
1862544 // Internal Data Update
1862645
1862746 // Perform the write.
1862847 oldDigest.t.size = CryptGetHashDigestSize(nvIndex.publicArea.nameAlg);
1862948 pAssert(oldDigest.t.size <= sizeof(oldDigest.t.buffer));
1863049 if(nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == SET)
1863150 {
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
1863751 NvGetIndexData(in->nvIndex, &nvIndex, 0,
1863852 oldDigest.t.size, oldDigest.t.buffer);
1863953 }
1864054 else
1864155 {
1864256 MemorySet(oldDigest.t.buffer, 0, oldDigest.t.size);
1864357 }
1864458 // Start hash
1864559 newDigest.t.size = CryptStartHash(nvIndex.publicArea.nameAlg, &hashState);
1864660
1864761 // Adding old digest
1864862 CryptUpdateDigest2B(&hashState, &oldDigest.b);
1864963
1865064 // Adding new data
1865165 CryptUpdateDigest2B(&hashState, &in->data.b);
1865266
1865367 // Complete hash
1865468 CryptCompleteHash2B(&hashState, &newDigest.b);
1865569
1865670 // Write extended hash back.
1865771 // Note, this routine will SET the TPMA_NV_WRITTEN attribute if necessary
1865872 return NvWriteIndexData(in->nvIndex, &nvIndex, 0,
1865973 newDigest.t.size, newDigest.t.buffer);
1866074 }
1866175 #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
1867131.10 TPM2_NV_SetBits
18672
1867331.10.1 General Description
18674
18675This command is used to SET bits in an NV Index that was created as a bit field. Any number of bits from
186760 to 64 may be SET. The contents of data are ORed with the current contents of the NV Index starting at
18677offset.
18678If TPMA_NV_WRITTEN is not SET, then, for the purposes of this command, the NV Index is considered
18679to contain all zero bits and data is OR with that value.
18680If TPMA_NV_BITS is not SET, then the TPM shall return TPM_RC_ATTRIBUTES.
18681After successful completion of this command, TPMA_NV_WRITTEN for the NV Index will be SET.
18682
18683NOTE TPMA_NV_WRITTEN will be SET even if no bits were SET.
18684
18685
18686
18687
18688Page 426 TCG Published Family “2.0”
18689October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
18690 Trusted Platform Module Library Part 3: Commands
18691
18692
1869331.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
18722Family “2.0” TCG Published Page 427
18723Level 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
187301 #include "InternalRoutines.h"
187312 #include "NV_SetBits_fp.h"
187323 #ifdef TPM_CC_NV_SetBits // Conditional expansion of this file
187334 #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 {
1874910 TPM_RC result;
1875011 NV_INDEX nvIndex;
1875112 UINT64 oldValue;
1875213 UINT64 newValue;
1875314
1875415 // Input Validation
1875516
1875617 // Common access checks, NvWriteAccessCheck() may return TPM_RC_NV_AUTHORIZATION
1875718 // or TPM_RC_NV_LOCKED
1875819 // error may be returned at this point
1875920 result = NvWriteAccessChecks(in->authHandle, in->nvIndex);
1876021 if(result != TPM_RC_SUCCESS)
1876122 return result;
1876223
1876324 // Get NV index info
1876425 NvGetIndexInfo(in->nvIndex, &nvIndex);
1876526
1876627 // Make sure that this is a bit field
1876728 if(nvIndex.publicArea.attributes.TPMA_NV_BITS != SET)
1876829 return TPM_RC_ATTRIBUTES + RC_NV_SetBits_nvIndex;
1876930
1877031 // If index is not been written, initialize it
1877132 if(nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == CLEAR)
1877233 oldValue = 0;
1877334 else
1877435 // Read index data
1877536 NvGetIntIndexData(in->nvIndex, &nvIndex, &oldValue);
1877637
1877738 // Figure out what the new value is going to be
1877839 newValue = oldValue | in->bits;
1877940
1878041 // If the Index is not-orderly and it has changed, or if this is the first
1878142 // write, NV will need to be updated.
1878243 if( ( nvIndex.publicArea.attributes.TPMA_NV_ORDERLY == CLEAR
1878344 && newValue != oldValue)
1878445 || nvIndex.publicArea.attributes.TPMA_NV_WRITTEN == CLEAR)
1878546 {
1878647
1878748 // Internal Data Update
1878849 // Check if NV is available. NvIsAvailable may return TPM_RC_NV_UNAVAILABLE
1878950 // 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
1879551 result = NvIsAvailable();
1879652 if(result != TPM_RC_SUCCESS)
1879753 return result;
1879854
1879955 // Write index data back. If necessary, this function will SET
1880056 // TPMA_NV_WRITTEN.
1880157 result = NvWriteIndexData(in->nvIndex, &nvIndex, 0, 8, &newValue);
1880258 }
1880359 return result;
1880460
1880561 }
1880662 #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
1881631.11 TPM2_NV_WriteLock
18817
1881831.11.1 General Description
18819
18820If the TPMA_NV_WRITEDEFINE or TPMA_NV_WRITE_STCLEAR attributes of an NV location are SET,
18821then this command may be used to inhibit further writes of the NV Index.
18822Proper write authorization is required for this command as determined by TPMA_NV_PPWRITE,
18823TPMA_NV_OWNERWRITE, TPMA_NV_AUTHWRITE, and the authPolicy of the NV Index.
18824It is not an error if TPMA_NV_WRITELOCKED for the NV Index is already SET.
18825If neither TPMA_NV_WRITEDEFINE nor TPMA_NV_WRITE_STCLEAR of the NV Index is SET, then the
18826TPM shall return TPM_RC_ATTRIBUTES.
18827If the command is properly authorized and TPMA_NV_WRITE_STCLEAR or TPMA_NV_WRITEDEFINE
18828is SET, then the TPM shall SET TPMA_NV_WRITELOCKED for the NV Index.
18829TPMA_NV_WRITELOCKED will be clear on the next TPM2_Startup(TPM_SU_CLEAR) unless
18830TPMA_NV_WRITEDEFINE is SET or if TPM_NV_WRITTEN is CLEAR.
18831
18832
18833
18834
18835Page 430 TCG Published Family “2.0”
18836October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
18837 Trusted Platform Module Library Part 3: Commands
18838
18839
18840
1884131.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
18868Family “2.0” TCG Published Page 431
18869Level 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
188761 #include "InternalRoutines.h"
188772 #include "NV_WriteLock_fp.h"
188783 #ifdef TPM_CC_NV_WriteLock // Conditional expansion of this file
188794 #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 {
1889510 TPM_RC result;
1889611 NV_INDEX nvIndex;
1889712
1889813 // Input Validation:
1889914
1890015 // Common write access checks, a TPM_RC_NV_AUTHORIZATION or TPM_RC_NV_LOCKED
1890116 // error may be returned at this point
1890217 result = NvWriteAccessChecks(in->authHandle, in->nvIndex);
1890318 if(result != TPM_RC_SUCCESS)
1890419 {
1890520 if(result == TPM_RC_NV_AUTHORIZATION)
1890621 return TPM_RC_NV_AUTHORIZATION;
1890722 // If write access failed because the index is already locked, then it is
1890823 // no error.
1890924 return TPM_RC_SUCCESS;
1891025 }
1891126
1891227 // Get NV index info
1891328 NvGetIndexInfo(in->nvIndex, &nvIndex);
1891429
1891530 // if neither TPMA_NV_WRITEDEFINE nor TPMA_NV_WRITE_STCLEAR is set, the index
1891631 // can not be write-locked
1891732 if( nvIndex.publicArea.attributes.TPMA_NV_WRITEDEFINE == CLEAR
1891833 && nvIndex.publicArea.attributes.TPMA_NV_WRITE_STCLEAR == CLEAR)
1891934 return TPM_RC_ATTRIBUTES + RC_NV_WriteLock_nvIndex;
1892035
1892136 // Internal Data Update
1892237
1892338 // The command needs NV update. Check if NV is available.
1892439 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
1892540 // this point
1892641 result = NvIsAvailable();
1892742 if(result != TPM_RC_SUCCESS)
1892843 return result;
1892944
1893045 // Set the WRITELOCK attribute.
1893146 // Note: if TPMA_NV_WRITELOCKED were already SET, then the write access check
1893247 // above would have failed and this code isn't executed.
1893348 nvIndex.publicArea.attributes.TPMA_NV_WRITELOCKED = SET;
1893449
1893550 // Write index info back
1893651 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
1894252
1894353 return TPM_RC_SUCCESS;
1894454 }
1894555 #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
1895531.12 TPM2_NV_GlobalWriteLock
18956
1895731.12.1 General Description
18958
18959The command will SET TPMA_NV_WRITELOCKED for all indexes that have their
18960TPMA_NV_GLOBALLOCK attribute SET.
18961If an Index has both TPMA_NV_WRITELOCKED and TPMA_NV_WRITEDEFINE SET, then this
18962command will permanently lock the NV Index for writing unless TPMA_NV_WRITTEN is CLEAR.
18963
18964NOTE 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
18967This command requires either platformAuth/platformPolicy or ownerAuth/ownerPolicy.
18968
18969
18970
18971
18972Page 434 TCG Published Family “2.0”
18973October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
18974 Trusted Platform Module Library Part 3: Commands
18975
18976
18977
1897831.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
19001Family “2.0” TCG Published Page 435
19002Level 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;
1901810
1901911 // Input parameter is not reference in command action
1902012 in = NULL; // to silence compiler warnings.
1902113
1902214 // The command needs NV update. Check if NV is available.
1902315 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
1902416 // this point
1902517 result = NvIsAvailable();
1902618 if(result != TPM_RC_SUCCESS)
1902719 return result;
1902820
1902921 // Internal Data Update
1903022
1903123 // Implementation dependent method of setting the global lock
1903224 NvSetGlobalLock();
1903325
1903426 return TPM_RC_SUCCESS;
1903527 }
1903628 #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
1904631.13 TPM2_NV_Read
19047
1904831.13.1 General Description
19049
19050This command reads a value from an area in NV memory previously defined by
19051TPM2_NV_DefineSpace().
19052Proper authorizations are required for this command as determined by TPMA_NV_PPREAD,
19053TPMA_NV_OWNERREAD, TPMA_NV_AUTHREAD, and the authPolicy of the NV Index.
19054If TPMA_NV_READLOCKED of the NV Index is SET, then the TPM shall return TPM_RC_NV_LOCKED.
19055
19056NOTE If authorization sessions are present, they are checked before the read -lock status of the NV Index
19057 is checked.
19058
19059If the size parameter plus the offset parameter adds to a value that is greater than the size of the NV
19060Index data area, the TPM shall return TPM_RC_NV_RANGE and not read any data from the NV Index.
19061If the NV Index has been defined but the TPMA_NV_WRITTEN attribute is CLEAR, then this command
19062shall return TPM_RC_NV_UINITIALIZED even if size is zero.
19063The data parameter in the response may be encrypted using parameter encryption.
19064
19065
19066
19067
19068Family “2.0” TCG Published Page 437
19069Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
19070 Part 3: Commands Trusted Platform Module Library
19071
19072
19073
1907431.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
19110Page 438 TCG Published Family “2.0”
19111October 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
191181 #include "InternalRoutines.h"
191192 #include "NV_Read_fp.h"
191203 #ifdef TPM_CC_NV_Read // Conditional expansion of this file
191214 #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 )
1913810 {
1913911 NV_INDEX nvIndex;
1914012 TPM_RC result;
1914113
1914214 // Input Validation
1914315
1914416 // Get NV index info
1914517 NvGetIndexInfo(in->nvIndex, &nvIndex);
1914618
1914719 // Common read access checks. NvReadAccessChecks() returns
1914820 // TPM_RC_NV_AUTHORIZATION, TPM_RC_NV_LOCKED, or TPM_RC_NV_UNINITIALIZED
1914921 // error may be returned at this point
1915022 result = NvReadAccessChecks(in->authHandle, in->nvIndex);
1915123 if(result != TPM_RC_SUCCESS)
1915224 return result;
1915325
1915426 // Too much data
1915527 if((in->size + in->offset) > nvIndex.publicArea.dataSize)
1915628 return TPM_RC_NV_RANGE;
1915729
1915830 // Command Output
1915931
1916032 // Set the return size
1916133 out->data.t.size = in->size;
1916234 // Perform the read
1916335 NvGetIndexData(in->nvIndex, &nvIndex, in->offset, in->size, out->data.t.buffer);
1916436
1916537 return TPM_RC_SUCCESS;
1916638 }
1916739 #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
1917731.14 TPM2_NV_ReadLock
19178
1917931.14.1 General Description
19180
19181If TPMA_NV_READ_STCLEAR is SET in an Index, then this command may be used to prevent further
19182reads of the NV Index until the next TPM2_Startup (TPM_SU_CLEAR).
19183Proper authorizations are required for this command as determined by TPMA_NV_PPREAD,
19184TPMA_NV_OWNERREAD, TPMA_NV_AUTHREAD, and the authPolicy of the NV Index.
19185
19186NOTE Only an entity that may read an Index is allowed to lock the NV Index for read.
19187
19188If the command is properly authorized and TPMA_NV_READ_STCLEAR of the NV Index is SET, then the
19189TPM shall SET TPMA_NV_READLOCKED for the NV Index. If TPMA_NV_READ_STCLEAR of the NV
19190Index is CLEAR, then the TPM shall return TPM_RC_ATTRIBUTES. TPMA_NV_READLOCKED will be
19191CLEAR by the next TPM2_Startup(TPM_SU_CLEAR).
19192It is not an error to use this command for an Index that is already locked for reading.
19193An Index that had not been written may be locked for reading.
19194
19195
19196
19197
19198Page 440 TCG Published Family “2.0”
19199October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
19200 Trusted Platform Module Library Part 3: Commands
19201
19202
19203
1920431.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
19233Family “2.0” TCG Published Page 441
19234Level 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
192411 #include "InternalRoutines.h"
192422 #include "NV_ReadLock_fp.h"
192433 #ifdef TPM_CC_NV_ReadLock // Conditional expansion of this file
192444 #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 {
1925910 TPM_RC result;
1926011 NV_INDEX nvIndex;
1926112
1926213 // The command needs NV update. Check if NV is available.
1926314 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
1926415 // this point
1926516 result = NvIsAvailable();
1926617 if(result != TPM_RC_SUCCESS) return result;
1926718
1926819 // Input Validation
1926920
1927021 // Common read access checks. NvReadAccessChecks() returns
1927122 // TPM_RC_NV_AUTHORIZATION, TPM_RC_NV_LOCKED, or TPM_RC_NV_UNINITIALIZED
1927223 // error may be returned at this point
1927324 result = NvReadAccessChecks(in->authHandle, in->nvIndex);
1927425 if(result != TPM_RC_SUCCESS)
1927526 {
1927627 if(result == TPM_RC_NV_AUTHORIZATION)
1927728 return TPM_RC_NV_AUTHORIZATION;
1927829 // Index is already locked for write
1927930 else if(result == TPM_RC_NV_LOCKED)
1928031 return TPM_RC_SUCCESS;
1928132
1928233 // If NvReadAccessChecks return TPM_RC_NV_UNINITALIZED, then continue.
1928334 // It is not an error to read lock an uninitialized Index.
1928435 }
1928536
1928637 // Get NV index info
1928738 NvGetIndexInfo(in->nvIndex, &nvIndex);
1928839
1928940 // if TPMA_NV_READ_STCLEAR is not set, the index can not be read-locked
1929041 if(nvIndex.publicArea.attributes.TPMA_NV_READ_STCLEAR == CLEAR)
1929142 return TPM_RC_ATTRIBUTES + RC_NV_ReadLock_nvIndex;
1929243
1929344 // Internal Data Update
1929445
1929546 // Set the READLOCK attribute
1929647 nvIndex.publicArea.attributes.TPMA_NV_READLOCKED = SET;
1929748 // Write NV info back
1929849 NvWriteIndexInfo(in->nvIndex, &nvIndex);
1929950
1930051 return TPM_RC_SUCCESS;
1930152 }
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
1930753 #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
1931731.15 TPM2_NV_ChangeAuth
19318
1931931.15.1 General Description
19320
19321This command allows the authorization secret for an NV Index to be changed.
19322If successful, the authorization secret (authValue) of the NV Index associated with nvIndex is changed.
19323This command requires that a policy session be used for authorization of nvIndex so that the ADMIN role
19324may be asserted and that commandCode in the policy session context shall be
19325TPM_CC_NV_ChangeAuth. That is, the policy must contain a specific authorization for changing the
19326authorization value of the referenced object.
19327
19328NOTE 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
19331The size of the newAuth value may be no larger than the size of authorization indicated when the NV
19332Index was defined.
19333Since the NV Index authorization is changed before the response HMAC is calculated, the newAuth value
19334is used when generating the response HMAC key if required. See TPM 2.0 Part 4
19335ComputeResponseHMAC().
19336
19337
19338
19339
19340Page 444 TCG Published Family “2.0”
19341October 30, 2014 Copyright © TCG 2006-2014 Level 00 Revision 01.16
19342 Trusted Platform Module Library Part 3: Commands
19343
19344
19345
1934631.15.2 Command and Response
19347
19348 Table 221 — TPM2_NV_ChangeAuth Command
19349Type Name Description
19350
19351TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
19352UINT32 commandSize
19353TPM_CC commandCode TPM_CC_NV_ChangeAuth {NV}
19354
19355 handle of the object
19356TPMI_RH_NV_INDEX @nvIndex Auth Index: 1
19357 Auth Role: ADMIN
19358
19359TPM2B_AUTH newAuth new authorization value
19360
19361
19362 Table 222 — TPM2_NV_ChangeAuth Response
19363Type Name Description
19364
19365TPM_ST tag see clause 6
19366UINT32 responseSize
19367TPM_RC responseCode
19368
19369
19370
19371
19372Family “2.0” TCG Published Page 445
19373Level 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
193801 #include "InternalRoutines.h"
193812 #include "NV_ChangeAuth_fp.h"
193823 #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;
1939610 NV_INDEX nvIndex;
1939711
1939812 // Input Validation
1939913 // Check if NV is available. NvIsAvailable may return TPM_RC_NV_UNAVAILABLE
1940014 // TPM_RC_NV_RATE or TPM_RC_SUCCESS.
1940115 result = NvIsAvailable();
1940216 if(result != TPM_RC_SUCCESS) return result;
1940317
1940418 // Read index info from NV
1940519 NvGetIndexInfo(in->nvIndex, &nvIndex);
1940620
1940721 // Remove any trailing zeros that might have been added by the caller
1940822 // to obfuscate the size.
1940923 MemoryRemoveTrailingZeros(&(in->newAuth));
1941024
1941125 // Make sure that the authValue is no larger than the nameAlg of the Index
1941226 if(in->newAuth.t.size > CryptGetHashDigestSize(nvIndex.publicArea.nameAlg))
1941327 return TPM_RC_SIZE + RC_NV_ChangeAuth_newAuth;
1941428
1941529 // Internal Data Update
1941630 // Change auth
1941731 nvIndex.authValue = in->newAuth;
1941832 // Write index info back to NV
1941933 NvWriteIndexInfo(in->nvIndex, &nvIndex);
1942034
1942135 return TPM_RC_SUCCESS;
1942236 }
1942337 #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
1943331.16 TPM2_NV_Certify
19434
1943531.16.1 General Description
19436
19437The purpose of this command is to certify the contents of an NV Index or portion of an NV Index.
19438If proper authorization for reading the NV Index is provided, the portion of the NV Index selected by size
19439and offset are included in an attestation block and signed using the key indicated by signHandle. The
19440attestation also includes size and offset so that the range of the data can be determined.
19441
19442NOTE 1 See 18.1 for description of how the signing scheme is selected.
19443
19444NOTE 2 If signHandle is TPM_RH_NULL, the TPMS_ATTEST structure is returned and signature is a NULL
19445 Signature.
19446
19447
19448
19449
19450Family “2.0” TCG Published Page 447
19451Level 00 Revision 01.16 Copyright © TCG 2006-2014 October 30, 2014
19452 Part 3: Commands Trusted Platform Module Library
19453
19454
1945531.16.2 Command and Response
19456
19457 Table 223 — TPM2_NV_Certify Command
19458Type Name Description
19459
19460TPMI_ST_COMMAND_TAG tag TPM_ST_SESSIONS
19461UINT32 commandSize
19462TPM_CC commandCode TPM_CC_NV_Certify
19463
19464 handle of the key used to sign the attestation structure
19465TPMI_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
19476TPM2B_DATA qualifyingData user-provided qualifying data
19477 signing scheme to use if the scheme for signHandle is
19478TPMT_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
19487Type Name Description
19488
19489TPM_ST tag see clause 6
19490UINT32 responseSize
19491TPM_RC responseCode .
19492
19493TPM2B_ATTEST certifyInfo the structure that was signed
19494 the asymmetric signature over certifyInfo using the key
19495TPMT_SIGNATURE signature
19496 referenced by signHandle
19497
19498
19499
19500
19501Page 448 TCG Published Family “2.0”
19502October 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
195091 #include "InternalRoutines.h"
195102 #include "Attest_spt_fp.h"
195113 #include "NV_spt_fp.h"
195124 #include "NV_Certify_fp.h"
195135 #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
1953110 )
1953211 {
1953312 TPM_RC result;
1953413 NV_INDEX nvIndex;
1953514 TPMS_ATTEST certifyInfo;
1953615
1953716 // Attestation command may cause the orderlyState to be cleared due to
1953817 // the reporting of clock info. If this is the case, check if NV is
1953918 // available first
1954019 if(gp.orderlyState != SHUTDOWN_NONE)
1954120 {
1954221 // The command needs NV update. Check if NV is available.
1954322 // A TPM_RC_NV_UNAVAILABLE or TPM_RC_NV_RATE error may be returned at
1954423 // this point
1954524 result = NvIsAvailable();
1954625 if(result != TPM_RC_SUCCESS)
1954726 return result;
1954827 }
1954928
1955029 // Input Validation
1955130
1955231 // Get NV index info
1955332 NvGetIndexInfo(in->nvIndex, &nvIndex);
1955433
1955534 // Common access checks. A TPM_RC_NV_AUTHORIZATION or TPM_RC_NV_LOCKED
1955635 // error may be returned at this point
1955736 result = NvReadAccessChecks(in->authHandle, in->nvIndex);
1955837 if(result != TPM_RC_SUCCESS)
1955938 return result;
1956039
1956140 // See if the range to be certified is out of the bounds of the defined
1956241 // Index
1956342 if((in->size + in->offset) > nvIndex.publicArea.dataSize)
1956443 return TPM_RC_NV_RANGE;
1956544
1956645 // 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
19626100 return TPM_RC_SUCCESS;
19627101 }
19628102 #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