tpm2-tools源码分析之tpm2_createprimary.c（2）

接前一篇文章：tpm2-tools源码分析之tpm2_createprimary.c（1）

本文对tpm2_createprimary.c中的tpm2_tool_onstart函数进行详细解析。

先再次贴出该函数源码：

static bool tpm2_tool_onstart(tpm2_options **opts) {

    const struct option topts[] = {
        { "hierarchy",      required_argument, 0, 'C' },
        { "hierarchy-auth", required_argument, 0, 'P' },
        { "key-auth",       required_argument, 0, 'p' },
        { "hash-algorithm", required_argument, 0, 'g' },
        { "key-algorithm",  required_argument, 0, 'G' },
        { "key-context",    required_argument, 0, 'c' },
        { "policy",         required_argument, 0, 'L' },
        { "attributes",     required_argument, 0, 'a' },
        { "unique-data",    required_argument, 0, 'u' },
        { "creation-data",  required_argument, 0,  0  },
        { "template-data",  required_argument, 0,  1  },
        { "creation-ticket",required_argument, 0, 't' },
        { "creation-hash",  required_argument, 0, 'd' },
        { "outside-info",   required_argument, 0, 'q' },
        { "pcr-list",       required_argument, 0, 'l' },
        { "cphash",         required_argument, 0,  2  },
        { "format",         required_argument, 0, 'f' },
        { "output",         required_argument, 0, 'o' },
    };

    *opts = tpm2_options_new("C:P:p:g:G:c:L:a:u:t:d:q:l:o:f:", ARRAY_LEN(topts),
        topts, on_option, 0, 0);

    return *opts != 0;
}

tpm2_options结构的定义在tpm2-tools/lib/tpm2_options.h中，代码如下：

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;

struct option的定义在/usr/include/bits/getopt_ext.h中，代码如下：

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;
};

on_option函数的实现在同文件（tools/tpm_createprimary.c）中，如下：

static bool on_option(char key, char *value) {

    bool result = true;
    switch (key) {
    case 'C':
        ctx.auth_hierarchy.ctx_path = value;
        break;
    case 'P':
        ctx.auth_hierarchy.auth_str = value;
        break;
    case 'p':
        ctx.key_auth_str = value;
        break;
    case 'g':
        ctx.halg = value;
        break;
    case 'G':
        ctx.alg = value;
        break;
    case 'c':
        ctx.context_file = value;
        break;
    case 'u':
        ctx.unique_file = value;
        break;
    case 'L':
        ctx.policy = value;
        break;
    case 'a':
        ctx.attrs = value;
        break;
    case 0:
        ctx.creation_data_file = value;
        break;
    case 1:
        ctx.template_data_path = value;
        break;
    case 't':
        ctx.creation_ticket_file = value;
        break;
    case 'd':
        ctx.creation_hash_file = value;
        break;
    case 'q':
        ctx.outside_info_data = value;
        break;
    case 'l':
        result = pcr_parse_selections(value, &ctx.objdata.in.creation_pcr);
        if (!result) {
            LOG_ERR("Could not parse pcr selections, got: \"%s\"", value);
            return result;
        }
        break;
    case 2:
        ctx.cp_hash_path = value;
        break;
    case 'f':
        ctx.format = tpm2_convert_pubkey_fmt_from_optarg(value);
        if (ctx.format == pubkey_format_err) {
            return false;
        }
        ctx.format_set = true;
        break;
    case 'o':
        ctx.output_path = value;
        break;
        /* no default */
    }

    return result;
}

要更好地理解这些选项乃至tpm2_tool_onstart函数的功能，需要与tpm2_createprimary命令的说明相结合来看。tpm2_createprimary命令的详细说明参见：

tpm2-tools/tpm2_createprimary.1.md at master · tpm2-software/tpm2-tools · GitHub

下载了源码后，在tpm2-tools/man/tpm2_createprimary.1.md文件中。

其中的参数说明如下：

OPTIONS

• -C, --hierarchy=OBJECT:

  The hierarchy under which the object is created. This will also dictate which authorization secret (if any) must be supplied. Defaults to TPM_RH_OWNER, when no value specified. Supported options are: —— 创建对象的层次结构。这也将规定必须提供哪个授权secret（如果有）。默认为 TPM_RH_OWNER，当没有指定值时，支持的选项有：

  • o for TPM_RH_OWNER —— o代表TPM_RH_OWNER，所有者密钥 （默认值）
  • p for TPM_RH_PLATFORM —— p代表TPM_RH_PLATFORM，平台密钥
  • e for TPM_RH_ENDORSEMENT —— e代表TPM_RH_ENDORSEMENT，背书密钥
  • n for TPM_RH_NULL —— n代表TPM_RH_NULL，空
  •  where a raw number can be used. —— 可以使用原始数字。

• -P, --hierarchy-auth=AUTH:

  The authorization value for the hierarchy specified with -C. —— 使用-C指定的层次结构的授权值。

• -p, --key-auth=AUTH:

  The authorization value for the primary object created. —— 创建的主对象的授权值。

• -g, --hash-algorithm=ALGORITHM:

  The hash algorithm to use for generating the objects name. Defaults to sha256 if not specified. —— 用于生成对象名称的哈希算法。如果未指定，则默认为 sha256。

• -G, --key-algorithm=ALGORITHM:

  The algorithm type for the generated primary key. Defaults to rsa2048:null:aes128cfb. —— 生成的主密钥的算法类型。默认为 rsa2048:null:aes128cfb。

• -c, --key-context=FILE:

  The file path to save the object context of the generated primary object. —— 保存生成的主对象的对象上下文的文件路径。

• -L, --policy=FILE or HEX_STRING:

  An optional file input or hex string that contains the policy digest for policy based authorization of the object. —— 一个可选的文件输入或十六进制字符窜，其中包含基于策略的对象授权的策略摘要。

• -a, --attributes=ATTRIBUTES:

  The object attributes, optional. Defaults —— 对象属性，可选。默认为： to: TPMA_OBJECT_RESTRICTED|TPMA_OBJECT_DECRYPT|TPMA_OBJECT_FIXEDTPM| TPMA_OBJECT_FIXEDPARENT|TPMA_OBJECT_SENSITIVEDATAORIGIN| TPMA_OBJECT_USERWITHAUTH

• -u, --unique-data=FILE OR STDIN:

  An optional file input that contains the unique field of TPMT_PUBLIC in little-endian format. Primary key creator may place information that causes the primary key generation scheme internal to the TPM to generate statistically unique values. The TPM v2.0 specification calls this field unique and overloads it so that it contains one value when the application provides this structure as input and another value when the applications receives this structure as output (like public portion of the rsa key). —— 一个可选的文件输入，包含TPMT_PUBLIC的唯一字段，采用little-endian 格式。主密钥创建者可以放置导致TPM内部的主密钥生成方案生成统计上唯一值的信息。TPM v2.0规范将此字段称为唯一并对其进行重载，以便当应用程序提供此结构作为输入时它包含一个值，而当应用程序接收此结构作为输出时，它包含另一个值（如rsa密钥的公共部分）。

  If the data is specified as a file, the user is responsible for ensuring that this buffer is formatted per TPMU_PUBLIC_ID union. —— 如果将数据指定为文件，则用户负责确保此缓冲区按照 TPMU_PUBLIC_ID 联合进行格式化。

  The unique data can also be retrieved from stdin buffer by specifying "-" as the --unique-data option value and the tool will parse the key type and associate the input data with the unique data buffer associated with the key type. —— 

  也可以通过将 “-”指定为--unique-data选项值从标准输入缓冲区中检索唯一数据，并且该工具将解析密钥类型并将输入数据与与密钥类型关联的唯一数据缓冲区相关联。

  NOTE:

  1. The maximum allowed bytes is dependent on key type and the TPM implementation. Eg. While TSS allows a value upto 512 for MAX_RSA_KEY_BYTES, however the ibmSwTPM implementation supports a value upto 256 bytes. —— 最大允许字节数取决于密钥类型和TPM实现。例如。虽然TSS允许MAX_RSA_KEY_BYTES的值最多为512，但是ibmSwTPM实现支持最​​多256个字节的值。
  2. The unique input data specified on stdin for ECC is split for specifying the X coordinate and Y coordinate buffers. —— 在标准输入上为ECC指定的唯一输入数据被拆分用于指定X坐标和Y坐标缓冲区。

• --creation-data=FILE:

  An optional file output that saves the creation data for certification. —— 一个可选的文件输出，保存创建数据以供认证。

• --template-data=FILE:

  An optional file output that saves the key template data (TPM2B_PUBLIC) to be used in tpm2_policytemplate. —— 一个可选的文件输出，保存要在tpm2_policytemplate中使用的密钥模板数据 (TPM2B_PUBLIC) 。

• -t, --creation-ticket=FILE:

  An optional file output that saves the creation ticket for certification. —— 一个可选的文件输出，用于保存创建ticket以供认证。

• -d, --creation-hash=FILE:

  An optional file output that saves the creation hash for certification. —— 一个可选的文件输出，用于保存创建哈希以供认证。

• -q, --outside-info=FILE_OR_HEX:

  An optional file or hex string to add unique data to the creation data. Note that it does not contribute in creating statistically unique object. —— 用于将唯一数据添加到创建数据的可选文件或十六进制字符串。请注意，它不会有助于创建统计上唯一的对象。

• -l, --pcr-list=PCR:

  The list of PCR banks and selected PCRs' ids for each bank to be included in the creation data for certification. —— PCR banks列表和每个banks的选定PCR的ID，将包含在创建数据中以进行认证。

• --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. —— 记录命令参数哈希的文件路径。这通常称为cpHash。注意：选择此选项时，该工具不会实际执行命令，它只是返回一个cpHash。

pubkey options

Public key format.

• -o, --output=FILE:

  The output file path, recording the public portion of the object. —— 输出文件路径，记录对象的公共部分。

tpm2_options_new函数属于公共代码，在tpm2-tools/lib/tpm2_options.c中，代码如下：

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;
}

tpm2_new_options函数很容易理解，其功能是基于tpm2_tool_onstart函数中的struct option topts构建tpm2_options实例（*opts）。

至此，tpm2_createprimary.c中的tpm2_tool_onstart函数就基本分析完了。