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