1 /* Copyright 2013 The ChromiumOS Authors 2 * Use of this source code is governed by a BSD-style license that can be 3 * found in the LICENSE file. 4 */ 5 6 #ifndef VBOOT_REFERENCE_FUTILITY_H_ 7 #define VBOOT_REFERENCE_FUTILITY_H_ 8 9 #include <stdint.h> 10 11 #include "2common.h" 12 #include "host_key.h" 13 14 /* This program */ 15 #define MYNAME "futility" 16 17 /* Version string (autogenerated) */ 18 extern const char futility_version[]; 19 20 /* Bitfields indicating the struct/format versions supported by a command */ 21 enum vboot_version { 22 /* 23 * v1.0 is the original structs used since the dawn of time. 24 * v2.0 can verify the firmware in smaller chunks, but there's 25 * no difference in the on-device structs, so it's only 26 * meaningful for the firmware API. Futility doesn't care. 27 */ 28 VBOOT_VERSION_1_0 = 0x00000001, 29 30 /* 31 * v2.1 uses new and different structs, and is what v2.0 would have 32 * been if someone hadn't started using it before it was ready. 33 */ 34 VBOOT_VERSION_2_1 = 0x00000002, 35 36 /* 37 * Everything we know about to date. 38 */ 39 VBOOT_VERSION_ALL = 0x00000003, 40 }; 41 42 /* What's our preferred API & data format? */ 43 extern enum vboot_version vboot_version; 44 45 /* Here's a structure to define the commands that futility implements. */ 46 struct futil_cmd_t { 47 /* String used to invoke this command */ 48 const char *const name; 49 /* Function to do the work. Returns 0 on success. 50 * Called with argv[0] == "name". 51 * It should handle its own "--help" option. */ 52 int (*const handler) (int argc, char **argv); 53 /* Supported ABIs */ 54 enum vboot_version version; 55 /* One-line summary of what it does */ 56 const char *const shorthelp; 57 }; 58 59 /* Macro to define a command */ 60 #define DECLARE_FUTIL_COMMAND(NAME, HANDLER, VERSION, SHORTHELP) \ 61 const struct futil_cmd_t __cmd_##NAME = { \ 62 .name = #NAME, \ 63 .handler = HANDLER, \ 64 .version = VERSION, \ 65 .shorthelp = SHORTHELP, \ 66 } 67 68 /* This is the list of pointers to all commands. */ 69 extern const struct futil_cmd_t *const futil_cmds[]; 70 71 /* Size of an array */ 72 #ifndef ARRAY_SIZE 73 #define ARRAY_SIZE(array) (sizeof(array)/sizeof(array[0])) 74 #endif 75 76 /* Fatal error (print error message and exit). */ 77 #define FATAL(format, ...) do { \ 78 fprintf(stderr, "FATAL: %s: " format, __func__, \ 79 ##__VA_ARGS__ ); \ 80 exit(1); \ 81 } while (0) 82 83 /* Print error messages (won't exit). */ 84 #define ERROR(format, ...) fprintf(stderr, "ERROR: %s: " format, __func__, \ 85 ##__VA_ARGS__ ) 86 #define WARN(format, ...) fprintf(stderr, "WARNING: %s: " format, __func__, \ 87 ##__VA_ARGS__ ) 88 #define INFO(format, ...) fprintf(stderr, "INFO: %s: " format, __func__, \ 89 ##__VA_ARGS__ ) 90 #define STATUS(format, ...) fprintf(stderr, ">> " format, ##__VA_ARGS__ ) 91 92 extern const char *ft_print_header; 93 extern const char *ft_print_header2; 94 95 /* 96 * `futility show` supports two kinds of output: human readable and machine 97 * parseable. To keep the code simple, there is mostly a 1-to-1 relationship 98 * between lines of human readable and lines of machine parseable output. The 99 * FT_PRINT() macro should be used in those cases to define both output types 100 * for a given line in one statement. In rare cases where lines do not match 101 * 1-to-1, FT_READABLE_PRINT() and FT_PARSEABLE_PRINT() can be used to only 102 * print to one or the other format. 103 * 104 * The requirements for machine parseable output are as follows and must be 105 * strictly followed to ensure backwards-compatibility with tools using it: 106 * 107 * * Each line consists of a string of prefix tokens and one or more data 108 * values, separated by double colon delimiters (`::`). 109 * 110 * * Output lines are independent of each other. No information may be encoded 111 * by the position of one output line relative to another (e.g. no 112 * "headings" which apply to all following lines). 113 * 114 * * Tokens should form a hierarchy that groups related values together. 115 * 116 * * Do not just use delimiters to separate words. Each token should 117 * represent a real layer in the hierarchy (e.g. 118 * `preamble::firmware_version` instead of `preamble::firmware::version` 119 * since "firmware" isn't a real hierarchical layer within the preamble). 120 * 121 * * The toplevel token should be the same for all output lines and 122 * represent the futility file type being displayed (e.g. `bios`). 123 * 124 * * Neither tokens nor values may contain the colon character (`:`) or a 125 * line break (`\n`). 126 * 127 * * All integer values (even memory addresses) should be output in decimal. 128 * 129 * * Every line should represent one single piece of information (i.e. no 130 * aggregate lines that e.g. show both the offset and size of something in 131 * the same line). 132 * 133 * * If a single piece of information can be represented in multiple ways 134 * (e.g. hash algorithm by name and numerical ID), and it is useful to 135 * output both of them, they should be both output on the same line 136 * separated by `::`. 137 * 138 * * Values should generally be simple. For very complex values and those that 139 * need to contain the disallowed characters or raw binary data (like the 140 * kernel command line), consider just creating a separate command to 141 * extract them specifically (e.g. `futility dump_kernel_config`). 142 * 143 * * When a line represents a set (e.g. flags in textual representation), the 144 * individual set items should be separated by single colons (`:`). Callers 145 * should make no assumptions about the order of items listed in a set. 146 * 147 * * The parseable output is considered a stable API. Once an output line has 148 * been added, futility must forever return the exact same format (same prefix 149 * tokens, same data values in the same notation) on the same input file. 150 * 151 * * Output lines are independent. Callers must make no assumption about the 152 * order of output lines, and additional lines may be added in the future. 153 * 154 * * For values representing a set, new items may become possible for the set 155 * in future versions as long as the existing ones are still represented in 156 * the same way. 157 * 158 * * When input files themselves change in a way that certain output lines no 159 * longer make sense for them (e.g. switching from raw area signing to 160 * metadata hash signing), some of the output lines that used to appear for 161 * the old version of that file type may no longer appear for the new 162 * version. But the lines that do appear must still follow the same 163 * format as they did for the old version. 164 * 165 * * When there's a strong need to change the existing way something is 166 * represented, a new output line should be added that represents it in a 167 * better way. The old output line should be marked deprecated in a code 168 * comment but not removed or altered in any way from the output. (This 169 * means that as changes accrue information may be displayed in multiple 170 * redundant ways.) 171 * 172 * * If one day the burden of accumulated deprecated output lines becomes too 173 * high, we may consider a permanent deprecation and removal plan. But this 174 * would be done over a long time frame with plenty of heads-up notice to 175 * `futility show` consumers to ensure they have migrated to the new format. 176 * Consumers are meant to be able to trust that they can hardcode parsing 177 * for a certain output line and it will remain working without futility 178 * suddenly pulling the rug out from under them. 179 */ 180 181 /* futility print helpers to handle parseable prints */ 182 #define FT_READABLE_PRINT(fmt, args...) do { \ 183 if (!show_option.parseable) \ 184 printf(fmt, ##args); \ 185 } while (0) 186 187 #define FT_PARSEABLE_PRINT(fmt, args...) do { \ 188 if (!show_option.parseable) \ 189 break; \ 190 if (ft_print_header != NULL) \ 191 printf("%s::", ft_print_header); \ 192 if (ft_print_header2 != NULL) \ 193 printf("%s::", ft_print_header2); \ 194 printf(fmt, ##args); \ 195 } while (0) 196 197 #define FT_PRINT_RAW(normal_fmt, parse_fmt, args...) \ 198 printf(show_option.parseable ? parse_fmt : normal_fmt, ##args) 199 200 #define FT_PRINT(normal_fmt, parse_fmt, args...) do { \ 201 FT_READABLE_PRINT(normal_fmt, ##args); \ 202 FT_PARSEABLE_PRINT(parse_fmt, ##args); \ 203 } while (0) 204 205 /* Debug output (off by default) */ 206 extern int debugging_enabled; 207 208 /* Returns true if this looks enough like a GBB header to proceed. */ 209 int futil_looks_like_gbb(struct vb2_gbb_header *gbb, uint32_t len); 210 211 /* 212 * Returns true if the gbb header is valid (and optionally updates *maxlen). 213 * This doesn't verify the contents, though. 214 */ 215 int futil_valid_gbb_header(struct vb2_gbb_header *gbb, uint32_t len, 216 uint32_t *maxlen); 217 218 /* Sets the HWID string field inside a GBB header. */ 219 int futil_set_gbb_hwid(struct vb2_gbb_header *gbb, const char *hwid); 220 221 /* For GBB v1.2 and later, update the hwid_digest */ 222 void update_hwid_digest(struct vb2_gbb_header *gbb); 223 224 /* For GBB v1.2 and later, print the stored digest of the HWID (and whether 225 * it's correct). Return true if it is correct. */ 226 int print_hwid_digest(struct vb2_gbb_header *gbb, const char *banner); 227 228 /* Copies a file. */ 229 int futil_copy_file(const char *infile, const char *outfile); 230 231 /* Possible file operation errors */ 232 enum futil_file_err { 233 FILE_ERR_NONE, 234 FILE_ERR_STAT, 235 FILE_ERR_SIZE, 236 FILE_ERR_MMAP, 237 FILE_ERR_MSYNC, 238 FILE_ERR_MUNMAP, 239 FILE_ERR_OPEN, 240 FILE_ERR_CLOSE, 241 FILE_ERR_DIR, 242 FILE_ERR_CHR, 243 FILE_ERR_FIFO, 244 FILE_ERR_SOCK, 245 }; 246 247 enum file_mode { 248 FILE_RO, 249 FILE_RW, 250 }; 251 252 enum futil_file_err futil_open_file(const char *infile, int *fd, 253 enum file_mode mode); 254 enum futil_file_err futil_close_file(int fd); 255 256 /* Wrapper for mmap/munmap. Skips stupidly large files. */ 257 enum futil_file_err futil_map_file(int fd, enum file_mode mode, uint8_t **buf, 258 uint32_t *len); 259 enum futil_file_err futil_unmap_file(int fd, enum file_mode mode, uint8_t *buf, 260 uint32_t len); 261 262 enum futil_file_err futil_open_and_map_file(const char *infile, int *fd, 263 enum file_mode mode, uint8_t **buf, 264 uint32_t *len); 265 enum futil_file_err futil_unmap_and_close_file(int fd, enum file_mode mode, 266 uint8_t *buf, uint32_t len); 267 268 /* 269 * Parse input string as a hex representation of size len, exit with error if 270 * the string is not a valid hex string or is of a wrongs size. 271 */ 272 void parse_digest_or_die(uint8_t *buf, int len, const char *str); 273 274 /* 275 * Print provided buffer as hex string 276 */ 277 void print_bytes(const void *ptr, size_t len); 278 279 /* The CPU architecture is occasionally important */ 280 enum arch_t { 281 ARCH_UNSPECIFIED, 282 ARCH_X86, 283 ARCH_ARM, 284 ARCH_MIPS 285 }; 286 287 /* 288 * Write size bytes from start into filename. Print "%msg %filename" to stdout 289 * on success, if msg is non-NULL. Writes messages to stderr on failure. 290 * Returns 0 on success. 291 */ 292 int write_to_file(const char *msg, const char *filename, uint8_t *start, 293 size_t size); 294 295 #endif /* VBOOT_REFERENCE_FUTILITY_H_ */ 296