LXR uboot/lib/libavb/avb

   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
  16extern "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 */
  27typedef 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 */
  43typedef 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 */
  53bool 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 */
  65typedef 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 */
  84bool 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 */
 103const 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_ */
 113