• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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_SLOT_VERIFY_H_
30 #define AVB_SLOT_VERIFY_H_
31 
32 #include "avb_ops.h"
33 #include "avb_vbmeta_image.h"
34 
35 #ifdef __cplusplus
36 extern "C" {
37 #endif
38 
39 /* Return codes used in avb_slot_verify(), see that function for
40  * documentation for each field.
41  *
42  * Use avb_slot_verify_result_to_string() to get a textual
43  * representation usable for error/debug output.
44  */
45 typedef enum {
46   AVB_SLOT_VERIFY_RESULT_OK,
47   AVB_SLOT_VERIFY_RESULT_ERROR_OOM,
48   AVB_SLOT_VERIFY_RESULT_ERROR_IO,
49   AVB_SLOT_VERIFY_RESULT_ERROR_VERIFICATION,
50   AVB_SLOT_VERIFY_RESULT_ERROR_ROLLBACK_INDEX,
51   AVB_SLOT_VERIFY_RESULT_ERROR_PUBLIC_KEY_REJECTED,
52   AVB_SLOT_VERIFY_RESULT_ERROR_INVALID_METADATA,
53   AVB_SLOT_VERIFY_RESULT_ERROR_UNSUPPORTED_VERSION,
54   AVB_SLOT_VERIFY_RESULT_ERROR_INVALID_ARGUMENT
55 } AvbSlotVerifyResult;
56 
57 /* Various error handling modes for when verification fails using a
58  * hashtree at runtime inside the HLOS.
59  *
60  * AVB_HASHTREE_ERROR_MODE_RESTART_AND_INVALIDATE means that the OS
61  * will invalidate the current slot and restart.
62  *
63  * AVB_HASHTREE_ERROR_MODE_RESTART means that the OS will restart.
64  *
65  * AVB_HASHTREE_ERROR_MODE_EIO means that an EIO error will be
66  * returned to applications.
67  *
68  * AVB_HASHTREE_ERROR_MODE_LOGGING means that errors will be logged
69  * and corrupt data may be returned to applications. This mode should
70  * be used ONLY for diagnostics and debugging. It cannot be used
71  * unless AVB_SLOT_VERIFY_FLAGS_ALLOW_VERIFICATION_ERROR is also
72  * used.
73  */
74 typedef enum {
75   AVB_HASHTREE_ERROR_MODE_RESTART_AND_INVALIDATE,
76   AVB_HASHTREE_ERROR_MODE_RESTART,
77   AVB_HASHTREE_ERROR_MODE_EIO,
78   AVB_HASHTREE_ERROR_MODE_LOGGING
79 } AvbHashtreeErrorMode;
80 
81 /* Flags that influence how avb_slot_verify() works.
82  *
83  * If AVB_SLOT_VERIFY_FLAGS_ALLOW_VERIFICATION_ERROR is NOT set then
84  * avb_slot_verify() will bail out as soon as an error is encountered
85  * and |out_data| is set only if AVB_SLOT_VERIFY_RESULT_OK is
86  * returned.
87  *
88  * Otherwise if AVB_SLOT_VERIFY_FLAGS_ALLOW_VERIFICATION_ERROR is set
89  * avb_slot_verify() will continue verification efforts and |out_data|
90  * is also set if AVB_SLOT_VERIFY_RESULT_ERROR_PUBLIC_KEY_REJECTED,
91  * AVB_SLOT_VERIFY_RESULT_ERROR_VERIFICATION, or
92  * AVB_SLOT_VERIFY_RESULT_ERROR_ROLLBACK_INDEX is returned. It is
93  * undefined which error is returned if more than one distinct error
94  * is encountered. It is guaranteed that AVB_SLOT_VERIFY_RESULT_OK is
95  * returned if, and only if, there are no errors. This mode is needed
96  * to boot valid but unverified slots when the device is unlocked.
97  *
98  * Also, if AVB_SLOT_VERIFY_FLAGS_ALLOW_VERIFICATION_ERROR is set the
99  * contents loaded from |requested_partition| will be the contents of
100  * the entire partition instead of just the size specified in the hash
101  * descriptor.
102  */
103 typedef enum {
104   AVB_SLOT_VERIFY_FLAGS_NONE = 0,
105   AVB_SLOT_VERIFY_FLAGS_ALLOW_VERIFICATION_ERROR = (1 << 0)
106 } AvbSlotVerifyFlags;
107 
108 /* Get a textual representation of |result|. */
109 const char* avb_slot_verify_result_to_string(AvbSlotVerifyResult result);
110 
111 /* Maximum number of rollback index locations supported. */
112 #define AVB_MAX_NUMBER_OF_ROLLBACK_INDEX_LOCATIONS 32
113 
114 /* AvbPartitionData contains data loaded from partitions when using
115  * avb_slot_verify(). The |partition_name| field contains the name of
116  * the partition (without A/B suffix), |data| points to the loaded
117  * data which is |data_size| bytes long.
118  *
119  * Note that this is strictly less than the partition size - it's only
120  * the image stored there, not the entire partition nor any of the
121  * metadata.
122  */
123 typedef struct {
124   char* partition_name;
125   uint8_t* data;
126   size_t data_size;
127 } AvbPartitionData;
128 
129 /* AvbVBMetaData contains a vbmeta struct loaded from a partition when
130  * using avb_slot_verify(). The |partition_name| field contains the
131  * name of the partition (without A/B suffix), |vbmeta_data| points to
132  * the loaded data which is |vbmeta_size| bytes long.
133  *
134  * The |verify_result| field contains the result of
135  * avb_vbmeta_image_verify() on the data. This is guaranteed to be
136  * AVB_VBMETA_VERIFY_RESULT_OK for all vbmeta images if
137  * avb_slot_verify() returns AVB_SLOT_VERIFY_RESULT_OK.
138  *
139  * You can use avb_descriptor_get_all(), avb_descriptor_foreach(), and
140  * avb_vbmeta_image_header_to_host_byte_order() with this data.
141  */
142 typedef struct {
143   char* partition_name;
144   uint8_t* vbmeta_data;
145   size_t vbmeta_size;
146   AvbVBMetaVerifyResult verify_result;
147 } AvbVBMetaData;
148 
149 /* AvbSlotVerifyData contains data needed to boot a particular slot
150  * and is returned by avb_slot_verify() if partitions in a slot are
151  * successfully verified.
152  *
153  * All data pointed to by this struct - including data in each item in
154  * the |partitions| array - will be freed when the
155  * avb_slot_verify_data_free() function is called.
156  *
157  * The |ab_suffix| field is the copy of the of |ab_suffix| field
158  * passed to avb_slot_verify(). It is the A/B suffix of the slot. This
159  * value includes the leading underscore - typical values are "" (if
160  * no slots are in use), "_a" (for the first slot), and "_b" (for the
161  * second slot).
162  *
163  * The VBMeta images that were checked are available in the
164  * |vbmeta_images| field. The field |num_vbmeta_images| contains the
165  * number of elements in this array. The first element -
166  * vbmeta_images[0] - is guaranteed to be from the partition with the
167  * top-level vbmeta struct. This is usually the "vbmeta" partition in
168  * the requested slot but if there is no "vbmeta" partition it can
169  * also be the "boot" partition.
170  *
171  * The partitions loaded and verified from from the slot are
172  * accessible in the |loaded_partitions| array. The field
173  * |num_loaded_partitions| contains the number of elements in this
174  * array. The order of partitions in this array may not necessarily be
175  * the same order as in the passed-in |requested_partitions| array.
176  *
177  * Rollback indexes for the verified slot are stored in the
178  * |rollback_indexes| field. Note that avb_slot_verify() will NEVER
179  * modify stored_rollback_index[n] locations e.g. it will never use
180  * the write_rollback_index() AvbOps operation. Instead it is the job
181  * of the caller of avb_slot_verify() to do this based on e.g. A/B
182  * policy and other factors. See libavb_ab/avb_ab_flow.c for an
183  * example of how to do this.
184  *
185  * The |cmdline| field is a NUL-terminated string in UTF-8 resulting
186  * from concatenating all |AvbKernelCmdlineDescriptor| and then
187  * performing proper substitution of the variables
188  * $(ANDROID_SYSTEM_PARTUUID), $(ANDROID_BOOT_PARTUUID), and
189  * $(ANDROID_VBMETA_PARTUUID) using the
190  * get_unique_guid_for_partition() operation in |AvbOps|. Additionally
191  * $(ANDROID_VERITY_MODE) will be replaced with the proper dm-verity
192  * option depending on the value of |hashtree_error_mode|.
193  *
194  * Additionally, the |cmdline| field will have the following kernel
195  * command-line options set (unless verification is disabled, see
196  * below):
197  *
198  *   androidboot.veritymode: This is set to 'disabled' if the
199  *   AVB_VBMETA_IMAGE_FLAGS_HASHTREE_DISABLED flag is set in top-level
200  *   vbmeta struct. Otherwise it is set to 'enforcing' if the
201  *   passed-in hashtree error mode is AVB_HASHTREE_ERROR_MODE_RESTART
202  *   or AVB_HASHTREE_ERROR_MODE_RESTART_AND_INVALIDATE, 'eio' if it's
203  *   set to AVB_HASHTREE_ERROR_MODE_EIO, and 'logging' if it's set to
204  *   AVB_HASHTREE_ERROR_MODE_LOGGING.
205  *
206  *   androidboot.vbmeta.invalidate_on_error: This is set to 'yes' only
207  *   if hashtree validation isn't disabled and the passed-in hashtree
208  *   error mode is AVB_HASHTREE_ERROR_MODE_RESTART_AND_INVALIDATE.
209  *
210  *   androidboot.vbmeta.device_state: set to "locked" or "unlocked"
211  *   depending on the result of the result of AvbOps's
212  *   read_is_unlocked() function.
213  *
214  *   androidboot.vbmeta.{hash_alg, size, digest}: Will be set to
215  *   the digest of all images in |vbmeta_images|.
216  *
217  *   androidboot.vbmeta.device: This is set to the value
218  *   PARTUUID=$(ANDROID_VBMETA_PARTUUID) before substitution so it
219  *   will end up pointing to the vbmeta partition for the verified
220  *   slot. If there is no vbmeta partition it will point to the boot
221  *   partition of the verified slot.
222  *
223  *   androidboot.vbmeta.avb_version: This is set to the decimal value
224  *   of AVB_VERSION_MAJOR followed by a dot followed by the decimal
225  *   value of AVB_VERSION_MINOR, for example "1.0" or "1.4". This
226  *   version number represents the vbmeta file format version
227  *   supported by libavb copy used in the boot loader. This is not
228  *   necessarily the same version number of the on-disk metadata for
229  *   the slot that was verified.
230  *
231  * Note that androidboot.slot_suffix is not set in the |cmdline| field
232  * in |AvbSlotVerifyData| - you will have to set this yourself.
233  *
234  * If the |AVB_VBMETA_IMAGE_FLAGS_VERIFICATION_DISABLED| flag is set
235  * in the top-level vbmeta struct then only the top-level vbmeta
236  * struct is verified and descriptors will not processed. The return
237  * value will be set accordingly (if this flag is set via 'avbctl
238  * disable-verification' then the return value will be
239  * |AVB_SLOT_VERIFY_RESULT_ERROR_VERIFICATION|) and
240  * |AvbSlotVerifyData| is returned. Additionally all partitions in the
241  * |requested_partitions| are loaded and the |cmdline| field is set to
242  * "root=PARTUUID=$(ANDROID_SYSTEM_PARTUUID)" and the GUID for the
243  * appropriate system partition is substituted in. Note that none of
244  * the androidboot.* options mentioned above will be set.
245  *
246  * This struct may grow in the future without it being considered an
247  * ABI break.
248  */
249 typedef struct {
250   char* ab_suffix;
251   AvbVBMetaData* vbmeta_images;
252   size_t num_vbmeta_images;
253   AvbPartitionData* loaded_partitions;
254   size_t num_loaded_partitions;
255   char* cmdline;
256   uint64_t rollback_indexes[AVB_MAX_NUMBER_OF_ROLLBACK_INDEX_LOCATIONS];
257 } AvbSlotVerifyData;
258 
259 /* Frees a |AvbSlotVerifyData| including all data it points to. */
260 void avb_slot_verify_data_free(AvbSlotVerifyData* data);
261 
262 /* Performs a full verification of the slot identified by |ab_suffix|
263  * and load and verify the contents of the partitions whose name is in
264  * the NULL-terminated string array |requested_partitions| (each
265  * partition must use hash verification). If not using A/B, pass an
266  * empty string (e.g. "", not NULL) for |ab_suffix|. This parameter
267  * must include the leading underscore, for example "_a" should be
268  * used to refer to the first slot.
269  *
270  * Typically the |requested_partitions| array only contains a single
271  * item for the boot partition, 'boot'.
272  *
273  * Verification includes loading and verifying data from the 'vbmeta',
274  * the requested hash partitions, and possibly other partitions (with
275  * |ab_suffix| appended), inspecting rollback indexes, and checking if
276  * the public key used to sign the data is acceptable. The functions
277  * in |ops| will be used to do this.
278  *
279  * If |out_data| is not NULL, it will be set to a newly allocated
280  * |AvbSlotVerifyData| struct containing all the data needed to
281  * actually boot the slot. This data structure should be freed with
282  * avb_slot_verify_data_free() when you are done with it. See below
283  * for when this is returned.
284  *
285  * The |flags| parameter is used to influence the semantics of
286  * avb_slot_verify() - for example the
287  * AVB_SLOT_VERIFY_FLAGS_ALLOW_VERIFICATION_ERROR flag can be used to
288  * ignore verification errors which is something needed in the
289  * UNLOCKED state. See the AvbSlotVerifyFlags enumeration for details.
290  *
291  * The |hashtree_error_mode| parameter should be set to the desired
292  * error handling mode when hashtree validation fails inside the
293  * HLOS. This value isn't used by libavb per se - it is forwarded to
294  * the HLOS through the androidboot.veritymode and
295  * androidboot.vbmeta.invalidate_on_error cmdline parameters. See the
296  * AvbHashtreeErrorMode enumeration for details.
297  *
298  * Also note that |out_data| is never set if
299  * AVB_SLOT_VERIFY_RESULT_ERROR_OOM, AVB_SLOT_VERIFY_RESULT_ERROR_IO,
300  * or AVB_SLOT_VERIFY_RESULT_ERROR_INVALID_METADATA is returned.
301  *
302  * AVB_SLOT_VERIFY_RESULT_OK is returned if everything is verified
303  * correctly and all public keys are accepted.
304  *
305  * AVB_SLOT_VERIFY_RESULT_ERROR_PUBLIC_KEY_REJECTED is returned if
306  * everything is verified correctly out but one or more public keys
307  * are not accepted. This includes the case where integrity data is
308  * not signed.
309  *
310  * AVB_SLOT_VERIFY_RESULT_ERROR_OOM is returned if unable to
311  * allocate memory.
312  *
313  * AVB_SLOT_VERIFY_RESULT_ERROR_IO is returned if an I/O error
314  * occurred while trying to load data or get a rollback index.
315  *
316  * AVB_SLOT_VERIFY_RESULT_ERROR_VERIFICATION is returned if the data
317  * did not verify, e.g. the digest didn't match or signature checks
318  * failed.
319  *
320  * AVB_SLOT_VERIFY_RESULT_ERROR_ROLLBACK_INDEX is returned if a
321  * rollback index was less than its stored value.
322  *
323  * AVB_SLOT_VERIFY_RESULT_ERROR_INVALID_METADATA is returned if some
324  * of the metadata is invalid or inconsistent.
325  *
326  * AVB_SLOT_VERIFY_RESULT_ERROR_UNSUPPORTED_VERSION is returned if
327  * some of the metadata requires a newer version of libavb than what
328  * is in use.
329  *
330  * AVB_SLOT_VERIFY_RESULT_ERROR_INVALID_ARGUMENT is returned if the
331  * caller passed invalid parameters, for example trying to use
332  * AVB_HASHTREE_ERROR_MODE_LOGGING without
333  * AVB_SLOT_VERIFY_FLAGS_ALLOW_VERIFICATION_ERROR.
334  */
335 AvbSlotVerifyResult avb_slot_verify(AvbOps* ops,
336                                     const char* const* requested_partitions,
337                                     const char* ab_suffix,
338                                     AvbSlotVerifyFlags flags,
339                                     AvbHashtreeErrorMode hashtree_error_mode,
340                                     AvbSlotVerifyData** out_data);
341 
342 #ifdef __cplusplus
343 }
344 #endif
345 
346 #endif /* AVB_SLOT_VERIFY_H_ */
347