avb_slot_verify.h 17 KB

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