avb_slot_verify.h 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340
  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_SLOT_VERIFY_H_
  9. #define AVB_SLOT_VERIFY_H_
  10. #include "avb_ops.h"
  11. #include "avb_vbmeta_image.h"
  12. #ifdef __cplusplus
  13. extern "C" {
  14. #endif
  15. /* Return codes used in avb_slot_verify(), see that function for
  16. * documentation for each field.
  17. *
  18. * Use avb_slot_verify_result_to_string() to get a textual
  19. * representation usable for error/debug output.
  20. */
  21. typedef enum {
  22. AVB_SLOT_VERIFY_RESULT_OK,
  23. AVB_SLOT_VERIFY_RESULT_ERROR_OOM,
  24. AVB_SLOT_VERIFY_RESULT_ERROR_IO,
  25. AVB_SLOT_VERIFY_RESULT_ERROR_VERIFICATION,
  26. AVB_SLOT_VERIFY_RESULT_ERROR_ROLLBACK_INDEX,
  27. AVB_SLOT_VERIFY_RESULT_ERROR_PUBLIC_KEY_REJECTED,
  28. AVB_SLOT_VERIFY_RESULT_ERROR_INVALID_METADATA,
  29. AVB_SLOT_VERIFY_RESULT_ERROR_UNSUPPORTED_VERSION,
  30. AVB_SLOT_VERIFY_RESULT_ERROR_INVALID_ARGUMENT
  31. } AvbSlotVerifyResult;
  32. /* Various error handling modes for when verification fails using a
  33. * hashtree at runtime inside the HLOS.
  34. *
  35. * AVB_HASHTREE_ERROR_MODE_RESTART_AND_INVALIDATE means that the OS
  36. * will invalidate the current slot and restart.
  37. *
  38. * AVB_HASHTREE_ERROR_MODE_RESTART means that the OS will restart.
  39. *
  40. * AVB_HASHTREE_ERROR_MODE_EIO means that an EIO error will be
  41. * returned to applications.
  42. *
  43. * AVB_HASHTREE_ERROR_MODE_LOGGING means that errors will be logged
  44. * and corrupt data may be returned to applications. This mode should
  45. * be used ONLY for diagnostics and debugging. It cannot be used
  46. * unless AVB_SLOT_VERIFY_FLAGS_ALLOW_VERIFICATION_ERROR is also
  47. * used.
  48. */
  49. typedef enum {
  50. AVB_HASHTREE_ERROR_MODE_RESTART_AND_INVALIDATE,
  51. AVB_HASHTREE_ERROR_MODE_RESTART,
  52. AVB_HASHTREE_ERROR_MODE_EIO,
  53. AVB_HASHTREE_ERROR_MODE_LOGGING
  54. } AvbHashtreeErrorMode;
  55. /* Flags that influence how avb_slot_verify() works.
  56. *
  57. * If AVB_SLOT_VERIFY_FLAGS_ALLOW_VERIFICATION_ERROR is NOT set then
  58. * avb_slot_verify() will bail out as soon as an error is encountered
  59. * and |out_data| is set only if AVB_SLOT_VERIFY_RESULT_OK is
  60. * returned.
  61. *
  62. * Otherwise if AVB_SLOT_VERIFY_FLAGS_ALLOW_VERIFICATION_ERROR is set
  63. * avb_slot_verify() will continue verification efforts and |out_data|
  64. * is also set if AVB_SLOT_VERIFY_RESULT_ERROR_PUBLIC_KEY_REJECTED,
  65. * AVB_SLOT_VERIFY_RESULT_ERROR_VERIFICATION, or
  66. * AVB_SLOT_VERIFY_RESULT_ERROR_ROLLBACK_INDEX is returned. It is
  67. * undefined which error is returned if more than one distinct error
  68. * is encountered. It is guaranteed that AVB_SLOT_VERIFY_RESULT_OK is
  69. * returned if, and only if, there are no errors. This mode is needed
  70. * to boot valid but unverified slots when the device is unlocked.
  71. *
  72. * Also, if AVB_SLOT_VERIFY_FLAGS_ALLOW_VERIFICATION_ERROR is set the
  73. * contents loaded from |requested_partition| will be the contents of
  74. * the entire partition instead of just the size specified in the hash
  75. * descriptor.
  76. */
  77. typedef enum {
  78. AVB_SLOT_VERIFY_FLAGS_NONE = 0,
  79. AVB_SLOT_VERIFY_FLAGS_ALLOW_VERIFICATION_ERROR = (1 << 0)
  80. } AvbSlotVerifyFlags;
  81. /* Get a textual representation of |result|. */
  82. const char* avb_slot_verify_result_to_string(AvbSlotVerifyResult result);
  83. /* Maximum number of rollback index locations supported. */
  84. #define AVB_MAX_NUMBER_OF_ROLLBACK_INDEX_LOCATIONS 32
  85. /* AvbPartitionData contains data loaded from partitions when using
  86. * avb_slot_verify(). The |partition_name| field contains the name of
  87. * the partition (without A/B suffix), |data| points to the loaded
  88. * data which is |data_size| bytes long. If |preloaded| is set to true,
  89. * this structure dose not own |data|. The caller of |avb_slot_verify|
  90. * needs to make sure that the preloaded data outlives this
  91. * |AvbPartitionData| structure.
  92. *
  93. * Note that this is strictly less than the partition size - it's only
  94. * the image stored there, not the entire partition nor any of the
  95. * metadata.
  96. */
  97. typedef struct {
  98. char* partition_name;
  99. uint8_t* data;
  100. size_t data_size;
  101. bool preloaded;
  102. } AvbPartitionData;
  103. /* AvbVBMetaData contains a vbmeta struct loaded from a partition when
  104. * using avb_slot_verify(). The |partition_name| field contains the
  105. * name of the partition (without A/B suffix), |vbmeta_data| points to
  106. * the loaded data which is |vbmeta_size| bytes long.
  107. *
  108. * The |verify_result| field contains the result of
  109. * avb_vbmeta_image_verify() on the data. This is guaranteed to be
  110. * AVB_VBMETA_VERIFY_RESULT_OK for all vbmeta images if
  111. * avb_slot_verify() returns AVB_SLOT_VERIFY_RESULT_OK.
  112. *
  113. * You can use avb_descriptor_get_all(), avb_descriptor_foreach(), and
  114. * avb_vbmeta_image_header_to_host_byte_order() with this data.
  115. */
  116. typedef struct {
  117. char* partition_name;
  118. uint8_t* vbmeta_data;
  119. size_t vbmeta_size;
  120. AvbVBMetaVerifyResult verify_result;
  121. } AvbVBMetaData;
  122. /* AvbSlotVerifyData contains data needed to boot a particular slot
  123. * and is returned by avb_slot_verify() if partitions in a slot are
  124. * successfully verified.
  125. *
  126. * All data pointed to by this struct - including data in each item in
  127. * the |partitions| array - will be freed when the
  128. * avb_slot_verify_data_free() function is called.
  129. *
  130. * The |ab_suffix| field is the copy of the of |ab_suffix| field
  131. * passed to avb_slot_verify(). It is the A/B suffix of the slot. This
  132. * value includes the leading underscore - typical values are "" (if
  133. * no slots are in use), "_a" (for the first slot), and "_b" (for the
  134. * second slot).
  135. *
  136. * The VBMeta images that were checked are available in the
  137. * |vbmeta_images| field. The field |num_vbmeta_images| contains the
  138. * number of elements in this array. The first element -
  139. * vbmeta_images[0] - is guaranteed to be from the partition with the
  140. * top-level vbmeta struct. This is usually the "vbmeta" partition in
  141. * the requested slot but if there is no "vbmeta" partition it can
  142. * also be the "boot" partition.
  143. *
  144. * The partitions loaded and verified from from the slot are
  145. * accessible in the |loaded_partitions| array. The field
  146. * |num_loaded_partitions| contains the number of elements in this
  147. * array. The order of partitions in this array may not necessarily be
  148. * the same order as in the passed-in |requested_partitions| array.
  149. *
  150. * Rollback indexes for the verified slot are stored in the
  151. * |rollback_indexes| field. Note that avb_slot_verify() will NEVER
  152. * modify stored_rollback_index[n] locations e.g. it will never use
  153. * the write_rollback_index() AvbOps operation. Instead it is the job
  154. * of the caller of avb_slot_verify() to do this based on e.g. A/B
  155. * policy and other factors. See libavb_ab/avb_ab_flow.c for an
  156. * example of how to do this.
  157. *
  158. * The |cmdline| field is a NUL-terminated string in UTF-8 resulting
  159. * from concatenating all |AvbKernelCmdlineDescriptor| and then
  160. * performing proper substitution of the variables
  161. * $(ANDROID_SYSTEM_PARTUUID), $(ANDROID_BOOT_PARTUUID), and
  162. * $(ANDROID_VBMETA_PARTUUID) using the
  163. * get_unique_guid_for_partition() operation in |AvbOps|. Additionally
  164. * $(ANDROID_VERITY_MODE) will be replaced with the proper dm-verity
  165. * option depending on the value of |hashtree_error_mode|.
  166. *
  167. * Additionally, the |cmdline| field will have the following kernel
  168. * command-line options set (unless verification is disabled, see
  169. * below):
  170. *
  171. * androidboot.veritymode: This is set to 'disabled' if the
  172. * AVB_VBMETA_IMAGE_FLAGS_HASHTREE_DISABLED flag is set in top-level
  173. * vbmeta struct. Otherwise it is set to 'enforcing' if the
  174. * passed-in hashtree error mode is AVB_HASHTREE_ERROR_MODE_RESTART
  175. * or AVB_HASHTREE_ERROR_MODE_RESTART_AND_INVALIDATE, 'eio' if it's
  176. * set to AVB_HASHTREE_ERROR_MODE_EIO, and 'logging' if it's set to
  177. * AVB_HASHTREE_ERROR_MODE_LOGGING.
  178. *
  179. * androidboot.vbmeta.invalidate_on_error: This is set to 'yes' only
  180. * if hashtree validation isn't disabled and the passed-in hashtree
  181. * error mode is AVB_HASHTREE_ERROR_MODE_RESTART_AND_INVALIDATE.
  182. *
  183. * androidboot.vbmeta.device_state: set to "locked" or "unlocked"
  184. * depending on the result of the result of AvbOps's
  185. * read_is_unlocked() function.
  186. *
  187. * androidboot.vbmeta.{hash_alg, size, digest}: Will be set to
  188. * the digest of all images in |vbmeta_images|.
  189. *
  190. * androidboot.vbmeta.device: This is set to the value
  191. * PARTUUID=$(ANDROID_VBMETA_PARTUUID) before substitution so it
  192. * will end up pointing to the vbmeta partition for the verified
  193. * slot. If there is no vbmeta partition it will point to the boot
  194. * partition of the verified slot.
  195. *
  196. * androidboot.vbmeta.avb_version: This is set to the decimal value
  197. * of AVB_VERSION_MAJOR followed by a dot followed by the decimal
  198. * value of AVB_VERSION_MINOR, for example "1.0" or "1.4". This
  199. * version number represents the vbmeta file format version
  200. * supported by libavb copy used in the boot loader. This is not
  201. * necessarily the same version number of the on-disk metadata for
  202. * the slot that was verified.
  203. *
  204. * Note that androidboot.slot_suffix is not set in the |cmdline| field
  205. * in |AvbSlotVerifyData| - you will have to set this yourself.
  206. *
  207. * If the |AVB_VBMETA_IMAGE_FLAGS_VERIFICATION_DISABLED| flag is set
  208. * in the top-level vbmeta struct then only the top-level vbmeta
  209. * struct is verified and descriptors will not processed. The return
  210. * value will be set accordingly (if this flag is set via 'avbctl
  211. * disable-verification' then the return value will be
  212. * |AVB_SLOT_VERIFY_RESULT_ERROR_VERIFICATION|) and
  213. * |AvbSlotVerifyData| is returned. Additionally all partitions in the
  214. * |requested_partitions| are loaded and the |cmdline| field is set to
  215. * "root=PARTUUID=$(ANDROID_SYSTEM_PARTUUID)" and the GUID for the
  216. * appropriate system partition is substituted in. Note that none of
  217. * the androidboot.* options mentioned above will be set.
  218. *
  219. * This struct may grow in the future without it being considered an
  220. * ABI break.
  221. */
  222. typedef struct {
  223. char* ab_suffix;
  224. AvbVBMetaData* vbmeta_images;
  225. size_t num_vbmeta_images;
  226. AvbPartitionData* loaded_partitions;
  227. size_t num_loaded_partitions;
  228. char* cmdline;
  229. uint64_t rollback_indexes[AVB_MAX_NUMBER_OF_ROLLBACK_INDEX_LOCATIONS];
  230. } AvbSlotVerifyData;
  231. /* Calculates a digest of all vbmeta images in |data| using
  232. * the digest indicated by |digest_type|. Stores the result
  233. * in |out_digest| which must be large enough to hold a digest
  234. * of the requested type.
  235. */
  236. void avb_slot_verify_data_calculate_vbmeta_digest(AvbSlotVerifyData* data,
  237. AvbDigestType digest_type,
  238. uint8_t* out_digest);
  239. /* Frees a |AvbSlotVerifyData| including all data it points to. */
  240. void avb_slot_verify_data_free(AvbSlotVerifyData* data);
  241. /* Performs a full verification of the slot identified by |ab_suffix|
  242. * and load and verify the contents of the partitions whose name is in
  243. * the NULL-terminated string array |requested_partitions| (each
  244. * partition must use hash verification). If not using A/B, pass an
  245. * empty string (e.g. "", not NULL) for |ab_suffix|. This parameter
  246. * must include the leading underscore, for example "_a" should be
  247. * used to refer to the first slot.
  248. *
  249. * Typically the |requested_partitions| array only contains a single
  250. * item for the boot partition, 'boot'.
  251. *
  252. * Verification includes loading and verifying data from the 'vbmeta',
  253. * the requested hash partitions, and possibly other partitions (with
  254. * |ab_suffix| appended), inspecting rollback indexes, and checking if
  255. * the public key used to sign the data is acceptable. The functions
  256. * in |ops| will be used to do this.
  257. *
  258. * If |out_data| is not NULL, it will be set to a newly allocated
  259. * |AvbSlotVerifyData| struct containing all the data needed to
  260. * actually boot the slot. This data structure should be freed with
  261. * avb_slot_verify_data_free() when you are done with it. See below
  262. * for when this is returned.
  263. *
  264. * The |flags| parameter is used to influence the semantics of
  265. * avb_slot_verify() - for example the
  266. * AVB_SLOT_VERIFY_FLAGS_ALLOW_VERIFICATION_ERROR flag can be used to
  267. * ignore verification errors which is something needed in the
  268. * UNLOCKED state. See the AvbSlotVerifyFlags enumeration for details.
  269. *
  270. * The |hashtree_error_mode| parameter should be set to the desired
  271. * error handling mode when hashtree validation fails inside the
  272. * HLOS. This value isn't used by libavb per se - it is forwarded to
  273. * the HLOS through the androidboot.veritymode and
  274. * androidboot.vbmeta.invalidate_on_error cmdline parameters. See the
  275. * AvbHashtreeErrorMode enumeration for details.
  276. *
  277. * Also note that |out_data| is never set if
  278. * AVB_SLOT_VERIFY_RESULT_ERROR_OOM, AVB_SLOT_VERIFY_RESULT_ERROR_IO,
  279. * or AVB_SLOT_VERIFY_RESULT_ERROR_INVALID_METADATA is returned.
  280. *
  281. * AVB_SLOT_VERIFY_RESULT_OK is returned if everything is verified
  282. * correctly and all public keys are accepted.
  283. *
  284. * AVB_SLOT_VERIFY_RESULT_ERROR_PUBLIC_KEY_REJECTED is returned if
  285. * everything is verified correctly out but one or more public keys
  286. * are not accepted. This includes the case where integrity data is
  287. * not signed.
  288. *
  289. * AVB_SLOT_VERIFY_RESULT_ERROR_OOM is returned if unable to
  290. * allocate memory.
  291. *
  292. * AVB_SLOT_VERIFY_RESULT_ERROR_IO is returned if an I/O error
  293. * occurred while trying to load data or get a rollback index.
  294. *
  295. * AVB_SLOT_VERIFY_RESULT_ERROR_VERIFICATION is returned if the data
  296. * did not verify, e.g. the digest didn't match or signature checks
  297. * failed.
  298. *
  299. * AVB_SLOT_VERIFY_RESULT_ERROR_ROLLBACK_INDEX is returned if a
  300. * rollback index was less than its stored value.
  301. *
  302. * AVB_SLOT_VERIFY_RESULT_ERROR_INVALID_METADATA is returned if some
  303. * of the metadata is invalid or inconsistent.
  304. *
  305. * AVB_SLOT_VERIFY_RESULT_ERROR_UNSUPPORTED_VERSION is returned if
  306. * some of the metadata requires a newer version of libavb than what
  307. * is in use.
  308. *
  309. * AVB_SLOT_VERIFY_RESULT_ERROR_INVALID_ARGUMENT is returned if the
  310. * caller passed invalid parameters, for example trying to use
  311. * AVB_HASHTREE_ERROR_MODE_LOGGING without
  312. * AVB_SLOT_VERIFY_FLAGS_ALLOW_VERIFICATION_ERROR.
  313. */
  314. AvbSlotVerifyResult avb_slot_verify(AvbOps* ops,
  315. const char* const* requested_partitions,
  316. const char* ab_suffix,
  317. AvbSlotVerifyFlags flags,
  318. AvbHashtreeErrorMode hashtree_error_mode,
  319. AvbSlotVerifyData** out_data);
  320. #ifdef __cplusplus
  321. }
  322. #endif
  323. #endif /* AVB_SLOT_VERIFY_H_ */