blob: 7bf53604f4b7627831228b0322377cc80bae26fc [file] [log] [blame]
Gaurav Shah431b9882010-02-12 15:54:37 -08001/* 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 Shahed9c96a2010-03-30 18:56:07 -07005 * API definitions for a verified boot firmware image.
6 * (Userland Portion)
Gaurav Shah431b9882010-02-12 15:54:37 -08007 */
8
9#ifndef VBOOT_REFERENCE_FIRMWARE_IMAGE_H_
10#define VBOOT_REFERENCE_FIRMWARE_IMAGE_H_
11
Gaurav Shahed9c96a2010-03-30 18:56:07 -070012#include "firmware_image_fw.h"
Gaurav Shah431b9882010-02-12 15:54:37 -080013
14/* Allocate and return a new FirmwareImage structure. */
15FirmwareImage* FirmwareImageNew(void);
16
17/* Deep free the contents of [fw]. */
18void FirmwareImageFree(FirmwareImage* fw);
19
Gaurav Shahf5564fa2010-03-02 15:40:01 -080020/* Read firmware data from file named [input_file].
Gaurav Shah431b9882010-02-12 15:54:37 -080021 *
Gaurav Shah23a2f3a2010-02-26 15:09:43 -080022 * Returns a filled up FirmwareImage structure on success, NULL on error.
Gaurav Shah431b9882010-02-12 15:54:37 -080023 */
Gaurav Shah23a2f3a2010-02-26 15:09:43 -080024FirmwareImage* ReadFirmwareImage(const char* input_file);
Gaurav Shah431b9882010-02-12 15:54:37 -080025
Gaurav Shah80d129b2010-03-03 17:58:43 -080026/* Get the length of the header for image [image]. */
27int GetFirmwareHeaderLen(const FirmwareImage* image);
28
Gaurav Shah528a2c12010-03-18 13:10:10 -070029/* Calculate and store the firmware 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 */
35void CalculateFirmwareHeaderChecksum(const FirmwareImage *image,
36 uint8_t* header_checksum);
37
Gaurav Shahf5564fa2010-03-02 15:40:01 -080038/* Get firmware header binary blob from an [image].
39 *
40 * Caller owns the returned pointer and must Free() it.
Gaurav Shah431b9882010-02-12 15:54:37 -080041 */
Gaurav Shahf5564fa2010-03-02 15:40:01 -080042uint8_t* GetFirmwareHeaderBlob(const FirmwareImage* image);
Gaurav Shah431b9882010-02-12 15:54:37 -080043
Gaurav Shahf5564fa2010-03-02 15:40:01 -080044/* Get firmware preamble binary blob from an [image].
45 *
46 * Caller owns the returned pointer and must Free() it.
Gaurav Shah431b9882010-02-12 15:54:37 -080047 */
Gaurav Shahf5564fa2010-03-02 15:40:01 -080048uint8_t* GetFirmwarePreambleBlob(const FirmwareImage* image);
Gaurav Shah431b9882010-02-12 15:54:37 -080049
Gaurav Shahf5564fa2010-03-02 15:40:01 -080050/* Get a verified firmware binary blob from an [image] and fill its
51 * length into blob_len.
52 *
53 * Caller owns the returned pointer and must Free() it.
54 */
Gaurav Shah456678b2010-03-10 18:38:45 -080055uint8_t* GetFirmwareBlob(const FirmwareImage* image, uint64_t* blob_len);
Gaurav Shah431b9882010-02-12 15:54:37 -080056
57/* Write firmware data from [image] into a file named [input_file].
58 *
Gaurav Shah67660cd2010-05-29 01:58:07 -070059 * If [is_just_vblock] is non-zero, only the verification block (excluding the
60 * actual firmware_data) is output.
61 * if [is_subkey_out] is non-zero, only the firmware key verification (subkey)
62 * header is output.
63 *
Gaurav Shahf5564fa2010-03-02 15:40:01 -080064 * Return 1 on success, 0 on failure.
Gaurav Shah431b9882010-02-12 15:54:37 -080065 */
Gaurav Shahf5564fa2010-03-02 15:40:01 -080066int WriteFirmwareImage(const char* input_file,
Gaurav Shah65127cc2010-04-14 14:29:02 -070067 const FirmwareImage* image,
Gaurav Shah67660cd2010-05-29 01:58:07 -070068 int is_only_vblock,
69 int is_subkey_out);
Gaurav Shahf5564fa2010-03-02 15:40:01 -080070
Gaurav Shah431b9882010-02-12 15:54:37 -080071/* Pretty print the contents of [image]. Only headers and metadata information
72 * is printed.
73 */
Gaurav Shah08df9b82010-02-23 16:16:23 -080074void PrintFirmwareImage(const FirmwareImage* image);
75
Gaurav Shah3199eed2010-03-25 13:04:45 -070076/* Performs a chained verify of the firmware [image].
Gaurav Shah431b9882010-02-12 15:54:37 -080077 *
78 * Returns 0 on success, error code on failure.
79 */
Gaurav Shah08df9b82010-02-23 16:16:23 -080080int VerifyFirmwareImage(const RSAPublicKey* root_key,
Gaurav Shah3199eed2010-03-25 13:04:45 -070081 const FirmwareImage* image);
Gaurav Shah431b9882010-02-12 15:54:37 -080082
83/* Maps error codes from VerifyFirmware() to error description. */
Gaurav Shah23a2f3a2010-02-26 15:09:43 -080084const char* VerifyFirmwareErrorString(int error);
Gaurav Shah431b9882010-02-12 15:54:37 -080085
Gaurav Shah431b9882010-02-12 15:54:37 -080086/* Add a root key signature to the key header to a firmware image [image]
87 * using the private root key in file [root_key_file].
88 *
89 * Return 1 on success, 0 on failure.
90 */
Gaurav Shah23a2f3a2010-02-26 15:09:43 -080091int AddFirmwareKeySignature(FirmwareImage* image, const char* root_key_file);
Gaurav Shah431b9882010-02-12 15:54:37 -080092
93/* Add firmware and preamble signature to a firmware image [image]
94 * using the private signing key in file [signing_key_file].
95 *
96 * Return 1 on success, 0 on failure.
97 */
Gaurav Shahf5564fa2010-03-02 15:40:01 -080098int AddFirmwareSignature(FirmwareImage* image, const char* signing_key_file);
Gaurav Shah431b9882010-02-12 15:54:37 -080099
Gaurav Shah431b9882010-02-12 15:54:37 -0800100#endif /* VBOOT_REFERENCE_FIRMWARE_IMAGE_H_ */