1 /*
2  * Copyright 2021 Google LLC
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef PLATFORMS_SECURITY_TITAN_CR51_IMAGE_DESCRIPTOR_H_
18 #define PLATFORMS_SECURITY_TITAN_CR51_IMAGE_DESCRIPTOR_H_
19 #include <stddef.h>
20 #include <stdint.h>
21 
22 #ifdef __cplusplus
23 /* _Static_assert is usually not enabled in C++ mode by compilers. */
24 #include <assert.h>
25 #define _Static_assert static_assert
26 #endif
27 /* This structure encodes a superset of what we have historically encoded in:
28  *  - FMAP & HMAP
29  *  - BBINFO
30  *  - BIOS signature header
31  *
32  *  Unless explicitly noted all fields are little-endian & offset/size fields
33  *  are in bytes. This struct must reside in a IMAGE_REGION_STATIC region.
34  *  In the context of Haven it must also reside on a 64K boundary.
35  *  The size of the hashed/signed portion of the descriptor region can be
36  *  determined solely by parsing the (fixed) image_descriptor struct.
37  *
38  *  --------------------------------Flash layout--------------------------------
39  *  |                     struct image_descriptor (signed)                     |
40  *  |                struct image_region[region_count] (signed)                |
41  *  ----------------------------------------------------------------------------
42  *  |               (optional: hash_type) struct hash_* (signed)               |
43  *  ----------------------------------------------------------------------------
44  *  |           (optional: denylist_size) struct denylist (signed)             |
45  *  |             struct denylist_record[denylist_size] (signed)               |
46  *  ----------------------------------------------------------------------------
47  *  |                (optional: blob_size) struct blob (signed)                |
48  *  |                     uint8_t blob[blob_size] (signed)                     |
49  *  ----------------------------------------------------------------------------
50  *  |    (optional: signature_scheme) struct signature_* (partially signed)    |
51  *  ----------------------------------------------------------------------------
52  */
53 
54 // clang-format off
55 #define IMAGE_REGION_STATIC                     (1 << 0)
56 #define IMAGE_REGION_COMPRESSED                 (1 << 1)
57 #define IMAGE_REGION_WRITE_PROTECTED            (1 << 2)
58 #define IMAGE_REGION_READ_PROTECTED             (1 << 3)
59 #define IMAGE_REGION_PERSISTENT                 (1 << 4)
60 #define IMAGE_REGION_PERSISTENT_RELOCATABLE     (1 << 5)
61 #define IMAGE_REGION_PERSISTENT_EXPANDABLE      (1 << 6)
62 #define IMAGE_REGION_OVERRIDE                   (1 << 7)
63 #define IMAGE_REGION_OVERRIDE_ON_TRANSITION     (1 << 8)
64 #define IMAGE_REGION_MAILBOX                    (1 << 9)
65 #define IMAGE_REGION_SKIP_BOOT_VALIDATION       (1 << 10)
66 #define IMAGE_REGION_EMPTY                      (1 << 11)
67 // clang-format on
68 
69 /* Little endian on flash. */
70 #define DESCRIPTOR_MAGIC 0x5f435344474d495f // "_IMGDSC_"
71 #define HASH_MAGIC 0x48534148               // "HASH"
72 #define DENYLIST_MAGIC 0x4b434c42           // "BLCK"
73 #define BLOB_MAGIC 0x424f4c42               // "BLOB"
74 #define SIGNATURE_MAGIC 0x4e474953          // "SIGN"
75 
76 /* Values for 'blob_data.blob_type_magic'. Little-endian on flash. */
77 
78 /* Indicates that 'blob_data.blob_payload' contains a serialized
79  * platforms.security.titan.DescriptorExtensions protocol buffer message. There
80  * must be zero or one DescriptorExtensions in an image. If more than one is
81  * found, the image descriptor is invalid and the image must be treated as
82  * unsigned.
83  */
84 #define BLOB_TYPE_MAGIC_DESCRIPTOR_EXTENSIONS 0x58454250 // "PBEX"
85 
86 /* Indicates that 'blob_data.blob_payload' contains an image_mauv structure.
87  * There must be zero or one image_mauv
88  * structures in an image. If more than one is found, the image descriptor is
89  * invalid and the image must be treated as unsigned.
90  */
91 #define BLOB_TYPE_MAGIC_MAUV 0x5655414D // "MAUV"
92 
93 /* Indicates that 'blob_data.blob_payload' contains a 32-byte sha256 hash of
94  * all the IMAGE_REGION_STATIC partitions that don't have
95  * IMAGE_REGION_SKIP_BOOT_VALIDATION set.
96  */
97 #define BLOB_TYPE_MAGIC_BOOT_HASH_SHA256 0x48534842 // "BHSH"
98 
99 /* Indicates that 'blob_data.blob_payload' contains a lockdown_control
100  * structure. There must be zero or
101  * one lockdown_status structures in an image. If more than one is found, the
102  * image descriptor is invalid and the image must be treated as unsigned.
103  */
104 #define BLOB_TYPE_MAGIC_LOCKDOWN_CONTROL 0x4E444B4C // "LKDN"
105 
106 /* Indicates the type of the image. The type of the image also indicates the
107  * family of key that was used to sign the image. If the image type is signed
108  * with a key stored in RKM, then a corresponding enumeration should be added to
109  * google3/platforms/security/titan/keyspec.proto.
110  *
111  * Note: if the image type is IMAGE_UNSIGNED_INTEGRITY, the signature_scheme has
112  * to be of type
113  * *_NO_SIGNATURE. Also, all other image types cannot transition to an image of
114  * type IMAGE_UNSIGNED_INTEGRITY.
115  *
116  * The way to verify an image of type IMAGE_UNSIGNED_INTEGRITY differs from
117  * other types of images as it is not signed with an asymmetric key. Instead,
118  * one can verify the integrity by computing the shasum over the descriptor.
119  */
120 enum image_type
121 {
122     IMAGE_DEV = 0,
123     IMAGE_PROD = 1,
124     IMAGE_BREAKOUT = 2,
125     IMAGE_TEST = 3,
126     IMAGE_UNSIGNED_INTEGRITY = 4
127 };
128 
129 enum hash_type
130 {
131     HASH_NONE = 0,
132     HASH_SHA2_224 = 1,
133     HASH_SHA2_256 = 2,
134     HASH_SHA2_384 = 3,
135     HASH_SHA2_512 = 4,
136     HASH_SHA3_224 = 5,
137     HASH_SHA3_256 = 6,
138     HASH_SHA3_384 = 7,
139     HASH_SHA3_512 = 8
140 };
141 
142 /* Note: If the image is of type IMAGE_UNSIGNED_INTEGRITY, the signature_scheme
143  * has to be of type *_ONLY_NO_SIGNATURE.
144  */
145 enum signature_scheme
146 {
147     SIGNATURE_NONE = 0,
148     SIGNATURE_RSA2048_PKCS15 = 1,
149     SIGNATURE_RSA3072_PKCS15 = 2,
150     SIGNATURE_RSA4096_PKCS15 = 3,
151     SIGNATURE_RSA4096_PKCS15_SHA512 = 4,
152     SHA256_ONLY_NO_SIGNATURE = 5
153 };
154 
155 /* Payload image family. Distinct from the Haven image family. */
156 enum image_family
157 {
158     IMAGE_FAMILY_ALL = 0,
159     //  values < 256 are reserved for Google-internal use
160 };
161 
162 #define IMAGE_REGION_PROTECTED_ALIGNMENT (4096)
163 #define IMAGE_REGION_PROTECTED_PAGE_LENGTH (4096)
164 
165 struct image_region
166 {
167     uint8_t region_name[32]; // null-terminated ASCII string
168     uint32_t region_offset;  // read- and write- protected regions must be
169                              // aligned to IMAGE_REGION_PROTECTED_ALIGNMENT.
170                              // Other regions are also aligned which
171                              // simplifies their implementation.
172     uint32_t region_size;    // read- and write- protected regions must be a
173                              // multiple of IMAGE_REGION_PROTECTED_PAGE_LENGTH.
174     /* Regions will not be persisted across different versions.
175      * This field is intended to flag potential incompatibilities in the
176      * context of data migration (e.g. the ELOG format changed between
177      * two BIOS releases).
178      */
179     uint16_t region_version;
180     /* See IMAGE_REGION_* defines above. */
181     uint16_t region_attributes;
182 } __attribute__((__packed__));
183 
184 /* Main structure (major=1, minor=0). Verification process:
185  * - Hash(image_descriptor + region_count * struct image_region +
186  *        struct hash +
187  *        struct denylist + denylist_size * struct denylist_record +
188  *        struct blob + uint8_t blob[blob_size])
189  * - Verify the signature_* over the hash computed in the previous step
190  * - Compute the rolling hash of the regions marked IMAGE_REGION_STATIC
191  * - The image descriptor is excluded from the hash (descriptor_size bytes)
192  * - Compare the computed hash to the struct hash_*.hash
193  */
194 struct image_descriptor
195 {
196     uint64_t descriptor_magic; // #define DESCRIPTOR_MAGIC
197     /* Major revisions of this structure are not backwards compatible. */
198     uint8_t descriptor_major;
199     /* Minor revisions of this structure are backwards compatible. */
200     uint8_t descriptor_minor;
201     /* Padding. */
202     uint16_t reserved_0;
203 
204     /* This field allows us to mitigate a DOS vector if we end up
205      * scanning the image to discover the image descriptor. The offset
206      * and size are hashed with the rest of the descriptor to prevent
207      * an attacker from copying a valid descriptor to a different
208      * location.
209      *
210      * The offset is relative to the start of the image data.
211      */
212     uint32_t descriptor_offset;
213     /* Includes this struct as well as the auxiliary structs (hash_*,
214      * signature_*, denylist, and blob). This many bytes will be skipped when
215      * computing the hash of the region this struct resides in. Tail padding is
216      * allowed but must be all 0xff's.
217      */
218     uint32_t descriptor_area_size;
219 
220     /*** Image information. ***/
221 
222     /* Null-terminated ASCII string. For BIOS this would be the platform
223      * family-genus-version-date (e.g. ixion-hsw-2.8.0-2017.10.03).
224      * Intended for consumption by system software that generates human
225      * readable output (e.g. gsys).
226      */
227     uint8_t image_name[32];
228     /* Image transitions are enforced to be from/to the same family.
229      * 0 is treated as a wildcard (can upgrade to/from any image family).
230      * See image_family enum above.
231      */
232     uint32_t image_family;
233     /* Follow the Kibbles versioning scheme. */
234     uint32_t image_major;
235     uint32_t image_minor;
236     uint32_t image_point;
237     uint32_t image_subpoint;
238     /* Seconds since epoch. */
239     uint64_t build_timestamp;
240 
241     /* image_type enum { DEV, PROD, BREAKOUT, UNSIGNED_INTEGRITY} */
242     uint8_t image_type;
243     /* 0: no denylist struct, 1: watermark only, >1: watermark + denylist */
244     uint8_t denylist_size;
245     /* hash_type enum { NONE, SHA2_224, SHA2_256, ...} */
246     uint8_t hash_type;
247     /* signature_scheme enum { NONE, RSA2048_PKCS15, ...}
248      * If set, hash_type must be set as well (cannot be NONE).
249      */
250     uint8_t signature_scheme;
251 
252     /* struct image_region array size. */
253     uint8_t region_count;
254     uint8_t reserved_1;
255     uint16_t reserved_2;
256     /* The sum of the image_region.region_size fields must add up. */
257     uint32_t image_size;
258     /* Authenticated opaque data exposed to system software. Must be a multiple
259      * of 4 to maintain alignment. Does not include the blob struct magic.
260      */
261     uint32_t blob_size;
262     /* The list is strictly ordered by region_offset.
263      * Must exhaustively describe the image.
264      */
265     struct image_region image_regions[];
266 } __attribute__((__packed__));
267 
268 /* Hash the static regions (IMAGE_REGION_STATIC) excluding this descriptor
269  * structure i.e. skipping image_descriptor.descriptor_size bytes (optional).
270  */
271 struct hash_sha256
272 {
273     uint32_t hash_magic; // #define HASH_MAGIC
274     uint8_t hash[32];
275 } __attribute__((__packed__));
276 
277 struct hash_sha512
278 {
279     uint32_t hash_magic; // #define HASH_MAGIC
280     uint8_t hash[64];
281 } __attribute__((__packed__));
282 
283 struct denylist_record
284 {
285     uint32_t image_major;
286     uint32_t image_minor;
287     uint32_t image_point;
288     uint32_t image_subpoint;
289 } __attribute__((__packed__));
290 
291 struct denylist
292 {
293     uint32_t denylist_magic; // #define DENYLIST_MAGIC
294     /* Deny list. The first entry is the watermark. All subsequent entries must
295      * be newer than the watermark.
296      */
297     struct denylist_record denylist_record[];
298 } __attribute__((__packed__));
299 
300 struct blob
301 {
302     uint32_t blob_magic; // #define BLOB_MAGIC
303     /* Array of blob_data structures - see blob_data below for details. */
304     uint8_t blobs[];
305 } __attribute__((__packed__));
306 
307 /* blob data is expected to be aligned to 4 bytes */
308 #define BLOB_DATA_ALIGNMENT (4)
309 
310 /* If blobs[] is non-empty, it is expected to contain one more more instances
311  * of this struct. Each blob_data is followed by the minimum number of padding
312  * bytes (0-3) needed to maintain 4-byte alignment of blob_data structures.
313  * Padding bytes must be 0xFF and must be ignored by readers of blobs[].
314  *
315  * The ordering of the blob_data structures is undefined. Readers of blobs[]
316  * must locate expected blob_data by inspecting blob_type_magic of each
317  * blob_data. Readers are expected to ignore unknown blob_type_magic values,
318  * skipping over them to allow for future types.
319  *
320  * If blob_size is greater than zero but less than sizeof(struct blob_data), the
321  * blobs list is invalid. The blobs list is also invalid if there are multiple
322  * blob_data structures and the last one is truncated due to blob_size being too
323  * small to hold blob_payload_size. Readers must walk the entire length of the
324  * blob_data list to validate the list is well-formed. Any image with an
325  * invalid blobs list has an invalid descriptor and must be treated the same as
326  * an unsigned image.
327  */
328 struct blob_data
329 {
330     /* BLOB_TYPE_MAGIC_* */
331     uint32_t blob_type_magic;
332     /* Size of the data contained in blob_payload. Need not be a multiple of 4
333      * bytes. Must have sizeof(struct blob_data) + blob_payload_size <=
334      * blob_size.
335      */
336     uint32_t blob_payload_size;
337     uint8_t blob_payload[];
338 } __attribute__((__packed__));
339 
340 #define IMAGE_MAUV_STRUCT_VERSION 1
341 
342 struct image_mauv
343 {
344     /* Version of the MAUV structure. */
345     uint32_t mauv_struct_version;
346 
347     /* padding for 64-bit alignment of payload_security_version
348      * must be set to 0xffffffff */
349     uint32_t reserved_0;
350 
351     /* The version of the payload in which this `struct image_mauv` was
352      * embedded. This would be better inside of `struct image_descriptor`, but
353      * that structure doesn't have any spare fields or a reasonable way to grow
354      * the structure. When processing firmware updates, the update will be
355      * aborted if `payload_security_version` of the update payload is less than
356      * the `minimum_acceptable_update_version` in gNVRAM.
357      */
358     uint64_t payload_security_version;
359 
360     /* A monotonic counter that should be increased whenever the
361      * `minimum_acceptable_update_version or version_denylist fields are
362      * changed. In order for the image_mauv structure in gNVRAM to be updated
363      * after an payload update, the `mauv_update_timestamp` field in the new
364      * payload must be greater than the `mauv_update_timestamp` field in gNVRAM.
365      *
366      * Although the firmware doesn't assign any semantic meaning to this value,
367      * by convention should be the number of seconds since the unix epoch at the
368      * time the payload was signed.
369      */
370     uint64_t mauv_update_timestamp;
371 
372     /* Minimum acceptable update version.  An update to a payload with its
373      * `payload_security_version` field less than this field in gNVRAM is
374      * forbidden. This value is not monotonic.
375      */
376     uint64_t minimum_acceptable_update_version;
377 
378     /* padding for 64-bit alignment of version_denylist
379      * must be set to 0xffffffff */
380     uint32_t reserved_1;
381 
382     /* Number of entries in the denylist. */
383     uint32_t version_denylist_num_entries;
384 
385     /* A version denylist.  Updates to any version in this list will be rejected
386      * by the firmware.
387      */
388     uint64_t version_denylist[];
389 } __attribute__((packed));
390 
391 _Static_assert(offsetof(struct image_mauv, payload_security_version) %
392                        sizeof(uint64_t) ==
393                    0,
394                "bad payload_security_version alignment");
395 
396 _Static_assert(
397     offsetof(struct image_mauv, version_denylist) % sizeof(uint64_t) == 0,
398     "bad denylist alignment");
399 
400 // When A/B updates are enabled, SPS_EEPROM_LOCKDOWN_IMMUTABLE is invalid.
401 enum sps_eeprom_lockdown_status
402 {
403     // Unverified or invalid image. All writes allowed.
404     SPS_EEPROM_LOCKDOWN_FAILSAFE = 0,
405     // Valid image. Static regions are write protected. Write-protected
406     // non-static
407     // regions are still writable. In single image mode, can
408     // transition to SPS_EEPROM_LOCKDOWN_IMMUTABLE from this state.
409     SPS_EEPROM_LOCKDOWN_READY = 1,
410     // Entire image is write protected outside of the mailbox image region. Note
411     // that the payload image may be modified through EC Host mailbox
412     // update commands.
413     SPS_EEPROM_LOCKDOWN_IMMUTABLE = 2,
414     // Valid image. Immutable static and write-protected non-static regions. In
415     // single image mode, must reset to update.
416     SPS_EEPROM_LOCKDOWN_ENABLED = 3
417 };
418 
419 #define LOCKDOWN_CONTROL_STRUCT_VERSION 1
420 
421 struct lockdown_control
422 {
423     /* Version of the lockdown_status structure. */
424     uint32_t lockdown_control_struct_version;
425 
426     /* The default lockdown status for a valid signed payload image. The value
427      * is identical to `enum sps_eeprom_lockdown_status`. 0 = Failsafe, 1 =
428      * Ready.
429      */
430     uint32_t default_status;
431 };
432 
433 /* RSA4096 is the largest key type currently supported. */
434 #define MAX_KEY_SIZE_NBYTES 512
435 
436 /* Signature of the hash of the image_descriptor structure up to and including
437  * this struct but excluding the signature field (optional).
438  */
439 struct signature_rsa2048_pkcs15
440 {
441     uint32_t signature_magic; // #define SIGNATURE_MAGIC
442     /* Monotonic index of the key used to sign the image (starts at 1). */
443     uint16_t key_index;
444     /* Used to revoke keys, persisted by the enforcer. */
445     uint16_t min_key_index;
446     uint32_t exponent;      // little-endian
447     uint8_t modulus[256];   // big-endian
448     uint8_t signature[256]; // big-endian
449 } __attribute__((__packed__));
450 
451 struct signature_rsa3072_pkcs15
452 {
453     uint32_t signature_magic; // #define SIGNATURE_MAGIC
454     /* Monotonic index of the key used to sign the image (starts at 1). */
455     uint16_t key_index;
456     /* Used to revoke keys, persisted by the enforcer. */
457     uint16_t min_key_index;
458     uint32_t exponent;      // little-endian
459     uint8_t modulus[384];   // big-endian
460     uint8_t signature[384]; // big-endian
461 } __attribute__((__packed__));
462 
463 struct signature_rsa4096_pkcs15
464 {
465     uint32_t signature_magic; // #define SIGNATURE_MAGIC
466     /* Monotonic index of the key used to sign the image (starts at 1). */
467     uint16_t key_index;
468     /* Used to revoke keys, persisted by the enforcer. */
469     uint16_t min_key_index;
470     uint32_t exponent;      // little-endian
471     uint8_t modulus[512];   // big-endian
472     uint8_t signature[512]; // big-endian
473 } __attribute__((__packed__));
474 
475 struct sha256_only_no_signature
476 {
477     uint32_t signature_magic; // #define SIGNATURE_MAGIC
478     uint8_t digest[32];
479 } __attribute__((__packed__));
480 
481 #endif // PLATFORMS_SECURITY_TITAN_CR51_IMAGE_DESCRIPTOR_H_
482