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