cli.h

Go to the documentation of this file.

 
#ifndef __CLI_H
#define __CLI_H
 
#include <stdbool.h>
#include <stdlib.h>
#include <string.h>
#include "lib/cargs/include/cargs.h"
#include "utils.h"
 
 
// Error code to signify a 'correct' CLI config, even when 'required' options are not present.
// For example, -v or --version and -h or --help
#define CLI_OK 2
 
// Alignment the --vtor-align flag pads the binary to, in bytes
#define VTOR_ALIGN_BYTES 1024
 
// Shortest authentication key accepted, in bytes
#define AUTH_KEY_MIN_SIZE 16
 
struct builder_cli_configuration {
   const char *input;                        // Required
   const char *output;                       // Required
   const char *firmware_index;               // Optional
   const char *header_version;               // Optional, generates a backward compatible header (defaults to latest)
   bool vtor_align;                          // Optional, pads before the binary so the vector table is aligned
   const char *firmware_version;             // Optional, unless using anti-rollback
   const char *encryption_algo;              // Optional, unless encryption is required. AES-CBC by default as of v1
   const char *encryption_key_ascii;         // Optional
   const char *encryption_key_hex;           // Optional
   uint8_t *encryption_key;                  // Optional
   size_t encryption_key_len;                // Optional
   const char *authentication_algo;          // Optional, unless authentication is required. Supported algorithms: HMAC-[md5,sha256,sha512]
   const char *authentication_key_ascii;     // Optional
   const char *authentication_key_hex;       // Optional
   uint8_t *authentication_key;              // Optional
   size_t authentication_key_len;            // Optional
   const char *signature_algo;               // Optional
   const char *signature_key;                // Optional, unless a signature is required. Supported algorithms: ecdsa-sha256, rsa-sha256,
   const char *integrity_algo;               // Optional. CRC32 is chosen by default. Supported algorithms: MD5, SHA26, SHA512
   const char *update_type;                  // Optional. app is chosen by default. Supported types: app, boot
   const char *runtime_signature_algo;       // Optional, unless a runtime signature is required. Supported algorithms: ecdsa-sha256, rsa-sha256,
   const char *runtime_signature_key;        // Key generation mode
   const char *runtime_integrity_algo;       // Optional. Embeds a runtime integrity digest in the image data. Supported: md5, sha1, sha224, sha256, sha384, sha512
   bool keygen;                              // Specifies we are in key generator mode
   const char *keygen_keytype;               // In keygen mode, the type of key that's generated
   const char *keygen_publickey;             // In keygen mode, path to the public key that's generated
   const char *keygen_privatekey;            // In keygen mode, path to the private key that's generated
   bool verbose;                             // if passed, extra output will be passed to STDOUT
   bool version;                             // if passed, CLI version will be passed to STDOUT
   bool help;                                // if passed, a help message will be passed to STDOUT
   const char *build_time;                   // Optional, Unix epoch (seconds) for reproducible images. Defaults to current time
   const char *keygen_keysize;               // In keygen mode, the RSA key size in bits: 2048 (default), 3072 or 4096
   const char *keygen_curve;                 // In keygen mode, the ECDSA curve: p256 (default), p384 or p521
};
 
// The options the tool accepts and the help prints, per edition
static struct cag_option cli_option_table[] = {
 
   {
      .identifier = 'i',
      .access_letters = "iI",
      .access_name = "input",
      .value_name = "<firmware.bin>",
      .description = "[REQUIRED] Path to firmware binary"
   },
 
   {
      .identifier = 'o',
      .access_letters = "oO",
      .access_name = "output",
      .value_name = "<firmware_update.img>",
      .description = "[REQUIRED] Path to save firmware update image"
   },
 
   {
      .identifier = 'm',
      .access_letters = NULL,
      .access_name = "header-version",
      .value_name = "X.X.X",
      .description =
         "[OPTIONAL] Specify a specific header version to generate a backward compatible firmware update image."
   },
 
   {
      .identifier = 'f',
      .access_letters = NULL,
      .access_name = "firmware-version",
      .value_name = "X.X.X",
      .description = "[OPTIONAL] Firmware Version, mandatory for anti-rollback support"
   },
 
   {
      .identifier = 'T',
      .access_letters = NULL,
      .access_name = "build-time",
      .value_name = "<unix_epoch_seconds>",
      .description =
         "[OPTIONAL] Image build time (Unix epoch seconds) for reproducible images. Defaults to the current time."
   },
 
   {
      .identifier = 'n',
      .access_letters = NULL,
      .access_name = "integrity-algo",
      .value_name = "<crc32|md5|sha1|sha224|sha256|sha384|sha512>",
      .description =
         "[OPTIONAL] Integrity Algorithm to be used if integrity check is chosen. Defaults to CRC32"
   },
 
// Editions that carry a bootloader
#if defined(VARIANT_OPEN) || defined(VARIANT_EVAL) || defined(VARIANT_PRO) ||                        \
   defined(VARIANT_ULTIMATE)
 
   {
      .identifier = 't',
      .access_letters = NULL,
      .access_name = "update-type",
      .value_name = "<app|boot>",
      .description =
         "[OPTIONAL] Specify whether firmware update image generated is an app update or bootloader update. Defaults to app"
   },
 
   {
      .identifier = 'x',
      .access_letters = "xX",
      .access_name = "image-index",
      .value_name = "<numeric value>",
      .description = "[OPTIONAL] Index of an image written straight to flash. Defaults to 0"
   },
 
   {
      .identifier = 'p',
      .access_letters = NULL,
      .access_name = "vtor-align",
      .value_name = NULL,
      .description = "[OPTIONAL] Set the vector table alignment when necessary"
   },
 
   {
      .identifier = 'z',
      .access_letters = NULL,
      .access_name = "runtime-integrity-algo",
      .value_name = "<crc32|md5|sha1|sha224|sha256|sha384|sha512>",
      .description =
         "[OPTIONAL] Hash algorithm whose digest is embedded in the image data for runtime integrity verification"
   },
 
#endif
 
// Editions that carry encryption and signatures
#if defined(VARIANT_OPEN) || defined(VARIANT_EVAL) || defined(VARIANT_ULTIMATE)
 
   {
      .identifier = 'e',
      .access_letters = NULL,
      .access_name = "enc-algo",
      .value_name = "<aes-cbc>",
      .description = "[OPTIONAL] Encryption Algorithm to be used if encryption is required"
   },
 
   {
      .identifier = 'k',
      .access_letters = NULL,
      .access_name = "enc-key-ascii",
      .value_name = "<encryption_key_in_ascii>",
      .description = "[OPTIONAL] Encryption Key if encryption is required"
   },
 
   {
      .identifier = 'd',
      .access_letters = NULL,
      .access_name = "enc-key-hex",
      .value_name = "<encryption_key_in_hex>",
      .description = "[OPTIONAL] Encryption Key if encryption is required"
   },
 
   {
      .identifier = 'a',
      .access_letters = NULL,
      .access_name = "auth-algo",
      .value_name = "<hmac-md5|hmac-sha256|hmac-sha512>",
      .description = "[OPTIONAL] Authentication Algorithm to be used if authentication is chosen"
   },
 
   {
      .identifier = 'u',
      .access_letters = NULL,
      .access_name = "auth-key-ascii",
      .value_name = "<auth_key_in_ascii>",
      .description = "[OPTIONAL] Authentication Key if authentication is chosen"
   },
 
   {
      .identifier = 'j',
      .access_letters = NULL,
      .access_name = "auth-key-hex",
      .value_name = "<my_auth_key_in_hex>",
      .description = "[OPTIONAL] Authentication Key if authentication is chosen"
   },
 
   {
      .identifier = 's',
      .access_letters = NULL,
      .access_name = "sign-algo",
      .value_name = "<ecdsa-sha256|rsa-sha256>",
      .description = "[OPTIONAL] Signature Algorithm to be used if signature is chosen"
   },
 
   {
      .identifier = 'g',
      .access_letters = NULL,
      .access_name = "sign-key",
      .value_name = "<sign_key.pem>",
      .description = "[OPTIONAL] Private Signature Key if signature is chosen"
   },
 
   {
      .identifier = 'y',
      .access_letters = NULL,
      .access_name = "keygen",
      .value_name = NULL,
      .description = "[OPTIONAL] Enter sign key generation mode"
   },
 
   {
      .identifier = 'c',
      .access_letters = NULL,
      .access_name = "key-type",
      .value_name = "<rsa|ecdsa>",
      .description = "[REQUIRED in Keygen Mode] Enter sign key type"
   },
 
   {
      .identifier = 'S',
      .access_letters = NULL,
      .access_name = "key-size",
      .value_name = "<2048|3072|4096>",
      .description = "[OPTIONAL in Keygen Mode] RSA key size in bits. Defaults to 2048"
   },
 
   {
      .identifier = 'C',
      .access_letters = NULL,
      .access_name = "curve",
      .value_name = "<p256|p384|p521>",
      .description = "[OPTIONAL in Keygen Mode] ECDSA curve. Defaults to p256"
   },
 
   {
      .identifier = 'q',
      .access_letters = NULL,
      .access_name = "public-key",
      .value_name = "<public_key.pem>",
      .description = "[REQUIRED in Keygen Mode] Path to public key in PEM format"
   },
 
   {
      .identifier = 'w',
      .access_letters = NULL,
      .access_name = "private-key",
      .value_name = "<private_key.pem>",
      .description = "[REQUIRED in Keygen Mode] Path to private key in PEM format"
   },
 
   {
      .identifier = 'r',
      .access_letters = NULL,
      .access_name = "runtime-sign-algo",
      .value_name = "<ecdsa-sha256|rsa-sha256>",
      .description =
         "[OPTIONAL] Signature Algorithm to be used if runtime signature verification is chosen"
   },
 
   {
      .identifier = 'l',
      .access_letters = NULL,
      .access_name = "runtime-sign-key",
      .value_name = "<runtime_sign_key.pem>",
      .description = "[OPTIONAL] Private Signature Key if runtime signature verification is chosen"
   },
 
#endif
 
   {
      .identifier = 'b',
      .access_letters = NULL,
      .access_name = "verbose",
      .value_name = NULL,
      .description = "[OPTIONAL] Verbose mode"
   },
 
   {
      .identifier = 'v',
      .access_letters = "vV",
      .access_name = "version",
      .value_name = NULL,
      .description = "Show CLI version"
   },
 
   {
      .identifier = 'h',
      .access_letters = "h",
      .access_name = "help",
      .description = "Show the help message"
   }
};
 
// function to iterate over user parameters and copy to those to a struct
int parse_options(int argc, char **argv, struct builder_cli_configuration *cli_options);
 
#endif // __CLI_H