Debian Codegraph @

stubdom/vtpmmgr/vtpm_manager.h

raw
1 /*
2 * Copyright (c) 2010-2012 United States Government, as represented by
3 * the Secretary of Defense. All rights reserved.
4 *
5 * based off of the original tools/vtpm_manager code base which is:
6 * Copyright (c) 2005, Intel Corp.
7 * All rights reserved.
8 *
9 * Redistribution and use in source and binary forms, with or without
10 * modification, are permitted provided that the following conditions
11 * are met:
12 *
13 * * Redistributions of source code must retain the above copyright
14 * notice, this list of conditions and the following disclaimer.
15 * * Redistributions in binary form must reproduce the above
16 * copyright notice, this list of conditions and the following
17 * disclaimer in the documentation and/or other materials provided
18 * with the distribution.
19 * * Neither the name of Intel Corporation nor the names of its
20 * contributors may be used to endorse or promote products derived
21 * from this software without specific prior written permission.
22 *
23 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
24 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
25 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
26 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
27 * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
28 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
29 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
30 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
31 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
32 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
33 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
34 * OF THE POSSIBILITY OF SUCH DAMAGE.
35 */
36
37 #ifndef VTPM_MANAGER_H
38 #define VTPM_MANAGER_H
39
40 #define VTPM_TAG_REQ 0x01c1
41 #define VTPM_TAG_REQ2 0x01c2
42 #define VTPM_TAG_RSP 0x01c4
43 #define VTPM_TAG_RSP2 0x01c5
44 #define COMMAND_BUFFER_SIZE 4096
45
46 // Header size
47 #define VTPM_COMMAND_HEADER_SIZE ( 2 + 4 + 4)
48
49 //************************ Command Params ***************************
50 #define VTPM_QUOTE_FLAGS_HASH_UUID 0x00000001
51 #define VTPM_QUOTE_FLAGS_VTPM_MEASUREMENTS 0x00000002
52 #define VTPM_QUOTE_FLAGS_GROUP_INFO 0x00000004
53 #define VTPM_QUOTE_FLAGS_GROUP_PUBKEY 0x00000008
54
55 //************************ Command Codes ****************************
56 #define VTPM_ORD_BASE 0x0000
57 #define TPM_VENDOR_COMMAND 0x02000000 // TPM Main, part 2, section 17.
58 #define VTPM_PRIV_BASE (VTPM_ORD_BASE | TPM_VENDOR_COMMAND)
59
60 /*
61 * Non-priviledged VTPM Commands:
62 *
63 * The PCRs available to read, extend, or quote may be limited to a given vTPM
64 * based on a local security policy (this is not yet implemented).
65 *
66 * vTPMs may request the following commands which will be forwarded directly to
67 * the physical TPM:
68 *
69 * TPM_ORD_GetRandom
70 * TPM_ORD_PcrRead
71 * TPM_ORD_Extend
72 *
73 * In addition, the following command are available to all vTPMs:
74 */
75
76 /**
77 * Store a persistent key blob to TPM Manager storage
78 * Input:
79 * TPM_TAG tag VTPM_TAG_REQ
80 * UINT32 paramSize total size
81 * UINT32 ordinal VTPM_ORD_SAVEHASHKEY
82 * BYTE[] keyblob 52 or 64 bytes of key data
83 * Output:
84 * TPM_TAG tag VTPM_TAG_RSP
85 * UINT32 paramSize total size
86 * UINT32 status return code
87 */
88 #define VTPM_ORD_SAVEHASHKEY (VTPM_ORD_BASE + 1)
89 /**
90 * Load the persistent key blob from TPM Manager storage
91 * Input:
92 * TPM_TAG tag VTPM_TAG_REQ
93 * UINT32 paramSize total size
94 * UINT32 ordinal VTPM_ORD_LOADHASHKEY
95 * Output:
96 * TPM_TAG tag VTPM_TAG_RSP
97 * UINT32 paramSize total size
98 * UINT32 status return code
99 * BYTE[] keyblob 52 or 64 bytes of key data
100 */
101 #define VTPM_ORD_LOADHASHKEY (VTPM_ORD_BASE + 2)
102 /**
103 * Get a kernel hash of the control domain for this vTPM
104 * Input:
105 * TPM_TAG tag VTPM_TAG_REQ
106 * UINT32 paramSize total size
107 * UINT32 ordinal VTPM_ORD_GET_BOOT_HASH
108 * Output:
109 * TPM_TAG tag VTPM_TAG_RSP
110 * UINT32 paramSize total size
111 * UINT32 status return code
112 * TPM_DIGEST digest hash for the initial extend of PCR0
113 */
114 #define VTPM_ORD_GET_BOOT_HASH (VTPM_ORD_BASE + 3)
115 /**
116 * Get a hardware TPM quote for this vTPM. The quote will use the AIK
117 * associated with the group this vTPM was created in. Values specific to the
118 * vTPM will be extended to certain resettable PCRs.
119 * Additional info can be included when creating the signature by using
120 * quoteSelect as PCR selection and by setting flags param. The externData
121 * param for TPM_Quote is calculated as:
122 * externData = SHA1 (
123 * extraInfoFlags
124 * requestData
125 * [SHA1 (
126 * [SHA1 (UUIDs if requested)]
127 * [SHA1 (vTPM measurements if requested)]
128 * [SHA1 (vTPM group update policy if requested)]
129 * [SHA1 (vTPM group public key if requested)]
130 * ) if flags !=0 ]
131 * )
132 * The response param pcrValues is an array containing requested hashes used
133 * for externData calculation : UUIDs, vTPM measurements, vTPM group update
134 * policy, group public key. At the end of these hashes the PCR values are
135 * appended.
136 *
137 * Input:
138 * TPM_TAG tag VTPM_TAG_REQ
139 * UINT32 paramSize total size
140 * UINT32 ordinal VTPM_ORD_GET_QUOTE
141 * TPM_NONCE externData Data to be quoted
142 * PCR_SELECTION quoteSelect PCR selection for quote.
143 * UINT32 flags Bit mask of VTPM_QUOTE_FLAGS_*
144 * Output:
145 * TPM_TAG tag VTPM_TAG_RSP
146 * UINT32 paramSize total size
147 * UINT32 status return code
148 * BYTE[] signature 256 bytes of signature data
149 * TPM_PCRVALUE[] pcrValues Values of additional SHA1 hashes requested,
150 * concatenated with PCRs selected by the request
151 */
152 #define VTPM_ORD_GET_QUOTE (VTPM_ORD_BASE + 4)
153
154 /*
155 * Resettable PCR values in TPM Manager quotes (VTPM_ORD_GET_QUOTE):
156 *
157 * PCR#16:
158 * unused - debug PCR
159 *
160 * PCR#17-19: (cannot be reset by locality 2)
161 * DRTM measurements
162 *
163 * PCR#20: Remains constant over the life of the vTPM group
164 * SHA1(SAA pubkey)
165 *
166 * PCR#21: May change during the life; must be approved by SAA
167 * SHA1(TPM_MGR_CFG_LIST)
168 *
169 * PCR#22: May change during the life; must be in the cfg_list
170 * vTPM kernel build hash (truncated SHA256)
171 * Note: this is currently set to 20 zero bytes
172 *
173 * PCR#23: Remains constant over the life of the vTPM; system-specific
174 * group UUID || 00 00 00 00
175 * vTPM UUID || 00 00 00 00
176 *
177 *
178 * Group-only PCR values (VTPM_ORD_GROUP_*) are the same except:
179 *
180 * PCR#22: unused (value is zero)
181 * PCR#23:
182 * group UUID || 00 00 00 00
183 *
184 * The value of externalData for quotes using these PCRs is defined below; it is
185 * always a hash whose first 4 bytes identify the rest of the structure.
186 *
187 *
188 * The configuration list signed by a System Approval Agent (SAA) is:
189 *
190 * TPM_MGR_CFG_LIST:
191 * UINT64 sequence Monotonic sequence number
192 * UINT32 pltCfgSize Size of pltCfgs array
193 * TPM_COMPOSITE_HASH[] pltCfgs Valid platform configurations
194 * UINT32 kernSize Size of kernList array
195 * TPM_HASH[] kernList Valid vTPM kernels
196 */
197
198 /************************************\
199 * TPM Manager Management Interface *
200 \************************************/
201
202 /**
203 * List groups
204 *
205 * Input:
206 * TPM_TAG tag VTPM_TAG_REQ2
207 * UINT32 paramSize total size
208 * UINT32 ordinal VTPM_ORD_GROUP_LIST
209 * Output:
210 * TPM_TAG tag VTPM_TAG_RSP
211 * UINT32 paramSize total size
212 * UINT32 status return code
213 * UINT32 count number of valid groups
214 */
215 #define VTPM_ORD_GROUP_LIST (VTPM_PRIV_BASE + 0x101)
216 /**
217 * Create a group
218 *
219 * Input:
220 * TPM_TAG tag VTPM_TAG_REQ2
221 * UINT32 paramSize total size
222 * UINT32 ordinal VTPM_ORD_GROUP_NEW
223 * TPM_CHOSENID_HASH labelDigest Data for the privacy CA
224 * BYTE[256] SAASigKey RSA public signature key for the SAA
225 * Output:
226 * TPM_TAG tag VTPM_TAG_RSP
227 * UINT32 paramSize total size
228 * UINT32 status return code
229 * BYTE[16] groupUUID UUID for the group
230 * BYTE[256] aikPubKey Public key of the AIK
231 * BYTE[256] aikBinding TPM_IDENTITY_CONTENTS signature
232 */
233 #define VTPM_ORD_GROUP_NEW (VTPM_PRIV_BASE + 0x102)
234 /**
235 * Delete a group
236 *
237 * Input:
238 * TPM_TAG tag VTPM_TAG_REQ2
239 * UINT32 paramSize total size
240 * UINT32 ordinal VTPM_ORD_GROUP_DEL
241 * UINT32 groupID ID of the group to delete
242 * Output:
243 * TPM_TAG tag VTPM_TAG_RSP
244 * UINT32 paramSize total size
245 * UINT32 status return code
246 */
247 #define VTPM_ORD_GROUP_DEL (VTPM_PRIV_BASE + 0x103)
248 /**
249 * Activate the group's AIK (message from privacy CA)
250 *
251 * Input:
252 * TPM_TAG tag VTPM_TAG_REQ2
253 * UINT32 paramSize total size
254 * UINT32 ordinal VTPM_ORD_GROUP_ACTIVATE
255 * UINT32 groupID ID of the group to activate
256 * UINT32 blobSize
257 * BYTE[] blob Blob from the privay CA
258 * Output:
259 * TPM_TAG tag VTPM_TAG_RSP
260 * UINT32 paramSize total size
261 * UINT32 status return code
262 * TPM_SYMMETRIC_KEY key Output from TPM_ActivateIdentity
263 */
264 #define VTPM_ORD_GROUP_ACTIVATE (VTPM_PRIV_BASE + 0x104)
265 /**
266 * Register this TPM manager slot with the SAA and provision its recovery data.
267 * The initial registration must be done with no reboots between the creation of
268 * the group and the execution of this command; it can only be done once.
269 *
270 * The ExternalData value is SHA1("REGR" || dhkx_1 || dhkx_2 || recoverBlob)
271 *
272 * Input:
273 * TPM_TAG tag VTPM_TAG_REQ2
274 * UINT32 paramSize total size
275 * UINT32 ordinal VTPM_ORD_GROUP_REGISTER
276 * UINT32 groupID ID of the group to register
277 * BYTE[256] dhkx_1 One half of a diffie-hellman key exchange
278 * BYTE[256] SAAProof Signature (using SAASigKey) of derivData
279 * PCR_SELECTION quoteSelect PCR selection for quote.
280 * Output:
281 * TPM_TAG tag VTPM_TAG_RSP
282 * UINT32 paramSize total size
283 * UINT32 status return code
284 * BYTE[256] dhkx_2 One half of a diffie-hellman key exchange
285 * BYTE[32] recoverBlob Encrypted blob (using key derived from DH)
286 * BYTE[256] regProof Quote using the group's AIK
287 */
288 #define VTPM_ORD_GROUP_REGISTER (VTPM_PRIV_BASE + 0x105)
289 /**
290 * Update the configuration list
291 *
292 * Input:
293 * TPM_TAG tag VTPM_TAG_REQ2
294 * UINT32 paramSize total size
295 * UINT32 ordinal VTPM_ORD_GROUP_UPDATE
296 * UINT32 groupID ID of the group to update
297 * BYTE[256] cfgListSig Signature (using SAASigKey) of cfgList
298 * TPM_MGR_CFG_LIST cfgList Configurations the group is valid in
299 * PCR_SELECTION[] selForCfgs PCR selections used in the cfgList.pltCfgs
300 * Output:
301 * TPM_TAG tag VTPM_TAG_RSP
302 * UINT32 paramSize total size
303 * UINT32 status return code
304 */
305 #define VTPM_ORD_GROUP_UPDATE (VTPM_PRIV_BASE + 0x106)
306 /**
307 * Get the current contents of the group structure.
308 *
309 * Input:
310 * TPM_TAG tag VTPM_TAG_REQ2
311 * UINT32 paramSize total size
312 * UINT32 ordinal VTPM_ORD_GROUP_SHOW
313 * UINT32 groupID ID of the group to view
314 * Output:
315 * TPM_TAG tag VTPM_TAG_RSP
316 * UINT32 paramSize total size
317 * UINT32 status return code
318 * BYTE[16] groupUUID UUID for the group
319 * BYTE[256] pubkey public key of the SAA
320 * TPM_MGR_CFG_LIST cfgList current list for this group
321 */
322 #define VTPM_ORD_GROUP_SHOW (VTPM_PRIV_BASE + 0x107)
323 /**
324 * Get a quote of the current status of the TMA structure. This can be used to
325 * prove that an update has been applied; it is similar to VTPM_ORD_GET_QUOTE,
326 * but does not include measurements specific to any vTPM.
327 *
328 * The ExternalData value for the quote is SHA1("SHOW" || nonce)
329 *
330 * Input:
331 * TPM_TAG tag VTPM_TAG_REQ2
332 * UINT32 paramSize total size
333 * UINT32 ordinal VTPM_ORD_GROUP_QUOTE
334 * UINT32 groupID ID of the group to view
335 * TPM_NONCE nonce Anti-replay
336 * PCR_SELECTION quoteSelect PCR selection for quote.
337 * Output:
338 * TPM_TAG tag VTPM_TAG_RSP
339 * UINT32 paramSize total size
340 * UINT32 status return code
341 * BYTE[] signature 256 bytes of signature data
342 * TPM_PCRVALUE[] pcrValues Values of PCRs selected by the request
343 */
344 #define VTPM_ORD_GROUP_QUOTE (VTPM_PRIV_BASE + 0x108)
345 /**
346 * Prepare to use recovery data to open a currently-closed group.
347 *
348 * The ExternalData value is SHA1("RCVR" || nonce || dhkx_1)
349 *
350 * Input:
351 * TPM_TAG tag VTPM_TAG_REQ2
352 * UINT32 paramSize total size
353 * UINT32 ordinal VTPM_ORD_GROUP_RECOVER1
354 * UINT32 groupID ID of the group to recover
355 * TPM_KEY proxyAIK AIK to use for recovery quote
356 * TPM_NONCE nonce Anti-replay by challenger
357 * PCR_SELECTION quoteSelect PCR selection for quote
358 * Output:
359 * TPM_TAG tag VTPM_TAG_RSP
360 * UINT32 paramSize total size
361 * UINT32 status return code
362 * BYTE[256] dhkx_1 One half of a diffie-hellman key exchange
363 * BYTE[256] signature quote using proxyAIK
364 */
365 #define VTPM_ORD_GROUP_RECOVER1 (VTPM_PRIV_BASE + 0x109)
366 /**
367 * Use recovery data to open a currently-closed group
368 *
369 * Input:
370 * TPM_TAG tag VTPM_TAG_REQ2
371 * UINT32 paramSize total size
372 * UINT32 ordinal VTPM_ORD_GROUP_RECOVER2
373 * UINT32 groupID ID of the group to recover
374 * BYTE[256] dhkx_2 One half of a diffie-hellman key exchange
375 * BYTE[32] recoverBlob Encrypted blob (using key derived from DH)
376 * Output:
377 * TPM_TAG tag VTPM_TAG_RSP
378 * UINT32 paramSize total size
379 * UINT32 status return code
380 */
381 #define VTPM_ORD_GROUP_RECOVER2 (VTPM_PRIV_BASE + 0x10A)
382
383 /**
384 * List the UUIDs of vTPMs in an group. Multiple calls may be required to list
385 * all the vTPMs in an group; if the returned list is shorter than totalCount
386 * would imply, additional requests using the offest will be required
387 * to build the full list.
388 *
389 * Input:
390 * TPM_TAG tag VTPM_TAG_REQ2
391 * UINT32 paramSize total size
392 * UINT32 ordinal VTPM_ORD_VTPM_LIST
393 * UINT32 groupID ID of the group to list
394 * UINT32 offset Offset to start the list at
395 * Output:
396 * TPM_TAG tag VTPM_TAG_RSP
397 * UINT32 paramSize total size
398 * UINT32 status return code
399 * UINT32 totalCount Count of all vTPMs under this group
400 * BYTE[] uuids List of UUIDs (16 bytes each)
401 */
402 #define VTPM_ORD_VTPM_LIST (VTPM_PRIV_BASE + 0x201)
403 #define VTPM_ORD_VTPM_SHOW (VTPM_PRIV_BASE + 0x202)
404 #define VTPM_ORD_VTPM_EDIT (VTPM_PRIV_BASE + 0x203)
405 /**
406 * Input:
407 * TPM_TAG tag VTPM_TAG_REQ2
408 * UINT32 paramSize total size
409 * UINT32 ordinal VTPM_ORD_VTPM_NEW
410 * UINT32 groupID ID of the group to modify
411 * Output:
412 * TPM_TAG tag VTPM_TAG_RSP
413 * UINT32 paramSize total size
414 * UINT32 status return code
415 * BYTE[16] vtpmUUID UUID for the vTPM
416 */
417 #define VTPM_ORD_VTPM_NEW (VTPM_PRIV_BASE + 0x204)
418 /**
419 * Input:
420 * TPM_TAG tag VTPM_TAG_REQ2
421 * UINT32 paramSize total size
422 * UINT32 ordinal VTPM_ORD_VTPM_DEL
423 ## UINT32 groupID ID of the group to modify
424 * BYTE[16] vtpmUUID UUID for the vTPM to delete
425 * Output:
426 * TPM_TAG tag VTPM_TAG_RSP
427 * UINT32 paramSize total size
428 * UINT32 status return code
429 */
430 #define VTPM_ORD_VTPM_DEL (VTPM_PRIV_BASE + 0x205)
431
432 /**
433 * Generate an unbound AIK for the pTPM
434 *
435 * This unbound AIK can be used in the GROUP_RECOVER1 operation.
436 */
437 #define VTPM_ORD_MakeIdentity (VTPM_PRIV_BASE + 0x301)
438 /**
439 * Activate an unbound AIK for the pTPM
440 */
441 #define VTPM_ORD_ActivateIdentity (VTPM_PRIV_BASE + 0x302)
442 /**
443 * Get the EK from the pTPM
444 *
445 * Used for any AIK activation
446 */
447 #define VTPM_ORD_ReadPubek (VTPM_PRIV_BASE + 0x303)
448 /**
449 * Define an NVRAM slot
450 */
451 #define VTPM_NV_DefineSpace (VTPM_PRIV_BASE + 0x304)
452 /**
453 * Write to NVRAM
454 */
455 #define VTPM_NV_WriteValue (VTPM_PRIV_BASE + 0x305)
456 /**
457 * Read from NVRAM
458 */
459 #define VTPM_NV_ReadValue (VTPM_PRIV_BASE + 0x306)
460
461
462 //************************ Return Codes ****************************
463 #define VTPM_SUCCESS 0
464 #define VTPM_FAIL 1
465 #define VTPM_UNSUPPORTED 2
466 #define VTPM_FORBIDDEN 3
467 #define VTPM_RESTORE_CONTEXT_FAILED 4
468 #define VTPM_INVALID_REQUEST 5
469
470 #endif