David Zeuthen | 21e9526 | 2016-07-27 17:58:40 -0400 | [diff] [blame] | 1 | /* |
| 2 | * Copyright (C) 2016 The Android Open Source Project |
| 3 | * |
David Zeuthen | c612e2e | 2016-09-16 16:44:08 -0400 | [diff] [blame^] | 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: |
David Zeuthen | 21e9526 | 2016-07-27 17:58:40 -0400 | [diff] [blame] | 11 | * |
David Zeuthen | c612e2e | 2016-09-16 16:44:08 -0400 | [diff] [blame^] | 12 | * The above copyright notice and this permission notice shall be |
| 13 | * included in all copies or substantial portions of the Software. |
David Zeuthen | 21e9526 | 2016-07-27 17:58:40 -0400 | [diff] [blame] | 14 | * |
David Zeuthen | c612e2e | 2016-09-16 16:44:08 -0400 | [diff] [blame^] | 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. |
David Zeuthen | 21e9526 | 2016-07-27 17:58:40 -0400 | [diff] [blame] | 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 |
| 35 | extern "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 | /* The current MAJOR and MINOR versions used - keep in sync with avbtool. */ |
| 49 | #define AVB_MAJOR_VERSION 1 |
| 50 | #define AVB_MINOR_VERSION 0 |
| 51 | |
| 52 | /* Binary format for header of the vbmeta image. |
| 53 | * |
| 54 | * The vbmeta image consists of three blocks: |
| 55 | * |
| 56 | * +-----------------------------------------+ |
| 57 | * | Header data - fixed size | |
| 58 | * +-----------------------------------------+ |
| 59 | * | Authentication data - variable size | |
| 60 | * +-----------------------------------------+ |
| 61 | * | Auxiliary data - variable size | |
| 62 | * +-----------------------------------------+ |
| 63 | * |
| 64 | * The "Header data" block is described by this struct and is always |
| 65 | * |AVB_VBMETA_IMAGE_HEADER_SIZE| bytes long. |
| 66 | * |
| 67 | * The "Authentication data" block is |authentication_data_block_size| |
| 68 | * bytes long and contains the hash and signature used to authenticate |
| 69 | * the vbmeta image. The type of the hash and signature is defined by |
| 70 | * the |algorithm_type| field. |
| 71 | * |
| 72 | * The "Auxiliary data" is |auxiliary_data_block_size| bytes long and |
| 73 | * contains the auxiliary data including the public key used to make |
| 74 | * the signature and descriptors. |
| 75 | * |
| 76 | * The public key is at offset |public_key_offset| with size |
| 77 | * |public_key_size| in this block. The size of the public key data is |
| 78 | * defined by the |algorithm_type| field. The format of the public key |
| 79 | * data is described in the |AvbRSAPublicKeyHeader| struct. |
| 80 | * |
| 81 | * The descriptors starts at |descriptors_offset| from the beginning |
| 82 | * of the "Auxiliary Data" block and take up |descriptors_size| |
| 83 | * bytes. Each descriptor is stored as a |AvbDescriptor| with tag and |
| 84 | * number of bytes following. The number of descriptors can be |
| 85 | * determined by walking this data until |descriptors_size| is |
| 86 | * exhausted. |
| 87 | * |
| 88 | * The size of each of the "Authentication data" and "Auxiliary data" |
| 89 | * blocks must be divisible by 64. This is to ensure proper alignment. |
| 90 | * |
| 91 | * Descriptors are free-form blocks stored in a part of the vbmeta |
| 92 | * image subject to the same integrity checks as the rest of the |
| 93 | * image. See the documentation for |AvbDescriptor| for well-known |
| 94 | * descriptors. See avb_descriptor_foreach() for a convenience |
| 95 | * function to iterate over descriptors. |
| 96 | * |
| 97 | * This struct is versioned, see the |header_version_major| and |
| 98 | * |header_version_minor| fields. Compatibility is guaranteed only |
| 99 | * within the same major version. |
| 100 | * |
| 101 | * All fields are stored in network byte order when serialized. To |
| 102 | * generate a copy with fields swapped to native byte order, use the |
| 103 | * function avb_vbmeta_image_header_to_host_byte_order(). |
| 104 | * |
| 105 | * Before reading and/or using any of this data, you MUST verify it |
| 106 | * using avb_vbmeta_image_verify() and reject it unless it's signed by |
| 107 | * a known good public key. |
| 108 | */ |
| 109 | typedef struct AvbVBMetaImageHeader { |
| 110 | /* 0: Four bytes equal to "AVB0" (AVB_MAGIC). */ |
| 111 | uint8_t magic[AVB_MAGIC_LEN]; |
| 112 | /* 4: The major version of the vbmeta image header. */ |
| 113 | uint32_t header_version_major; |
| 114 | /* 8: The minor version of the vbmeta image header. */ |
| 115 | uint32_t header_version_minor; |
| 116 | |
| 117 | /* 12: The size of the signature block. */ |
| 118 | uint64_t authentication_data_block_size; |
| 119 | /* 20: The size of the auxiliary data block. */ |
| 120 | uint64_t auxiliary_data_block_size; |
| 121 | |
| 122 | /* 28: The verification algorithm used, see |AvbAlgorithmType| enum. */ |
| 123 | uint32_t algorithm_type; |
| 124 | |
| 125 | /* 32: Offset into the "Authentication data" block of hash data. */ |
| 126 | uint64_t hash_offset; |
| 127 | /* 40: Length of the hash data. */ |
| 128 | uint64_t hash_size; |
| 129 | |
| 130 | /* 48: Offset into the "Authentication data" block of signature data. */ |
| 131 | uint64_t signature_offset; |
| 132 | /* 56: Length of the signature data. */ |
| 133 | uint64_t signature_size; |
| 134 | |
| 135 | /* 64: Offset into the "Auxiliary data" block of public key data. */ |
| 136 | uint64_t public_key_offset; |
| 137 | /* 72: Length of the public key data. */ |
| 138 | uint64_t public_key_size; |
| 139 | |
| 140 | /* 80: Offset into the "Auxiliary data" block of descriptor data. */ |
| 141 | uint64_t descriptors_offset; |
| 142 | /* 88: Length of descriptor data. */ |
| 143 | uint64_t descriptors_size; |
| 144 | |
| 145 | /* 96: The rollback index which can be used to prevent rollback to |
| 146 | * older versions. |
| 147 | */ |
| 148 | uint64_t rollback_index; |
| 149 | |
| 150 | /* 104: Padding to ensure struct is size AVB_VBMETA_IMAGE_HEADER_SIZE |
| 151 | * bytes. This must be set to zeroes. |
| 152 | */ |
| 153 | uint8_t reserved[152]; |
| 154 | } AVB_ATTR_PACKED AvbVBMetaImageHeader; |
| 155 | |
| 156 | /* Copies |src| to |dest|, byte-swapping fields in the process. |
| 157 | * |
| 158 | * Make sure you've verified |src| using avb_vbmeta_image_verify() |
| 159 | * before accessing the data and/or using this function. |
| 160 | */ |
| 161 | void avb_vbmeta_image_header_to_host_byte_order(const AvbVBMetaImageHeader* src, |
| 162 | AvbVBMetaImageHeader* dest); |
| 163 | |
| 164 | /* Return codes used in avb_vbmeta_image_verify(). |
| 165 | * |
| 166 | * AVB_VBMETA_VERIFY_RESULT_OK is returned if the vbmeta image header |
| 167 | * is valid, the hash is correct and the signature is correct. Keep in |
| 168 | * mind that you still need to check that you know the public key used |
| 169 | * to sign the image, see avb_vbmeta_image_verify() for details. |
| 170 | * |
| 171 | * AVB_VBMETA_VERIFY_RESULT_OK_NOT_SIGNED is returned if the vbmeta |
| 172 | * image header is valid but there is no signature or hash. |
| 173 | * |
| 174 | * AVB_VERIFY_INVALID_VBMETA_HEADER is returned if the header of |
| 175 | * the vbmeta image is invalid, for example, invalid magic or |
| 176 | * inconsistent data. |
| 177 | * |
| 178 | * AVB_VERIFY_HASH_MISMATCH is returned if the hash stored in the |
| 179 | * "Authentication data" block does not match the calculated hash. |
| 180 | * |
| 181 | * AVB_VERIFY_SIGNATURE_MISMATCH is returned if the signature stored |
| 182 | * in the "Authentication data" block is invalid or doesn't match the |
| 183 | * public key stored in the vbmeta image. |
| 184 | */ |
| 185 | typedef enum { |
| 186 | AVB_VBMETA_VERIFY_RESULT_OK, |
| 187 | AVB_VBMETA_VERIFY_RESULT_OK_NOT_SIGNED, |
| 188 | AVB_VBMETA_VERIFY_RESULT_INVALID_VBMETA_HEADER, |
| 189 | AVB_VBMETA_VERIFY_RESULT_HASH_MISMATCH, |
| 190 | AVB_VBMETA_VERIFY_RESULT_SIGNATURE_MISMATCH, |
| 191 | } AvbVBMetaVerifyResult; |
| 192 | |
| 193 | /* Checks that vbmeta image at |data| of size |length| is a valid |
| 194 | * vbmeta image. The complete contents of the vbmeta image must be |
| 195 | * passed in. It's fine if |length| is bigger than the actual image, |
| 196 | * typically callers of this function will load the entire contents of |
| 197 | * the 'vbmeta_a' or 'vbmeta_b' partition and pass in its length (for |
| 198 | * example, 1 MiB). |
| 199 | * |
| 200 | * See the |AvbVBMetaImageHeader| struct for information about the |
| 201 | * three blocks (header, authentication, auxiliary) that make up a |
| 202 | * vbmeta image. |
| 203 | * |
| 204 | * If the function returns |AVB_VBMETA_VERIFY_RESULT_OK| and |
| 205 | * |out_public_key_data| is non-NULL, it will be set to point inside |
| 206 | * |data| for where the serialized public key data is stored and |
| 207 | * |out_public_key_length|, if non-NULL, will be set to the length of |
| 208 | * the public key data. |
| 209 | * |
| 210 | * See the |AvbVBMetaVerifyResult| enum for possible return values. |
| 211 | * |
| 212 | * VERY IMPORTANT: |
| 213 | * |
| 214 | * 1. Even if |AVB_VBMETA_VERIFY_RESULT_OK| is returned, you still |
| 215 | * need to check that the public key embedded in the image |
| 216 | * matches a known key! You can use 'avbtool extract_public_key' |
| 217 | * to extract the key (at build time, then store it along your |
| 218 | * code) and compare it to what is returned in |
| 219 | * |out_public_key_data|. |
| 220 | * |
| 221 | * 2. You need to check the |rollback_index| field against a stored |
| 222 | * value in NVRAM and reject the vbmeta image if the value in |
| 223 | * NVRAM is bigger than |rollback_index|. You must also update |
| 224 | * the value stored in NVRAM to the smallest value of |
| 225 | * |rollback_index| field from boot images in all bootable and |
| 226 | * authentic slots marked as GOOD. |
| 227 | * |
| 228 | * This is a low-level function to only verify the vbmeta data - you |
| 229 | * are likely looking for avb_slot_verify() instead for verifying |
| 230 | * integrity data for a whole set of partitions. |
| 231 | */ |
| 232 | AvbVBMetaVerifyResult avb_vbmeta_image_verify( |
| 233 | const uint8_t* data, size_t length, const uint8_t** out_public_key_data, |
| 234 | size_t* out_public_key_length) AVB_ATTR_WARN_UNUSED_RESULT; |
| 235 | |
| 236 | #ifdef __cplusplus |
| 237 | } |
| 238 | #endif |
| 239 | |
| 240 | #endif /* AVB_VBMETA_IMAGE_H_ */ |