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