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