OLD | NEW |
| (Empty) |
1 /* 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 kernel image. | |
6 * (Firmware Portion) | |
7 */ | |
8 | |
9 #ifndef VBOOT_REFERENCE_KERNEL_IMAGE_FW_H_ | |
10 #define VBOOT_REFERENCE_KERNEL_IMAGE_FW_H_ | |
11 | |
12 #include <stdint.h> | |
13 | |
14 #include "cryptolib.h" | |
15 | |
16 #define KERNEL_MAGIC "CHROMEOS" | |
17 #define KERNEL_MAGIC_SIZE 8 | |
18 | |
19 #define DEV_MODE_ENABLED 1 | |
20 #define DEV_MODE_DISABLED 0 | |
21 | |
22 typedef struct KernelImage { | |
23 uint8_t magic[KERNEL_MAGIC_SIZE]; | |
24 /* Key header */ | |
25 uint16_t header_version; /* Header version. */ | |
26 uint16_t header_len; /* Length of the header. */ | |
27 uint16_t firmware_sign_algorithm; /* Signature algorithm used by the firmware | |
28 * signing key (used to sign this kernel | |
29 * header. */ | |
30 uint16_t kernel_sign_algorithm; /* Signature algorithm used by the kernel | |
31 * signing key. */ | |
32 uint16_t kernel_key_version; /* Key Version# for preventing rollbacks. */ | |
33 uint8_t* kernel_sign_key; /* Pre-processed public half of signing key. */ | |
34 /* TODO(gauravsh): Do we need a choice of digest algorithms for the header | |
35 * checksum? */ | |
36 uint8_t header_checksum[SHA512_DIGEST_SIZE]; /* SHA-512 Crytographic hash of | |
37 * the concatenation of the | |
38 * header fields, i.e. | |
39 * [header_len, | |
40 * firmware_sign_algorithm, | |
41 * sign_algorithm, sign_key, | |
42 * key_version] */ | |
43 /* End of kernel key header. */ | |
44 uint8_t* kernel_key_signature; /* Signature of the header above. */ | |
45 | |
46 /* Kernel preamble */ | |
47 uint16_t kernel_version; /* Kernel Version# for preventing rollbacks. */ | |
48 uint64_t kernel_len; /* Length of the actual kernel image. */ | |
49 uint64_t bootloader_offset; /* Offset of bootloader in kernel_data. */ | |
50 uint64_t bootloader_size; /* Size of bootloader in bytes. */ | |
51 uint64_t padded_header_size; /* start of kernel_data in disk partition */ | |
52 uint8_t* kernel_signature; /* Signature on [kernel_data] below. | |
53 * NOTE: This is only considered valid | |
54 * if preamble_signature successfully verifies. */ | |
55 /* end of preamble */ | |
56 uint8_t* preamble_signature; /* signature on preamble, (includes | |
57 [kernel_signature]) */ | |
58 uint8_t* kernel_data; /* Actual kernel data. */ | |
59 | |
60 } KernelImage; | |
61 | |
62 /* Error Codes for VerifyFirmware. */ | |
63 #define VERIFY_KERNEL_SUCCESS 0 | |
64 #define VERIFY_KERNEL_INVALID_IMAGE 1 | |
65 #define VERIFY_KERNEL_KEY_SIGNATURE_FAILED 2 | |
66 #define VERIFY_KERNEL_INVALID_ALGORITHM 3 | |
67 #define VERIFY_KERNEL_PREAMBLE_SIGNATURE_FAILED 4 | |
68 #define VERIFY_KERNEL_SIGNATURE_FAILED 5 | |
69 #define VERIFY_KERNEL_WRONG_MAGIC 6 | |
70 #define VERIFY_KERNEL_MAX 7 /* Generic catch-all. */ | |
71 | |
72 extern char* kVerifyKernelErrors[VERIFY_KERNEL_MAX]; | |
73 | |
74 /* Returns the length of the verified boot kernel preamble based on | |
75 * kernel signing algorithm [algorithm]. */ | |
76 uint64_t GetKernelPreambleLen(int algorithm); | |
77 | |
78 /* Returns the length of the Kernel Verified Boot header excluding | |
79 * [kernel_data]. | |
80 * | |
81 * This is always non-zero, so a return value of 0 signifies an error. | |
82 */ | |
83 uint64_t GetVBlockHeaderSize(const uint8_t* vkernel_blob); | |
84 | |
85 /* Checks for the sanity of the kernel key header at [kernel_header_blob]. | |
86 * If [dev_mode] is enabled, also checks the kernel key signature using the | |
87 * pre-processed public firmware signing key [firmware_sign_key_blob]. | |
88 * | |
89 * On success, puts firmware signature algorithm in [firmware_algorithm], | |
90 * kernel signature algorithm in [kernel_algorithm], kernel header | |
91 * length in [header_len], and return 0. | |
92 * Else, return error code on failure. | |
93 */ | |
94 int VerifyKernelKeyHeader(const uint8_t* firmware_sign_key_blob, | |
95 const uint8_t* kernel_header_blob, | |
96 const int dev_mode, | |
97 int* firmware_algorithm, | |
98 int* kernel_algorithm, | |
99 int* header_len); | |
100 | |
101 /* Checks the kernel preamble signature at [kernel_preamble_blob] | |
102 * using the signing key [kernel_sign_key]. | |
103 * | |
104 * On success, put kernel length into [kernel_len], and return 0. | |
105 * Else, return error code on failure. | |
106 */ | |
107 int VerifyKernelPreamble(RSAPublicKey* kernel_sign_key, | |
108 const uint8_t* kernel_preamble_blob, | |
109 int algorithm, | |
110 uint64_t* kernel_len); | |
111 | |
112 /* Checks [kernel_signature] on the kernel data at location [kernel_data]. The | |
113 * signature is assumed to be generated using algorithm [algorithm]. | |
114 * The length of the kernel data is [kernel_len]. | |
115 * | |
116 * Return 0 on success, error code on failure. | |
117 */ | |
118 int VerifyKernelData(RSAPublicKey* kernel_sign_key, | |
119 const uint8_t* kernel_signature, | |
120 const uint8_t* kernel_data, | |
121 uint64_t kernel_len, | |
122 int algorithm); | |
123 | |
124 /* Verifies the kernel key header and preamble at [kernel_header_blob] | |
125 * using the firmware public key [firmware_key_blob]. If [dev_mode] is 1 | |
126 * (active), then key header verification is skipped. | |
127 * | |
128 * On success, fills in the fields of image with the kernel header and | |
129 * preamble fields. | |
130 * | |
131 * Note that pointers in the image point directly into the input | |
132 * kernel_header_blob. image->kernel_data is set to NULL, since it's not | |
133 * part of the header and preamble data itself. | |
134 * | |
135 * On success, the signing key to use for kernel data verification is | |
136 * returned in [kernel_sign_key], This must be free-d explicitly by | |
137 * the caller after use. On failure, the signing key is set to NULL. | |
138 * | |
139 * Returns 0 on success, error code on failure. | |
140 */ | |
141 int VerifyKernelHeader(const uint8_t* firmware_key_blob, | |
142 const uint8_t* kernel_header_blob, | |
143 uint64_t kernel_header_blob_len, | |
144 const int dev_mode, | |
145 KernelImage* image, | |
146 RSAPublicKey** kernel_sign_key); | |
147 | |
148 /* Performs a chained verify of the kernel blob [kernel_blob]. If | |
149 * [dev_mode] is 0 [inactive], then the pre-processed public signing key | |
150 * [root_key_blob] is used to verify the signature of the signing key, | |
151 * else the check is skipped. | |
152 * Returns 0 on success, error code on failure. | |
153 * | |
154 * NOTE: The length of the kernel blob is derived from reading the fields | |
155 * in the first few bytes of the buffer. This might look risky but in firmware | |
156 * land, the start address of the kernel_blob will always be fixed depending | |
157 * on the memory map on the particular platform. In addition, the signature on | |
158 * length itself is checked early in the verification process for extra safety. | |
159 */ | |
160 int VerifyKernel(const uint8_t* signing_key_blob, | |
161 const uint8_t* kernel_blob, | |
162 const int dev_mode); | |
163 | |
164 /* Returns the logical version of a kernel blob which is calculated as | |
165 * (kernel_key_version << 16 | kernel_version). */ | |
166 uint32_t GetLogicalKernelVersion(uint8_t* kernel_blob); | |
167 | |
168 #endif /* VBOOT_REFERENCE_KERNEL_IMAGE_FW_H_ */ | |
OLD | NEW |