Continued from the previous article: tpm2_sign.c of tpm2-tools source code analysis (1)
This article analyzes the tpm2_tool_onstart function in tpm2_sign.c in detail.
First post the source code of the function again:
static bool tpm2_tool_onstart(tpm2_options **opts) {
static const struct option topts[] = {
{ "auth", required_argument, 0, 'p' },
{ "hash-algorithm", required_argument, 0, 'g' },
{ "scheme", required_argument, 0, 's' },
{ "digest", no_argument, 0, 'd' },
{ "signature", required_argument, 0, 'o' },
{ "ticket", required_argument, 0, 't' },
{ "key-context", required_argument, 0, 'c' },
{ "format", required_argument, 0, 'f' },
{ "cphash", required_argument, 0, 0 },
{ "commit-index", required_argument, 0, 1 },
};
*opts = tpm2_options_new("p:g:dt:o:c:f:s:", ARRAY_LEN(topts), topts,
on_option, on_args, 0);
return *opts != 0;
}The definition of the tpm2_options structure is in tpm2-tools/lib/tpm2_options.h, the code is as follows:
struct tpm2_options {
struct {
tpm2_option_handler on_opt;
tpm2_arg_handler on_arg;
} callbacks;
char *short_opts;
size_t len;
uint32_t flags;
struct option long_opts[];
};
typedef struct tpm2_options tpm2_options;The definition of struct option is in /usr/include/bits/getopt_ext.h, the code is as follows:
struct option
{
const char *name;
/* has_arg can't be an enum because some compilers complain about
type mismatches in all the code that assumes it is an int. */
int has_arg;
int *flag;
int val;
};The implementation of the on_option function is in the same file (tools/tpm2_sign.c), as follows:
static bool on_option(char key, char *value) {
switch (key) {
case 'c':
ctx.signing_key.ctx_path = value;
break;
case 'p':
ctx.signing_key.auth_str = value;
break;
case 'g':
ctx.halg = tpm2_alg_util_from_optarg(value, tpm2_alg_util_flags_hash);
if (ctx.halg == TPM2_ALG_ERROR) {
LOG_ERR("Could not convert to number or lookup algorithm, got: "
"\"%s\"", value);
return false;
}
break;
case 's': {
ctx.sig_scheme = tpm2_alg_util_from_optarg(value,
tpm2_alg_util_flags_sig);
if (ctx.sig_scheme == TPM2_ALG_ERROR) {
LOG_ERR("Unknown signing scheme, got: \"%s\"", value);
return false;
}
}
break;
case 'd':
ctx.is_input_msg_digest = true;
break;
case 't': {
bool result = files_load_validation(value, &ctx.validation);
if (!result) {
return false;
}
ctx.is_hash_ticket_specified = true;
}
break;
case 'o':
ctx.output_path = value;
break;
case 0:
ctx.cp_hash_path = value;
break;
case 1:
ctx.commit_index = value;
break;
case 'f':
ctx.sig_format = tpm2_convert_sig_fmt_from_optarg(value);
if (ctx.sig_format == signature_format_err) {
return false;
}
/* no default */
}
return true;
}
To better understand these options and even the function of the tpm2_tool_onstart function, it needs to be combined with the description of the tpm2_sign command. For a detailed description of the tpm2_sign command, see:
tpm2-tools/tpm2_sign.1.md at master · tpm2-software/tpm2-tools · GitHub
After downloading the source code, it is in tpm2-tools/man/tpm2_sign.1.md.
The parameters are described as follows:
OPTIONS
-c, --key-context=OBJECT:
Context object pointing to the the key used for signing. Either a file or a handle number. See section "Context Object Format". - Context object pointing to the key used for signing. File number or handle number.
-p, --authAUTH:
Optional authorization value to use the key specified by -c . Authorization values should follow the "authorization formatting standards", see section "Authorization Formatting". Authorization values shall follow the "Authorization Format Standard".
-g, --hash-algorithm=ALGORITHM:
The hash algorithm used to digest the message. Algorithms should follow the "formatting standards", see section "Algorithm Specifiers". Also, see section "Supported Hash Algorithms" for a list of supported hash algorithms. Greek algorithm.
-s, --scheme=ALGORITHM:
The signing scheme used to sign the message. Optional.
Signing schemes should follow the "formatting standards", see section "Algorithm Specifiers". - The signature scheme used to sign the message. optional.
If specified, the signature scheme must match the key type. If left unspecified, a default signature scheme for the key type will be used. —— If specified, the signature scheme must match the key type. If not specified, the default signature scheme for the key type will be used.
-d, --digest:
Indicate that FILE is a file containing the digest of the message. When this option and -t is specified, a warning is generated and the validation ticket (-t) is ignored . You cannot use this option to sign a digest against a restricted signing key. - Indicates that FILE is a file containing message digests. When this option is specified with -t, a warning will be generated and authentication tickets (-t) will be ignored. Digests cannot be signed against a restricted signing key using this option.
-t, --ticket=FILE:
The ticket file, containing the validation structure, optional. —— The ticket file, containing the validation structure, optional.
-o, --signature=FILE:
The signature file, records the signature structure. —— The signature file, records the signature structure.
-f, --format=FORMAT:
Format selection for the signature output file. See section "Signature Format Specifiers". —— Format selection for the signature output file.
--cphash=FILE
File path to record the hash of the command parameters. This is commonly termed as cpHash. NOTE: When this option is selected, The tool will not actually execute the command, it simply returns a cpHash. —— Used to record the command parameter hash file path. This is often called cpHash. NOTE: When this option is selected, the tool will not actually execute the command, it will just return a cpHash.
--commit-index=NATURALNUMBER
The commit counter value to determine the key index to use in an ECDAA signing scheme. The default counter value is 0. —— The commit counter value to determine the key index to use in an ECDAA signing scheme. The default count value is 0.
ARGUMENT the command line argument specifies the file data for sign. —— The command line argument specifies the file data to be signed.
The tpm2_options_new function belongs to the public code. In tpm2-tools/lib/tpm2_options.c, the code is as follows:
tpm2_options *tpm2_options_new(const char *short_opts, size_t len,
const struct option *long_opts, tpm2_option_handler on_opt,
tpm2_arg_handler on_arg, uint32_t flags) {
tpm2_options *opts = calloc(1, sizeof(*opts) + (sizeof(*long_opts) * len));
if (!opts) {
LOG_ERR("oom");
return NULL;
}
/*
* On NULL, just make it a zero length string so we don't have to keep
* checking it for NULL.
*/
if (!short_opts) {
short_opts = "";
}
opts->short_opts = strdup(short_opts);
if (!opts->short_opts) {
LOG_ERR("oom");
free(opts);
return NULL;
}
opts->callbacks.on_opt = on_opt;
opts->callbacks.on_arg = on_arg;
opts->len = len;
opts->flags = flags;
memcpy(opts->long_opts, long_opts, len * sizeof(*long_opts));
return opts;
}The tpm2_new_options function is easy to understand, and its function is to construct a tpm2_options instance (*opts) based on the struct option topts in the tpm2_tool_onstart function.
So far, the tpm2_tool_onstart function in tpm2_sign.c is basically analyzed.