tpm_api.h 9.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322
  1. /* SPDX-License-Identifier: GPL-2.0+ */
  2. /*
  3. * Copyright (c) 2013 The Chromium OS Authors.
  4. * Coypright (c) 2013 Guntermann & Drunck GmbH
  5. */
  6. #ifndef __TPM_API_H
  7. #define __TPM_API_H
  8. #include <tpm-common.h>
  9. #include <tpm-v1.h>
  10. #include <tpm-v2.h>
  11. /**
  12. * Issue a TPM_Startup command.
  13. *
  14. * @param dev TPM device
  15. * @param mode TPM startup mode
  16. * @return return code of the operation
  17. */
  18. u32 tpm_startup(struct udevice *dev, enum tpm_startup_type mode);
  19. /**
  20. * Issue a TPM_SelfTestFull command.
  21. *
  22. * @param dev TPM device
  23. * @return return code of the operation
  24. */
  25. u32 tpm_self_test_full(struct udevice *dev);
  26. /**
  27. * Issue a TPM_ContinueSelfTest command.
  28. *
  29. * @param dev TPM device
  30. * @return return code of the operation
  31. */
  32. u32 tpm_continue_self_test(struct udevice *dev);
  33. /**
  34. * Issue a TPM_NV_DefineSpace command. The implementation is limited
  35. * to specify TPM_NV_ATTRIBUTES and size of the area. The area index
  36. * could be one of the special value listed in enum tpm_nv_index.
  37. *
  38. * @param dev TPM device
  39. * @param index index of the area
  40. * @param perm TPM_NV_ATTRIBUTES of the area
  41. * @param size size of the area
  42. * @return return code of the operation
  43. */
  44. u32 tpm_nv_define_space(struct udevice *dev, u32 index, u32 perm, u32 size);
  45. /**
  46. * Issue a TPM_NV_ReadValue command. This implementation is limited
  47. * to read the area from offset 0. The area index could be one of
  48. * the special value listed in enum tpm_nv_index.
  49. *
  50. * @param dev TPM device
  51. * @param index index of the area
  52. * @param data output buffer of the area contents
  53. * @param count size of output buffer
  54. * @return return code of the operation
  55. */
  56. u32 tpm_nv_read_value(struct udevice *dev, u32 index, void *data, u32 count);
  57. /**
  58. * Issue a TPM_NV_WriteValue command. This implementation is limited
  59. * to write the area from offset 0. The area index could be one of
  60. * the special value listed in enum tpm_nv_index.
  61. *
  62. * @param dev TPM device
  63. * @param index index of the area
  64. * @param data input buffer to be wrote to the area
  65. * @param length length of data bytes of input buffer
  66. * @return return code of the operation
  67. */
  68. u32 tpm_nv_write_value(struct udevice *dev, u32 index, const void *data,
  69. u32 length);
  70. /**
  71. * Issue a TPM_Extend command.
  72. *
  73. * @param dev TPM device
  74. * @param index index of the PCR
  75. * @param in_digest 160-bit value representing the event to be
  76. * recorded
  77. * @param out_digest 160-bit PCR value after execution of the
  78. * command
  79. * @return return code of the operation
  80. */
  81. u32 tpm_pcr_extend(struct udevice *dev, u32 index, const void *in_digest,
  82. void *out_digest);
  83. /**
  84. * Issue a TPM_PCRRead command.
  85. *
  86. * @param dev TPM device
  87. * @param index index of the PCR
  88. * @param data output buffer for contents of the named PCR
  89. * @param count size of output buffer
  90. * @return return code of the operation
  91. */
  92. u32 tpm_pcr_read(struct udevice *dev, u32 index, void *data, size_t count);
  93. /**
  94. * Issue a TSC_PhysicalPresence command. TPM physical presence flag
  95. * is bit-wise OR'ed of flags listed in enum tpm_physical_presence.
  96. *
  97. * @param dev TPM device
  98. * @param presence TPM physical presence flag
  99. * @return return code of the operation
  100. */
  101. u32 tpm_tsc_physical_presence(struct udevice *dev, u16 presence);
  102. /**
  103. * Issue a TPM_ReadPubek command.
  104. *
  105. * @param dev TPM device
  106. * @param data output buffer for the public endorsement key
  107. * @param count size of output buffer
  108. * @return return code of the operation
  109. */
  110. u32 tpm_read_pubek(struct udevice *dev, void *data, size_t count);
  111. /**
  112. * Issue a TPM_ForceClear command.
  113. *
  114. * @param dev TPM device
  115. * @return return code of the operation
  116. */
  117. u32 tpm_force_clear(struct udevice *dev);
  118. /**
  119. * Issue a TPM_PhysicalEnable command.
  120. *
  121. * @param dev TPM device
  122. * @return return code of the operation
  123. */
  124. u32 tpm_physical_enable(struct udevice *dev);
  125. /**
  126. * Issue a TPM_PhysicalDisable command.
  127. *
  128. * @param dev TPM device
  129. * @return return code of the operation
  130. */
  131. u32 tpm_physical_disable(struct udevice *dev);
  132. /**
  133. * Issue a TPM_PhysicalSetDeactivated command.
  134. *
  135. * @param dev TPM device
  136. * @param state boolean state of the deactivated flag
  137. * @return return code of the operation
  138. */
  139. u32 tpm_physical_set_deactivated(struct udevice *dev, u8 state);
  140. /**
  141. * Issue a TPM_GetCapability command. This implementation is limited
  142. * to query sub_cap index that is 4-byte wide.
  143. *
  144. * @param dev TPM device
  145. * @param cap_area partition of capabilities
  146. * @param sub_cap further definition of capability, which is
  147. * limited to be 4-byte wide
  148. * @param cap output buffer for capability information
  149. * @param count size of output buffer
  150. * @return return code of the operation
  151. */
  152. u32 tpm_get_capability(struct udevice *dev, u32 cap_area, u32 sub_cap,
  153. void *cap, size_t count);
  154. /**
  155. * Issue a TPM_FlushSpecific command for a AUTH resource.
  156. *
  157. * @param dev TPM device
  158. * @param auth_handle handle of the auth session
  159. * @return return code of the operation
  160. */
  161. u32 tpm_terminate_auth_session(struct udevice *dev, u32 auth_handle);
  162. /**
  163. * Issue a TPM_OIAP command to setup an object independent authorization
  164. * session.
  165. * Information about the session is stored internally.
  166. * If there was already an OIAP session active it is terminated and a new
  167. * session is set up.
  168. *
  169. * @param dev TPM device
  170. * @param auth_handle pointer to the (new) auth handle or NULL.
  171. * @return return code of the operation
  172. */
  173. u32 tpm_oiap(struct udevice *dev, u32 *auth_handle);
  174. /**
  175. * Ends an active OIAP session.
  176. *
  177. * @param dev TPM device
  178. * @return return code of the operation
  179. */
  180. u32 tpm_end_oiap(struct udevice *dev);
  181. /**
  182. * Issue a TPM_LoadKey2 (Auth1) command using an OIAP session for authenticating
  183. * the usage of the parent key.
  184. *
  185. * @param dev TPM device
  186. * @param parent_handle handle of the parent key.
  187. * @param key pointer to the key structure (TPM_KEY or TPM_KEY12).
  188. * @param key_length size of the key structure
  189. * @param parent_key_usage_auth usage auth for the parent key
  190. * @param key_handle pointer to the key handle
  191. * @return return code of the operation
  192. */
  193. u32 tpm_load_key2_oiap(struct udevice *dev, u32 parent_handle, const void *key,
  194. size_t key_length, const void *parent_key_usage_auth,
  195. u32 *key_handle);
  196. /**
  197. * Issue a TPM_GetPubKey (Auth1) command using an OIAP session for
  198. * authenticating the usage of the key.
  199. *
  200. * @param dev TPM device
  201. * @param key_handle handle of the key
  202. * @param usage_auth usage auth for the key
  203. * @param pubkey pointer to the pub key buffer; may be NULL if the pubkey
  204. * should not be stored.
  205. * @param pubkey_len pointer to the pub key buffer len. On entry: the size of
  206. * the provided pubkey buffer. On successful exit: the size
  207. * of the stored TPM_PUBKEY structure (iff pubkey != NULL).
  208. * @return return code of the operation
  209. */
  210. u32 tpm_get_pub_key_oiap(struct udevice *dev, u32 key_handle,
  211. const void *usage_auth, void *pubkey,
  212. size_t *pubkey_len);
  213. /**
  214. * Get the TPM permissions
  215. *
  216. * @param dev TPM device
  217. * @param perm Returns permissions value
  218. * @return return code of the operation
  219. */
  220. u32 tpm_get_permissions(struct udevice *dev, u32 index, u32 *perm);
  221. /**
  222. * Flush a resource with a given handle and type from the TPM
  223. *
  224. * @param dev TPM device
  225. * @param key_handle handle of the resource
  226. * @param resource_type type of the resource
  227. * @return return code of the operation
  228. */
  229. u32 tpm_flush_specific(struct udevice *dev, u32 key_handle, u32 resource_type);
  230. #ifdef CONFIG_TPM_LOAD_KEY_BY_SHA1
  231. /**
  232. * Search for a key by usage AuthData and the hash of the parent's pub key.
  233. *
  234. * @param dev TPM device
  235. * @param auth Usage auth of the key to search for
  236. * @param pubkey_digest SHA1 hash of the pub key structure of the key
  237. * @param[out] handle The handle of the key (Non-null iff found)
  238. * @return 0 if key was found in TPM; != 0 if not.
  239. */
  240. u32 tpm_find_key_sha1(struct udevice *dev, const u8 auth[20],
  241. const u8 pubkey_digest[20], u32 *handle);
  242. #endif /* CONFIG_TPM_LOAD_KEY_BY_SHA1 */
  243. /**
  244. * Read random bytes from the TPM RNG. The implementation deals with the fact
  245. * that the TPM may legally return fewer bytes than requested by retrying
  246. * until @p count bytes have been received.
  247. *
  248. * @param dev TPM device
  249. * @param data output buffer for the random bytes
  250. * @param count size of output buffer
  251. * @return return code of the operation
  252. */
  253. u32 tpm_get_random(struct udevice *dev, void *data, u32 count);
  254. /**
  255. * tpm_finalise_physical_presence() - Finalise physical presence
  256. *
  257. * @param dev TPM device
  258. * @return return code of the operation (0 = success)
  259. */
  260. u32 tpm_finalise_physical_presence(struct udevice *dev);
  261. /**
  262. * tpm_nv_enable_locking() - lock the non-volatile space
  263. *
  264. * @param dev TPM device
  265. * @return return code of the operation (0 = success)
  266. */
  267. u32 tpm_nv_enable_locking(struct udevice *dev);
  268. /**
  269. * tpm_set_global_lock() - set the global lock
  270. *
  271. * @param dev TPM device
  272. * @return return code of the operation (0 = success)
  273. */
  274. u32 tpm_set_global_lock(struct udevice *dev);
  275. /**
  276. * tpm_write_lock() - lock the non-volatile space
  277. *
  278. * @param dev TPM device
  279. * @param index Index of space to lock
  280. * @return return code of the operation (0 = success)
  281. */
  282. u32 tpm_write_lock(struct udevice *dev, u32 index);
  283. /**
  284. * tpm_resume() - start up the TPM from resume (after suspend)
  285. *
  286. * @param dev TPM device
  287. * @return return code of the operation (0 = success)
  288. */
  289. u32 tpm_resume(struct udevice *dev);
  290. #endif /* __TPM_API_H */