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(offsetof(struct image_mauv, version_denylist) % 397 sizeof(uint64_t) == 398 0, 399 "bad denylist alignment"); 400 401 // When A/B updates are enabled, SPS_EEPROM_LOCKDOWN_IMMUTABLE is invalid. 402 enum sps_eeprom_lockdown_status 403 { 404 // Unverified or invalid image. All writes allowed. 405 SPS_EEPROM_LOCKDOWN_FAILSAFE = 0, 406 // Valid image. Static regions are write protected. Write-protected 407 // non-static 408 // regions are still writable. In single image mode, can 409 // transition to SPS_EEPROM_LOCKDOWN_IMMUTABLE from this state. 410 SPS_EEPROM_LOCKDOWN_READY = 1, 411 // Entire image is write protected outside of the mailbox image region. Note 412 // that the payload image may be modified through EC Host mailbox 413 // update commands. 414 SPS_EEPROM_LOCKDOWN_IMMUTABLE = 2, 415 // Valid image. Immutable static and write-protected non-static regions. In 416 // single image mode, must reset to update. 417 SPS_EEPROM_LOCKDOWN_ENABLED = 3 418 }; 419 420 #define LOCKDOWN_CONTROL_STRUCT_VERSION 1 421 422 struct lockdown_control 423 { 424 /* Version of the lockdown_status structure. */ 425 uint32_t lockdown_control_struct_version; 426 427 /* The default lockdown status for a valid signed payload image. The value 428 * is identical to `enum sps_eeprom_lockdown_status`. 0 = Failsafe, 1 = 429 * Ready. 430 */ 431 uint32_t default_status; 432 }; 433 434 /* RSA4096 is the largest key type currently supported. */ 435 #define MAX_KEY_SIZE_NBYTES 512 436 437 /* Signature of the hash of the image_descriptor structure up to and including 438 * this struct but excluding the signature field (optional). 439 */ 440 struct signature_rsa2048_pkcs15 441 { 442 uint32_t signature_magic; // #define SIGNATURE_MAGIC 443 /* Monotonic index of the key used to sign the image (starts at 1). */ 444 uint16_t key_index; 445 /* Used to revoke keys, persisted by the enforcer. */ 446 uint16_t min_key_index; 447 uint32_t exponent; // little-endian 448 uint8_t modulus[256]; // big-endian 449 uint8_t signature[256]; // big-endian 450 } __attribute__((__packed__)); 451 452 struct signature_rsa3072_pkcs15 453 { 454 uint32_t signature_magic; // #define SIGNATURE_MAGIC 455 /* Monotonic index of the key used to sign the image (starts at 1). */ 456 uint16_t key_index; 457 /* Used to revoke keys, persisted by the enforcer. */ 458 uint16_t min_key_index; 459 uint32_t exponent; // little-endian 460 uint8_t modulus[384]; // big-endian 461 uint8_t signature[384]; // big-endian 462 } __attribute__((__packed__)); 463 464 struct signature_rsa4096_pkcs15 465 { 466 uint32_t signature_magic; // #define SIGNATURE_MAGIC 467 /* Monotonic index of the key used to sign the image (starts at 1). */ 468 uint16_t key_index; 469 /* Used to revoke keys, persisted by the enforcer. */ 470 uint16_t min_key_index; 471 uint32_t exponent; // little-endian 472 uint8_t modulus[512]; // big-endian 473 uint8_t signature[512]; // big-endian 474 } __attribute__((__packed__)); 475 476 struct sha256_only_no_signature 477 { 478 uint32_t signature_magic; // #define SIGNATURE_MAGIC 479 uint8_t digest[32]; 480 } __attribute__((__packed__)); 481 482 #endif // PLATFORMS_SECURITY_TITAN_CR51_IMAGE_DESCRIPTOR_H_ 483