HiTSS

简介

HiTSS是基于TPM（Trusted Platform Module）2.0规范开发的组件，它提供了访问TPM 2.0芯片的API，包括命令传输接口、系统级接口和序列化反序列化接口，使开发者可以更方便地使用TPM 2.0芯片用于执行各种TPM操作，例如创建密钥、签名验签等，帮助开发者轻松与TPM 2.0芯片进行通信。HiTSS目前只针对鸿蒙电脑企业客户开放。

HiTSS版本

从API 6.0.0(20)开始，HiTSS匹配TCG （Trusted Computing Group）TSS（TPM2 Software Stack）规范版本为：

• TCG TSS 2.0 Overview and Common Structures Specification Version 1.0 Revision 10, September 23 2021

• TCG TSS 2.0 Marshaling/Unmarshaling API Specification Version 1.0 Revision 07, 10 March 2020

• TCG TSS 2.0 System Level API (SAPI) Specification Version 1.1 Revision 36, October 1 2021

• TCG TSS 2.0 TPM Command Transmission Interface (TCTI) API Specification Version 1.0 Revision 18, 24 January 2020

HiTSS支持的能力

• 命令传输接口，具体内容请参见HiTSS支持的命令传输接口列表。

• 序列化反序列化接口，具体内容请参见HiTSS支持的序列化和反序列化接口列表。

• 系统级接口（由于芯片能力限制，HiTSS只支持部分系统级接口），具体内容请参见HiTSS支持的系统级接口列表。

引入HiTSS能力

1. 开发应用时，在访问命令传输接口或系统级接口前，需要申请权限：ohos.permission.CALL_TPM_CMD，申请方式请参考：申请使用受限权限。

2. 如果开发者需要使用HiTSS相关能力，首先请添加头文件。

   #include <tss2/tss2_common.h>
   #include <tss2/tss2_tpm2_types.h>
   #include <tss2/tss2_mu.h>
   #include <tss2/tss2_sys.h>
   #include <tss2/tss2_tcti.h>
   #include <tss2/tss2_tctildr.h>

3. 其次在CMakeLists.txt中添加以下动态链接库。

   libtss2-mu.so
   libtss2-sys.so
   libtss2-tctildr.so

使用示例

#include <stdio.h>
#include <tss2/tss2_tctildr.h>
#include <tss2/tss2_sys.h>
#include <tss2/tss2_mu.h>

#define SAFE_FREE(p) do { \
    if ((p) != NULL) { \
        free(p); \
        (p) = NULL; \
    } \
} while (false)

// 初始化上下文
TSS2_SYS_CONTEXT* InitSysCtx()
{
    TSS2_TCTI_CONTEXT *tctiCtx = NULL;
    const char *nameConf = "hmsa";
    // nameConf参数字符串中不支持设定conf，conf必须为空
    // 正确用法
    // Tss2_TctiLdr_Initialize("hmsa", &tctiCtx);
    // Tss2_TctiLdr_Initialize("hmsa:", &tctiCtx);
    // 错误用法
    // Tss2_TctiLdr_Initialize("hmsa:/dev/tpm0", &tctiCtx);
    TSS2_RC rc = Tss2_TctiLdr_Initialize(nameConf, &tctiCtx);
    if (rc != TSS2_RC_SUCCESS) {
        return NULL;
    }
    size_t size = Tss2_Sys_GetContextSize(0);
    TSS2_SYS_CONTEXT *sysCtx = (TSS2_SYS_CONTEXT *)calloc(1, size);
    if (sysCtx == nullptr) {
        return NULL;
    }
    TSS2_ABI_VERSION ver = TSS2_ABI_VERSION_CURRENT;
    rc = Tss2_Sys_Initialize(sysCtx, size, tctiCtx, &ver);
    if (rc != TSS2_RC_SUCCESS) {
        Tss2_TctiLdr_Finalize(&tctiCtx);
        SAFE_FREE(sysCtx);
        return NULL;
    }
    return sysCtx;
}

// 释放上下文
void ReleaseSysCtx(TSS2_SYS_CONTEXT **sysCtx)
{
    TSS2_TCTI_CONTEXT *tctiCtx = NULL;
    TSS2_RC rc = Tss2_Sys_GetTctiContext(*sysCtx, &tctiCtx);
    if (rc != TSS2_RC_SUCCESS) {
        return;
    }
    if (tctiCtx != NULL) {
        Tss2_TctiLdr_Finalize(&tctiCtx);
    }
    Tss2_Sys_Finalize(*sysCtx);
    SAFE_FREE(*sysCtx);
}

// 通过Sys API获取随机数示例
void GetRandomExample()
{
    TSS2_SYS_CONTEXT *sysCtx = InitSysCtx();
    if (sysCtx == NULL) {
        return;
    }
    TPM2B_DIGEST random = {};
    TSS2_RC rc = Tss2_Sys_GetRandom(sysCtx, NULL, 32, &random, NULL); // 32: 随机数长度
    if (rc != TSS2_RC_SUCCESS) {
        printf("Failed to get random, error:%d.\n", rc);
    }
    ReleaseSysCtx(&sysCtx);
}

// 通过Sys API获取随机数示例
void GetRandomExample2()
{
    TSS2_SYS_CONTEXT *sysCtx = InitSysCtx();
    if (sysCtx == NULL) {
        return;
    }
    TPM2B_DIGEST random = {};
    do {
        if (Tss2_Sys_GetRandom_Prepare(sysCtx, 32) != TSS2_RC_SUCCESS) { // 32: 随机数长度
            break;
        }
        if (Tss2_Sys_Execute(sysCtx) != TSS2_RC_SUCCESS) {
            break;
        }
        if (Tss2_Sys_GetRandom_Complete(sysCtx, &random) != TSS2_RC_SUCCESS) {
            break;
        }
    } while(false);
    ReleaseSysCtx(&sysCtx);
}

// MU API使用示例
void Int32MarshalUnmarshalExample()
{
    INT32 data = 20;
    uint8_t buffer[sizeof(data)] = { 0 };
    size_t bufferSize = sizeof(data);
    // 序列化data
    TSS2_RC rc = Tss2_MU_INT32_Marshal(data, buffer, bufferSize, NULL);
    if (rc != TSS2_RC_SUCCESS) {
        printf("Failed to marshal data, error:%d.\n", rc);
    }
    INT32 dest = 0;
    // 反序列化data，然后打印
    rc = Tss2_MU_INT32_Unmarshal(buffer, bufferSize, NULL, &dest);
    if (rc != TSS2_RC_SUCCESS) {
        printf("Failed to unmarshal data, error:%d.\n", rc);
    }
    printf("The unmarshal result is %d.\n", dest);
}

错误码

以下仅介绍HiTSS特有错误码，通用错误码请参考TCG TSS 2.0 Overview and Common Structures Specification。

[h2]TSS2_BASE_RC_INTERNAL_ERROR

错误描述

内部错误。

可能原因

代码内部处理逻辑与预期不符。

处理步骤

检查代码逻辑和芯片状态是否正确。

[h2]TSS2_BASE_RC_SAPI_INIT

错误描述

SAPI上下文初始化失败。

可能原因

参数不正确。

处理步骤

检查函数入参是否正确。

[h2]TSS2_BASE_RC_CANCEL

错误描述

命令取消错误。

可能原因

命令队列已满。

处理步骤

尝试重试。

[h2]TSS2_TCTI_RC_MEMORY

错误描述

TCTI接口内存错误。

可能原因

设备内存不足或其它内存异常。

处理步骤

查看设备可用内存是否大于申请内存，并及时清理设备内存。

与TCG TSS标准规范的差异

以下类型和结构体与TCG TSS标准规范存在差异，HiTSS在标准规范基础上进行了能力扩充和错误修复。

// HiTSS新增宏定义
#define TPM2_ST_ATTEST_NV_DIGEST ((TPM2_ST) 0x801C)

// HiTSS新增nvDigest字段
typedef union TPMU_ATTEST TPMU_ATTEST;
union TPMU_ATTEST {
    TPMS_CERTIFY_INFO certify; /* TPM2_ST_ATTEST_CERTIFY */
    TPMS_CREATION_INFO creation; /* TPM2_ST_ATTEST_CREATION */
    TPMS_QUOTE_INFO quote; /* TPM2_ST_ATTEST_QUOTE */
    TPMS_COMMAND_AUDIT_INFO commandAudit; /* TPM2_ST_ATTEST_COMMAND_AUDIT */
    TPMS_SESSION_AUDIT_INFO sessionAudit; /* TPM2_ST_ATTEST_SESSION_AUDIT */
    TPMS_TIME_ATTEST_INFO time; /* TPM2_ST_ATTEST_TIME */
    TPMS_NV_CERTIFY_INFO nv; /* TPM2_ST_ATTEST_NV */
    TPMS_NV_DIGEST_CERTIFY_INFO nvDigest; /* TPM2_ST_ATTEST_NV_DIGEST */
};

// HiTSS新增类型
typedef TPM2_KEY_BITS TPMI_TDES_KEY_BITS;

// HiTSS新增tdes字段
typedef union TPMU_SYM_KEY_BITS TPMU_SYM_KEY_BITS;
union TPMU_SYM_KEY_BITS {
    TPMI_TDES_KEY_BITS tdes; /* TPM2_ALG_TDES */
    TPMI_AES_KEY_BITS aes; /* TPM2_ALG_AES */
    TPMI_SM4_KEY_BITS sm4; /* TPM2_ALG_SM4 */
    TPMI_CAMELLIA_KEY_BITS camellia; /* TPM2_ALG_CAMELLIA */
    TPM2_KEY_BITS sym;
    TPMI_ALG_HASH exclusiveOr; /* TPM2_ALG_XOR */
    TPMS_EMPTY null; /* TPM2_ALG_NULL */
};

// HiTSS新增tdes字段
typedef union TPMU_SYM_MODE TPMU_SYM_MODE;
union TPMU_SYM_MODE {
    TPMI_ALG_SYM_MODE tdes; /* TPM2_ALG_TDES */
    TPMI_ALG_SYM_MODE aes; /* TPM2_ALG_AES */
    TPMI_ALG_SYM_MODE sm4; /* TPM2_ALG_SM4 */
    TPMI_ALG_SYM_MODE camellia; /* TPM2_ALG_CAMELLIA */
    TPMI_ALG_SYM_MODE sym;
    TPMS_EMPTY exclusiveOr; /* TPM2_ALG_XOR */
    TPMS_EMPTY null; /* TPM2_ALG_NULL */
};

// TCG规范中缺失的定义
typedef UINT32 TPM2_AT;

// TCG规范中缺失的定义
#define TPM2_MAX_AC_CAPABILITIES (TPM2_MAX_CAP_BUFFER / sizeof(TPMS_AC_OUTPUT))

// 为方便用户使用，HiTSS新增TPM2B结构体
typedef struct {
    UINT16 size;
    BYTE buffer[];
} TPM2B;

// TCG规范中缺失的定义
typedef TPM2_HANDLE TPMI_RH_HIERARCHY_POLICY;

// TCG规范中错误定义了tag字段的类型，HiTSS进行了修正
typedef struct TPMS_AC_OUTPUT TPMS_AC_OUTPUT;
struct TPMS_AC_OUTPUT {
    TPM2_AT tag;
    UINT32 data;
};

相关参考

• TCG TSS 2.0 Marshaling/Unmarshaling API Specification

• TCG TSS 2.0 System Level API (SAPI) Specification

• TCG TSS 2.0 TPM Command Transmission Interface (TCTI) API Specification

• TCG TSS 2.0 Overview and Common Structures Specification

HiTSS支持的系统级接口列表

[h2]命令上下文管理

• Tss2_Sys_GetContextSize

• Tss2_Sys_Initialize

• Tss2_Sys_Finalize

• Tss2_Sys_GetTctiContext

[h2]命令准备

• Tss2_Sys_SetCmdAuths

[h2]命令执行

• Tss2_Sys_ExecuteAsync

• Tss2_Sys_ExecuteFinish

• Tss2_Sys_Execute

• Tss2_Sys_GetRspAuths

[h2]TPM命令调用

HiTSS支持的序列化和反序列化接口列表

HiTSS支持的命令传输接口列表

• Tss2_TctiLdr_Initialize

• Tss2_TctiLdr_Initialize_Ex

• Tss2_TctiLdr_Finalize

• Tss2_TctiLdr_GetInfo

• Tss2_TctiLdr_FreeInfo

模拟器支持情况

本Kit暂不支持模拟器。