avb_vbmeta_image.h 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275
  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_VBMETA_IMAGE_H_
  9. #define AVB_VBMETA_IMAGE_H_
  10. #include "avb_sysdeps.h"
  11. #ifdef __cplusplus
  12. extern "C" {
  13. #endif
  14. #include "avb_crypto.h"
  15. #include "avb_descriptor.h"
  16. /* Size of the vbmeta image header. */
  17. #define AVB_VBMETA_IMAGE_HEADER_SIZE 256
  18. /* Magic for the vbmeta image header. */
  19. #define AVB_MAGIC "AVB0"
  20. #define AVB_MAGIC_LEN 4
  21. /* Maximum size of the release string including the terminating NUL byte. */
  22. #define AVB_RELEASE_STRING_SIZE 48
  23. /* Flags for the vbmeta image.
  24. *
  25. * AVB_VBMETA_IMAGE_FLAGS_HASHTREE_DISABLED: If this flag is set,
  26. * hashtree image verification will be disabled.
  27. *
  28. * AVB_VBMETA_IMAGE_FLAGS_VERIFICATION_DISABLED: If this flag is set,
  29. * verification will be disabled and descriptors will not be parsed.
  30. */
  31. typedef enum {
  32. AVB_VBMETA_IMAGE_FLAGS_HASHTREE_DISABLED = (1 << 0),
  33. AVB_VBMETA_IMAGE_FLAGS_VERIFICATION_DISABLED = (1 << 1)
  34. } AvbVBMetaImageFlags;
  35. /* Binary format for header of the vbmeta image.
  36. *
  37. * The vbmeta image consists of three blocks:
  38. *
  39. * +-----------------------------------------+
  40. * | Header data - fixed size |
  41. * +-----------------------------------------+
  42. * | Authentication data - variable size |
  43. * +-----------------------------------------+
  44. * | Auxiliary data - variable size |
  45. * +-----------------------------------------+
  46. *
  47. * The "Header data" block is described by this struct and is always
  48. * |AVB_VBMETA_IMAGE_HEADER_SIZE| bytes long.
  49. *
  50. * The "Authentication data" block is |authentication_data_block_size|
  51. * bytes long and contains the hash and signature used to authenticate
  52. * the vbmeta image. The type of the hash and signature is defined by
  53. * the |algorithm_type| field.
  54. *
  55. * The "Auxiliary data" is |auxiliary_data_block_size| bytes long and
  56. * contains the auxiliary data including the public key used to make
  57. * the signature and descriptors.
  58. *
  59. * The public key is at offset |public_key_offset| with size
  60. * |public_key_size| in this block. The size of the public key data is
  61. * defined by the |algorithm_type| field. The format of the public key
  62. * data is described in the |AvbRSAPublicKeyHeader| struct.
  63. *
  64. * The descriptors starts at |descriptors_offset| from the beginning
  65. * of the "Auxiliary Data" block and take up |descriptors_size|
  66. * bytes. Each descriptor is stored as a |AvbDescriptor| with tag and
  67. * number of bytes following. The number of descriptors can be
  68. * determined by walking this data until |descriptors_size| is
  69. * exhausted.
  70. *
  71. * The size of each of the "Authentication data" and "Auxiliary data"
  72. * blocks must be divisible by 64. This is to ensure proper alignment.
  73. *
  74. * Descriptors are free-form blocks stored in a part of the vbmeta
  75. * image subject to the same integrity checks as the rest of the
  76. * image. See the documentation for |AvbDescriptor| for well-known
  77. * descriptors. See avb_descriptor_foreach() for a convenience
  78. * function to iterate over descriptors.
  79. *
  80. * This struct is versioned, see the |required_libavb_version_major|
  81. * and |required_libavb_version_minor| fields. This represents the
  82. * minimum version of libavb required to verify the header and depends
  83. * on the features (e.g. algorithms, descriptors) used. Note that this
  84. * may be 1.0 even if generated by an avbtool from 1.4 but where no
  85. * features introduced after 1.0 has been used. See the "Versioning
  86. * and compatibility" section in the README.md file for more details.
  87. *
  88. * All fields are stored in network byte order when serialized. To
  89. * generate a copy with fields swapped to native byte order, use the
  90. * function avb_vbmeta_image_header_to_host_byte_order().
  91. *
  92. * Before reading and/or using any of this data, you MUST verify it
  93. * using avb_vbmeta_image_verify() and reject it unless it's signed by
  94. * a known good public key.
  95. */
  96. typedef struct AvbVBMetaImageHeader {
  97. /* 0: Four bytes equal to "AVB0" (AVB_MAGIC). */
  98. uint8_t magic[AVB_MAGIC_LEN];
  99. /* 4: The major version of libavb required for this header. */
  100. uint32_t required_libavb_version_major;
  101. /* 8: The minor version of libavb required for this header. */
  102. uint32_t required_libavb_version_minor;
  103. /* 12: The size of the signature block. */
  104. uint64_t authentication_data_block_size;
  105. /* 20: The size of the auxiliary data block. */
  106. uint64_t auxiliary_data_block_size;
  107. /* 28: The verification algorithm used, see |AvbAlgorithmType| enum. */
  108. uint32_t algorithm_type;
  109. /* 32: Offset into the "Authentication data" block of hash data. */
  110. uint64_t hash_offset;
  111. /* 40: Length of the hash data. */
  112. uint64_t hash_size;
  113. /* 48: Offset into the "Authentication data" block of signature data. */
  114. uint64_t signature_offset;
  115. /* 56: Length of the signature data. */
  116. uint64_t signature_size;
  117. /* 64: Offset into the "Auxiliary data" block of public key data. */
  118. uint64_t public_key_offset;
  119. /* 72: Length of the public key data. */
  120. uint64_t public_key_size;
  121. /* 80: Offset into the "Auxiliary data" block of public key metadata. */
  122. uint64_t public_key_metadata_offset;
  123. /* 88: Length of the public key metadata. Must be set to zero if there
  124. * is no public key metadata.
  125. */
  126. uint64_t public_key_metadata_size;
  127. /* 96: Offset into the "Auxiliary data" block of descriptor data. */
  128. uint64_t descriptors_offset;
  129. /* 104: Length of descriptor data. */
  130. uint64_t descriptors_size;
  131. /* 112: The rollback index which can be used to prevent rollback to
  132. * older versions.
  133. */
  134. uint64_t rollback_index;
  135. /* 120: Flags from the AvbVBMetaImageFlags enumeration. This must be
  136. * set to zero if the vbmeta image is not a top-level image.
  137. */
  138. uint32_t flags;
  139. /* 124: Reserved to ensure |release_string| start on a 16-byte
  140. * boundary. Must be set to zeroes.
  141. */
  142. uint8_t reserved0[4];
  143. /* 128: The release string from avbtool, e.g. "avbtool 1.0.0" or
  144. * "avbtool 1.0.0 xyz_board Git-234abde89". Is guaranteed to be NUL
  145. * terminated. Applications must not make assumptions about how this
  146. * string is formatted.
  147. */
  148. uint8_t release_string[AVB_RELEASE_STRING_SIZE];
  149. /* 176: Padding to ensure struct is size AVB_VBMETA_IMAGE_HEADER_SIZE
  150. * bytes. This must be set to zeroes.
  151. */
  152. uint8_t reserved[80];
  153. } AVB_ATTR_PACKED AvbVBMetaImageHeader;
  154. /* Copies |src| to |dest|, byte-swapping fields in the process.
  155. *
  156. * Make sure you've verified |src| using avb_vbmeta_image_verify()
  157. * before accessing the data and/or using this function.
  158. */
  159. void avb_vbmeta_image_header_to_host_byte_order(const AvbVBMetaImageHeader* src,
  160. AvbVBMetaImageHeader* dest);
  161. /* Return codes used in avb_vbmeta_image_verify().
  162. *
  163. * AVB_VBMETA_VERIFY_RESULT_OK is returned if the vbmeta image header
  164. * is valid, the hash is correct and the signature is correct. Keep in
  165. * mind that you still need to check that you know the public key used
  166. * to sign the image, see avb_vbmeta_image_verify() for details.
  167. *
  168. * AVB_VBMETA_VERIFY_RESULT_OK_NOT_SIGNED is returned if the vbmeta
  169. * image header is valid but there is no signature or hash.
  170. *
  171. * AVB_VBMETA_VERIFY_RESULT_INVALID_VBMETA_HEADER is returned if the
  172. * header of the vbmeta image is invalid, for example, invalid magic
  173. * or inconsistent data.
  174. *
  175. * AVB_VBMETA_VERIFY_RESULT_UNSUPPORTED_VERSION is returned if a) the
  176. * vbmeta image requires a minimum version of libavb which exceeds the
  177. * version of libavb used; or b) the vbmeta image major version
  178. * differs from the major version of libavb in use.
  179. *
  180. * AVB_VBMETA_VERIFY_RESULT_HASH_MISMATCH is returned if the hash
  181. * stored in the "Authentication data" block does not match the
  182. * calculated hash.
  183. *
  184. * AVB_VBMETA_VERIFY_RESULT_SIGNATURE_MISMATCH is returned if the
  185. * signature stored in the "Authentication data" block is invalid or
  186. * doesn't match the public key stored in the vbmeta image.
  187. */
  188. typedef enum {
  189. AVB_VBMETA_VERIFY_RESULT_OK,
  190. AVB_VBMETA_VERIFY_RESULT_OK_NOT_SIGNED,
  191. AVB_VBMETA_VERIFY_RESULT_INVALID_VBMETA_HEADER,
  192. AVB_VBMETA_VERIFY_RESULT_UNSUPPORTED_VERSION,
  193. AVB_VBMETA_VERIFY_RESULT_HASH_MISMATCH,
  194. AVB_VBMETA_VERIFY_RESULT_SIGNATURE_MISMATCH,
  195. } AvbVBMetaVerifyResult;
  196. /* Get a textual representation of |result|. */
  197. const char* avb_vbmeta_verify_result_to_string(AvbVBMetaVerifyResult result);
  198. /* Checks that vbmeta image at |data| of size |length| is a valid
  199. * vbmeta image. The complete contents of the vbmeta image must be
  200. * passed in. It's fine if |length| is bigger than the actual image,
  201. * typically callers of this function will load the entire contents of
  202. * the 'vbmeta_a' or 'vbmeta_b' partition and pass in its length (for
  203. * example, 1 MiB).
  204. *
  205. * See the |AvbVBMetaImageHeader| struct for information about the
  206. * three blocks (header, authentication, auxiliary) that make up a
  207. * vbmeta image.
  208. *
  209. * If the function returns |AVB_VBMETA_VERIFY_RESULT_OK| and
  210. * |out_public_key_data| is non-NULL, it will be set to point inside
  211. * |data| for where the serialized public key data is stored and
  212. * |out_public_key_length|, if non-NULL, will be set to the length of
  213. * the public key data. If there is no public key in the metadata then
  214. * |out_public_key_data| is set to NULL.
  215. *
  216. * See the |AvbVBMetaVerifyResult| enum for possible return values.
  217. *
  218. * VERY IMPORTANT:
  219. *
  220. * 1. Even if |AVB_VBMETA_VERIFY_RESULT_OK| is returned, you still
  221. * need to check that the public key embedded in the image
  222. * matches a known key! You can use 'avbtool extract_public_key'
  223. * to extract the key (at build time, then store it along your
  224. * code) and compare it to what is returned in
  225. * |out_public_key_data|.
  226. *
  227. * 2. You need to check the |rollback_index| field against a stored
  228. * value in NVRAM and reject the vbmeta image if the value in
  229. * NVRAM is bigger than |rollback_index|. You must also update
  230. * the value stored in NVRAM to the smallest value of
  231. * |rollback_index| field from boot images in all bootable and
  232. * authentic slots marked as GOOD.
  233. *
  234. * This is a low-level function to only verify the vbmeta data - you
  235. * are likely looking for avb_slot_verify() instead for verifying
  236. * integrity data for a whole set of partitions.
  237. */
  238. AvbVBMetaVerifyResult avb_vbmeta_image_verify(
  239. const uint8_t* data,
  240. size_t length,
  241. const uint8_t** out_public_key_data,
  242. size_t* out_public_key_length) AVB_ATTR_WARN_UNUSED_RESULT;
  243. #ifdef __cplusplus
  244. }
  245. #endif
  246. #endif /* AVB_VBMETA_IMAGE_H_ */