1 /* Copyright 2014 The ChromiumOS Authors 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_VB21_STRUCT_H_ 12 #define VBOOT_REFERENCE_VB21_STRUCT_H_ 13 14 #include "2id.h" 15 #include "2sysincludes.h" 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif /* __cplusplus */ 20 21 /* 22 * Magic numbers used by vb21_struct_common.magic. 23 * 24 * All valid numbers should be listed here to avoid accidental overlap. 25 * Numbers start at a large value, so that previous parsers (which stored 26 * things like lengths and offsets at that field) will detect and reject new 27 * structs as invalid. 28 */ 29 enum vb21_struct_common_magic { 30 /* "Vb2I" = vb21_packed_private_key.c.magic */ 31 VB21_MAGIC_PACKED_PRIVATE_KEY = 0x49326256, 32 33 /* "Vb2P" = vb21_packed_key.c.magic */ 34 VB21_MAGIC_PACKED_KEY = 0x50326256, 35 36 /* "Vb2S" = vb21_signature.c.magic */ 37 VB21_MAGIC_SIGNATURE = 0x53326256, 38 }; 39 40 41 /* 42 * Generic struct header for all vboot2.1 structs. This makes it easy to 43 * automatically parse and identify vboot structs (e.g., in futility). This 44 * must be the first member of the parent vboot2.1 struct. 45 */ 46 struct vb21_struct_common { 47 /* Magic number; see vb21_struct_common_magic for expected values */ 48 uint32_t magic; 49 50 /* 51 * Parent struct version; see each struct for the expected value. 52 * 53 * How to handle struct version mismatches, if the parser is version 54 * A.b and the data is version C.d: 55 * 1) If A.b == C.d, we're good. 56 * 2) If A != C, the data cannot be parsed at all. 57 * 3) If b < d, C.d is a newer version of data which is backwards- 58 * compatible to old parsers. We're good. 59 * 4) If b > d, C.d is an older version of data. The parser should 60 * use default values for fields added after version d. We're 61 * good. 62 * 63 * Struct versions start at 3.0, since the highest version of the old 64 * structures was 2.1. This way, there is no possibility of collision 65 * for old code which depends on the version number. 66 */ 67 uint16_t struct_version_major; 68 uint16_t struct_version_minor; 69 70 /* 71 * Size of the parent structure and all its data, including the 72 * description and any necessary padding. That is, all data must lie 73 * in a contiguous region of <total_size> bytes starting at the first 74 * byte of this header. 75 */ 76 uint32_t total_size; 77 78 /* 79 * Size of the fixed portion of the parent structure. If a description 80 * is present, it must start at this offset. 81 */ 82 uint32_t fixed_size; 83 84 /* 85 * The object may contain an ASCII description following the fixed 86 * portion of the structure. If it is present, it must be 87 * null-terminated, and padded with 0 (null) bytes to a multiple of 32 88 * bits. 89 * 90 * Size of ASCII description in bytes, counting null terminator and 91 * padding (if any). Set 0 if no description is present. If non-zero, 92 * there must be a null terminator (0) at offset (fixed_size + 93 * desc_size - 1). 94 */ 95 uint32_t desc_size; 96 } __attribute__((packed)); 97 98 #define EXPECTED_VB21_STRUCT_COMMON_SIZE 20 99 100 /* Current version of vb21_packed_key struct */ 101 #define VB21_PACKED_KEY_VERSION_MAJOR 3 102 #define VB21_PACKED_KEY_VERSION_MINOR 0 103 104 /* 105 * Packed public key data 106 * 107 * The key data must be arranged like this: 108 * 1) vb21_packed_key header struct h 109 * 2) Key description (pointed to by h.c.fixed_size) 110 * 3) Key data key (pointed to by h.key_offset) 111 */ 112 struct vb21_packed_key { 113 /* Common header fields */ 114 struct vb21_struct_common c; 115 116 /* Offset of key data from start of this struct */ 117 uint32_t key_offset; 118 119 /* Size of key data in bytes (NOT strength of key in bits) */ 120 uint32_t key_size; 121 122 /* Signature algorithm used by the key (enum vb2_signature_algorithm) */ 123 uint16_t sig_alg; 124 125 /* 126 * Hash digest algorithm used with the key (enum vb2_hash_algorithm). 127 * This is explicitly specified as part of the key to prevent use of a 128 * strong key with a weak hash. 129 */ 130 uint16_t hash_alg; 131 132 /* Key version */ 133 uint32_t key_version; 134 135 /* Key ID */ 136 struct vb2_id id; 137 } __attribute__((packed)); 138 139 #define EXPECTED_VB21_PACKED_KEY_SIZE \ 140 (EXPECTED_VB21_STRUCT_COMMON_SIZE + 16 + EXPECTED_ID_SIZE) 141 142 /* Current version of vb21_packed_private_key struct */ 143 #define VB21_PACKED_PRIVATE_KEY_VERSION_MAJOR 3 144 #define VB21_PACKED_PRIVATE_KEY_VERSION_MINOR 0 145 146 /* 147 * Packed private key data 148 * 149 * The key data must be arranged like this: 150 * 1) vb21_packed_private_key header struct h 151 * 2) Key description (pointed to by h.c.fixed_size) 152 * 3) Key data key (pointed to by h.key_offset) 153 */ 154 struct vb21_packed_private_key { 155 /* Common header fields */ 156 struct vb21_struct_common c; 157 158 /* Offset of key data from start of this struct */ 159 uint32_t key_offset; 160 161 /* Size of key data in bytes (NOT strength of key in bits) */ 162 uint32_t key_size; 163 164 /* Signature algorithm used by the key (enum vb2_signature_algorithm) */ 165 uint16_t sig_alg; 166 167 /* 168 * Hash digest algorithm used with the key (enum vb2_hash_algorithm). 169 * This is explicitly specified as part of the key to prevent use of a 170 * strong key with a weak hash. 171 */ 172 uint16_t hash_alg; 173 174 /* Key ID */ 175 struct vb2_id id; 176 } __attribute__((packed)); 177 178 #define EXPECTED_VB21_PACKED_PRIVATE_KEY_SIZE \ 179 (EXPECTED_VB21_STRUCT_COMMON_SIZE + 12 + EXPECTED_ID_SIZE) 180 181 /* Current version of vb21_signature struct */ 182 #define VB21_SIGNATURE_VERSION_MAJOR 3 183 #define VB21_SIGNATURE_VERSION_MINOR 0 184 185 /* 186 * Signature data 187 * 188 * The signature data must be arranged like this: 189 * 1) vb21_signature header struct h 190 * 2) Signature description (pointed to by h.c.fixed_size) 191 * 3) Signature data (pointed to by h.sig_offset) 192 */ 193 struct vb21_signature { 194 /* Common header fields */ 195 struct vb21_struct_common c; 196 197 /* Offset of signature data from start of this struct */ 198 uint32_t sig_offset; 199 200 /* Size of signature data in bytes */ 201 uint32_t sig_size; 202 203 /* Size of the data block which was signed in bytes */ 204 uint32_t data_size; 205 206 /* Signature algorithm used (enum vb2_signature_algorithm) */ 207 uint16_t sig_alg; 208 209 /* Hash digest algorithm used (enum vb2_hash_algorithm) */ 210 uint16_t hash_alg; 211 212 /* 213 * ID for the signature. 214 * 215 * If this is a keyblock signature entry, this is the ID of the key 216 * used to generate this signature. This allows the firmware to 217 * quickly determine which signature block (if any) goes with the key 218 * being used by the firmware. 219 * 220 * If this is a preamble hash entry, this is the ID of the data type 221 * being hashed. There is no key ID, because sig_alg=VB2_ALG_NONE. 222 */ 223 struct vb2_id id; 224 } __attribute__((packed)); 225 226 #define EXPECTED_VB21_SIGNATURE_SIZE \ 227 (EXPECTED_VB21_STRUCT_COMMON_SIZE + 16 + EXPECTED_ID_SIZE) 228 229 #ifdef __cplusplus 230 } 231 #endif /* __cplusplus */ 232 233 #endif /* VBOOT_REFERENCE_VB21_STRUCT_H_ */ 234