lib/libavb/avb_vbmeta_image.h

   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_ */