lib/libavb/avb_descriptor.h

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