xref: /openbmc/u-boot/lib/libavb/avb_descriptor.h (revision 4ac5df4b)
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_ */
113