blob: 5d0f0c699fe18f68d7504f2f9842a685ae3a53ec
1 | /* |
2 | * Copyright (C) 2016 The Android Open Source Project |
3 | * |
4 | * Permission is hereby granted, free of charge, to any person |
5 | * obtaining a copy of this software and associated documentation |
6 | * files (the "Software"), to deal in the Software without |
7 | * restriction, including without limitation the rights to use, copy, |
8 | * modify, merge, publish, distribute, sublicense, and/or sell copies |
9 | * of the Software, and to permit persons to whom the Software is |
10 | * furnished to do so, subject to the following conditions: |
11 | * |
12 | * The above copyright notice and this permission notice shall be |
13 | * included in all copies or substantial portions of the Software. |
14 | * |
15 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, |
16 | * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF |
17 | * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND |
18 | * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS |
19 | * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN |
20 | * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN |
21 | * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE |
22 | * SOFTWARE. |
23 | */ |
24 | |
25 | #if !defined(AVB_INSIDE_LIBAVB_H) && !defined(AVB_COMPILATION) |
26 | #error "Never include this file directly, include libavb.h instead." |
27 | #endif |
28 | |
29 | #ifndef AVB_DESCRIPTOR_H_ |
30 | #define AVB_DESCRIPTOR_H_ |
31 | |
32 | #include "avb_sysdeps.h" |
33 | |
34 | #ifdef __cplusplus |
35 | extern "C" { |
36 | #endif |
37 | |
38 | /* Well-known descriptor tags. |
39 | * |
40 | * AVB_DESCRIPTOR_TAG_PROPERTY: see |AvbPropertyDescriptor| struct. |
41 | * AVB_DESCRIPTOR_TAG_HASHTREE: see |AvbHashtreeDescriptor| struct. |
42 | * AVB_DESCRIPTOR_TAG_HASH: see |AvbHashDescriptor| struct. |
43 | * AVB_DESCRIPTOR_TAG_KERNEL_CMDLINE: see |AvbKernelCmdlineDescriptor| struct. |
44 | * AVB_DESCRIPTOR_TAG_CHAIN_PARTITION: see |AvbChainPartitionDescriptor| struct. |
45 | */ |
46 | typedef enum { |
47 | AVB_DESCRIPTOR_TAG_PROPERTY, |
48 | AVB_DESCRIPTOR_TAG_HASHTREE, |
49 | AVB_DESCRIPTOR_TAG_HASH, |
50 | AVB_DESCRIPTOR_TAG_KERNEL_CMDLINE, |
51 | AVB_DESCRIPTOR_TAG_CHAIN_PARTITION, |
52 | } AvbDescriptorTag; |
53 | |
54 | /* The header for a serialized descriptor. |
55 | * |
56 | * A descriptor always have two fields, a |tag| (denoting its type, |
57 | * see the |AvbDescriptorTag| enumeration) and the size of the bytes |
58 | * following, |num_bytes_following|. |
59 | * |
60 | * For padding, |num_bytes_following| is always a multiple of 8. |
61 | */ |
62 | typedef struct AvbDescriptor { |
63 | uint64_t tag; |
64 | uint64_t num_bytes_following; |
65 | } AVB_ATTR_PACKED AvbDescriptor; |
66 | |
67 | /* Copies |src| to |dest| and validates, byte-swapping fields in the |
68 | * process if needed. Returns true if valid, false if invalid. |
69 | * |
70 | * Data following the struct is not validated nor copied. |
71 | */ |
72 | bool avb_descriptor_validate_and_byteswap( |
73 | const AvbDescriptor* src, AvbDescriptor* dest) AVB_ATTR_WARN_UNUSED_RESULT; |
74 | |
75 | /* Signature for callback function used in avb_descriptor_foreach(). |
76 | * The passed in descriptor is given by |descriptor| and the |
77 | * |user_data| passed to avb_descriptor_foreach() function is in |
78 | * |user_data|. Return true to continue iterating, false to stop |
79 | * iterating. |
80 | * |
81 | * Note that |descriptor| points into the image passed to |
82 | * avb_descriptor_foreach() - all fields need to be byteswapped! |
83 | */ |
84 | typedef bool AvbDescriptorForeachFunc(const AvbDescriptor* descriptor, |
85 | void* user_data); |
86 | |
87 | /* Convenience function to iterate over all descriptors in an vbmeta |
88 | * image. |
89 | * |
90 | * The function given by |foreach_func| will be called for each |
91 | * descriptor. The given function should return true to continue |
92 | * iterating, false to stop. |
93 | * |
94 | * The |user_data| parameter will be passed to |foreach_func|. |
95 | * |
96 | * Returns false if the iteration was short-circuited, that is if |
97 | * an invocation of |foreach_func| returned false. |
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 | bool avb_descriptor_foreach(const uint8_t* image_data, |
104 | size_t image_size, |
105 | AvbDescriptorForeachFunc foreach_func, |
106 | void* user_data); |
107 | |
108 | /* Gets all descriptors in a vbmeta image. |
109 | * |
110 | * The return value is a NULL-pointer terminated array of |
111 | * AvbDescriptor pointers. Free with avb_free() when you are done with |
112 | * it. If |out_num_descriptors| is non-NULL, the number of descriptors |
113 | * will be returned there. |
114 | * |
115 | * Note that each AvbDescriptor pointer in the array points into |
116 | * |image_data| - all fields need to be byteswapped! |
117 | * |
118 | * Before using this function, you MUST verify |image_data| with |
119 | * avb_vbmeta_image_verify() and reject it unless it's signed by a known |
120 | * good public key. Additionally, |image_data| must be word-aligned. |
121 | */ |
122 | const AvbDescriptor** avb_descriptor_get_all(const uint8_t* image_data, |
123 | size_t image_size, |
124 | size_t* out_num_descriptors) |
125 | AVB_ATTR_WARN_UNUSED_RESULT; |
126 | |
127 | #ifdef __cplusplus |
128 | } |
129 | #endif |
130 | |
131 | #endif /* AVB_DESCRIPTOR_H_ */ |
132 |