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