1 /* 2 * Copyright (C) 2016 The Android Open Source Project 3 * 4 * SPDX-License-Identifier: MIT 5 */ 6 7 #if !defined(AVB_INSIDE_LIBAVB_H) && !defined(AVB_COMPILATION) 8 #error "Never include this file directly, include libavb.h instead." 9 #endif 10 11 #ifndef AVB_VBMETA_IMAGE_H_ 12 #define AVB_VBMETA_IMAGE_H_ 13 14 #include "avb_sysdeps.h" 15 16 #ifdef __cplusplus 17 extern "C" { 18 #endif 19 20 #include "avb_crypto.h" 21 #include "avb_descriptor.h" 22 23 /* Size of the vbmeta image header. */ 24 #define AVB_VBMETA_IMAGE_HEADER_SIZE 256 25 26 /* Magic for the vbmeta image header. */ 27 #define AVB_MAGIC "AVB0" 28 #define AVB_MAGIC_LEN 4 29 30 /* Maximum size of the release string including the terminating NUL byte. */ 31 #define AVB_RELEASE_STRING_SIZE 48 32 33 /* Flags for the vbmeta image. 34 * 35 * AVB_VBMETA_IMAGE_FLAGS_HASHTREE_DISABLED: If this flag is set, 36 * hashtree image verification will be disabled. 37 * 38 * AVB_VBMETA_IMAGE_FLAGS_VERIFICATION_DISABLED: If this flag is set, 39 * verification will be disabled and descriptors will not be parsed. 40 */ 41 typedef enum { 42 AVB_VBMETA_IMAGE_FLAGS_HASHTREE_DISABLED = (1 << 0), 43 AVB_VBMETA_IMAGE_FLAGS_VERIFICATION_DISABLED = (1 << 1) 44 } AvbVBMetaImageFlags; 45 46 /* Binary format for header of the vbmeta image. 47 * 48 * The vbmeta image consists of three blocks: 49 * 50 * +-----------------------------------------+ 51 * | Header data - fixed size | 52 * +-----------------------------------------+ 53 * | Authentication data - variable size | 54 * +-----------------------------------------+ 55 * | Auxiliary data - variable size | 56 * +-----------------------------------------+ 57 * 58 * The "Header data" block is described by this struct and is always 59 * |AVB_VBMETA_IMAGE_HEADER_SIZE| bytes long. 60 * 61 * The "Authentication data" block is |authentication_data_block_size| 62 * bytes long and contains the hash and signature used to authenticate 63 * the vbmeta image. The type of the hash and signature is defined by 64 * the |algorithm_type| field. 65 * 66 * The "Auxiliary data" is |auxiliary_data_block_size| bytes long and 67 * contains the auxiliary data including the public key used to make 68 * the signature and descriptors. 69 * 70 * The public key is at offset |public_key_offset| with size 71 * |public_key_size| in this block. The size of the public key data is 72 * defined by the |algorithm_type| field. The format of the public key 73 * data is described in the |AvbRSAPublicKeyHeader| struct. 74 * 75 * The descriptors starts at |descriptors_offset| from the beginning 76 * of the "Auxiliary Data" block and take up |descriptors_size| 77 * bytes. Each descriptor is stored as a |AvbDescriptor| with tag and 78 * number of bytes following. The number of descriptors can be 79 * determined by walking this data until |descriptors_size| is 80 * exhausted. 81 * 82 * The size of each of the "Authentication data" and "Auxiliary data" 83 * blocks must be divisible by 64. This is to ensure proper alignment. 84 * 85 * Descriptors are free-form blocks stored in a part of the vbmeta 86 * image subject to the same integrity checks as the rest of the 87 * image. See the documentation for |AvbDescriptor| for well-known 88 * descriptors. See avb_descriptor_foreach() for a convenience 89 * function to iterate over descriptors. 90 * 91 * This struct is versioned, see the |required_libavb_version_major| 92 * and |required_libavb_version_minor| fields. This represents the 93 * minimum version of libavb required to verify the header and depends 94 * on the features (e.g. algorithms, descriptors) used. Note that this 95 * may be 1.0 even if generated by an avbtool from 1.4 but where no 96 * features introduced after 1.0 has been used. See the "Versioning 97 * and compatibility" section in the README.md file for more details. 98 * 99 * All fields are stored in network byte order when serialized. To 100 * generate a copy with fields swapped to native byte order, use the 101 * function avb_vbmeta_image_header_to_host_byte_order(). 102 * 103 * Before reading and/or using any of this data, you MUST verify it 104 * using avb_vbmeta_image_verify() and reject it unless it's signed by 105 * a known good public key. 106 */ 107 typedef struct AvbVBMetaImageHeader { 108 /* 0: Four bytes equal to "AVB0" (AVB_MAGIC). */ 109 uint8_t magic[AVB_MAGIC_LEN]; 110 111 /* 4: The major version of libavb required for this header. */ 112 uint32_t required_libavb_version_major; 113 /* 8: The minor version of libavb required for this header. */ 114 uint32_t required_libavb_version_minor; 115 116 /* 12: The size of the signature block. */ 117 uint64_t authentication_data_block_size; 118 /* 20: The size of the auxiliary data block. */ 119 uint64_t auxiliary_data_block_size; 120 121 /* 28: The verification algorithm used, see |AvbAlgorithmType| enum. */ 122 uint32_t algorithm_type; 123 124 /* 32: Offset into the "Authentication data" block of hash data. */ 125 uint64_t hash_offset; 126 /* 40: Length of the hash data. */ 127 uint64_t hash_size; 128 129 /* 48: Offset into the "Authentication data" block of signature data. */ 130 uint64_t signature_offset; 131 /* 56: Length of the signature data. */ 132 uint64_t signature_size; 133 134 /* 64: Offset into the "Auxiliary data" block of public key data. */ 135 uint64_t public_key_offset; 136 /* 72: Length of the public key data. */ 137 uint64_t public_key_size; 138 139 /* 80: Offset into the "Auxiliary data" block of public key metadata. */ 140 uint64_t public_key_metadata_offset; 141 /* 88: Length of the public key metadata. Must be set to zero if there 142 * is no public key metadata. 143 */ 144 uint64_t public_key_metadata_size; 145 146 /* 96: Offset into the "Auxiliary data" block of descriptor data. */ 147 uint64_t descriptors_offset; 148 /* 104: Length of descriptor data. */ 149 uint64_t descriptors_size; 150 151 /* 112: The rollback index which can be used to prevent rollback to 152 * older versions. 153 */ 154 uint64_t rollback_index; 155 156 /* 120: Flags from the AvbVBMetaImageFlags enumeration. This must be 157 * set to zero if the vbmeta image is not a top-level image. 158 */ 159 uint32_t flags; 160 161 /* 124: Reserved to ensure |release_string| start on a 16-byte 162 * boundary. Must be set to zeroes. 163 */ 164 uint8_t reserved0[4]; 165 166 /* 128: The release string from avbtool, e.g. "avbtool 1.0.0" or 167 * "avbtool 1.0.0 xyz_board Git-234abde89". Is guaranteed to be NUL 168 * terminated. Applications must not make assumptions about how this 169 * string is formatted. 170 */ 171 uint8_t release_string[AVB_RELEASE_STRING_SIZE]; 172 173 /* 176: Padding to ensure struct is size AVB_VBMETA_IMAGE_HEADER_SIZE 174 * bytes. This must be set to zeroes. 175 */ 176 uint8_t reserved[80]; 177 } AVB_ATTR_PACKED AvbVBMetaImageHeader; 178 179 /* Copies |src| to |dest|, byte-swapping fields in the process. 180 * 181 * Make sure you've verified |src| using avb_vbmeta_image_verify() 182 * before accessing the data and/or using this function. 183 */ 184 void avb_vbmeta_image_header_to_host_byte_order(const AvbVBMetaImageHeader* src, 185 AvbVBMetaImageHeader* dest); 186 187 /* Return codes used in avb_vbmeta_image_verify(). 188 * 189 * AVB_VBMETA_VERIFY_RESULT_OK is returned if the vbmeta image header 190 * is valid, the hash is correct and the signature is correct. Keep in 191 * mind that you still need to check that you know the public key used 192 * to sign the image, see avb_vbmeta_image_verify() for details. 193 * 194 * AVB_VBMETA_VERIFY_RESULT_OK_NOT_SIGNED is returned if the vbmeta 195 * image header is valid but there is no signature or hash. 196 * 197 * AVB_VBMETA_VERIFY_RESULT_INVALID_VBMETA_HEADER is returned if the 198 * header of the vbmeta image is invalid, for example, invalid magic 199 * or inconsistent data. 200 * 201 * AVB_VBMETA_VERIFY_RESULT_UNSUPPORTED_VERSION is returned if a) the 202 * vbmeta image requires a minimum version of libavb which exceeds the 203 * version of libavb used; or b) the vbmeta image major version 204 * differs from the major version of libavb in use. 205 * 206 * AVB_VBMETA_VERIFY_RESULT_HASH_MISMATCH is returned if the hash 207 * stored in the "Authentication data" block does not match the 208 * calculated hash. 209 * 210 * AVB_VBMETA_VERIFY_RESULT_SIGNATURE_MISMATCH is returned if the 211 * signature stored in the "Authentication data" block is invalid or 212 * doesn't match the public key stored in the vbmeta image. 213 */ 214 typedef enum { 215 AVB_VBMETA_VERIFY_RESULT_OK, 216 AVB_VBMETA_VERIFY_RESULT_OK_NOT_SIGNED, 217 AVB_VBMETA_VERIFY_RESULT_INVALID_VBMETA_HEADER, 218 AVB_VBMETA_VERIFY_RESULT_UNSUPPORTED_VERSION, 219 AVB_VBMETA_VERIFY_RESULT_HASH_MISMATCH, 220 AVB_VBMETA_VERIFY_RESULT_SIGNATURE_MISMATCH, 221 } AvbVBMetaVerifyResult; 222 223 /* Get a textual representation of |result|. */ 224 const char* avb_vbmeta_verify_result_to_string(AvbVBMetaVerifyResult result); 225 226 /* Checks that vbmeta image at |data| of size |length| is a valid 227 * vbmeta image. The complete contents of the vbmeta image must be 228 * passed in. It's fine if |length| is bigger than the actual image, 229 * typically callers of this function will load the entire contents of 230 * the 'vbmeta_a' or 'vbmeta_b' partition and pass in its length (for 231 * example, 1 MiB). 232 * 233 * See the |AvbVBMetaImageHeader| struct for information about the 234 * three blocks (header, authentication, auxiliary) that make up a 235 * vbmeta image. 236 * 237 * If the function returns |AVB_VBMETA_VERIFY_RESULT_OK| and 238 * |out_public_key_data| is non-NULL, it will be set to point inside 239 * |data| for where the serialized public key data is stored and 240 * |out_public_key_length|, if non-NULL, will be set to the length of 241 * the public key data. If there is no public key in the metadata then 242 * |out_public_key_data| is set to NULL. 243 * 244 * See the |AvbVBMetaVerifyResult| enum for possible return values. 245 * 246 * VERY IMPORTANT: 247 * 248 * 1. Even if |AVB_VBMETA_VERIFY_RESULT_OK| is returned, you still 249 * need to check that the public key embedded in the image 250 * matches a known key! You can use 'avbtool extract_public_key' 251 * to extract the key (at build time, then store it along your 252 * code) and compare it to what is returned in 253 * |out_public_key_data|. 254 * 255 * 2. You need to check the |rollback_index| field against a stored 256 * value in NVRAM and reject the vbmeta image if the value in 257 * NVRAM is bigger than |rollback_index|. You must also update 258 * the value stored in NVRAM to the smallest value of 259 * |rollback_index| field from boot images in all bootable and 260 * authentic slots marked as GOOD. 261 * 262 * This is a low-level function to only verify the vbmeta data - you 263 * are likely looking for avb_slot_verify() instead for verifying 264 * integrity data for a whole set of partitions. 265 */ 266 AvbVBMetaVerifyResult avb_vbmeta_image_verify( 267 const uint8_t* data, 268 size_t length, 269 const uint8_t** out_public_key_data, 270 size_t* out_public_key_length) AVB_ATTR_WARN_UNUSED_RESULT; 271 272 #ifdef __cplusplus 273 } 274 #endif 275 276 #endif /* AVB_VBMETA_IMAGE_H_ */ 277