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 159 /* Writes |num_bytes| from |bffer| at offset |offset| to partition 160 * with name |partition| (NUL-terminated UTF-8 string). If |offset| 161 * is negative, its absolute value should be interpreted as the 162 * number of bytes from the end of the partition. 163 * 164 * This function returns AVB_IO_RESULT_ERROR_NO_SUCH_PARTITION if 165 * there is no partition with the given name, 166 * AVB_IO_RESULT_ERROR_RANGE_OUTSIDE_PARTITION if the requested 167 * byterange goes outside the partition, and AVB_IO_RESULT_ERROR_IO 168 * if there was an I/O error from the underlying I/O subsystem. If 169 * the operation succeeds as requested AVB_IO_RESULT_OK is 170 * returned. 171 * 172 * This function never does any partial I/O, it either transfers all 173 * of the requested bytes or returns an error. 174 */ 175 AvbIOResult (*write_to_partition)(AvbOps* ops, 176 const char* partition, 177 int64_t offset, 178 size_t num_bytes, 179 const void* buffer); 180 181 /* Checks if the given public key used to sign the 'vbmeta' 182 * partition is trusted. Boot loaders typically compare this with 183 * embedded key material generated with 'avbtool 184 * extract_public_key'. 185 * 186 * The public key is in the array pointed to by |public_key_data| 187 * and is of |public_key_length| bytes. 188 * 189 * If there is no public key metadata (set with the avbtool option 190 * --public_key_metadata) then |public_key_metadata| will be set to 191 * NULL. Otherwise this field points to the data which is 192 * |public_key_metadata_length| bytes long. 193 * 194 * If AVB_IO_RESULT_OK is returned then |out_is_trusted| is set - 195 * true if trusted or false if untrusted. 196 * 197 * NOTE: If AVB_SLOT_VERIFY_FLAGS_NO_VBMETA_PARTITION is passed to 198 * avb_slot_verify() then this operation is never used. Instead, the 199 * validate_public_key_for_partition() operation is used 200 */ 201 AvbIOResult (*validate_vbmeta_public_key)(AvbOps* ops, 202 const uint8_t* public_key_data, 203 size_t public_key_length, 204 const uint8_t* public_key_metadata, 205 size_t public_key_metadata_length, 206 bool* out_is_trusted); 207 208 /* Gets the rollback index corresponding to the location given by 209 * |rollback_index_location|. The value is returned in 210 * |out_rollback_index|. Returns AVB_IO_RESULT_OK if the rollback 211 * index was retrieved, otherwise an error code. 212 * 213 * A device may have a limited amount of rollback index locations (say, 214 * one or four) so may error out if |rollback_index_location| exceeds 215 * this number. 216 */ 217 AvbIOResult (*read_rollback_index)(AvbOps* ops, 218 size_t rollback_index_location, 219 uint64_t* out_rollback_index); 220 221 /* Sets the rollback index corresponding to the location given by 222 * |rollback_index_location| to |rollback_index|. Returns 223 * AVB_IO_RESULT_OK if the rollback index was set, otherwise an 224 * error code. 225 * 226 * A device may have a limited amount of rollback index locations (say, 227 * one or four) so may error out if |rollback_index_location| exceeds 228 * this number. 229 */ 230 AvbIOResult (*write_rollback_index)(AvbOps* ops, 231 size_t rollback_index_location, 232 uint64_t rollback_index); 233 234 /* Gets whether the device is unlocked. The value is returned in 235 * |out_is_unlocked| (true if unlocked, false otherwise). Returns 236 * AVB_IO_RESULT_OK if the state was retrieved, otherwise an error 237 * code. 238 */ 239 AvbIOResult (*read_is_device_unlocked)(AvbOps* ops, bool* out_is_unlocked); 240 241 /* write the device lock flag. Returns 242 * AVB_IO_RESULT_OK if the state was retrieved, otherwise an error 243 * code. 244 */ 245 AvbIOResult (*write_is_device_unlocked)(AvbOps* ops, bool* out_is_unlocked); 246 247 /* Gets the unique partition GUID for a partition with name in 248 * |partition| (NUL-terminated UTF-8 string). The GUID is copied as 249 * a string into |guid_buf| of size |guid_buf_size| and will be NUL 250 * terminated. The string must be lower-case and properly 251 * hyphenated. For example: 252 * 253 * 527c1c6d-6361-4593-8842-3c78fcd39219 254 * 255 * Returns AVB_IO_RESULT_OK on success, otherwise an error code. 256 */ 257 AvbIOResult (*get_unique_guid_for_partition)(AvbOps* ops, 258 const char* partition, 259 char* guid_buf, 260 size_t guid_buf_size); 261 262 /* Gets the size of a partition with the name in |partition| 263 * (NUL-terminated UTF-8 string). Returns the value in 264 * |out_size_num_bytes|. 265 * 266 * If the partition doesn't exist the AVB_IO_RESULT_ERROR_NO_SUCH_PARTITION 267 * error code should be returned. 268 * 269 * Returns AVB_IO_RESULT_OK on success, otherwise an error code. 270 */ 271 AvbIOResult (*get_size_of_partition)(AvbOps* ops, 272 const char* partition, 273 uint64_t* out_size_num_bytes); 274 275 /* Reads a persistent value corresponding to the given |name|. The value is 276 * returned in |out_buffer| which must point to |buffer_size| bytes. On 277 * success |out_num_bytes_read| contains the number of bytes read into 278 * |out_buffer|. If AVB_IO_RESULT_ERROR_INSUFFICIENT_SPACE is returned, 279 * |out_num_bytes_read| contains the number of bytes that would have been read 280 * which can be used to allocate a buffer. 281 * 282 * The |buffer_size| may be zero and the |out_buffer| may be NULL, but if 283 * |out_buffer| is NULL then |buffer_size| *must* be zero. 284 * 285 * Returns AVB_IO_RESULT_OK on success, otherwise an error code. 286 * 287 * If the value does not exist, is not supported, or is not populated, returns 288 * AVB_IO_RESULT_ERROR_NO_SUCH_VALUE. If |buffer_size| is smaller than the 289 * size of the stored value, returns AVB_IO_RESULT_ERROR_INSUFFICIENT_SPACE. 290 * 291 * This operation is currently only used to support persistent digests or the 292 * AVB_HASHTREE_ERROR_MODE_MANAGED_RESTART_AND_EIO hashtree error mode. If a 293 * device does not use one of these features this function pointer can be set 294 * to NULL. 295 */ 296 AvbIOResult (*read_persistent_value)(AvbOps* ops, 297 const char* name, 298 size_t buffer_size, 299 uint8_t* out_buffer, 300 size_t* out_num_bytes_read); 301 302 /* Writes a persistent value corresponding to the given |name|. The value is 303 * supplied in |value| which must point to |value_size| bytes. Any existing 304 * value with the same name is overwritten. If |value_size| is zero, future 305 * calls to |read_persistent_value| will return 306 * AVB_IO_RESULT_ERROR_NO_SUCH_VALUE. 307 * 308 * Returns AVB_IO_RESULT_OK on success, otherwise an error code. 309 * 310 * If the value |name| is not supported, returns 311 * AVB_IO_RESULT_ERROR_NO_SUCH_VALUE. If the |value_size| is not supported, 312 * returns AVB_IO_RESULT_ERROR_INVALID_VALUE_SIZE. 313 * 314 * This operation is currently only used to support persistent digests or the 315 * AVB_HASHTREE_ERROR_MODE_MANAGED_RESTART_AND_EIO hashtree error mode. If a 316 * device does not use one of these features this function pointer can be set 317 * to NULL. 318 */ 319 AvbIOResult (*write_persistent_value)(AvbOps* ops, 320 const char* name, 321 size_t value_size, 322 const uint8_t* value); 323 324 /* Like validate_vbmeta_public_key() but for when the flag 325 * AVB_SLOT_VERIFY_FLAGS_NO_VBMETA_PARTITION is being used. The name of the 326 * partition to get the public key for is passed in |partition_name|. 327 * 328 * Also returns the rollback index location to use for the partition, in 329 * |out_rollback_index_location|. 330 * 331 * Returns AVB_IO_RESULT_OK on success, otherwise an error code. 332 */ 333 AvbIOResult (*validate_public_key_for_partition)( 334 AvbOps* ops, 335 const char* partition, 336 const uint8_t* public_key_data, 337 size_t public_key_length, 338 const uint8_t* public_key_metadata, 339 size_t public_key_metadata_length, 340 bool* out_is_trusted, 341 uint32_t* out_rollback_index_location); 342 }; 343 344 #ifdef __cplusplus 345 } 346 #endif 347 348 #endif /* AVB_OPS_H_ */ 349