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