blob: fb90f0271b8d8f6e67dc80ab657eca52f9ed4012 [file] [log] [blame]
Gaurav Shahed9c96a2010-03-30 18:56:07 -07001/* Copyright (c) 2010 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 * Data structure and API definitions for a verified boot firmware image.
6 * (Firmware Portion)
7 */
8
9#ifndef VBOOT_REFERENCE_FIRMWARE_IMAGE_FW_H_
10#define VBOOT_REFERENCE_FIRMWARE_IMAGE_FW_H_
11
12#include <stdint.h>
Gaurav Shah5411c7a2010-03-31 10:56:49 -070013#include "cryptolib.h"
Gaurav Shahed9c96a2010-03-30 18:56:07 -070014
15#define FIRMWARE_MAGIC "CHROMEOS"
16#define FIRMWARE_MAGIC_SIZE 8
17#define FIRMWARE_PREAMBLE_SIZE 8
18
19/* RSA 8192 and SHA-512. */
20#define ROOT_SIGNATURE_ALGORITHM 11
21#define ROOT_SIGNATURE_ALGORITHM_STRING "11"
22
23typedef struct FirmwareImage {
24 uint8_t magic[FIRMWARE_MAGIC_SIZE];
25 /* Key Header */
26 uint16_t header_len; /* Length of the header. */
27 uint16_t firmware_sign_algorithm; /* Signature algorithm used by the signing
28 * key. */
29 uint16_t firmware_key_version; /* Key Version# for preventing rollbacks. */
30 uint8_t* firmware_sign_key; /* Pre-processed public half of signing key. */
31 uint8_t header_checksum[SHA512_DIGEST_SIZE]; /* SHA-512 hash of the header.*/
32
33 uint8_t firmware_key_signature[RSA8192NUMBYTES]; /* Signature of the header
34 * above. */
35
36 /* Firmware Preamble. */
37 uint16_t firmware_version; /* Firmware Version# for preventing rollbacks.*/
38 uint64_t firmware_len; /* Length of the rest of the R/W firmware data. */
Gaurav Shah95929192010-06-03 11:11:33 -070039 uint16_t kernel_subkey_sign_algorithm; /* Signature algorithm used for
40 * signing the kernel subkey. */
41 uint8_t* kernel_subkey_sign_key; /* Pre-processed public half of the kernel
42 * subkey signing key. */
Gaurav Shahed9c96a2010-03-30 18:56:07 -070043 uint8_t preamble[FIRMWARE_PREAMBLE_SIZE]; /* Remaining preamble data.*/
44
45 uint8_t* preamble_signature; /* Signature over the preamble. */
46
47 /* The firmware signature comes first as it may allow us to parallelize
48 * the firmware data fetch and RSA public operation.
49 */
50 uint8_t* firmware_signature; /* Signature on the Preamble +
51 [firmware_data]. */
52 uint8_t* firmware_data; /* Rest of firmware data */
53
54} FirmwareImage;
55
56
57/* Error Codes for VerifyFirmware* family of functions. */
58#define VERIFY_FIRMWARE_SUCCESS 0
59#define VERIFY_FIRMWARE_INVALID_IMAGE 1
60#define VERIFY_FIRMWARE_ROOT_SIGNATURE_FAILED 2
61#define VERIFY_FIRMWARE_INVALID_ALGORITHM 3
62#define VERIFY_FIRMWARE_PREAMBLE_SIGNATURE_FAILED 4
63#define VERIFY_FIRMWARE_SIGNATURE_FAILED 5
64#define VERIFY_FIRMWARE_WRONG_MAGIC 6
65#define VERIFY_FIRMWARE_WRONG_HEADER_CHECKSUM 7
66#define VERIFY_FIRMWARE_KEY_ROLLBACK 8
67#define VERIFY_FIRMWARE_VERSION_ROLLBACK 9
68#define VERIFY_FIRMWARE_MAX 10 /* Total number of error codes. */
69
70extern char* kVerifyFirmwareErrors[VERIFY_FIRMWARE_MAX];
71
Gaurav Shah95929192010-06-03 11:11:33 -070072/* Returns the length of the verified boot firmware preamble based on
73 * kernel subkey signing algorithm [algorithm]. */
74uint64_t GetFirmwarePreambleLen(int algorithm);
75
Gaurav Shahed9c96a2010-03-30 18:56:07 -070076/* Checks for the sanity of the firmware header pointed by [header_blob].
77 *
78 * On success, put signature algorithm in [algorithm], header length
79 * in [header_len], and return 0.
80 * Else, return error code on failure.
81 */
82int VerifyFirmwareHeader(const uint8_t* root_key_blob,
83 const uint8_t* header_blob,
84 int* algorithm,
85 int* header_len);
86
87/* Checks the preamble signature on firmware preamble pointed by
88 * [preamble_blob] using the signing key [sign_key].
89 *
90 * On success, put firmware length into [firmware_len], and return 0.
91 * Else, return error code on failure.
92 */
93int VerifyFirmwarePreamble(RSAPublicKey* sign_key,
94 const uint8_t* preamble_blob,
95 int algorithm,
96 uint64_t* firmware_len);
97
98/* Checks the signature on the preamble + firmware data at
Gaurav Shah02658822010-04-18 16:35:07 -070099 * [preamble_start] and [firmware_data].
Gaurav Shahed9c96a2010-03-30 18:56:07 -0700100 * The length of the actual firmware data is firmware_len and it is assumed to
101 * be prepended with the signature whose size depends on the signature_algorithm
102 * [algorithm]. This signature also covers the preamble data (but not the
103 * preamble signature itself).
104 *
105 * Return 0 on success, error code on failure.
106 */
107int VerifyFirmwareData(RSAPublicKey* sign_key,
108 const uint8_t* preamble_start,
Gaurav Shah02658822010-04-18 16:35:07 -0700109 const uint8_t* firmware_data,
Gaurav Shahed9c96a2010-03-30 18:56:07 -0700110 uint64_t firmware_len,
111 int algorithm);
112
Gaurav Shah02658822010-04-18 16:35:07 -0700113/* Performs a chained verify of the firmware blob [firmware_blob], using root
114 * key [root_key] and verification header [verification_header_blob].
Gaurav Shahed9c96a2010-03-30 18:56:07 -0700115 *
116 * Returns 0 on success, error code on failure.
117 *
118 * NOTE: The length of the firmware blob is derived from reading the fields
Gaurav Shah02658822010-04-18 16:35:07 -0700119 * in the first few bytes of the verification header. This might look risky but
120 * in firmware land, the start address of the firmware_blob will always be fixed
121 * depending on the memory map on the particular platform. In addition, the
122 * signature on length itself is checked early in the verification process for
123 * extra safety.
Gaurav Shahed9c96a2010-03-30 18:56:07 -0700124 */
125int VerifyFirmware(const uint8_t* root_key_blob,
Gaurav Shah02658822010-04-18 16:35:07 -0700126 const uint8_t* verification_header_blob,
Gaurav Shahed9c96a2010-03-30 18:56:07 -0700127 const uint8_t* firmware_blob);
128
129/* Returns the logical version of a firmware blob which is calculated as
130 * (firmware_key_version << 16 | firmware_version). */
131uint32_t GetLogicalFirmwareVersion(uint8_t* firmware_blob);
132
133#define BOOT_FIRMWARE_A_CONTINUE 1
134#define BOOT_FIRMWARE_B_CONTINUE 2
135#define BOOT_FIRMWARE_RECOVERY_CONTINUE 3
136
137/* This function is the driver used by the RO firmware to
138 * determine which copy of the firmware to boot from. It performs
139 * the requisite rollback index checking, including updating them,
140 * if required.
141 *
142 * Returns the code path to follow. It is one of:
143 * BOOT_FIRMWARE_A_CONTINUE Boot from Firmware A
144 * BOOT_FIRMWARE_B_CONTINUE Boot from Firmware B
145 * BOOT_FIRMWARE_RECOVERY_CONTINUE Jump to recovery mode
146 */
147int VerifyFirmwareDriver_f(uint8_t* root_key_blob,
Gaurav Shah02658822010-04-18 16:35:07 -0700148 uint8_t* verification_headerA,
Gaurav Shahed9c96a2010-03-30 18:56:07 -0700149 uint8_t* firmwareA,
Gaurav Shah02658822010-04-18 16:35:07 -0700150 uint8_t* verification_headerB,
Gaurav Shahed9c96a2010-03-30 18:56:07 -0700151 uint8_t* firmwareB);
152
Gaurav Shahed9c96a2010-03-30 18:56:07 -0700153#endif /* VBOOT_REFERENCE_FIRMWARE_IMAGE_FW_H_ */