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 /* Return codes used for I/O operations. 41 * 42 * AVB_IO_RESULT_OK is returned if the requested operation was 43 * successful. 44 * 45 * AVB_IO_RESULT_ERROR_IO is returned if the underlying hardware (disk 46 * or other subsystem) encountered an I/O error. 47 * 48 * AVB_IO_RESULT_ERROR_OOM is returned if unable to allocate memory. 49 * 50 * AVB_IO_RESULT_ERROR_NO_SUCH_PARTITION is returned if the requested 51 * partition does not exist. 52 * 53 * AVB_IO_RESULT_ERROR_RANGE_OUTSIDE_PARTITION is returned if the 54 * range of bytes requested to be read or written is outside the range 55 * of the partition. 56 */ 57 typedef enum { 58 AVB_IO_RESULT_OK, 59 AVB_IO_RESULT_ERROR_OOM, 60 AVB_IO_RESULT_ERROR_IO, 61 AVB_IO_RESULT_ERROR_NO_SUCH_PARTITION, 62 AVB_IO_RESULT_ERROR_RANGE_OUTSIDE_PARTITION 63 } AvbIOResult; 64 65 struct AvbOps; 66 typedef struct AvbOps AvbOps; 67 68 /* Forward-declaration of operations in libavb_ab. */ 69 struct AvbABOps; 70 71 /* Forward-declaration of operations in libavb_atx. */ 72 struct AvbAtxOps; 73 74 /* High-level operations/functions/methods that are platform 75 * dependent. 76 * 77 * Operations may be added in the future so when implementing it 78 * always make sure to zero out sizeof(AvbOps) bytes of the struct to 79 * ensure that unimplemented operations are set to NULL. 80 */ 81 struct AvbOps { 82 /* This pointer can be used by the application/bootloader using 83 * libavb and is typically used in each operation to get a pointer 84 * to platform-specific resources. It cannot be used by libraries. 85 */ 86 void* user_data; 87 88 /* If libavb_ab is used, this should point to the 89 * AvbABOps. Otherwise it must be set to NULL. 90 */ 91 struct AvbABOps* ab_ops; 92 93 /* If libavb_atx is used, this should point to the 94 * AvbAtxOps. Otherwise it must be set to NULL. 95 */ 96 struct AvbAtxOps* atx_ops; 97 98 /* Reads |num_bytes| from offset |offset| from partition with name 99 * |partition| (NUL-terminated UTF-8 string). If |offset| is 100 * negative, its absolute value should be interpreted as the number 101 * of bytes from the end of the partition. 102 * 103 * This function returns AVB_IO_RESULT_ERROR_NO_SUCH_PARTITION if 104 * there is no partition with the given name, 105 * AVB_IO_RESULT_ERROR_RANGE_OUTSIDE_PARTITION if the requested 106 * |offset| is outside the partition, and AVB_IO_RESULT_ERROR_IO if 107 * there was an I/O error from the underlying I/O subsystem. If the 108 * operation succeeds as requested AVB_IO_RESULT_OK is returned and 109 * the data is available in |buffer|. 110 * 111 * The only time partial I/O may occur is if reading beyond the end 112 * of the partition. In this case the value returned in 113 * |out_num_read| may be smaller than |num_bytes|. 114 */ 115 AvbIOResult (*read_from_partition)(AvbOps* ops, 116 const char* partition, 117 int64_t offset, 118 size_t num_bytes, 119 void* buffer, 120 size_t* out_num_read); 121 122 /* Gets the starting pointer of a partition that is pre-loaded in memory, and 123 * save it to |out_pointer|. The preloaded partition is expected to be 124 * |num_bytes|, where the actual preloaded byte count is returned in 125 * |out_num_bytes_preloaded|. |out_num_bytes_preloaded| must be no larger than 126 * |num_bytes|. 127 * 128 * This provides an alternative way to access a partition that is preloaded 129 * into memory without a full memory copy. When this function pointer is not 130 * set (has value NULL), or when the |out_pointer| is set to NULL as a result, 131 * |read_from_partition| will be used as the fallback. This function is mainly 132 * used for accessing the entire partition content to calculate its hash. 133 * 134 * Preloaded partition data must outlive the lifespan of the 135 * |AvbSlotVerifyData| structure that |avb_slot_verify| outputs. 136 */ 137 AvbIOResult (*get_preloaded_partition)(AvbOps* ops, 138 const char* partition, 139 size_t num_bytes, 140 uint8_t** out_pointer, 141 size_t* out_num_bytes_preloaded); 142 143 /* Writes |num_bytes| from |bffer| at offset |offset| to partition 144 * with name |partition| (NUL-terminated UTF-8 string). If |offset| 145 * is negative, its absolute value should be interpreted as the 146 * number of bytes from the end of the partition. 147 * 148 * This function returns AVB_IO_RESULT_ERROR_NO_SUCH_PARTITION if 149 * there is no partition with the given name, 150 * AVB_IO_RESULT_ERROR_RANGE_OUTSIDE_PARTITION if the requested 151 * byterange goes outside the partition, and AVB_IO_RESULT_ERROR_IO 152 * if there was an I/O error from the underlying I/O subsystem. If 153 * the operation succeeds as requested AVB_IO_RESULT_OK is 154 * returned. 155 * 156 * This function never does any partial I/O, it either transfers all 157 * of the requested bytes or returns an error. 158 */ 159 AvbIOResult (*write_to_partition)(AvbOps* ops, 160 const char* partition, 161 int64_t offset, 162 size_t num_bytes, 163 const void* buffer); 164 165 /* Checks if the given public key used to sign the 'vbmeta' 166 * partition is trusted. Boot loaders typically compare this with 167 * embedded key material generated with 'avbtool 168 * extract_public_key'. 169 * 170 * The public key is in the array pointed to by |public_key_data| 171 * and is of |public_key_length| bytes. 172 * 173 * If there is no public key metadata (set with the avbtool option 174 * --public_key_metadata) then |public_key_metadata| will be set to 175 * NULL. Otherwise this field points to the data which is 176 * |public_key_metadata_length| bytes long. 177 * 178 * If AVB_IO_RESULT_OK is returned then |out_is_trusted| is set - 179 * true if trusted or false if untrusted. 180 */ 181 AvbIOResult (*validate_vbmeta_public_key)(AvbOps* ops, 182 const uint8_t* public_key_data, 183 size_t public_key_length, 184 const uint8_t* public_key_metadata, 185 size_t public_key_metadata_length, 186 bool* out_is_trusted); 187 188 /* Gets the rollback index corresponding to the location given by 189 * |rollback_index_location|. The value is returned in 190 * |out_rollback_index|. Returns AVB_IO_RESULT_OK if the rollback 191 * index was retrieved, otherwise an error code. 192 * 193 * A device may have a limited amount of rollback index locations (say, 194 * one or four) so may error out if |rollback_index_location| exceeds 195 * this number. 196 */ 197 AvbIOResult (*read_rollback_index)(AvbOps* ops, 198 size_t rollback_index_location, 199 uint64_t* out_rollback_index); 200 201 /* Sets the rollback index corresponding to the location given by 202 * |rollback_index_location| to |rollback_index|. Returns 203 * AVB_IO_RESULT_OK if the rollback index was set, otherwise an 204 * error code. 205 * 206 * A device may have a limited amount of rollback index locations (say, 207 * one or four) so may error out if |rollback_index_location| exceeds 208 * this number. 209 */ 210 AvbIOResult (*write_rollback_index)(AvbOps* ops, 211 size_t rollback_index_location, 212 uint64_t rollback_index); 213 214 /* Gets whether the device is unlocked. The value is returned in 215 * |out_is_unlocked| (true if unlocked, false otherwise). Returns 216 * AVB_IO_RESULT_OK if the state was retrieved, otherwise an error 217 * code. 218 */ 219 AvbIOResult (*read_is_device_unlocked)(AvbOps* ops, bool* out_is_unlocked); 220 221 /* write the device lock flag. Returns 222 * AVB_IO_RESULT_OK if the state was retrieved, otherwise an error 223 * code. 224 */ 225 AvbIOResult (*write_is_device_unlocked)(AvbOps* ops, bool* out_is_unlocked); 226 /* Gets the unique partition GUID for a partition with name in 227 * |partition| (NUL-terminated UTF-8 string). The GUID is copied as 228 * a string into |guid_buf| of size |guid_buf_size| and will be NUL 229 * terminated. The string must be lower-case and properly 230 * hyphenated. For example: 231 * 232 * 527c1c6d-6361-4593-8842-3c78fcd39219 233 * 234 * Returns AVB_IO_RESULT_OK on success, otherwise an error code. 235 */ 236 AvbIOResult (*get_unique_guid_for_partition)(AvbOps* ops, 237 const char* partition, 238 char* guid_buf, 239 size_t guid_buf_size); 240 241 /* Gets the size of a partition with the name in |partition| 242 * (NUL-terminated UTF-8 string). Returns the value in 243 * |out_size_num_bytes|. 244 * 245 * Returns AVB_IO_RESULT_OK on success, otherwise an error code. 246 */ 247 AvbIOResult (*get_size_of_partition)(AvbOps* ops, 248 const char* partition, 249 uint64_t* out_size_num_bytes); 250 }; 251 252 #ifdef __cplusplus 253 } 254 #endif 255 256 #endif /* AVB_OPS_H_ */ 257