1 /* SPDX-License-Identifier: MIT */
3 * Copyright (C) 2016 The Android Open Source Project
6 #if !defined(AVB_INSIDE_LIBAVB_H) && !defined(AVB_COMPILATION)
7 #error "Never include this file directly, include libavb.h instead."
13 #include "avb_sysdeps.h"
19 /* Well-known names of named persistent values. */
20 #define AVB_NPV_PERSISTENT_DIGEST_PREFIX "avb.persistent_digest."
21 #define AVB_NPV_MANAGED_VERITY_MODE "avb.managed_verity_mode"
23 /* Return codes used for I/O operations.
25 * AVB_IO_RESULT_OK is returned if the requested operation was
28 * AVB_IO_RESULT_ERROR_IO is returned if the underlying hardware (disk
29 * or other subsystem) encountered an I/O error.
31 * AVB_IO_RESULT_ERROR_OOM is returned if unable to allocate memory.
33 * AVB_IO_RESULT_ERROR_NO_SUCH_PARTITION is returned if the requested
34 * partition does not exist.
36 * AVB_IO_RESULT_ERROR_RANGE_OUTSIDE_PARTITION is returned if the
37 * range of bytes requested to be read or written is outside the range
40 * AVB_IO_RESULT_ERROR_NO_SUCH_VALUE is returned if a named persistent value
43 * AVB_IO_RESULT_ERROR_INVALID_VALUE_SIZE is returned if a named persistent
44 * value size is not supported or does not match the expected size.
46 * AVB_IO_RESULT_ERROR_INSUFFICIENT_SPACE is returned if a buffer is too small
47 * for the requested operation.
51 AVB_IO_RESULT_ERROR_OOM,
52 AVB_IO_RESULT_ERROR_IO,
53 AVB_IO_RESULT_ERROR_NO_SUCH_PARTITION,
54 AVB_IO_RESULT_ERROR_RANGE_OUTSIDE_PARTITION,
55 AVB_IO_RESULT_ERROR_NO_SUCH_VALUE,
56 AVB_IO_RESULT_ERROR_INVALID_VALUE_SIZE,
57 AVB_IO_RESULT_ERROR_INSUFFICIENT_SPACE,
61 typedef struct AvbOps AvbOps;
63 /* Forward-declaration of operations in libavb_ab. */
66 /* Forward-declaration of operations in libavb_atx. */
69 /* High-level operations/functions/methods that are platform
72 * Operations may be added in the future so when implementing it
73 * always make sure to zero out sizeof(AvbOps) bytes of the struct to
74 * ensure that unimplemented operations are set to NULL.
77 /* This pointer can be used by the application/bootloader using
78 * libavb and is typically used in each operation to get a pointer
79 * to platform-specific resources. It cannot be used by libraries.
83 /* If libavb_ab is used, this should point to the
84 * AvbABOps. Otherwise it must be set to NULL.
86 struct AvbABOps* ab_ops;
88 /* If libavb_atx is used, this should point to the
89 * AvbAtxOps. Otherwise it must be set to NULL.
91 struct AvbAtxOps* atx_ops;
93 /* Reads |num_bytes| from offset |offset| from partition with name
94 * |partition| (NUL-terminated UTF-8 string). If |offset| is
95 * negative, its absolute value should be interpreted as the number
96 * of bytes from the end of the partition.
98 * This function returns AVB_IO_RESULT_ERROR_NO_SUCH_PARTITION if
99 * there is no partition with the given name,
100 * AVB_IO_RESULT_ERROR_RANGE_OUTSIDE_PARTITION if the requested
101 * |offset| is outside the partition, and AVB_IO_RESULT_ERROR_IO if
102 * there was an I/O error from the underlying I/O subsystem. If the
103 * operation succeeds as requested AVB_IO_RESULT_OK is returned and
104 * the data is available in |buffer|.
106 * The only time partial I/O may occur is if reading beyond the end
107 * of the partition. In this case the value returned in
108 * |out_num_read| may be smaller than |num_bytes|.
110 AvbIOResult (*read_from_partition)(AvbOps* ops,
111 const char* partition,
115 size_t* out_num_read);
117 /* Gets the starting pointer of a partition that is pre-loaded in memory, and
118 * save it to |out_pointer|. The preloaded partition is expected to be
119 * |num_bytes|, where the actual preloaded byte count is returned in
120 * |out_num_bytes_preloaded|. |out_num_bytes_preloaded| must be no larger than
123 * This provides an alternative way to access a partition that is preloaded
124 * into memory without a full memory copy. When this function pointer is not
125 * set (has value NULL), or when the |out_pointer| is set to NULL as a result,
126 * |read_from_partition| will be used as the fallback. This function is mainly
127 * used for accessing the entire partition content to calculate its hash.
129 * Preloaded partition data must outlive the lifespan of the
130 * |AvbSlotVerifyData| structure that |avb_slot_verify| outputs.
132 AvbIOResult (*get_preloaded_partition)(AvbOps* ops,
133 const char* partition,
135 uint8_t** out_pointer,
136 size_t* out_num_bytes_preloaded);
138 /* Writes |num_bytes| from |bffer| at offset |offset| to partition
139 * with name |partition| (NUL-terminated UTF-8 string). If |offset|
140 * is negative, its absolute value should be interpreted as the
141 * number of bytes from the end of the partition.
143 * This function returns AVB_IO_RESULT_ERROR_NO_SUCH_PARTITION if
144 * there is no partition with the given name,
145 * AVB_IO_RESULT_ERROR_RANGE_OUTSIDE_PARTITION if the requested
146 * byterange goes outside the partition, and AVB_IO_RESULT_ERROR_IO
147 * if there was an I/O error from the underlying I/O subsystem. If
148 * the operation succeeds as requested AVB_IO_RESULT_OK is
151 * This function never does any partial I/O, it either transfers all
152 * of the requested bytes or returns an error.
154 AvbIOResult (*write_to_partition)(AvbOps* ops,
155 const char* partition,
160 /* Checks if the given public key used to sign the 'vbmeta'
161 * partition is trusted. Boot loaders typically compare this with
162 * embedded key material generated with 'avbtool
163 * extract_public_key'.
165 * The public key is in the array pointed to by |public_key_data|
166 * and is of |public_key_length| bytes.
168 * If there is no public key metadata (set with the avbtool option
169 * --public_key_metadata) then |public_key_metadata| will be set to
170 * NULL. Otherwise this field points to the data which is
171 * |public_key_metadata_length| bytes long.
173 * If AVB_IO_RESULT_OK is returned then |out_is_trusted| is set -
174 * true if trusted or false if untrusted.
176 * NOTE: If AVB_SLOT_VERIFY_FLAGS_NO_VBMETA_PARTITION is passed to
177 * avb_slot_verify() then this operation is never used. Instead, the
178 * validate_public_key_for_partition() operation is used
180 AvbIOResult (*validate_vbmeta_public_key)(AvbOps* ops,
181 const uint8_t* public_key_data,
182 size_t public_key_length,
183 const uint8_t* public_key_metadata,
184 size_t public_key_metadata_length,
185 bool* out_is_trusted);
187 /* Gets the rollback index corresponding to the location given by
188 * |rollback_index_location|. The value is returned in
189 * |out_rollback_index|. Returns AVB_IO_RESULT_OK if the rollback
190 * index was retrieved, otherwise an error code.
192 * A device may have a limited amount of rollback index locations (say,
193 * one or four) so may error out if |rollback_index_location| exceeds
196 AvbIOResult (*read_rollback_index)(AvbOps* ops,
197 size_t rollback_index_location,
198 uint64_t* out_rollback_index);
200 /* Sets the rollback index corresponding to the location given by
201 * |rollback_index_location| to |rollback_index|. Returns
202 * AVB_IO_RESULT_OK if the rollback index was set, otherwise an
205 * A device may have a limited amount of rollback index locations (say,
206 * one or four) so may error out if |rollback_index_location| exceeds
209 AvbIOResult (*write_rollback_index)(AvbOps* ops,
210 size_t rollback_index_location,
211 uint64_t rollback_index);
213 /* Gets whether the device is unlocked. The value is returned in
214 * |out_is_unlocked| (true if unlocked, false otherwise). Returns
215 * AVB_IO_RESULT_OK if the state was retrieved, otherwise an error
218 AvbIOResult (*read_is_device_unlocked)(AvbOps* ops, bool* out_is_unlocked);
220 /* Gets the unique partition GUID for a partition with name in
221 * |partition| (NUL-terminated UTF-8 string). The GUID is copied as
222 * a string into |guid_buf| of size |guid_buf_size| and will be NUL
223 * terminated. The string must be lower-case and properly
224 * hyphenated. For example:
226 * 527c1c6d-6361-4593-8842-3c78fcd39219
228 * Returns AVB_IO_RESULT_OK on success, otherwise an error code.
230 AvbIOResult (*get_unique_guid_for_partition)(AvbOps* ops,
231 const char* partition,
233 size_t guid_buf_size);
235 /* Gets the size of a partition with the name in |partition|
236 * (NUL-terminated UTF-8 string). Returns the value in
237 * |out_size_num_bytes|.
239 * If the partition doesn't exist the AVB_IO_RESULT_ERROR_NO_SUCH_PARTITION
240 * error code should be returned.
242 * Returns AVB_IO_RESULT_OK on success, otherwise an error code.
244 AvbIOResult (*get_size_of_partition)(AvbOps* ops,
245 const char* partition,
246 uint64_t* out_size_num_bytes);
248 /* Reads a persistent value corresponding to the given |name|. The value is
249 * returned in |out_buffer| which must point to |buffer_size| bytes. On
250 * success |out_num_bytes_read| contains the number of bytes read into
251 * |out_buffer|. If AVB_IO_RESULT_ERROR_INSUFFICIENT_SPACE is returned,
252 * |out_num_bytes_read| contains the number of bytes that would have been read
253 * which can be used to allocate a buffer.
255 * The |buffer_size| may be zero and the |out_buffer| may be NULL, but if
256 * |out_buffer| is NULL then |buffer_size| *must* be zero.
258 * Returns AVB_IO_RESULT_OK on success, otherwise an error code.
260 * If the value does not exist, is not supported, or is not populated, returns
261 * AVB_IO_RESULT_ERROR_NO_SUCH_VALUE. If |buffer_size| is smaller than the
262 * size of the stored value, returns AVB_IO_RESULT_ERROR_INSUFFICIENT_SPACE.
264 * This operation is currently only used to support persistent digests or the
265 * AVB_HASHTREE_ERROR_MODE_MANAGED_RESTART_AND_EIO hashtree error mode. If a
266 * device does not use one of these features this function pointer can be set
269 AvbIOResult (*read_persistent_value)(AvbOps* ops,
273 size_t* out_num_bytes_read);
275 /* Writes a persistent value corresponding to the given |name|. The value is
276 * supplied in |value| which must point to |value_size| bytes. Any existing
277 * value with the same name is overwritten. If |value_size| is zero, future
278 * calls to |read_persistent_value| will return
279 * AVB_IO_RESULT_ERROR_NO_SUCH_VALUE.
281 * Returns AVB_IO_RESULT_OK on success, otherwise an error code.
283 * If the value |name| is not supported, returns
284 * AVB_IO_RESULT_ERROR_NO_SUCH_VALUE. If the |value_size| is not supported,
285 * returns AVB_IO_RESULT_ERROR_INVALID_VALUE_SIZE.
287 * This operation is currently only used to support persistent digests or the
288 * AVB_HASHTREE_ERROR_MODE_MANAGED_RESTART_AND_EIO hashtree error mode. If a
289 * device does not use one of these features this function pointer can be set
292 AvbIOResult (*write_persistent_value)(AvbOps* ops,
295 const uint8_t* value);
297 /* Like validate_vbmeta_public_key() but for when the flag
298 * AVB_SLOT_VERIFY_FLAGS_NO_VBMETA_PARTITION is being used. The name of the
299 * partition to get the public key for is passed in |partition_name|.
301 * Also returns the rollback index location to use for the partition, in
302 * |out_rollback_index_location|.
304 * Returns AVB_IO_RESULT_OK on success, otherwise an error code.
306 AvbIOResult (*validate_public_key_for_partition)(
308 const char* partition,
309 const uint8_t* public_key_data,
310 size_t public_key_length,
311 const uint8_t* public_key_metadata,
312 size_t public_key_metadata_length,
313 bool* out_is_trusted,
314 uint32_t* out_rollback_index_location);
321 #endif /* AVB_OPS_H_ */