1 /* Copyright (c) 2014 The Chromium OS Authors. All rights reserved. 2 * Use of this source code is governed by a BSD-style license that can be 3 * found in the LICENSE file. 4 * 5 * Vboot 2.1 data structures 6 * 7 * Offsets should be padded to 32-bit boundaries, since some architectures 8 * have trouble with accessing unaligned integers. 9 */ 10 11 #ifndef VBOOT_REFERENCE_VB2_STRUCT_H_ 12 #define VBOOT_REFERENCE_VB2_STRUCT_H_ 13 #include <stdint.h> 14 15 #include "2guid.h" 16 17 /* 18 * Magic numbers used by vb2_struct_common.magic. 19 * 20 * All valid numbers should be listed here to avoid accidental overlap. 21 * Numbers start at a large value, so that previous parsers (which stored 22 * things like lengths and offsets at that field) will detect and reject new 23 * structs as invalid. 24 */ 25 enum vb2_struct_common_magic { 26 /* "Vb2B" = vb2_keyblock.c.magic */ 27 VB2_MAGIC_KEYBLOCK = 0x42326256, 28 29 /* "Vb2F" = vb2_fw_preamble.c.magic */ 30 VB2_MAGIC_FW_PREAMBLE = 0x46326256, 31 32 /* "Vb2I" = vb2_packed_private_key.c.magic */ 33 VB2_MAGIC_PACKED_PRIVATE_KEY = 0x49326256, 34 35 /* "Vb2K" = vb2_kernel_preamble.c.magic */ 36 VB2_MAGIC_KERNEL_PREAMBLE = 0x4b326256, 37 38 /* "Vb2P" = vb2_packed_key.c.magic */ 39 VB2_MAGIC_PACKED_KEY = 0x50326256, 40 41 /* "Vb2S" = vb2_signature.c.magic */ 42 VB2_MAGIC_SIGNATURE = 0x53326256, 43 }; 44 45 46 /* 47 * Generic struct header for all vboot2 structs. This makes it easy to 48 * automatically parse and identify vboot structs (e.g., in futility). This 49 * must be the first member of the parent vboot2 struct. 50 */ 51 struct vb2_struct_common { 52 /* Magic number; see vb2_struct_common_magic for expected values */ 53 uint32_t magic; 54 55 /* 56 * Parent struct version; see each struct for the expected value. 57 * 58 * How to handle struct version mismatches, if the parser is version 59 * A.b and the data is version C.d: 60 * 1) If A.b == C.d, we're good. 61 * 2) If A != C, the data cannot be parsed at all. 62 * 3) If b < d, C.d is a newer version of data which is backwards- 63 * compatible to old parsers. We're good. 64 * 4) If b > d, C.d is an older version of data. The parser should 65 * use default values for fields added after version d. We're 66 * good. 67 * 68 * Struct versions start at 3.0, since the highest version of the old 69 * structures was 2.1. This way, there is no possibility of collision 70 * for old code which depends on the version number. 71 */ 72 uint16_t struct_version_major; 73 uint16_t struct_version_minor; 74 75 /* 76 * Size of the parent structure and all its data, including the 77 * description and any necessary padding. That is, all data must lie 78 * in a contiguous region of <total_size> bytes starting at the first 79 * byte of this header. 80 */ 81 uint32_t total_size; 82 83 /* 84 * Size of the fixed portion of the parent structure. If a description 85 * is present, it must start at this offset. 86 */ 87 uint32_t fixed_size; 88 89 /* 90 * The object may contain an ASCII description following the fixed 91 * portion of the structure. If it is present, it must be 92 * null-terminated, and padded with 0 (null) bytes to a multiple of 32 93 * bits. 94 * 95 * Size of ASCII description in bytes, counting null terminator and 96 * padding (if any). Set 0 if no description is present. If non-zero, 97 * there must be a null terminator (0) at offset (fixed_size + 98 * desc_size - 1). 99 */ 100 uint32_t desc_size; 101 } __attribute__((packed)); 102 103 #define EXPECTED_VB2_STRUCT_COMMON_SIZE 20 104 105 /* Current version of vb2_packed_key struct */ 106 #define VB2_PACKED_KEY_VERSION_MAJOR 3 107 #define VB2_PACKED_KEY_VERSION_MINOR 0 108 109 /* 110 * Packed public key data 111 * 112 * The key data must be arranged like this: 113 * 1) vb2_packed_key header struct h 114 * 2) Key description (pointed to by h.c.fixed_size) 115 * 3) Key data key (pointed to by h.key_offset) 116 */ 117 struct vb2_packed_key { 118 /* Common header fields */ 119 struct vb2_struct_common c; 120 121 /* Offset of key data from start of this struct */ 122 uint32_t key_offset; 123 124 /* Size of key data in bytes (NOT strength of key in bits) */ 125 uint32_t key_size; 126 127 /* Signature algorithm used by the key (enum vb2_signature_algorithm) */ 128 uint16_t sig_alg; 129 130 /* 131 * Hash digest algorithm used with the key (enum vb2_hash_algorithm). 132 * This is explicitly specified as part of the key to prevent use of a 133 * strong key with a weak hash. 134 */ 135 uint16_t hash_alg; 136 137 /* Key version */ 138 uint32_t key_version; 139 140 /* Key GUID */ 141 struct vb2_guid guid; 142 } __attribute__((packed)); 143 144 #define EXPECTED_VB2_PACKED_KEY_SIZE \ 145 (EXPECTED_VB2_STRUCT_COMMON_SIZE + EXPECTED_GUID_SIZE + 16) 146 147 /* Current version of vb2_packed_private_key struct */ 148 #define VB2_PACKED_PRIVATE_KEY_VERSION_MAJOR 3 149 #define VB2_PACKED_PRIVATE_KEY_VERSION_MINOR 0 150 151 /* 152 * Packed private key data 153 * 154 * The key data must be arranged like this: 155 * 1) vb2_packed_private_key header struct h 156 * 2) Key description (pointed to by h.c.fixed_size) 157 * 3) Key data key (pointed to by h.key_offset) 158 */ 159 struct vb2_packed_private_key { 160 /* Common header fields */ 161 struct vb2_struct_common c; 162 163 /* Offset of key data from start of this struct */ 164 uint32_t key_offset; 165 166 /* Size of key data in bytes (NOT strength of key in bits) */ 167 uint32_t key_size; 168 169 /* Signature algorithm used by the key (enum vb2_signature_algorithm) */ 170 uint16_t sig_alg; 171 172 /* 173 * Hash digest algorithm used with the key (enum vb2_hash_algorithm). 174 * This is explicitly specified as part of the key to prevent use of a 175 * strong key with a weak hash. 176 */ 177 uint16_t hash_alg; 178 179 /* Key GUID */ 180 struct vb2_guid guid; 181 } __attribute__((packed)); 182 183 #define EXPECTED_VB2_PACKED_PRIVATE_KEY_SIZE \ 184 (EXPECTED_VB2_STRUCT_COMMON_SIZE + EXPECTED_GUID_SIZE + 12) 185 186 /* Current version of vb2_signature struct */ 187 #define VB2_SIGNATURE_VERSION_MAJOR 3 188 #define VB2_SIGNATURE_VERSION_MINOR 0 189 190 /* 191 * Signature data 192 * 193 * The signature data must be arranged like this: 194 * 1) vb2_signature header struct h 195 * 2) Signature description (pointed to by h.c.fixed_size) 196 * 3) Signature data (pointed to by h.sig_offset) 197 */ 198 struct vb2_signature { 199 /* Common header fields */ 200 struct vb2_struct_common c; 201 202 /* Offset of signature data from start of this struct */ 203 uint32_t sig_offset; 204 205 /* Size of signature data in bytes */ 206 uint32_t sig_size; 207 208 /* Size of the data block which was signed in bytes */ 209 uint32_t data_size; 210 211 /* Signature algorithm used (enum vb2_signature_algorithm) */ 212 uint16_t sig_alg; 213 214 /* Hash digest algorithm used (enum vb2_hash_algorithm) */ 215 uint16_t hash_alg; 216 217 /* 218 * GUID for the signature. 219 * 220 * If this is a keyblock signature entry, this is the GUID of the key 221 * used to generate this signature. This allows the firmware to 222 * quickly determine which signature block (if any) goes with the key 223 * being used by the firmware. 224 * 225 * If this is a preamble hash entry, this is the GUID of the data type 226 * being hashed. There is no key GUID, because sig_alg=VB2_ALG_NONE. 227 */ 228 struct vb2_guid guid; 229 } __attribute__((packed)); 230 231 #define EXPECTED_VB2_SIGNATURE_SIZE \ 232 (EXPECTED_VB2_STRUCT_COMMON_SIZE + EXPECTED_GUID_SIZE + 16) 233 234 235 /* Current version of vb2_keyblock struct */ 236 #define VB2_KEYBLOCK_VERSION_MAJOR 3 237 #define VB2_KEYBLOCK_VERSION_MINOR 0 238 239 /* 240 * Key block. This contains a signed, versioned key for use in the next stage 241 * of verified boot. 242 * 243 * The key block data must be arranged like this: 244 * 1) vb2_keyblock header struct h 245 * 2) Keyblock description (pointed to by h.c.fixed_size) 246 * 3) Data key (pointed to by h.data_key_offset) 247 * 4) Signatures (first signature pointed to by h.sig_offset) 248 * 249 * The signatures from 4) must cover all the data from 1), 2), 3). That is, 250 * signatures must sign all data up to sig_offset. 251 */ 252 struct vb2_keyblock { 253 /* Common header fields */ 254 struct vb2_struct_common c; 255 256 /* Flags (VB2_KEY_BLOCK_FLAG_*) */ 257 uint32_t flags; 258 259 /* 260 * Offset of key (struct vb2_packed_key) to use in next stage of 261 * verification, from start of the keyblock. 262 */ 263 uint32_t key_offset; 264 265 /* Number of keyblock signatures which follow */ 266 uint32_t sig_count; 267 268 /* 269 * Offset of the first signature (struct vb2_signature) from the start 270 * of the keyblock. 271 * 272 * Signatures sign the contents of this struct and the data pointed to 273 * by data_key_offset, but not themselves or other signatures. 274 * 275 * For the firmware, there may be only one signature. 276 * 277 * Kernels often have at least two signatures - one using the kernel 278 * subkey from the RW firmware (for signed kernels) and one which is 279 * simply a SHA-512 hash (for unsigned developer kernels). 280 * 281 * The GUID for each signature indicates which key was used to generate 282 * the signature. 283 */ 284 uint32_t sig_offset; 285 } __attribute__((packed)); 286 287 #define EXPECTED_VB2_KEYBLOCK_SIZE (EXPECTED_VB2_STRUCT_COMMON_SIZE + 16) 288 289 290 /* Current version of vb2_fw_preamble struct */ 291 #define VB2_FW_PREAMBLE_VERSION_MAJOR 3 292 #define VB2_FW_PREAMBLE_VERSION_MINOR 0 293 294 /* Flags for vb2_fw_preamble.flags */ 295 /* Reserved; do not use */ 296 #define VB2_FIRMWARE_PREAMBLE_RESERVED0 0x00000001 297 /* Do not allow use of any hardware crypto accelerators. */ 298 #define VB2_FIRMWARE_PREAMBLE_DISALLOW_HWCRYPTO 0x00000002 299 300 /* 301 * Firmware preamble 302 * 303 * The preamble data must be arranged like this: 304 * 1) vb2_fw_preamble header struct h 305 * 2) Preamble description (pointed to by h.c.fixed_size) 306 * 3) Hashes (pointed to by h.hash_offset) 307 * 4) Signature (pointed to by h.sig_offset) 308 * 309 * The signature 4) must cover all the data from 1), 2), 3). 310 */ 311 struct vb2_fw_preamble { 312 /* Common header fields */ 313 struct vb2_struct_common c; 314 315 /* Flags; see VB2_FIRMWARE_PREAMBLE_* */ 316 uint32_t flags; 317 318 /* Firmware version */ 319 uint32_t fw_version; 320 321 /* Offset of signature (struct vb2_signature) for this preamble */ 322 uint32_t sig_offset; 323 324 /* 325 * The preamble contains a list of hashes (struct vb2_signature) for 326 * the various firmware components. These have sig_alg=VB2_SIG_NONE, 327 * and the GUID for each hash identifies the component being hashed. 328 * The calling firmware is responsible for knowing where to find those 329 * components, which may be on a different storage device than this 330 * preamble. 331 */ 332 333 /* Number of hash entries */ 334 uint32_t hash_count; 335 336 /* Offset of first hash entry from start of preamble */ 337 uint32_t hash_offset; 338 } __attribute__((packed)); 339 340 #define EXPECTED_VB2_FW_PREAMBLE_SIZE (EXPECTED_VB2_STRUCT_COMMON_SIZE + 20) 341 342 #endif /* VBOOT_REFERENCE_VB2_STRUCT_H_ */ 343