tpm-v2.h 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432
  1. /* SPDX-License-Identifier: GPL-2.0+ */
  2. /*
  3. * Defines APIs and structures that allow software to interact with a
  4. * TPM2 device
  5. *
  6. * Copyright (c) 2020 Linaro
  7. * Copyright (c) 2018 Bootlin
  8. *
  9. * https://trustedcomputinggroup.org/resource/tss-overview-common-structures-specification/
  10. *
  11. * Author: Miquel Raynal <miquel.raynal@bootlin.com>
  12. */
  13. #ifndef __TPM_V2_H
  14. #define __TPM_V2_H
  15. #include <tpm-common.h>
  16. #define TPM2_DIGEST_LEN 32
  17. #define TPM2_MAX_PCRS 32
  18. #define TPM2_PCR_SELECT_MAX ((TPM2_MAX_PCRS + 7) / 8)
  19. #define TPM2_MAX_CAP_BUFFER 1024
  20. #define TPM2_MAX_TPM_PROPERTIES ((TPM2_MAX_CAP_BUFFER - sizeof(u32) /* TPM2_CAP */ - \
  21. sizeof(u32)) / sizeof(struct tpms_tagged_property))
  22. /*
  23. * We deviate from this draft of the specification by increasing the value of
  24. * TPM2_NUM_PCR_BANKS from 3 to 16 to ensure compatibility with TPM2
  25. * implementations that have enabled a larger than typical number of PCR
  26. * banks. This larger value for TPM2_NUM_PCR_BANKS is expected to be included
  27. * in a future revision of the specification.
  28. */
  29. #define TPM2_NUM_PCR_BANKS 16
  30. /* Definition of (UINT32) TPM2_CAP Constants */
  31. #define TPM2_CAP_PCRS 0x00000005U
  32. #define TPM2_CAP_TPM_PROPERTIES 0x00000006U
  33. /* Definition of (UINT32) TPM2_PT Constants */
  34. #define TPM2_PT_GROUP (u32)(0x00000100)
  35. #define TPM2_PT_FIXED (u32)(TPM2_PT_GROUP * 1)
  36. #define TPM2_PT_MANUFACTURER (u32)(TPM2_PT_FIXED + 5)
  37. #define TPM2_PT_PCR_COUNT (u32)(TPM2_PT_FIXED + 18)
  38. #define TPM2_PT_MAX_COMMAND_SIZE (u32)(TPM2_PT_FIXED + 30)
  39. #define TPM2_PT_MAX_RESPONSE_SIZE (u32)(TPM2_PT_FIXED + 31)
  40. /* TPMS_TAGGED_PROPERTY Structure */
  41. struct tpms_tagged_property {
  42. u32 property;
  43. u32 value;
  44. } __packed;
  45. /* TPMS_PCR_SELECTION Structure */
  46. struct tpms_pcr_selection {
  47. u16 hash;
  48. u8 size_of_select;
  49. u8 pcr_select[TPM2_PCR_SELECT_MAX];
  50. } __packed;
  51. /* TPML_PCR_SELECTION Structure */
  52. struct tpml_pcr_selection {
  53. u32 count;
  54. struct tpms_pcr_selection selection[TPM2_NUM_PCR_BANKS];
  55. } __packed;
  56. /* TPML_TAGGED_TPM_PROPERTY Structure */
  57. struct tpml_tagged_tpm_property {
  58. u32 count;
  59. struct tpms_tagged_property tpm_property[TPM2_MAX_TPM_PROPERTIES];
  60. } __packed;
  61. /* TPMU_CAPABILITIES Union */
  62. union tpmu_capabilities {
  63. /*
  64. * Non exhaustive. Only added the structs needed for our
  65. * current code
  66. */
  67. struct tpml_pcr_selection assigned_pcr;
  68. struct tpml_tagged_tpm_property tpm_properties;
  69. } __packed;
  70. /* TPMS_CAPABILITY_DATA Structure */
  71. struct tpms_capability_data {
  72. u32 capability;
  73. union tpmu_capabilities data;
  74. } __packed;
  75. /**
  76. * TPM2 Structure Tags for command/response buffers.
  77. *
  78. * @TPM2_ST_NO_SESSIONS: the command does not need an authentication.
  79. * @TPM2_ST_SESSIONS: the command needs an authentication.
  80. */
  81. enum tpm2_structures {
  82. TPM2_ST_NO_SESSIONS = 0x8001,
  83. TPM2_ST_SESSIONS = 0x8002,
  84. };
  85. /**
  86. * TPM2 type of boolean.
  87. */
  88. enum tpm2_yes_no {
  89. TPMI_YES = 1,
  90. TPMI_NO = 0,
  91. };
  92. /**
  93. * TPM2 startup values.
  94. *
  95. * @TPM2_SU_CLEAR: reset the internal state.
  96. * @TPM2_SU_STATE: restore saved state (if any).
  97. */
  98. enum tpm2_startup_types {
  99. TPM2_SU_CLEAR = 0x0000,
  100. TPM2_SU_STATE = 0x0001,
  101. };
  102. /**
  103. * TPM2 permanent handles.
  104. *
  105. * @TPM2_RH_OWNER: refers to the 'owner' hierarchy.
  106. * @TPM2_RS_PW: indicates a password.
  107. * @TPM2_RH_LOCKOUT: refers to the 'lockout' hierarchy.
  108. * @TPM2_RH_ENDORSEMENT: refers to the 'endorsement' hierarchy.
  109. * @TPM2_RH_PLATFORM: refers to the 'platform' hierarchy.
  110. */
  111. enum tpm2_handles {
  112. TPM2_RH_OWNER = 0x40000001,
  113. TPM2_RS_PW = 0x40000009,
  114. TPM2_RH_LOCKOUT = 0x4000000A,
  115. TPM2_RH_ENDORSEMENT = 0x4000000B,
  116. TPM2_RH_PLATFORM = 0x4000000C,
  117. };
  118. /**
  119. * TPM2 command codes used at the beginning of a buffer, gives the command.
  120. *
  121. * @TPM2_CC_STARTUP: TPM2_Startup().
  122. * @TPM2_CC_SELF_TEST: TPM2_SelfTest().
  123. * @TPM2_CC_CLEAR: TPM2_Clear().
  124. * @TPM2_CC_CLEARCONTROL: TPM2_ClearControl().
  125. * @TPM2_CC_HIERCHANGEAUTH: TPM2_HierarchyChangeAuth().
  126. * @TPM2_CC_PCR_SETAUTHPOL: TPM2_PCR_SetAuthPolicy().
  127. * @TPM2_CC_DAM_RESET: TPM2_DictionaryAttackLockReset().
  128. * @TPM2_CC_DAM_PARAMETERS: TPM2_DictionaryAttackParameters().
  129. * @TPM2_CC_GET_CAPABILITY: TPM2_GetCapibility().
  130. * @TPM2_CC_GET_RANDOM: TPM2_GetRandom().
  131. * @TPM2_CC_PCR_READ: TPM2_PCR_Read().
  132. * @TPM2_CC_PCR_EXTEND: TPM2_PCR_Extend().
  133. * @TPM2_CC_PCR_SETAUTHVAL: TPM2_PCR_SetAuthValue().
  134. */
  135. enum tpm2_command_codes {
  136. TPM2_CC_STARTUP = 0x0144,
  137. TPM2_CC_SELF_TEST = 0x0143,
  138. TPM2_CC_CLEAR = 0x0126,
  139. TPM2_CC_CLEARCONTROL = 0x0127,
  140. TPM2_CC_HIERCHANGEAUTH = 0x0129,
  141. TPM2_CC_PCR_SETAUTHPOL = 0x012C,
  142. TPM2_CC_DAM_RESET = 0x0139,
  143. TPM2_CC_DAM_PARAMETERS = 0x013A,
  144. TPM2_CC_NV_READ = 0x014E,
  145. TPM2_CC_GET_CAPABILITY = 0x017A,
  146. TPM2_CC_GET_RANDOM = 0x017B,
  147. TPM2_CC_PCR_READ = 0x017E,
  148. TPM2_CC_PCR_EXTEND = 0x0182,
  149. TPM2_CC_PCR_SETAUTHVAL = 0x0183,
  150. };
  151. /**
  152. * TPM2 return codes.
  153. */
  154. enum tpm2_return_codes {
  155. TPM2_RC_SUCCESS = 0x0000,
  156. TPM2_RC_BAD_TAG = 0x001E,
  157. TPM2_RC_FMT1 = 0x0080,
  158. TPM2_RC_HASH = TPM2_RC_FMT1 + 0x0003,
  159. TPM2_RC_VALUE = TPM2_RC_FMT1 + 0x0004,
  160. TPM2_RC_SIZE = TPM2_RC_FMT1 + 0x0015,
  161. TPM2_RC_BAD_AUTH = TPM2_RC_FMT1 + 0x0022,
  162. TPM2_RC_HANDLE = TPM2_RC_FMT1 + 0x000B,
  163. TPM2_RC_VER1 = 0x0100,
  164. TPM2_RC_INITIALIZE = TPM2_RC_VER1 + 0x0000,
  165. TPM2_RC_FAILURE = TPM2_RC_VER1 + 0x0001,
  166. TPM2_RC_DISABLED = TPM2_RC_VER1 + 0x0020,
  167. TPM2_RC_AUTH_MISSING = TPM2_RC_VER1 + 0x0025,
  168. TPM2_RC_COMMAND_CODE = TPM2_RC_VER1 + 0x0043,
  169. TPM2_RC_AUTHSIZE = TPM2_RC_VER1 + 0x0044,
  170. TPM2_RC_AUTH_CONTEXT = TPM2_RC_VER1 + 0x0045,
  171. TPM2_RC_NEEDS_TEST = TPM2_RC_VER1 + 0x0053,
  172. TPM2_RC_WARN = 0x0900,
  173. TPM2_RC_TESTING = TPM2_RC_WARN + 0x000A,
  174. TPM2_RC_REFERENCE_H0 = TPM2_RC_WARN + 0x0010,
  175. TPM2_RC_LOCKOUT = TPM2_RC_WARN + 0x0021,
  176. };
  177. /**
  178. * TPM2 algorithms.
  179. */
  180. enum tpm2_algorithms {
  181. TPM2_ALG_SHA1 = 0x04,
  182. TPM2_ALG_XOR = 0x0A,
  183. TPM2_ALG_SHA256 = 0x0B,
  184. TPM2_ALG_SHA384 = 0x0C,
  185. TPM2_ALG_SHA512 = 0x0D,
  186. TPM2_ALG_NULL = 0x10,
  187. TPM2_ALG_SM3_256 = 0x12,
  188. };
  189. /* NV index attributes */
  190. enum tpm_index_attrs {
  191. TPMA_NV_PPWRITE = 1UL << 0,
  192. TPMA_NV_OWNERWRITE = 1UL << 1,
  193. TPMA_NV_AUTHWRITE = 1UL << 2,
  194. TPMA_NV_POLICYWRITE = 1UL << 3,
  195. TPMA_NV_COUNTER = 1UL << 4,
  196. TPMA_NV_BITS = 1UL << 5,
  197. TPMA_NV_EXTEND = 1UL << 6,
  198. TPMA_NV_POLICY_DELETE = 1UL << 10,
  199. TPMA_NV_WRITELOCKED = 1UL << 11,
  200. TPMA_NV_WRITEALL = 1UL << 12,
  201. TPMA_NV_WRITEDEFINE = 1UL << 13,
  202. TPMA_NV_WRITE_STCLEAR = 1UL << 14,
  203. TPMA_NV_GLOBALLOCK = 1UL << 15,
  204. TPMA_NV_PPREAD = 1UL << 16,
  205. TPMA_NV_OWNERREAD = 1UL << 17,
  206. TPMA_NV_AUTHREAD = 1UL << 18,
  207. TPMA_NV_POLICYREAD = 1UL << 19,
  208. TPMA_NV_NO_DA = 1UL << 25,
  209. TPMA_NV_ORDERLY = 1UL << 26,
  210. TPMA_NV_CLEAR_STCLEAR = 1UL << 27,
  211. TPMA_NV_READLOCKED = 1UL << 28,
  212. TPMA_NV_WRITTEN = 1UL << 29,
  213. TPMA_NV_PLATFORMCREATE = 1UL << 30,
  214. TPMA_NV_READ_STCLEAR = 1UL << 31,
  215. TPMA_NV_MASK_READ = TPMA_NV_PPREAD | TPMA_NV_OWNERREAD |
  216. TPMA_NV_AUTHREAD | TPMA_NV_POLICYREAD,
  217. TPMA_NV_MASK_WRITE = TPMA_NV_PPWRITE | TPMA_NV_OWNERWRITE |
  218. TPMA_NV_AUTHWRITE | TPMA_NV_POLICYWRITE,
  219. };
  220. enum {
  221. TPM_ACCESS_VALID = 1 << 7,
  222. TPM_ACCESS_ACTIVE_LOCALITY = 1 << 5,
  223. TPM_ACCESS_REQUEST_PENDING = 1 << 2,
  224. TPM_ACCESS_REQUEST_USE = 1 << 1,
  225. TPM_ACCESS_ESTABLISHMENT = 1 << 0,
  226. };
  227. enum {
  228. TPM_STS_FAMILY_SHIFT = 26,
  229. TPM_STS_FAMILY_MASK = 0x3 << TPM_STS_FAMILY_SHIFT,
  230. TPM_STS_FAMILY_TPM2 = 1 << TPM_STS_FAMILY_SHIFT,
  231. TPM_STS_RESE_TESTABLISMENT_BIT = 1 << 25,
  232. TPM_STS_COMMAND_CANCEL = 1 << 24,
  233. TPM_STS_BURST_COUNT_SHIFT = 8,
  234. TPM_STS_BURST_COUNT_MASK = 0xffff << TPM_STS_BURST_COUNT_SHIFT,
  235. TPM_STS_VALID = 1 << 7,
  236. TPM_STS_COMMAND_READY = 1 << 6,
  237. TPM_STS_GO = 1 << 5,
  238. TPM_STS_DATA_AVAIL = 1 << 4,
  239. TPM_STS_DATA_EXPECT = 1 << 3,
  240. TPM_STS_SELF_TEST_DONE = 1 << 2,
  241. TPM_STS_RESPONSE_RETRY = 1 << 1,
  242. };
  243. enum {
  244. TPM_CMD_COUNT_OFFSET = 2,
  245. TPM_CMD_ORDINAL_OFFSET = 6,
  246. TPM_MAX_BUF_SIZE = 1260,
  247. };
  248. /**
  249. * Issue a TPM2_Startup command.
  250. *
  251. * @dev TPM device
  252. * @mode TPM startup mode
  253. *
  254. * @return code of the operation
  255. */
  256. u32 tpm2_startup(struct udevice *dev, enum tpm2_startup_types mode);
  257. /**
  258. * Issue a TPM2_SelfTest command.
  259. *
  260. * @dev TPM device
  261. * @full_test Asking to perform all tests or only the untested ones
  262. *
  263. * @return code of the operation
  264. */
  265. u32 tpm2_self_test(struct udevice *dev, enum tpm2_yes_no full_test);
  266. /**
  267. * Issue a TPM2_Clear command.
  268. *
  269. * @dev TPM device
  270. * @handle Handle
  271. * @pw Password
  272. * @pw_sz Length of the password
  273. *
  274. * @return code of the operation
  275. */
  276. u32 tpm2_clear(struct udevice *dev, u32 handle, const char *pw,
  277. const ssize_t pw_sz);
  278. /**
  279. * Issue a TPM2_PCR_Extend command.
  280. *
  281. * @dev TPM device
  282. * @index Index of the PCR
  283. * @digest Value representing the event to be recorded
  284. *
  285. * @return code of the operation
  286. */
  287. u32 tpm2_pcr_extend(struct udevice *dev, u32 index, const uint8_t *digest);
  288. /**
  289. * Issue a TPM2_PCR_Read command.
  290. *
  291. * @dev TPM device
  292. * @idx Index of the PCR
  293. * @idx_min_sz Minimum size in bytes of the pcrSelect array
  294. * @data Output buffer for contents of the named PCR
  295. * @updates Optional out parameter: number of updates for this PCR
  296. *
  297. * @return code of the operation
  298. */
  299. u32 tpm2_pcr_read(struct udevice *dev, u32 idx, unsigned int idx_min_sz,
  300. void *data, unsigned int *updates);
  301. /**
  302. * Issue a TPM2_GetCapability command. This implementation is limited
  303. * to query property index that is 4-byte wide.
  304. *
  305. * @dev TPM device
  306. * @capability Partition of capabilities
  307. * @property Further definition of capability, limited to be 4 bytes wide
  308. * @buf Output buffer for capability information
  309. * @prop_count Size of output buffer
  310. *
  311. * @return code of the operation
  312. */
  313. u32 tpm2_get_capability(struct udevice *dev, u32 capability, u32 property,
  314. void *buf, size_t prop_count);
  315. /**
  316. * Issue a TPM2_DictionaryAttackLockReset command.
  317. *
  318. * @dev TPM device
  319. * @pw Password
  320. * @pw_sz Length of the password
  321. *
  322. * @return code of the operation
  323. */
  324. u32 tpm2_dam_reset(struct udevice *dev, const char *pw, const ssize_t pw_sz);
  325. /**
  326. * Issue a TPM2_DictionaryAttackParameters command.
  327. *
  328. * @dev TPM device
  329. * @pw Password
  330. * @pw_sz Length of the password
  331. * @max_tries Count of authorizations before lockout
  332. * @recovery_time Time before decrementation of the failure count
  333. * @lockout_recovery Time to wait after a lockout
  334. *
  335. * @return code of the operation
  336. */
  337. u32 tpm2_dam_parameters(struct udevice *dev, const char *pw,
  338. const ssize_t pw_sz, unsigned int max_tries,
  339. unsigned int recovery_time,
  340. unsigned int lockout_recovery);
  341. /**
  342. * Issue a TPM2_HierarchyChangeAuth command.
  343. *
  344. * @dev TPM device
  345. * @handle Handle
  346. * @newpw New password
  347. * @newpw_sz Length of the new password
  348. * @oldpw Old password
  349. * @oldpw_sz Length of the old password
  350. *
  351. * @return code of the operation
  352. */
  353. int tpm2_change_auth(struct udevice *dev, u32 handle, const char *newpw,
  354. const ssize_t newpw_sz, const char *oldpw,
  355. const ssize_t oldpw_sz);
  356. /**
  357. * Issue a TPM_PCR_SetAuthPolicy command.
  358. *
  359. * @dev TPM device
  360. * @pw Platform password
  361. * @pw_sz Length of the password
  362. * @index Index of the PCR
  363. * @digest New key to access the PCR
  364. *
  365. * @return code of the operation
  366. */
  367. u32 tpm2_pcr_setauthpolicy(struct udevice *dev, const char *pw,
  368. const ssize_t pw_sz, u32 index, const char *key);
  369. /**
  370. * Issue a TPM_PCR_SetAuthValue command.
  371. *
  372. * @dev TPM device
  373. * @pw Platform password
  374. * @pw_sz Length of the password
  375. * @index Index of the PCR
  376. * @digest New key to access the PCR
  377. * @key_sz Length of the new key
  378. *
  379. * @return code of the operation
  380. */
  381. u32 tpm2_pcr_setauthvalue(struct udevice *dev, const char *pw,
  382. const ssize_t pw_sz, u32 index, const char *key,
  383. const ssize_t key_sz);
  384. /**
  385. * Issue a TPM2_GetRandom command.
  386. *
  387. * @dev TPM device
  388. * @param data output buffer for the random bytes
  389. * @param count size of output buffer
  390. *
  391. * @return return code of the operation
  392. */
  393. u32 tpm2_get_random(struct udevice *dev, void *data, u32 count);
  394. #endif /* __TPM_V2_H */