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 /* 26 #if !defined(AVB_INSIDE_LIBAVB_H) && !defined(AVB_COMPILATION) 27 #error "Never include this file directly, include libavb.h instead." 28 #endif 29 */ 30 31 #ifndef AVB_OPS_H_ 32 #define AVB_OPS_H_ 33 34 #include <android_avb/avb_sysdeps.h> 35 36 #ifdef __cplusplus 37 extern "C" { 38 #endif 39 40 /* Well-known names of named persistent values. */ 41 #define AVB_NPV_PERSISTENT_DIGEST_PREFIX "avb.persistent_digest." 42 #define AVB_NPV_MANAGED_VERITY_MODE "avb.managed_verity_mode" 43 44 /* Return codes used for I/O operations. 45 * 46 * AVB_IO_RESULT_OK is returned if the requested operation was 47 * successful. 48 * 49 * AVB_IO_RESULT_ERROR_IO is returned if the underlying hardware (disk 50 * or other subsystem) encountered an I/O error. 51 * 52 * AVB_IO_RESULT_ERROR_OOM is returned if unable to allocate memory. 53 * 54 * AVB_IO_RESULT_ERROR_NO_SUCH_PARTITION is returned if the requested 55 * partition does not exist. 56 * 57 * AVB_IO_RESULT_ERROR_RANGE_OUTSIDE_PARTITION is returned if the 58 * range of bytes requested to be read or written is outside the range 59 * of the partition. 60 * 61 * AVB_IO_RESULT_ERROR_NO_SUCH_VALUE is returned if a named persistent value 62 * does not exist. 63 * 64 * AVB_IO_RESULT_ERROR_INVALID_VALUE_SIZE is returned if a named persistent 65 * value size is not supported or does not match the expected size. 66 * 67 * AVB_IO_RESULT_ERROR_INSUFFICIENT_SPACE is returned if a buffer is too small 68 * for the requested operation. 69 */ 70 typedef enum { 71 AVB_IO_RESULT_OK, 72 AVB_IO_RESULT_ERROR_OOM, 73 AVB_IO_RESULT_ERROR_IO, 74 AVB_IO_RESULT_ERROR_NO_SUCH_PARTITION, 75 AVB_IO_RESULT_ERROR_RANGE_OUTSIDE_PARTITION, 76 AVB_IO_RESULT_ERROR_NO_SUCH_VALUE, 77 AVB_IO_RESULT_ERROR_INVALID_VALUE_SIZE, 78 AVB_IO_RESULT_ERROR_INSUFFICIENT_SPACE, 79 } AvbIOResult; 80 81 struct AvbOps; 82 typedef struct AvbOps AvbOps; 83 84 /* Forward-declaration of operations in libavb_ab. */ 85 struct AvbABOps; 86 87 /* Forward-declaration of operations in libavb_atx. */ 88 struct AvbAtxOps; 89 90 /* High-level operations/functions/methods that are platform 91 * dependent. 92 * 93 * Operations may be added in the future so when implementing it 94 * always make sure to zero out sizeof(AvbOps) bytes of the struct to 95 * ensure that unimplemented operations are set to NULL. 96 */ 97 struct AvbOps { 98 /* This pointer can be used by the application/bootloader using 99 * libavb and is typically used in each operation to get a pointer 100 * to platform-specific resources. It cannot be used by libraries. 101 */ 102 void* user_data; 103 104 /* If libavb_ab is used, this should point to the 105 * AvbABOps. Otherwise it must be set to NULL. 106 */ 107 struct AvbABOps* ab_ops; 108 109 /* If libavb_atx is used, this should point to the 110 * AvbAtxOps. Otherwise it must be set to NULL. 111 */ 112 struct AvbAtxOps* atx_ops; 113 114 /* Reads |num_bytes| from offset |offset| from partition with name 115 * |partition| (NUL-terminated UTF-8 string). If |offset| is 116 * negative, its absolute value should be interpreted as the number 117 * of bytes from the end of the partition. 118 * 119 * This function returns AVB_IO_RESULT_ERROR_NO_SUCH_PARTITION if 120 * there is no partition with the given name, 121 * AVB_IO_RESULT_ERROR_RANGE_OUTSIDE_PARTITION if the requested 122 * |offset| is outside the partition, and AVB_IO_RESULT_ERROR_IO if 123 * there was an I/O error from the underlying I/O subsystem. If the 124 * operation succeeds as requested AVB_IO_RESULT_OK is returned and 125 * the data is available in |buffer|. 126 * 127 * The only time partial I/O may occur is if reading beyond the end 128 * of the partition. In this case the value returned in 129 * |out_num_read| may be smaller than |num_bytes|. 130 */ 131 AvbIOResult (*read_from_partition)(AvbOps* ops, 132 const char* partition, 133 int64_t offset, 134 size_t num_bytes, 135 void* buffer, 136 size_t* out_num_read); 137 138 /* Gets the starting pointer of a partition that is pre-loaded in memory, and 139 * save it to |out_pointer|. The preloaded partition is expected to be 140 * |num_bytes|, where the actual preloaded byte count is returned in 141 * |out_num_bytes_preloaded|. |out_num_bytes_preloaded| must be no larger than 142 * |num_bytes|. 143 * 144 * This provides an alternative way to access a partition that is preloaded 145 * into memory without a full memory copy. When this function pointer is not 146 * set (has value NULL), or when the |out_pointer| is set to NULL as a result, 147 * |read_from_partition| will be used as the fallback. This function is mainly 148 * used for accessing the entire partition content to calculate its hash. 149 * 150 * Preloaded partition data must outlive the lifespan of the 151 * |AvbSlotVerifyData| structure that |avb_slot_verify| outputs. 152 */ 153 AvbIOResult (*get_preloaded_partition)(AvbOps* ops, 154 const char* partition, 155 size_t num_bytes, 156 uint8_t** out_pointer, 157 size_t* out_num_bytes_preloaded, 158 int allow_verification_error); 159 160 /* Writes |num_bytes| from |bffer| at offset |offset| to partition 161 * with name |partition| (NUL-terminated UTF-8 string). If |offset| 162 * is negative, its absolute value should be interpreted as the 163 * number of bytes from the end of the partition. 164 * 165 * This function returns AVB_IO_RESULT_ERROR_NO_SUCH_PARTITION if 166 * there is no partition with the given name, 167 * AVB_IO_RESULT_ERROR_RANGE_OUTSIDE_PARTITION if the requested 168 * byterange goes outside the partition, and AVB_IO_RESULT_ERROR_IO 169 * if there was an I/O error from the underlying I/O subsystem. If 170 * the operation succeeds as requested AVB_IO_RESULT_OK is 171 * returned. 172 * 173 * This function never does any partial I/O, it either transfers all 174 * of the requested bytes or returns an error. 175 */ 176 AvbIOResult (*write_to_partition)(AvbOps* ops, 177 const char* partition, 178 int64_t offset, 179 size_t num_bytes, 180 const void* buffer); 181 182 /* Checks if the given public key used to sign the 'vbmeta' 183 * partition is trusted. Boot loaders typically compare this with 184 * embedded key material generated with 'avbtool 185 * extract_public_key'. 186 * 187 * The public key is in the array pointed to by |public_key_data| 188 * and is of |public_key_length| bytes. 189 * 190 * If there is no public key metadata (set with the avbtool option 191 * --public_key_metadata) then |public_key_metadata| will be set to 192 * NULL. Otherwise this field points to the data which is 193 * |public_key_metadata_length| bytes long. 194 * 195 * If AVB_IO_RESULT_OK is returned then |out_is_trusted| is set - 196 * true if trusted or false if untrusted. 197 * 198 * NOTE: If AVB_SLOT_VERIFY_FLAGS_NO_VBMETA_PARTITION is passed to 199 * avb_slot_verify() then this operation is never used. Instead, the 200 * validate_public_key_for_partition() operation is used 201 */ 202 AvbIOResult (*validate_vbmeta_public_key)(AvbOps* ops, 203 const uint8_t* public_key_data, 204 size_t public_key_length, 205 const uint8_t* public_key_metadata, 206 size_t public_key_metadata_length, 207 bool* out_is_trusted); 208 209 /* Gets the rollback index corresponding to the location given by 210 * |rollback_index_location|. The value is returned in 211 * |out_rollback_index|. Returns AVB_IO_RESULT_OK if the rollback 212 * index was retrieved, otherwise an error code. 213 * 214 * A device may have a limited amount of rollback index locations (say, 215 * one or four) so may error out if |rollback_index_location| exceeds 216 * this number. 217 */ 218 AvbIOResult (*read_rollback_index)(AvbOps* ops, 219 size_t rollback_index_location, 220 uint64_t* out_rollback_index); 221 222 /* Sets the rollback index corresponding to the location given by 223 * |rollback_index_location| to |rollback_index|. Returns 224 * AVB_IO_RESULT_OK if the rollback index was set, otherwise an 225 * error code. 226 * 227 * A device may have a limited amount of rollback index locations (say, 228 * one or four) so may error out if |rollback_index_location| exceeds 229 * this number. 230 */ 231 AvbIOResult (*write_rollback_index)(AvbOps* ops, 232 size_t rollback_index_location, 233 uint64_t rollback_index); 234 235 /* Gets whether the device is unlocked. The value is returned in 236 * |out_is_unlocked| (true if unlocked, false otherwise). Returns 237 * AVB_IO_RESULT_OK if the state was retrieved, otherwise an error 238 * code. 239 */ 240 AvbIOResult (*read_is_device_unlocked)(AvbOps* ops, bool* out_is_unlocked); 241 242 /* write the device lock flag. Returns 243 * AVB_IO_RESULT_OK if the state was retrieved, otherwise an error 244 * code. 245 */ 246 AvbIOResult (*write_is_device_unlocked)(AvbOps* ops, bool* out_is_unlocked); 247 248 /* Gets the unique partition GUID for a partition with name in 249 * |partition| (NUL-terminated UTF-8 string). The GUID is copied as 250 * a string into |guid_buf| of size |guid_buf_size| and will be NUL 251 * terminated. The string must be lower-case and properly 252 * hyphenated. For example: 253 * 254 * 527c1c6d-6361-4593-8842-3c78fcd39219 255 * 256 * Returns AVB_IO_RESULT_OK on success, otherwise an error code. 257 */ 258 AvbIOResult (*get_unique_guid_for_partition)(AvbOps* ops, 259 const char* partition, 260 char* guid_buf, 261 size_t guid_buf_size); 262 263 /* Gets the size of a partition with the name in |partition| 264 * (NUL-terminated UTF-8 string). Returns the value in 265 * |out_size_num_bytes|. 266 * 267 * If the partition doesn't exist the AVB_IO_RESULT_ERROR_NO_SUCH_PARTITION 268 * error code should be returned. 269 * 270 * Returns AVB_IO_RESULT_OK on success, otherwise an error code. 271 */ 272 AvbIOResult (*get_size_of_partition)(AvbOps* ops, 273 const char* partition, 274 uint64_t* out_size_num_bytes); 275 276 /* Reads a persistent value corresponding to the given |name|. The value is 277 * returned in |out_buffer| which must point to |buffer_size| bytes. On 278 * success |out_num_bytes_read| contains the number of bytes read into 279 * |out_buffer|. If AVB_IO_RESULT_ERROR_INSUFFICIENT_SPACE is returned, 280 * |out_num_bytes_read| contains the number of bytes that would have been read 281 * which can be used to allocate a buffer. 282 * 283 * The |buffer_size| may be zero and the |out_buffer| may be NULL, but if 284 * |out_buffer| is NULL then |buffer_size| *must* be zero. 285 * 286 * Returns AVB_IO_RESULT_OK on success, otherwise an error code. 287 * 288 * If the value does not exist, is not supported, or is not populated, returns 289 * AVB_IO_RESULT_ERROR_NO_SUCH_VALUE. If |buffer_size| is smaller than the 290 * size of the stored value, returns AVB_IO_RESULT_ERROR_INSUFFICIENT_SPACE. 291 * 292 * This operation is currently only used to support persistent digests or the 293 * AVB_HASHTREE_ERROR_MODE_MANAGED_RESTART_AND_EIO hashtree error mode. If a 294 * device does not use one of these features this function pointer can be set 295 * to NULL. 296 */ 297 AvbIOResult (*read_persistent_value)(AvbOps* ops, 298 const char* name, 299 size_t buffer_size, 300 uint8_t* out_buffer, 301 size_t* out_num_bytes_read); 302 303 /* Writes a persistent value corresponding to the given |name|. The value is 304 * supplied in |value| which must point to |value_size| bytes. Any existing 305 * value with the same name is overwritten. If |value_size| is zero, future 306 * calls to |read_persistent_value| will return 307 * AVB_IO_RESULT_ERROR_NO_SUCH_VALUE. 308 * 309 * Returns AVB_IO_RESULT_OK on success, otherwise an error code. 310 * 311 * If the value |name| is not supported, returns 312 * AVB_IO_RESULT_ERROR_NO_SUCH_VALUE. If the |value_size| is not supported, 313 * returns AVB_IO_RESULT_ERROR_INVALID_VALUE_SIZE. 314 * 315 * This operation is currently only used to support persistent digests or the 316 * AVB_HASHTREE_ERROR_MODE_MANAGED_RESTART_AND_EIO hashtree error mode. If a 317 * device does not use one of these features this function pointer can be set 318 * to NULL. 319 */ 320 AvbIOResult (*write_persistent_value)(AvbOps* ops, 321 const char* name, 322 size_t value_size, 323 const uint8_t* value); 324 325 /* Like validate_vbmeta_public_key() but for when the flag 326 * AVB_SLOT_VERIFY_FLAGS_NO_VBMETA_PARTITION is being used. The name of the 327 * partition to get the public key for is passed in |partition_name|. 328 * 329 * Also returns the rollback index location to use for the partition, in 330 * |out_rollback_index_location|. 331 * 332 * Returns AVB_IO_RESULT_OK on success, otherwise an error code. 333 */ 334 AvbIOResult (*validate_public_key_for_partition)( 335 AvbOps* ops, 336 const char* partition, 337 const uint8_t* public_key_data, 338 size_t public_key_length, 339 const uint8_t* public_key_metadata, 340 size_t public_key_metadata_length, 341 bool* out_is_trusted, 342 uint32_t* out_rollback_index_location); 343 }; 344 345 #ifdef __cplusplus 346 } 347 #endif 348 349 #endif /* AVB_OPS_H_ */ 350