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