Gaurav Shah | f67bcaa | 2010-02-28 19:18:24 -0800 | [diff] [blame] | 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 | * |
Gaurav Shah | ed9c96a | 2010-03-30 18:56:07 -0700 | [diff] [blame] | 5 | * API definitions for a generating and manipulating verified boot kernel images. |
| 6 | * (Userland portion.) |
Gaurav Shah | f67bcaa | 2010-02-28 19:18:24 -0800 | [diff] [blame] | 7 | */ |
| 8 | |
| 9 | #ifndef VBOOT_REFERENCE_KERNEL_IMAGE_H_ |
| 10 | #define VBOOT_REFERENCE_KERNEL_IMAGE_H_ |
| 11 | |
Gaurav Shah | ed9c96a | 2010-03-30 18:56:07 -0700 | [diff] [blame] | 12 | #include "kernel_image_fw.h" |
Gaurav Shah | f67bcaa | 2010-02-28 19:18:24 -0800 | [diff] [blame] | 13 | |
| 14 | /* Allocate and return a new KernelImage structure. */ |
| 15 | KernelImage* KernelImageNew(void); |
| 16 | |
| 17 | /* Deep free the contents of [image]. */ |
| 18 | void KernelImageFree(KernelImage* image); |
| 19 | |
| 20 | /* Read kernel data from file named [input_file]. |
| 21 | * |
| 22 | * Returns a filled up KernelImage on success, NULL on error. |
| 23 | */ |
| 24 | KernelImage* ReadKernelImage(const char* input_file); |
| 25 | |
Gaurav Shah | 80d129b | 2010-03-03 17:58:43 -0800 | [diff] [blame] | 26 | /* Get the length of the header for kernel image [image]. */ |
| 27 | int GetKernelHeaderLen(const KernelImage* image); |
| 28 | |
Gaurav Shah | 528a2c1 | 2010-03-18 13:10:10 -0700 | [diff] [blame] | 29 | /* Calculate and store the kernel header checksum of [image] |
| 30 | * in [header_checksum]. |
| 31 | * |
| 32 | * [header_checksum] must be a valid pointer to a buffer of |
| 33 | * SHA512_DIGEST_SIZE. |
| 34 | */ |
| 35 | void CalculateKernelHeaderChecksum(const KernelImage* image, |
| 36 | uint8_t* header_checksum); |
| 37 | |
Gaurav Shah | f5564fa | 2010-03-02 15:40:01 -0800 | [diff] [blame] | 38 | /* Get kernel header binary blob from an [image]. |
| 39 | * |
| 40 | * Caller owns the returned pointer and must Free() it. |
Gaurav Shah | f67bcaa | 2010-02-28 19:18:24 -0800 | [diff] [blame] | 41 | */ |
Gaurav Shah | f5564fa | 2010-03-02 15:40:01 -0800 | [diff] [blame] | 42 | uint8_t* GetKernelHeaderBlob(const KernelImage* image); |
Gaurav Shah | f67bcaa | 2010-02-28 19:18:24 -0800 | [diff] [blame] | 43 | |
Gaurav Shah | f5564fa | 2010-03-02 15:40:01 -0800 | [diff] [blame] | 44 | /* Get kernel config binary blob from an [image]. |
| 45 | * |
| 46 | * Caller owns the returned pointer and must Free() it. |
Gaurav Shah | f67bcaa | 2010-02-28 19:18:24 -0800 | [diff] [blame] | 47 | */ |
Gaurav Shah | f5564fa | 2010-03-02 15:40:01 -0800 | [diff] [blame] | 48 | uint8_t* GetKernelConfigBlob(const KernelImage* image); |
| 49 | |
| 50 | /* Get a verified kernel binary blob from an [image] and fill |
| 51 | * its length into blob_len. |
| 52 | * |
| 53 | * Caller owns the returned pointer and must Free() it. |
| 54 | */ |
Gaurav Shah | 1393711 | 2010-03-22 17:59:09 -0700 | [diff] [blame] | 55 | uint8_t* GetKernelBlob(const KernelImage* image, uint64_t* blob_len); |
Gaurav Shah | f67bcaa | 2010-02-28 19:18:24 -0800 | [diff] [blame] | 56 | |
Gaurav Shah | b85b06b | 2010-05-27 13:29:20 -0700 | [diff] [blame] | 57 | |
Gaurav Shah | f67bcaa | 2010-02-28 19:18:24 -0800 | [diff] [blame] | 58 | /* Write kernel data from [image] to a file named [input_file]. |
Gaurav Shah | 67660cd | 2010-05-29 01:58:07 -0700 | [diff] [blame] | 59 | * |
| 60 | * If [is_only_vblock] is non-zero, only the verification block (excluding the |
| 61 | * actual kernel data) is output. |
| 62 | * If [is_subkey_out] is non-zero, only the kernel key verification (subkey) |
| 63 | * header is output. |
Gaurav Shah | f67bcaa | 2010-02-28 19:18:24 -0800 | [diff] [blame] | 64 | * |
Gaurav Shah | f5564fa | 2010-03-02 15:40:01 -0800 | [diff] [blame] | 65 | * Return 1 on success, 0 on error. |
Gaurav Shah | f67bcaa | 2010-02-28 19:18:24 -0800 | [diff] [blame] | 66 | */ |
Gaurav Shah | f5564fa | 2010-03-02 15:40:01 -0800 | [diff] [blame] | 67 | int WriteKernelImage(const char* input_file, |
Gaurav Shah | 2480a18 | 2010-04-26 11:41:53 -0700 | [diff] [blame] | 68 | const KernelImage* image, |
Gaurav Shah | b85b06b | 2010-05-27 13:29:20 -0700 | [diff] [blame] | 69 | int is_only_vblock, |
| 70 | int is_subkey_out); |
Gaurav Shah | f67bcaa | 2010-02-28 19:18:24 -0800 | [diff] [blame] | 71 | |
Bill Richardson | f5db4b8 | 2010-05-27 11:15:14 -0700 | [diff] [blame] | 72 | /* Create a kernel_data blob from its components and fill |
| 73 | * its length into blob_len, plus some information about the bootloader. |
| 74 | * |
| 75 | * Caller owns the returned pointer and must Free() it. |
| 76 | */ |
| 77 | uint8_t* GenerateKernelBlob(const char* vmlinuz_file, |
| 78 | const char* config_file, |
| 79 | const char* bootloader_file, |
| 80 | uint64_t* blob_len, |
| 81 | uint64_t* bootloader_offset, |
| 82 | uint64_t* bootloader_size); |
| 83 | |
Gaurav Shah | f67bcaa | 2010-02-28 19:18:24 -0800 | [diff] [blame] | 84 | /* Pretty print the contents of [image]. Only headers and metadata information |
| 85 | * is printed. |
| 86 | */ |
| 87 | void PrintKernelImage(const KernelImage* image); |
| 88 | |
Gaurav Shah | f67bcaa | 2010-02-28 19:18:24 -0800 | [diff] [blame] | 89 | /* Performs a chained verify of the kernel [image]. If [dev_mode] is |
| 90 | * 0 (inactive), then the [firmware_signing_key] is used to verify the signature |
| 91 | * of the signing key, else the check is skipped. |
| 92 | * |
| 93 | * Returns 0 on success, error code on failure. |
| 94 | */ |
| 95 | int VerifyKernelImage(const RSAPublicKey* firmware_signing_key, |
| 96 | const KernelImage* image, |
| 97 | int dev_mode); |
| 98 | |
| 99 | |
| 100 | /* Maps error codes from VerifyKernel*() to error description. */ |
| 101 | const char* VerifyKernelErrorString(int error); |
| 102 | |
| 103 | /* Add a kernel signing key signature to the key header to a kernel image |
| 104 | * [image] using the private key in file [firmware_key_file]. |
| 105 | * |
| 106 | * Return 1 on success, 0 on failure. |
| 107 | */ |
| 108 | int AddKernelKeySignature(KernelImage* image, const char* firmware_key_file); |
| 109 | |
| 110 | /* Add a kernel and kernel config signature to a kernel image [image] |
| 111 | * using the private signing key in file [kernel_sigining_key_file]. |
| 112 | * |
| 113 | * Return 1 on success, 0 on failure. |
| 114 | */ |
Gaurav Shah | f5564fa | 2010-03-02 15:40:01 -0800 | [diff] [blame] | 115 | int AddKernelSignature(KernelImage* image, |
| 116 | const char* kernel_sigining_key_file); |
Gaurav Shah | f67bcaa | 2010-02-28 19:18:24 -0800 | [diff] [blame] | 117 | |
Gaurav Shah | f67bcaa | 2010-02-28 19:18:24 -0800 | [diff] [blame] | 118 | #endif /* VBOOT_REFERENCE_KERNEL_IMAGE_H_ */ |