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 /* Writes |num_bytes| from |bffer| at offset |offset| to partition 123 * with name |partition| (NUL-terminated UTF-8 string). If |offset| 124 * is negative, its absolute value should be interpreted as the 125 * number of bytes from the end of the partition. 126 * 127 * This function returns AVB_IO_RESULT_ERROR_NO_SUCH_PARTITION if 128 * there is no partition with the given name, 129 * AVB_IO_RESULT_ERROR_RANGE_OUTSIDE_PARTITION if the requested 130 * byterange goes outside the partition, and AVB_IO_RESULT_ERROR_IO 131 * if there was an I/O error from the underlying I/O subsystem. If 132 * the operation succeeds as requested AVB_IO_RESULT_OK is 133 * returned. 134 * 135 * This function never does any partial I/O, it either transfers all 136 * of the requested bytes or returns an error. 137 */ 138 AvbIOResult (*write_to_partition)(AvbOps* ops, 139 const char* partition, 140 int64_t offset, 141 size_t num_bytes, 142 const void* buffer); 143 144 /* Checks if the given public key used to sign the 'vbmeta' 145 * partition is trusted. Boot loaders typically compare this with 146 * embedded key material generated with 'avbtool 147 * extract_public_key'. 148 * 149 * The public key is in the array pointed to by |public_key_data| 150 * and is of |public_key_length| bytes. 151 * 152 * If there is no public key metadata (set with the avbtool option 153 * --public_key_metadata) then |public_key_metadata| will be set to 154 * NULL. Otherwise this field points to the data which is 155 * |public_key_metadata_length| bytes long. 156 * 157 * If AVB_IO_RESULT_OK is returned then |out_is_trusted| is set - 158 * true if trusted or false if untrusted. 159 */ 160 AvbIOResult (*validate_vbmeta_public_key)(AvbOps* ops, 161 const uint8_t* public_key_data, 162 size_t public_key_length, 163 const uint8_t* public_key_metadata, 164 size_t public_key_metadata_length, 165 bool* out_is_trusted); 166 167 /* Gets the rollback index corresponding to the location given by 168 * |rollback_index_location|. The value is returned in 169 * |out_rollback_index|. Returns AVB_IO_RESULT_OK if the rollback 170 * index was retrieved, otherwise an error code. 171 * 172 * A device may have a limited amount of rollback index locations (say, 173 * one or four) so may error out if |rollback_index_location| exceeds 174 * this number. 175 */ 176 AvbIOResult (*read_rollback_index)(AvbOps* ops, 177 size_t rollback_index_location, 178 uint64_t* out_rollback_index); 179 180 /* Sets the rollback index corresponding to the location given by 181 * |rollback_index_location| to |rollback_index|. Returns 182 * AVB_IO_RESULT_OK if the rollback index was set, otherwise an 183 * error code. 184 * 185 * A device may have a limited amount of rollback index locations (say, 186 * one or four) so may error out if |rollback_index_location| exceeds 187 * this number. 188 */ 189 AvbIOResult (*write_rollback_index)(AvbOps* ops, 190 size_t rollback_index_location, 191 uint64_t rollback_index); 192 193 /* Gets whether the device is unlocked. The value is returned in 194 * |out_is_unlocked| (true if unlocked, false otherwise). Returns 195 * AVB_IO_RESULT_OK if the state was retrieved, otherwise an error 196 * code. 197 */ 198 AvbIOResult (*read_is_device_unlocked)(AvbOps* ops, bool* out_is_unlocked); 199 AvbIOResult (*write_is_device_unlocked)(AvbOps* ops, bool* out_is_unlocked); 200 201 /* Gets the unique partition GUID for a partition with name in 202 * |partition| (NUL-terminated UTF-8 string). The GUID is copied as 203 * a string into |guid_buf| of size |guid_buf_size| and will be NUL 204 * terminated. The string must be lower-case and properly 205 * hyphenated. For example: 206 * 207 * 527c1c6d-6361-4593-8842-3c78fcd39219 208 * 209 * Returns AVB_IO_RESULT_OK on success, otherwise an error code. 210 */ 211 AvbIOResult (*get_unique_guid_for_partition)(AvbOps* ops, 212 const char* partition, 213 char* guid_buf, 214 size_t guid_buf_size); 215 216 /* Gets the size of a partition with the name in |partition| 217 * (NUL-terminated UTF-8 string). Returns the value in 218 * |out_size_num_bytes|. 219 * 220 * Returns AVB_IO_RESULT_OK on success, otherwise an error code. 221 */ 222 AvbIOResult (*get_size_of_partition)(AvbOps* ops, 223 const char* partition, 224 uint64_t* out_size_num_bytes); 225 }; 226 227 #ifdef __cplusplus 228 } 229 #endif 230 231 #endif /* AVB_OPS_H_ */ 232