avb_descriptor.h 3.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112
  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_DESCRIPTOR_H_
  9. #define AVB_DESCRIPTOR_H_
  10. #include "avb_sysdeps.h"
  11. #ifdef __cplusplus
  12. extern "C" {
  13. #endif
  14. /* Well-known descriptor tags.
  15. *
  16. * AVB_DESCRIPTOR_TAG_PROPERTY: see |AvbPropertyDescriptor| struct.
  17. * AVB_DESCRIPTOR_TAG_HASHTREE: see |AvbHashtreeDescriptor| struct.
  18. * AVB_DESCRIPTOR_TAG_HASH: see |AvbHashDescriptor| struct.
  19. * AVB_DESCRIPTOR_TAG_KERNEL_CMDLINE: see |AvbKernelCmdlineDescriptor| struct.
  20. * AVB_DESCRIPTOR_TAG_CHAIN_PARTITION: see |AvbChainPartitionDescriptor| struct.
  21. */
  22. typedef enum {
  23. AVB_DESCRIPTOR_TAG_PROPERTY,
  24. AVB_DESCRIPTOR_TAG_HASHTREE,
  25. AVB_DESCRIPTOR_TAG_HASH,
  26. AVB_DESCRIPTOR_TAG_KERNEL_CMDLINE,
  27. AVB_DESCRIPTOR_TAG_CHAIN_PARTITION,
  28. } AvbDescriptorTag;
  29. /* The header for a serialized descriptor.
  30. *
  31. * A descriptor always have two fields, a |tag| (denoting its type,
  32. * see the |AvbDescriptorTag| enumeration) and the size of the bytes
  33. * following, |num_bytes_following|.
  34. *
  35. * For padding, |num_bytes_following| is always a multiple of 8.
  36. */
  37. typedef struct AvbDescriptor {
  38. uint64_t tag;
  39. uint64_t num_bytes_following;
  40. } AVB_ATTR_PACKED AvbDescriptor;
  41. /* Copies |src| to |dest| and validates, byte-swapping fields in the
  42. * process if needed. Returns true if valid, false if invalid.
  43. *
  44. * Data following the struct is not validated nor copied.
  45. */
  46. bool avb_descriptor_validate_and_byteswap(
  47. const AvbDescriptor* src, AvbDescriptor* dest) AVB_ATTR_WARN_UNUSED_RESULT;
  48. /* Signature for callback function used in avb_descriptor_foreach().
  49. * The passed in descriptor is given by |descriptor| and the
  50. * |user_data| passed to avb_descriptor_foreach() function is in
  51. * |user_data|. Return true to continue iterating, false to stop
  52. * iterating.
  53. *
  54. * Note that |descriptor| points into the image passed to
  55. * avb_descriptor_foreach() - all fields need to be byteswapped!
  56. */
  57. typedef bool AvbDescriptorForeachFunc(const AvbDescriptor* descriptor,
  58. void* user_data);
  59. /* Convenience function to iterate over all descriptors in an vbmeta
  60. * image.
  61. *
  62. * The function given by |foreach_func| will be called for each
  63. * descriptor. The given function should return true to continue
  64. * iterating, false to stop.
  65. *
  66. * The |user_data| parameter will be passed to |foreach_func|.
  67. *
  68. * Returns false if the iteration was short-circuited, that is if
  69. * an invocation of |foreach_func| returned false.
  70. *
  71. * Before using this function, you MUST verify |image_data| with
  72. * avb_vbmeta_image_verify() and reject it unless it's signed by a known
  73. * good public key. Additionally, |image_data| must be word-aligned.
  74. */
  75. bool avb_descriptor_foreach(const uint8_t* image_data,
  76. size_t image_size,
  77. AvbDescriptorForeachFunc foreach_func,
  78. void* user_data);
  79. /* Gets all descriptors in a vbmeta image.
  80. *
  81. * The return value is a NULL-pointer terminated array of
  82. * AvbDescriptor pointers. Free with avb_free() when you are done with
  83. * it. If |out_num_descriptors| is non-NULL, the number of descriptors
  84. * will be returned there.
  85. *
  86. * Note that each AvbDescriptor pointer in the array points into
  87. * |image_data| - all fields need to be byteswapped!
  88. *
  89. * Before using this function, you MUST verify |image_data| with
  90. * avb_vbmeta_image_verify() and reject it unless it's signed by a known
  91. * good public key. Additionally, |image_data| must be word-aligned.
  92. */
  93. const AvbDescriptor** avb_descriptor_get_all(const uint8_t* image_data,
  94. size_t image_size,
  95. size_t* out_num_descriptors)
  96. AVB_ATTR_WARN_UNUSED_RESULT;
  97. #ifdef __cplusplus
  98. }
  99. #endif
  100. #endif /* AVB_DESCRIPTOR_H_ */