TPM2 工作原理及操作 -- API Doc（一）

目录

前言

 API Doc

1、tpm2_createprimary [OPTIONS]  - 创建一个主密钥。

命令描述

例子

2、tpm2_create [OPTIONS]  - 创建一个主密钥。

命令描述

例子

3、tpm2_load [OPTIONS]  - 将对象加载到 TPM。

命令描述

例子

4、tpm2_changeauth [OPTIONS] [ARGUMENT] - 更改 TPM 对象的授权值。

命令描述

例子

5、tpm2_startauthsession [OPTIONS] - 使用 TPM 启动会话。

命令描述

例子

---

前言

以下部分内容来自我对tpm2-tools API文档、《A Practical Guide to TPM 2.0》的翻译和理解

关于TPM2基本原理、特性、密钥、层次、PCR等内容，TPM-JS这个项目有较详细的说明： 

TPM-JShttps://google.github.io/tpm-js/#pg_welcome想自学以及更深入了解的同学可以参考tpm2-tools doc ：Home - tpm2-tools

TPM 的外部编程接口规范： https ://trustedcomputinggroup.org/tpm-library-specification/

TPM2.0实用指南 《A Practical Guide to TPM 2.0》：

​​​​​​https://link.springer.com/content/pdf/10.1007/978-1-4302-6584-9.pdf

 API Doc

以下命令，我都有过测试 ，如果有问题，可以观察是否版本问题，或者直接查看tools API

1、tpm2_createprimary [OPTIONS]  - 创建一个主密钥。

命令描述

此命令用于在以下层次结构之一下创建主对象：所有者、平台、背书、NULL。该命令将创建并加载主对象。敏感和公共部分不返回信息。已创建对象句柄的上下文文件保存为文件，以供将来与创建的主对象交互。

1. OPTIONS

• -C, --hierarchy=OBJECT: 创建对象的层次结构。

这也将规定必须提供哪个授权secret（如果有）。

默认为 TPM_RH_OWNER，当没有指定值时，支持的选项有：

* o代表TPM_RH_OWNER 

* p代表TPM_RH_PLATFORM 

* e代表TPM_RH_ENDORSEMENT 

* n代表TPM_RH_NULL 

* <num>可以使用原始数字。

• -P, --hierarchy-auth=AUTH: 使用-C指定的层次结构的授权值。
• -p, --key-auth=AUTH: 创建的主要对象的授权值。
• -g, --hash-algorithm=ALGORITHM: 用于生成对象名称的哈希算法。如果未指定，则默认为 sha256。
• -G, --key-algorithm=ALGORITHM:  生成的主密钥的算法类型。默认为 rsa2048:null:aes128cfb。
• -c, --key-context=FILE: 保存生成的主对象的对象上下文的文件路径。
• -L, --policy=FILE: 一个可选的文件输入，其中包含基于策略的对象授权的策略摘要。
• -a, --attributes=ATTRIBUTES: 对象属性，可选。

默认为：TPMA_OBJECT_RESTRICTED|TPMA_OBJECT_DECRYPT|TPMA_OBJECT_FIXEDTPM| TPMA_OBJECT_FIXEDPARENT|TPMA_OBJECT_SENSITIVEDATAORIGIN| TPMA_OBJECT_USERWITHAUTH

• -u, --unique-data=FILE OR STDIN: 一个可选的文件输入，包含TPMT_PUBLIC的唯一字段，采用little-endian 格式。主密钥创建者可以放置导致 TPM 内部的主密钥生成方案生成统计上唯一值的信息。TPM v2.0 规范将此字段称为唯一并对其进行重载，以便当应用程序提供此结构作为输入时它包含一个值，而当应用程序接收此结构作为输出时它包含另一个值（如 rsa 密钥的公共部分）。

如果将数据指定为文件，则用户负责确保此缓冲区按照 TPMU_PUBLIC_ID 联合进行格式化。

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

注意： 1. 最大允许字节数取决于密钥类型和 TPM 实现。例如。虽然 TSS 允许 MAX_RSA_KEY_BYTES 的值最多为 512，但是 ibmSwTPM 实现支持最​​多 256 个字节的值。2. 在标准输入上为 ECC 指定的唯一输入数据被拆分用于指定 X 坐标和 Y 坐标缓冲区。

• --creation-data=FILE: 一个可选的文件输出，保存创建数据以供认证
• --template-data=FILE: 一个可选的文件输出，保存要在tpm2_policytemplate中使用的密钥模板数据 (TPM2B_PUBLIC) 
• -t, --creation-ticket=FILE: 一个可选的文件输出，用于保存创建ticket以供认证。
• -d, --creation-hash=FILE: 一个可选的文件输出，用于保存创建哈希以供认证。
• -q, --outside-info=FILE_OR_HEX: 用于将唯一数据添加到创建数据的可选文件或十六进制字符串。请注意，它不会有助于创建统计上唯一的对象。
• -l, --pcr-list=PCR:  PCR banks列表和每个banks的选定 PCR 的 ID ，将包含在创建数据中以进行认证。
• --cphash=FILE： 记录命令参数哈希的文件路径。这通常称为 cpHash。注意：选择此选项时，该工具不会实际执行命令，它只是返回一个 cpHash。
• -o, --output=FILE: 输出文件路径，记录对象的公共部分。

例子

创建 ECC 主对象

tpm2_createprimary -C o -g sha256 -G ecc -c context.out

创建一个遵循 TCG Provisioning guide 的主要对象

参阅：https://trustedcomputinggroup.org/wp-content/uploads/TCG-TPM-v2.0-Provisioning-Guidance-Published-v1r1.pdf

其中 unique.dat 包含二进制格式的数据：0x00 0x01 (0x00 * 256)

tpm2_createprimary -C o -G rsa2048:aes128cfb -g sha256 -c prim.ctx \

-a 'restricted|decrypt|fixedtpm|fixedparent|sensitivedataorigin|userwithauth|\

noda' -u unique.dat

## Create a primary object and output the public key in pem format

```bash

tpm2_createprimary -c primary.ctx --format=pem --output=public.pem

2、tpm2_create [OPTIONS]  - 创建一个主密钥。

命令描述

创建一个子对象。该对象可以是钥匙或密封对象。密封对象允许将用户数据密封到 TPM，最大大小为 128 字节。此外，如果指定了-c，它将加载创建的对象。

1. OPTIONS

• -C, --parent-context=OBJECT: 要创建的对象的父级。
• -P, --parent-auth=AUTH: 使用-C指定的父对象的授权值。
• -p, --key-auth=AUTH: 创建对象的授权值。
• -g, --hash-algorithm=ALGORITHM: 用于生成对象名称的哈希算法。这是可选的，未指定时默认为 sha256。
• -G, --key-algorithm=ALGORITHM: 与此对象关联的密钥算法。如果未指定，则默认为“rsa”。
• -a, --attributes=ATTRIBUTES: 对象属性，可选。

默认为：TPMA_OBJECT_RESTRICTED|TPMA_OBJECT_DECRYPT|TPMA_OBJECT_FIXEDTPM| TPMA_OBJECT_FIXEDPARENT|TPMA_OBJECT_SENSITIVEDATAORIGIN| TPMA_OBJECT_USERWITHAUTH

当 –i 被指定为密封时，TPMA_OBJECT_SIGN_ENCRYPT 和TPMA_OBJECT_DECRYPT从默认属性集中删除。该算法以对象仅对密封和解封有效的方式设置。即不能使用对象进行密封加密操作。

指定-L并且未指定字符串密码为添加基于策略的授权信息时，除非通过使用-a选项设置属性做出明确选择，否则将清除属性TPMA_OBJECT_USERWITHAUTH。这可以防止创建具有无意身份验证模型的对象，其中用户打算强制执行策略，但无意中创建了具有空身份验证的对象，该对象可用于代替策略授权。

• -i, --sealing-input=FILE or STDIN: 要密封的数据文件，可选。

如果文件是 -，从标准输入读取。密封数据时，仅允许使用 NULL 方案的TPM_ALG_KEYEDHASH算法。因此，无法指定-G 。

• -L, --policy=FILE: 输入策略文件，可选。
• -u, --public=FILE: 包含已创建对象的公共部分的输出文件，可选。
• -r, --private=FILE: 包含对象敏感部分的输出文件，可选。

可以移出 TPM 的对象需要受到保护其机密性和完整性。此 blob 包含对象的敏感部分。对象的敏感部分受到父对象的保护，使用父对象的对称加密细节来加密敏感数据并对其进行 HMAC。

• -c, --key-context=FILE: 包含密钥上下文的输出文件，可选。

key-context类似于 tpm2_load生成的上下文文件，但是是通过tpm2_createloaded 命令生成的。此选项可用于避免正常的tpm2_create和tpm2_load命令序列，并以原子方式在一个命令中完成所有操作。

• --creation-data=FILE: 一个可选的文件输出，保存创建数据以供认证。
• --template-data=FILE: 一个可选的文件输出，保存要在tpm2_policytemplate中使用的密钥模板数据 (TPM2B_PUBLIC) 
• -t, --creation-ticket=FILE: 一个可选的文件输出，用于保存创建ticket以供认证。
• -d, --creation-hash=FILE: 一个可选的文件输出，用于保存创建哈希以供认证。
• -q, --outside-info=HEX_STR_OR_FILE: 用于将唯一数据添加到创建数据的可选十六进制字符串或路径。它不会有助于创建统计上唯一的对象。
• -l, --pcr-list=PCR: PCR banks列表和每个banks的选定 PCR 的 ID ，将包含在创建数据中以进行认证。
• --cphash=FILE： 记录命令参数哈希的文件路径。这通常称为 cpHash。注意：选择此选项时，该工具不会实际执行命令，它只是返回一个 cpHash。
• --rphash=FILE： 记录响应参数哈希的文件路径。这通常被称为 rpHash。
• -S, --session=FILE:  使用tpm2_startauthsession创建的会话。可以指定其中的多个。例如，您可以有一个会话用于审计，另一个用于参数的加密/解密。
• -o, --output=FILE: 输出文件路径，记录对象的公共部分。

例子

为了创建一个对象，我们必须首先创建一个主密钥作为它的父密钥。

tpm2_createprimary -c primary.ctx

创建对象

这将使用所有默认值创建一个对象，并将 TPM 密封的私有和公共部分分别存储到通过 -u 和 -r 指定的路径中。该工具默认使用 RSA 密钥。

tpm2_create -C primary.ctx -u obj.pub -r obj.priv

将数据密封到 TPM

在密钥对象之外，TPM 允许将少量用户指定的数据密封到 TPM。

echo "my sealed data" > seal.dat

tpm2_create -C primary.ctx -i seal.dat -u obj.pub -r obj.priv

创建 ECC 密钥对象并将其加载到 TPM

通常，在创建对象时，只返回对象的公共和私有部分，调用者需要使用 tpm2_load(1) 将这些公共和私有部分加载到 TPM 才能使用该对象。但是，当 TPM 支持时，这也可以在此命令中完成。您可以通过检查 tpm2_getcap(1) 命令在命令集中返回 TPM2_CC_CreateLoaded 来验证您的 TPM 是否支持此功能。如果您的 TPM 不支持 TPM2_CC_CreateLoaded，将返回不受支持的命令代码错误。如果不支持，则必须使用 tpm2_load(1)。

tpm2_create -C primary.ctx -G ecc -u obj.pub -r obj.priv -c ecc.ctx

创建一个对象并将公钥作为 PEM 文件获取

这将使用所有默认值创建一个对象，但还将公钥输出为与 OpenSSL 等工具兼容的 PEM 文件以及任何支持 PEM 文件的工具。

tpm2_create -C primary.ctx -u obj.pub -r obj.priv -f pem -o obj.pem

3、tpm2_load [OPTIONS]  - 将对象加载到 TPM。

命令描述

将对象的私有和公共部分都加载到 TPM 中。

注意：必须指定 tpm 密钥的私有和公共部分。

该工具以 YAML 字典格式输出已加载对象的名称以及密钥名，其中该密钥的值是十六进制格式的对象名称，例如：

name: 000bac25cb8743111c8e1f52f2ee7279d05d3902a18dd1af694db5d1afa7adf1c8b3

它还保存一个上下文文件以供将来与对象交互。

1. OPTIONS

• -C, --parent-context=OBJECT: 父对象
• -P, --auth=AUTH:  -C指定的父对象的授权值。
• -u, --public=FILE: 包含对象公共部分的文件。
• -r, --private=FILE:  包含对象敏感部分的文件。
• -n, --name=FILE:  用于保存对象名称结构的可选文件。
• -c, --key-context=FILE:  已保存对象上下文的文件名，必填。
• --cphash=FILE ：记录命令参数哈希的文件路径。这通常称为 cpHash。注意：选择此选项时，该工具不会实际执行命令，它只是返回一个 cpHash。

例子

要加载对象，您首先必须在主对象下创建一个对象。

所以第1步是创建主要对象。

tpm2_createprimary -c primary.ctx

第 2 步是在主对象下创建一个对象。

tpm2_create -C primary.ctx -u key.pub -r key.priv

创建 TPM 对象的私有和公共部分。通过这些对象部分，现在可以将该对象加载到 TPM 中以供后续使用。

将对象加载到 TPM

最后一步是将对象的公共和私有部分加载到 TPM 中。

tpm2_load  -C primary.ctx -u key.pub -r key.priv -c key.ctx

name: 000bac25cb8743111c8e1f52f2ee7279d05d3902a18dd1af694db5d1afa7adf1c8b3

4、tpm2_changeauth [OPTIONS] [ARGUMENT] - 更改 TPM 对象的授权值。

命令描述

tpm2_changeauth - 为各种层次结构、NV 索引、瞬态和持久对象配置授权值。

注意：对于非永久对象（瞬态对象和持久对象），在更改身份验证之前创建的私有信息（文件或持久句柄）的副本不会失效。

1. OPTIONS

密码应遵循“密码授权格式标准”，请参阅“授权格式”部分。

• -c，--object-context = OBJECT ：用于操作的密钥上下文对象。
• -p , --object-auth = AUTH : 使用-c指定的 TPM 对象的旧授权值。
• -C，--parent-context = OBJECT ：父对象。如果操作的对象是瞬态或持久对象，则这是必需的。
• -r , --private = FILE ：输出文件，其中包含正在更改身份验证的对象的新敏感部分。
• --cphash = FILE ：

记录命令参数哈希的文件路径。这通常称为 cpHash。注意：选择此选项时，该工具不会实际执行命令，它只会返回一个 cpHash，除非还需要 rphash。

• --rphash = FILE ：

记录响应参数哈希的文件路径。这通常被称为 rpHash。

• -S，--会话= FILE ：

使用tpm2_startauthsession创建的会话。这可用于指定一个辅助会话，用于对参数进行审计 或加密/解密。

1. ARGUMENT

命令行参数指定要为使用-c指定的对象设置的AUTH。

例子

将所有者、背书和lockout授权设置为 newpass

tpm2_changeauth -c owner newpass

tpm2_changeauth -c endorsement newpass

tpm2_changeauth -c lockout newpass

更改所有者、背书和lockout 授权

tpm2_changeauth -c o -p newpass newerpass

tpm2_changeauth -c e -p newpass newerpass

tpm2_changeauth -c l -p newpass newerpass

将所有者授权设置为空密码

tpm2_changeauth -c o -p oldpass

修改可加载瞬态对象的授权

tpm2_createprimary -Q -C o -c prim.ctx

tpm2_create -Q -g sha256 -G aes -u key.pub -r key.priv -C prim.ctx

tpm2_load -C prim.ctx -u key.pub -r key.priv -n key.name -c key.ctx

tpm2_changeauth -c key.ctx -C prim.ctx -r key.priv newkeyauth

修改 NV 索引的授权

需要扩展会话支持。

tpm2_startauthsession -S session.ctx

tpm2_policycommandcode -S session.ctx -L policy.nvchange TPM2_CC_NV_ChangeAuth

tpm2_flushcontext session.ctx

NVIndex=0x1500015

tpm2_nvdefine   $NVIndex -C o -s 32 -a "authread|authwrite" -L policy.nvchange

tpm2_startauthsession \--policy-session -S session.ctx

tpm2_policycommandcode -S session.ctx -L policy.nvchange TPM2_CC_NV_ChangeAuth

tpm2_changeauth -p session:session.ctx -c $NVIndex newindexauth

5、tpm2_startauthsession [OPTIONS] - 使用 TPM 启动会话。

命令描述

启动与 TPM 的会话。除非指定了-a选项，否则默认设置是启动trial会话。将policy会话数据保存到文件中，然后，该文件可以在后续工具中使用，这些工​​具可以使用策略文件进行授权或策略事件。

此命令不适用于 tpm2-abrmd之外的资源管理器 (RM) ，因为当客户端从 IPC 通道断开连接时，大多数 RM 将刷新会话句柄。但是，当使用没有会话间隙功能的 RM 时，可以使用命令 TCTI 保持连接打开。具体参考tpm2-tools。

1. OPTIONS

• --policy-session: 启动TPM_SE_POLICY类型的策略会话。

没有此选项的默认值为TPM_SE_TRIAL。

注意：构建策略时使用trial会话，使用策略进行身份验证时使用策略会话。

• --audit-session: 启动 HMAC 会话以用作审计会话。

没有此选项的默认值为TPM2_SE_TRIAL。

• --hmac-session : 启动TPM_SE_HMAC类型的 HMAC 会话。

没有此选项的默认值为TPM2_SE_TRIAL。

• -g, --hash-algorithm=ALGORITHM : 用于计算策略摘要的哈希算法。
• -c, --key-context=OBJECT : 将 tpmkey 和 bind 对象设置为相同。

会话参数加密已打开；会话参数解密已打开。参数加密/解密symmetric-key 设置为 AES-CFB。

• -S, --session=FILE : 策略会话文件的名称，必填。
• --bind-context=FILE : 设置绑定对象。

会话参数加密已关闭；会话参数解密已关闭。使用tpm2_sessionconfig开启。参数加密/解密symmetric-key 设置为 AES-CFB。

• --bind-auth=AUTH : 设置绑定对象的授权值。
• --tpmkey-context=FILE:  设置 tpmkey 对象。

会话参数加密已关闭；会话参数解密已关闭。使用tpm2_sessionconfig开启。参数加密/解密symmetric-key 设置为 AES-CFB。

例子

开始试用会话并将会话数据保存到文件中

tpm2_startauthsession -S mysession.ctx

启动策略会话并将会话数据保存到文件

tpm2_startauthsession --policy-session -S mysession.ctx

启动加密和绑定策略会话并将会话数据保存到文件

tpm2_createprimary -c primary.ctx

tpm2_startauthsession --policy-session -c primary.ctx -S mysession.ctx