futility/futility.h

/* Copyright 2013 The ChromiumOS Authors
 * Use of this source code is governed by a BSD-style license that can be
 * found in the LICENSE file.
 */

#ifndef VBOOT_REFERENCE_FUTILITY_H_
#define VBOOT_REFERENCE_FUTILITY_H_

#include <stdint.h>

#include "2common.h"
#include "host_key.h"

/* This program */
#define MYNAME "futility"

/* Version string (autogenerated) */
extern const char futility_version[];

/* Bitfields indicating the struct/format versions supported by a command */
enum vboot_version  {
	/*
	 * v1.0 is the original structs used since the dawn of time.
	 * v2.0 can verify the firmware in smaller chunks, but there's
	 * no difference in the on-device structs, so it's only
	 * meaningful for the firmware API. Futility doesn't care.
	 */
	VBOOT_VERSION_1_0 = 0x00000001,

	/*
	 * v2.1 uses new and different structs, and is what v2.0 would have
	 * been if someone hadn't started using it before it was ready.
	 */
	VBOOT_VERSION_2_1 = 0x00000002,

	/*
	 * Everything we know about to date.
	 */
	VBOOT_VERSION_ALL = 0x00000003,
};

/* What's our preferred API & data format? */
extern enum vboot_version vboot_version;

/* Here's a structure to define the commands that futility implements. */
struct futil_cmd_t {
	/* String used to invoke this command */
	const char *const name;
	/* Function to do the work. Returns 0 on success.
	 * Called with argv[0] == "name".
	 * It should handle its own "--help" option. */
	int (*const handler) (int argc, char **argv);
	/* Supported ABIs */
	enum vboot_version version;
	/* One-line summary of what it does */
	const char *const shorthelp;
};

/* Macro to define a command */
#define DECLARE_FUTIL_COMMAND(NAME, HANDLER, VERSION, SHORTHELP)	\
	const struct futil_cmd_t __cmd_##NAME = {			\
		.name = #NAME,						\
		.handler = HANDLER,					\
		.version = VERSION,					\
		.shorthelp = SHORTHELP,					\
	}

/* This is the list of pointers to all commands. */
extern const struct futil_cmd_t *const futil_cmds[];

/* Size of an array */
#ifndef ARRAY_SIZE
#define ARRAY_SIZE(array) (sizeof(array)/sizeof(array[0]))
#endif

/* Fatal error (print error message and exit). */
#define FATAL(format, ...) do { \
		fprintf(stderr, "FATAL: %s: " format, __func__, \
			##__VA_ARGS__ ); \
		exit(1); \
	} while (0)

/* Print error messages (won't exit). */
#define ERROR(format, ...) fprintf(stderr, "ERROR: %s: " format, __func__, \
				   ##__VA_ARGS__ )
#define WARN(format, ...) fprintf(stderr, "WARNING: %s: " format, __func__, \
				  ##__VA_ARGS__ )
#define INFO(format, ...) fprintf(stderr, "INFO: %s: " format, __func__, \
				  ##__VA_ARGS__ )
#define STATUS(format, ...) fprintf(stderr, ">> " format, ##__VA_ARGS__ )

extern const char *ft_print_header;
extern const char *ft_print_header2;

/*
 * `futility show` supports two kinds of output: human readable and machine
 * parseable. To keep the code simple, there is mostly a 1-to-1 relationship
 * between lines of human readable and lines of machine parseable output. The
 * FT_PRINT() macro should be used in those cases to define both output types
 * for a given line in one statement. In rare cases where lines do not match
 * 1-to-1, FT_READABLE_PRINT() and FT_PARSEABLE_PRINT() can be used to only
 * print to one or the other format.
 *
 * The requirements for machine parseable output are as follows and must be
 * strictly followed to ensure backwards-compatibility with tools using it:
 *
 * * Each line consists of a string of prefix tokens and one or more data
 *   values, separated by double colon delimiters (`::`).
 *
 *   * Output lines are independent of each other. No information may be encoded
 *     by the position of one output line relative to another (e.g. no
 *     "headings" which apply to all following lines).
 *
 *   * Tokens should form a hierarchy that groups related values together.
 *
 *     * Do not just use delimiters to separate words. Each token should
 *       represent a real layer in the hierarchy (e.g.
 *       `preamble::firmware_version` instead of `preamble::firmware::version`
 *       since "firmware" isn't a real hierarchical layer within the preamble).
 *
 *     * The toplevel token should be the same for all output lines and
 *       represent the futility file type being displayed (e.g. `bios`).
 *
 *   * Neither tokens nor values may contain the colon character (`:`) or a
 *     line break (`\n`).
 *
 *   * All integer values (even memory addresses) should be output in decimal.
 *
 *   * Every line should represent one single piece of information (i.e. no
 *     aggregate lines that e.g. show both the offset and size of something in
 *     the same line).
 *
 *     * If a single piece of information can be represented in multiple ways
 *       (e.g. hash algorithm by name and numerical ID), and it is useful to
 *       output both of them, they should be both output on the same line
 *       separated by `::`.
 *
 *   * Values should generally be simple. For very complex values and those that
 *     need to contain the disallowed characters or raw binary data (like the
 *     kernel command line), consider just creating a separate command to
 *     extract them specifically (e.g. `futility dump_kernel_config`).
 *
 *   * When a line represents a set (e.g. flags in textual representation), the
 *     individual set items should be separated by single colons (`:`). Callers
 *     should make no assumptions about the order of items listed in a set.
 *
 * * The parseable output is considered a stable API. Once an output line has
 *   been added, futility must forever return the exact same format (same prefix
 *   tokens, same data values in the same notation) on the same input file.
 *
 *   * Output lines are independent. Callers must make no assumption about the
 *     order of output lines, and additional lines may be added in the future.
 *
 *   * For values representing a set, new items may become possible for the set
 *     in future versions as long as the existing ones are still represented in
 *     the same way.
 *
 *   * When input files themselves change in a way that certain output lines no
 *     longer make sense for them (e.g. switching from raw area signing to
 *     metadata hash signing), some of the output lines that used to appear for
 *     the old version of that file type may no longer appear for the new
 *     version. But the lines that do appear must still follow the same
 *     format as they did for the old version.
 *
 *   * When there's a strong need to change the existing way something is
 *     represented, a new output line should be added that represents it in a
 *     better way. The old output line should be marked deprecated in a code
 *     comment but not removed or altered in any way from the output. (This
 *     means that as changes accrue information may be displayed in multiple
 *     redundant ways.)
 *
 *   * If one day the burden of accumulated deprecated output lines becomes too
 *     high, we may consider a permanent deprecation and removal plan. But this
 *     would be done over a long time frame with plenty of heads-up notice to
 *     `futility show` consumers to ensure they have migrated to the new format.
 *     Consumers are meant to be able to trust that they can hardcode parsing
 *     for a certain output line and it will remain working without futility
 *     suddenly pulling the rug out from under them.
 */

/* futility print helpers to handle parseable prints */
#define FT_READABLE_PRINT(fmt, args...) do { \
		if (!show_option.parseable) \
			printf(fmt, ##args); \
	} while (0)

#define FT_PARSEABLE_PRINT(fmt, args...) do { \
		if (!show_option.parseable) \
			break; \
		if (ft_print_header != NULL) \
			printf("%s::", ft_print_header); \
		if (ft_print_header2 != NULL) \
			printf("%s::", ft_print_header2); \
		printf(fmt, ##args); \
	} while (0)

#define FT_PRINT_RAW(normal_fmt, parse_fmt, args...) \
	printf(show_option.parseable ? parse_fmt : normal_fmt, ##args)

#define FT_PRINT(normal_fmt, parse_fmt, args...) do { \
		FT_READABLE_PRINT(normal_fmt, ##args); \
		FT_PARSEABLE_PRINT(parse_fmt, ##args); \
	} while (0)

/* Debug output (off by default) */
extern int debugging_enabled;

/* Returns true if this looks enough like a GBB header to proceed. */
int futil_looks_like_gbb(struct vb2_gbb_header *gbb, uint32_t len);

/*
 * Returns true if the gbb header is valid (and optionally updates *maxlen).
 * This doesn't verify the contents, though.
 */
int futil_valid_gbb_header(struct vb2_gbb_header *gbb, uint32_t len,
			   uint32_t *maxlen);

/* Sets the HWID string field inside a GBB header. */
int futil_set_gbb_hwid(struct vb2_gbb_header *gbb, const char *hwid);

/* For GBB v1.2 and later, update the hwid_digest */
void update_hwid_digest(struct vb2_gbb_header *gbb);

/* For GBB v1.2 and later, print the stored digest of the HWID (and whether
 * it's correct). Return true if it is correct. */
int print_hwid_digest(struct vb2_gbb_header *gbb, const char *banner);

/* Copies a file. */
int futil_copy_file(const char *infile, const char *outfile);

/* Possible file operation errors */
enum futil_file_err {
	FILE_ERR_NONE,
	FILE_ERR_STAT,
	FILE_ERR_SIZE,
	FILE_ERR_MMAP,
	FILE_ERR_MSYNC,
	FILE_ERR_MUNMAP,
	FILE_ERR_OPEN,
	FILE_ERR_CLOSE,
	FILE_ERR_DIR,
	FILE_ERR_CHR,
	FILE_ERR_FIFO,
	FILE_ERR_SOCK,
};

enum file_mode {
	FILE_RO,
	FILE_RW,
};

enum futil_file_err futil_open_file(const char *infile, int *fd,
				    enum file_mode mode);
enum futil_file_err futil_close_file(int fd);

/* Wrapper for mmap/munmap. Skips stupidly large files. */
enum futil_file_err futil_map_file(int fd, enum file_mode mode, uint8_t **buf,
				   uint32_t *len);
enum futil_file_err futil_unmap_file(int fd, enum file_mode mode, uint8_t *buf,
				     uint32_t len);

enum futil_file_err futil_open_and_map_file(const char *infile, int *fd,
					    enum file_mode mode, uint8_t **buf,
					    uint32_t *len);
enum futil_file_err futil_unmap_and_close_file(int fd, enum file_mode mode,
					       uint8_t *buf, uint32_t len);

/*
 * Parse input string as a hex representation of size len, exit with error if
 *  the string is not a valid hex string or is of a wrongs size.
 */
void parse_digest_or_die(uint8_t *buf, int len, const char *str);

/*
 * Print provided buffer as hex string
 */
void print_bytes(const void *ptr, size_t len);

/* The CPU architecture is occasionally important */
enum arch_t {
	ARCH_UNSPECIFIED,
	ARCH_X86,
	ARCH_ARM,
	ARCH_MIPS
};

/*
 * Write size bytes from start into filename. Print "%msg %filename" to stdout
 * on success, if msg is non-NULL. Writes messages to stderr on failure.
 * Returns 0 on success.
 */
int write_to_file(const char *msg, const char *filename, uint8_t *start,
		  size_t size);

#endif  /* VBOOT_REFERENCE_FUTILITY_H_ */