avb_ops.h 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321
  1. /* SPDX-License-Identifier: MIT */
  2. /*
  3. * Copyright (C) 2016 The Android Open Source Project
  4. */
  5. #if !defined(AVB_INSIDE_LIBAVB_H) && !defined(AVB_COMPILATION)
  6. #error "Never include this file directly, include libavb.h instead."
  7. #endif
  8. #ifndef AVB_OPS_H_
  9. #define AVB_OPS_H_
  10. #include "avb_sysdeps.h"
  11. #ifdef __cplusplus
  12. extern "C" {
  13. #endif
  14. /* Well-known names of named persistent values. */
  15. #define AVB_NPV_PERSISTENT_DIGEST_PREFIX "avb.persistent_digest."
  16. #define AVB_NPV_MANAGED_VERITY_MODE "avb.managed_verity_mode"
  17. /* Return codes used for I/O operations.
  18. *
  19. * AVB_IO_RESULT_OK is returned if the requested operation was
  20. * successful.
  21. *
  22. * AVB_IO_RESULT_ERROR_IO is returned if the underlying hardware (disk
  23. * or other subsystem) encountered an I/O error.
  24. *
  25. * AVB_IO_RESULT_ERROR_OOM is returned if unable to allocate memory.
  26. *
  27. * AVB_IO_RESULT_ERROR_NO_SUCH_PARTITION is returned if the requested
  28. * partition does not exist.
  29. *
  30. * AVB_IO_RESULT_ERROR_RANGE_OUTSIDE_PARTITION is returned if the
  31. * range of bytes requested to be read or written is outside the range
  32. * of the partition.
  33. *
  34. * AVB_IO_RESULT_ERROR_NO_SUCH_VALUE is returned if a named persistent value
  35. * does not exist.
  36. *
  37. * AVB_IO_RESULT_ERROR_INVALID_VALUE_SIZE is returned if a named persistent
  38. * value size is not supported or does not match the expected size.
  39. *
  40. * AVB_IO_RESULT_ERROR_INSUFFICIENT_SPACE is returned if a buffer is too small
  41. * for the requested operation.
  42. */
  43. typedef enum {
  44. AVB_IO_RESULT_OK,
  45. AVB_IO_RESULT_ERROR_OOM,
  46. AVB_IO_RESULT_ERROR_IO,
  47. AVB_IO_RESULT_ERROR_NO_SUCH_PARTITION,
  48. AVB_IO_RESULT_ERROR_RANGE_OUTSIDE_PARTITION,
  49. AVB_IO_RESULT_ERROR_NO_SUCH_VALUE,
  50. AVB_IO_RESULT_ERROR_INVALID_VALUE_SIZE,
  51. AVB_IO_RESULT_ERROR_INSUFFICIENT_SPACE,
  52. } AvbIOResult;
  53. struct AvbOps;
  54. typedef struct AvbOps AvbOps;
  55. /* Forward-declaration of operations in libavb_ab. */
  56. struct AvbABOps;
  57. /* Forward-declaration of operations in libavb_atx. */
  58. struct AvbAtxOps;
  59. /* High-level operations/functions/methods that are platform
  60. * dependent.
  61. *
  62. * Operations may be added in the future so when implementing it
  63. * always make sure to zero out sizeof(AvbOps) bytes of the struct to
  64. * ensure that unimplemented operations are set to NULL.
  65. */
  66. struct AvbOps {
  67. /* This pointer can be used by the application/bootloader using
  68. * libavb and is typically used in each operation to get a pointer
  69. * to platform-specific resources. It cannot be used by libraries.
  70. */
  71. void* user_data;
  72. /* If libavb_ab is used, this should point to the
  73. * AvbABOps. Otherwise it must be set to NULL.
  74. */
  75. struct AvbABOps* ab_ops;
  76. /* If libavb_atx is used, this should point to the
  77. * AvbAtxOps. Otherwise it must be set to NULL.
  78. */
  79. struct AvbAtxOps* atx_ops;
  80. /* Reads |num_bytes| from offset |offset| from partition with name
  81. * |partition| (NUL-terminated UTF-8 string). If |offset| is
  82. * negative, its absolute value should be interpreted as the number
  83. * of bytes from the end of the partition.
  84. *
  85. * This function returns AVB_IO_RESULT_ERROR_NO_SUCH_PARTITION if
  86. * there is no partition with the given name,
  87. * AVB_IO_RESULT_ERROR_RANGE_OUTSIDE_PARTITION if the requested
  88. * |offset| is outside the partition, and AVB_IO_RESULT_ERROR_IO if
  89. * there was an I/O error from the underlying I/O subsystem. If the
  90. * operation succeeds as requested AVB_IO_RESULT_OK is returned and
  91. * the data is available in |buffer|.
  92. *
  93. * The only time partial I/O may occur is if reading beyond the end
  94. * of the partition. In this case the value returned in
  95. * |out_num_read| may be smaller than |num_bytes|.
  96. */
  97. AvbIOResult (*read_from_partition)(AvbOps* ops,
  98. const char* partition,
  99. int64_t offset,
  100. size_t num_bytes,
  101. void* buffer,
  102. size_t* out_num_read);
  103. /* Gets the starting pointer of a partition that is pre-loaded in memory, and
  104. * save it to |out_pointer|. The preloaded partition is expected to be
  105. * |num_bytes|, where the actual preloaded byte count is returned in
  106. * |out_num_bytes_preloaded|. |out_num_bytes_preloaded| must be no larger than
  107. * |num_bytes|.
  108. *
  109. * This provides an alternative way to access a partition that is preloaded
  110. * into memory without a full memory copy. When this function pointer is not
  111. * set (has value NULL), or when the |out_pointer| is set to NULL as a result,
  112. * |read_from_partition| will be used as the fallback. This function is mainly
  113. * used for accessing the entire partition content to calculate its hash.
  114. *
  115. * Preloaded partition data must outlive the lifespan of the
  116. * |AvbSlotVerifyData| structure that |avb_slot_verify| outputs.
  117. */
  118. AvbIOResult (*get_preloaded_partition)(AvbOps* ops,
  119. const char* partition,
  120. size_t num_bytes,
  121. uint8_t** out_pointer,
  122. size_t* out_num_bytes_preloaded);
  123. /* Writes |num_bytes| from |bffer| at offset |offset| to partition
  124. * with name |partition| (NUL-terminated UTF-8 string). If |offset|
  125. * is negative, its absolute value should be interpreted as the
  126. * number of bytes from the end of the partition.
  127. *
  128. * This function returns AVB_IO_RESULT_ERROR_NO_SUCH_PARTITION if
  129. * there is no partition with the given name,
  130. * AVB_IO_RESULT_ERROR_RANGE_OUTSIDE_PARTITION if the requested
  131. * byterange goes outside the partition, and AVB_IO_RESULT_ERROR_IO
  132. * if there was an I/O error from the underlying I/O subsystem. If
  133. * the operation succeeds as requested AVB_IO_RESULT_OK is
  134. * returned.
  135. *
  136. * This function never does any partial I/O, it either transfers all
  137. * of the requested bytes or returns an error.
  138. */
  139. AvbIOResult (*write_to_partition)(AvbOps* ops,
  140. const char* partition,
  141. int64_t offset,
  142. size_t num_bytes,
  143. const void* buffer);
  144. /* Checks if the given public key used to sign the 'vbmeta'
  145. * partition is trusted. Boot loaders typically compare this with
  146. * embedded key material generated with 'avbtool
  147. * extract_public_key'.
  148. *
  149. * The public key is in the array pointed to by |public_key_data|
  150. * and is of |public_key_length| bytes.
  151. *
  152. * If there is no public key metadata (set with the avbtool option
  153. * --public_key_metadata) then |public_key_metadata| will be set to
  154. * NULL. Otherwise this field points to the data which is
  155. * |public_key_metadata_length| bytes long.
  156. *
  157. * If AVB_IO_RESULT_OK is returned then |out_is_trusted| is set -
  158. * true if trusted or false if untrusted.
  159. *
  160. * NOTE: If AVB_SLOT_VERIFY_FLAGS_NO_VBMETA_PARTITION is passed to
  161. * avb_slot_verify() then this operation is never used. Instead, the
  162. * validate_public_key_for_partition() operation is used
  163. */
  164. AvbIOResult (*validate_vbmeta_public_key)(AvbOps* ops,
  165. const uint8_t* public_key_data,
  166. size_t public_key_length,
  167. const uint8_t* public_key_metadata,
  168. size_t public_key_metadata_length,
  169. bool* out_is_trusted);
  170. /* Gets the rollback index corresponding to the location given by
  171. * |rollback_index_location|. The value is returned in
  172. * |out_rollback_index|. Returns AVB_IO_RESULT_OK if the rollback
  173. * index was retrieved, otherwise an error code.
  174. *
  175. * A device may have a limited amount of rollback index locations (say,
  176. * one or four) so may error out if |rollback_index_location| exceeds
  177. * this number.
  178. */
  179. AvbIOResult (*read_rollback_index)(AvbOps* ops,
  180. size_t rollback_index_location,
  181. uint64_t* out_rollback_index);
  182. /* Sets the rollback index corresponding to the location given by
  183. * |rollback_index_location| to |rollback_index|. Returns
  184. * AVB_IO_RESULT_OK if the rollback index was set, otherwise an
  185. * error code.
  186. *
  187. * A device may have a limited amount of rollback index locations (say,
  188. * one or four) so may error out if |rollback_index_location| exceeds
  189. * this number.
  190. */
  191. AvbIOResult (*write_rollback_index)(AvbOps* ops,
  192. size_t rollback_index_location,
  193. uint64_t rollback_index);
  194. /* Gets whether the device is unlocked. The value is returned in
  195. * |out_is_unlocked| (true if unlocked, false otherwise). Returns
  196. * AVB_IO_RESULT_OK if the state was retrieved, otherwise an error
  197. * code.
  198. */
  199. AvbIOResult (*read_is_device_unlocked)(AvbOps* ops, bool* out_is_unlocked);
  200. /* Gets the unique partition GUID for a partition with name in
  201. * |partition| (NUL-terminated UTF-8 string). The GUID is copied as
  202. * a string into |guid_buf| of size |guid_buf_size| and will be NUL
  203. * terminated. The string must be lower-case and properly
  204. * hyphenated. For example:
  205. *
  206. * 527c1c6d-6361-4593-8842-3c78fcd39219
  207. *
  208. * Returns AVB_IO_RESULT_OK on success, otherwise an error code.
  209. */
  210. AvbIOResult (*get_unique_guid_for_partition)(AvbOps* ops,
  211. const char* partition,
  212. char* guid_buf,
  213. size_t guid_buf_size);
  214. /* Gets the size of a partition with the name in |partition|
  215. * (NUL-terminated UTF-8 string). Returns the value in
  216. * |out_size_num_bytes|.
  217. *
  218. * If the partition doesn't exist the AVB_IO_RESULT_ERROR_NO_SUCH_PARTITION
  219. * error code should be returned.
  220. *
  221. * Returns AVB_IO_RESULT_OK on success, otherwise an error code.
  222. */
  223. AvbIOResult (*get_size_of_partition)(AvbOps* ops,
  224. const char* partition,
  225. uint64_t* out_size_num_bytes);
  226. /* Reads a persistent value corresponding to the given |name|. The value is
  227. * returned in |out_buffer| which must point to |buffer_size| bytes. On
  228. * success |out_num_bytes_read| contains the number of bytes read into
  229. * |out_buffer|. If AVB_IO_RESULT_ERROR_INSUFFICIENT_SPACE is returned,
  230. * |out_num_bytes_read| contains the number of bytes that would have been read
  231. * which can be used to allocate a buffer.
  232. *
  233. * The |buffer_size| may be zero and the |out_buffer| may be NULL, but if
  234. * |out_buffer| is NULL then |buffer_size| *must* be zero.
  235. *
  236. * Returns AVB_IO_RESULT_OK on success, otherwise an error code.
  237. *
  238. * If the value does not exist, is not supported, or is not populated, returns
  239. * AVB_IO_RESULT_ERROR_NO_SUCH_VALUE. If |buffer_size| is smaller than the
  240. * size of the stored value, returns AVB_IO_RESULT_ERROR_INSUFFICIENT_SPACE.
  241. *
  242. * This operation is currently only used to support persistent digests or the
  243. * AVB_HASHTREE_ERROR_MODE_MANAGED_RESTART_AND_EIO hashtree error mode. If a
  244. * device does not use one of these features this function pointer can be set
  245. * to NULL.
  246. */
  247. AvbIOResult (*read_persistent_value)(AvbOps* ops,
  248. const char* name,
  249. size_t buffer_size,
  250. uint8_t* out_buffer,
  251. size_t* out_num_bytes_read);
  252. /* Writes a persistent value corresponding to the given |name|. The value is
  253. * supplied in |value| which must point to |value_size| bytes. Any existing
  254. * value with the same name is overwritten. If |value_size| is zero, future
  255. * calls to |read_persistent_value| will return
  256. * AVB_IO_RESULT_ERROR_NO_SUCH_VALUE.
  257. *
  258. * Returns AVB_IO_RESULT_OK on success, otherwise an error code.
  259. *
  260. * If the value |name| is not supported, returns
  261. * AVB_IO_RESULT_ERROR_NO_SUCH_VALUE. If the |value_size| is not supported,
  262. * returns AVB_IO_RESULT_ERROR_INVALID_VALUE_SIZE.
  263. *
  264. * This operation is currently only used to support persistent digests or the
  265. * AVB_HASHTREE_ERROR_MODE_MANAGED_RESTART_AND_EIO hashtree error mode. If a
  266. * device does not use one of these features this function pointer can be set
  267. * to NULL.
  268. */
  269. AvbIOResult (*write_persistent_value)(AvbOps* ops,
  270. const char* name,
  271. size_t value_size,
  272. const uint8_t* value);
  273. /* Like validate_vbmeta_public_key() but for when the flag
  274. * AVB_SLOT_VERIFY_FLAGS_NO_VBMETA_PARTITION is being used. The name of the
  275. * partition to get the public key for is passed in |partition_name|.
  276. *
  277. * Also returns the rollback index location to use for the partition, in
  278. * |out_rollback_index_location|.
  279. *
  280. * Returns AVB_IO_RESULT_OK on success, otherwise an error code.
  281. */
  282. AvbIOResult (*validate_public_key_for_partition)(
  283. AvbOps* ops,
  284. const char* partition,
  285. const uint8_t* public_key_data,
  286. size_t public_key_length,
  287. const uint8_t* public_key_metadata,
  288. size_t public_key_metadata_length,
  289. bool* out_is_trusted,
  290. uint32_t* out_rollback_index_location);
  291. };
  292. #ifdef __cplusplus
  293. }
  294. #endif
  295. #endif /* AVB_OPS_H_ */