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_VBMETA_IMAGE_H_
11 #define AVB_VBMETA_IMAGE_H_
12 
13 #include "avb_sysdeps.h"
14 
15 #ifdef __cplusplus
16 extern "C" {
17 #endif
18 
19 #include "avb_crypto.h"
20 #include "avb_descriptor.h"
21 
22 /* Size of the vbmeta image header. */
23 #define AVB_VBMETA_IMAGE_HEADER_SIZE 256
24 
25 /* Magic for the vbmeta image header. */
26 #define AVB_MAGIC "AVB0"
27 #define AVB_MAGIC_LEN 4
28 
29 /* Maximum size of the release string including the terminating NUL byte. */
30 #define AVB_RELEASE_STRING_SIZE 48
31 
32 /* Flags for the vbmeta image.
33  *
34  * AVB_VBMETA_IMAGE_FLAGS_HASHTREE_DISABLED: If this flag is set,
35  * hashtree image verification will be disabled.
36  *
37  * AVB_VBMETA_IMAGE_FLAGS_VERIFICATION_DISABLED: If this flag is set,
38  * verification will be disabled and descriptors will not be parsed.
39  */
40 typedef enum {
41   AVB_VBMETA_IMAGE_FLAGS_HASHTREE_DISABLED = (1 << 0),
42   AVB_VBMETA_IMAGE_FLAGS_VERIFICATION_DISABLED = (1 << 1)
43 } AvbVBMetaImageFlags;
44 
45 /* Binary format for header of the vbmeta image.
46  *
47  * The vbmeta image consists of three blocks:
48  *
49  *  +-----------------------------------------+
50  *  | Header data - fixed size                |
51  *  +-----------------------------------------+
52  *  | Authentication data - variable size     |
53  *  +-----------------------------------------+
54  *  | Auxiliary data - variable size          |
55  *  +-----------------------------------------+
56  *
57  * The "Header data" block is described by this struct and is always
58  * |AVB_VBMETA_IMAGE_HEADER_SIZE| bytes long.
59  *
60  * The "Authentication data" block is |authentication_data_block_size|
61  * bytes long and contains the hash and signature used to authenticate
62  * the vbmeta image. The type of the hash and signature is defined by
63  * the |algorithm_type| field.
64  *
65  * The "Auxiliary data" is |auxiliary_data_block_size| bytes long and
66  * contains the auxiliary data including the public key used to make
67  * the signature and descriptors.
68  *
69  * The public key is at offset |public_key_offset| with size
70  * |public_key_size| in this block. The size of the public key data is
71  * defined by the |algorithm_type| field. The format of the public key
72  * data is described in the |AvbRSAPublicKeyHeader| struct.
73  *
74  * The descriptors starts at |descriptors_offset| from the beginning
75  * of the "Auxiliary Data" block and take up |descriptors_size|
76  * bytes. Each descriptor is stored as a |AvbDescriptor| with tag and
77  * number of bytes following. The number of descriptors can be
78  * determined by walking this data until |descriptors_size| is
79  * exhausted.
80  *
81  * The size of each of the "Authentication data" and "Auxiliary data"
82  * blocks must be divisible by 64. This is to ensure proper alignment.
83  *
84  * Descriptors are free-form blocks stored in a part of the vbmeta
85  * image subject to the same integrity checks as the rest of the
86  * image. See the documentation for |AvbDescriptor| for well-known
87  * descriptors. See avb_descriptor_foreach() for a convenience
88  * function to iterate over descriptors.
89  *
90  * This struct is versioned, see the |required_libavb_version_major|
91  * and |required_libavb_version_minor| fields. This represents the
92  * minimum version of libavb required to verify the header and depends
93  * on the features (e.g. algorithms, descriptors) used. Note that this
94  * may be 1.0 even if generated by an avbtool from 1.4 but where no
95  * features introduced after 1.0 has been used. See the "Versioning
96  * and compatibility" section in the README.md file for more details.
97  *
98  * All fields are stored in network byte order when serialized. To
99  * generate a copy with fields swapped to native byte order, use the
100  * function avb_vbmeta_image_header_to_host_byte_order().
101  *
102  * Before reading and/or using any of this data, you MUST verify it
103  * using avb_vbmeta_image_verify() and reject it unless it's signed by
104  * a known good public key.
105  */
106 typedef struct AvbVBMetaImageHeader {
107   /*   0: Four bytes equal to "AVB0" (AVB_MAGIC). */
108   uint8_t magic[AVB_MAGIC_LEN];
109 
110   /*   4: The major version of libavb required for this header. */
111   uint32_t required_libavb_version_major;
112   /*   8: The minor version of libavb required for this header. */
113   uint32_t required_libavb_version_minor;
114 
115   /*  12: The size of the signature block. */
116   uint64_t authentication_data_block_size;
117   /*  20: The size of the auxiliary data block. */
118   uint64_t auxiliary_data_block_size;
119 
120   /*  28: The verification algorithm used, see |AvbAlgorithmType| enum. */
121   uint32_t algorithm_type;
122 
123   /*  32: Offset into the "Authentication data" block of hash data. */
124   uint64_t hash_offset;
125   /*  40: Length of the hash data. */
126   uint64_t hash_size;
127 
128   /*  48: Offset into the "Authentication data" block of signature data. */
129   uint64_t signature_offset;
130   /*  56: Length of the signature data. */
131   uint64_t signature_size;
132 
133   /*  64: Offset into the "Auxiliary data" block of public key data. */
134   uint64_t public_key_offset;
135   /*  72: Length of the public key data. */
136   uint64_t public_key_size;
137 
138   /*  80: Offset into the "Auxiliary data" block of public key metadata. */
139   uint64_t public_key_metadata_offset;
140   /*  88: Length of the public key metadata. Must be set to zero if there
141    *  is no public key metadata.
142    */
143   uint64_t public_key_metadata_size;
144 
145   /*  96: Offset into the "Auxiliary data" block of descriptor data. */
146   uint64_t descriptors_offset;
147   /* 104: Length of descriptor data. */
148   uint64_t descriptors_size;
149 
150   /* 112: The rollback index which can be used to prevent rollback to
151    *  older versions.
152    */
153   uint64_t rollback_index;
154 
155   /* 120: Flags from the AvbVBMetaImageFlags enumeration. This must be
156    * set to zero if the vbmeta image is not a top-level image.
157    */
158   uint32_t flags;
159 
160   /* 124: Reserved to ensure |release_string| start on a 16-byte
161    * boundary. Must be set to zeroes.
162    */
163   uint8_t reserved0[4];
164 
165   /* 128: The release string from avbtool, e.g. "avbtool 1.0.0" or
166    * "avbtool 1.0.0 xyz_board Git-234abde89". Is guaranteed to be NUL
167    * terminated. Applications must not make assumptions about how this
168    * string is formatted.
169    */
170   uint8_t release_string[AVB_RELEASE_STRING_SIZE];
171 
172   /* 176: Padding to ensure struct is size AVB_VBMETA_IMAGE_HEADER_SIZE
173    * bytes. This must be set to zeroes.
174    */
175   uint8_t reserved[80];
176 } AVB_ATTR_PACKED AvbVBMetaImageHeader;
177 
178 /* Copies |src| to |dest|, byte-swapping fields in the process.
179  *
180  * Make sure you've verified |src| using avb_vbmeta_image_verify()
181  * before accessing the data and/or using this function.
182  */
183 void avb_vbmeta_image_header_to_host_byte_order(const AvbVBMetaImageHeader* src,
184                                                 AvbVBMetaImageHeader* dest);
185 
186 /* Return codes used in avb_vbmeta_image_verify().
187  *
188  * AVB_VBMETA_VERIFY_RESULT_OK is returned if the vbmeta image header
189  * is valid, the hash is correct and the signature is correct. Keep in
190  * mind that you still need to check that you know the public key used
191  * to sign the image, see avb_vbmeta_image_verify() for details.
192  *
193  * AVB_VBMETA_VERIFY_RESULT_OK_NOT_SIGNED is returned if the vbmeta
194  * image header is valid but there is no signature or hash.
195  *
196  * AVB_VBMETA_VERIFY_RESULT_INVALID_VBMETA_HEADER is returned if the
197  * header of the vbmeta image is invalid, for example, invalid magic
198  * or inconsistent data.
199  *
200  * AVB_VBMETA_VERIFY_RESULT_UNSUPPORTED_VERSION is returned if a) the
201  * vbmeta image requires a minimum version of libavb which exceeds the
202  * version of libavb used; or b) the vbmeta image major version
203  * differs from the major version of libavb in use.
204  *
205  * AVB_VBMETA_VERIFY_RESULT_HASH_MISMATCH is returned if the hash
206  * stored in the "Authentication data" block does not match the
207  * calculated hash.
208  *
209  * AVB_VBMETA_VERIFY_RESULT_SIGNATURE_MISMATCH is returned if the
210  * signature stored in the "Authentication data" block is invalid or
211  * doesn't match the public key stored in the vbmeta image.
212  */
213 typedef enum {
214   AVB_VBMETA_VERIFY_RESULT_OK,
215   AVB_VBMETA_VERIFY_RESULT_OK_NOT_SIGNED,
216   AVB_VBMETA_VERIFY_RESULT_INVALID_VBMETA_HEADER,
217   AVB_VBMETA_VERIFY_RESULT_UNSUPPORTED_VERSION,
218   AVB_VBMETA_VERIFY_RESULT_HASH_MISMATCH,
219   AVB_VBMETA_VERIFY_RESULT_SIGNATURE_MISMATCH,
220 } AvbVBMetaVerifyResult;
221 
222 /* Get a textual representation of |result|. */
223 const char* avb_vbmeta_verify_result_to_string(AvbVBMetaVerifyResult result);
224 
225 /* Checks that vbmeta image at |data| of size |length| is a valid
226  * vbmeta image. The complete contents of the vbmeta image must be
227  * passed in. It's fine if |length| is bigger than the actual image,
228  * typically callers of this function will load the entire contents of
229  * the 'vbmeta_a' or 'vbmeta_b' partition and pass in its length (for
230  * example, 1 MiB).
231  *
232  * See the |AvbVBMetaImageHeader| struct for information about the
233  * three blocks (header, authentication, auxiliary) that make up a
234  * vbmeta image.
235  *
236  * If the function returns |AVB_VBMETA_VERIFY_RESULT_OK| and
237  * |out_public_key_data| is non-NULL, it will be set to point inside
238  * |data| for where the serialized public key data is stored and
239  * |out_public_key_length|, if non-NULL, will be set to the length of
240  * the public key data. If there is no public key in the metadata then
241  * |out_public_key_data| is set to NULL.
242  *
243  * See the |AvbVBMetaVerifyResult| enum for possible return values.
244  *
245  * VERY IMPORTANT:
246  *
247  *   1. Even if |AVB_VBMETA_VERIFY_RESULT_OK| is returned, you still
248  *      need to check that the public key embedded in the image
249  *      matches a known key! You can use 'avbtool extract_public_key'
250  *      to extract the key (at build time, then store it along your
251  *      code) and compare it to what is returned in
252  *      |out_public_key_data|.
253  *
254  *   2. You need to check the |rollback_index| field against a stored
255  *      value in NVRAM and reject the vbmeta image if the value in
256  *      NVRAM is bigger than |rollback_index|. You must also update
257  *      the value stored in NVRAM to the smallest value of
258  *      |rollback_index| field from boot images in all bootable and
259  *      authentic slots marked as GOOD.
260  *
261  * This is a low-level function to only verify the vbmeta data - you
262  * are likely looking for avb_slot_verify() instead for verifying
263  * integrity data for a whole set of partitions.
264  */
265 AvbVBMetaVerifyResult avb_vbmeta_image_verify(
266     const uint8_t* data,
267     size_t length,
268     const uint8_t** out_public_key_data,
269     size_t* out_public_key_length) AVB_ATTR_WARN_UNUSED_RESULT;
270 
271 #ifdef __cplusplus
272 }
273 #endif
274 
275 #endif /* AVB_VBMETA_IMAGE_H_ */
276