lib/libavb/avb_descriptor.h

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