OPTEE：持久化对象相关接口

一、Persistent Object Functions

1、TEE_OpenPersistentObject

TEE_Result TEE_OpenPersistentObject(                                                                    uint32_t                      storageID,                              [in(objectIDLength)]      void*                            objectID,                                                                    size_t                          objectIDLen,                                                                    uint32_t                       flags,                              [out]                              TEE_ObjectHandle*    object );
函数简介	1）该接口打开现有持久化对象(existing persistent object)的句柄(handle)。 2）它返回一个句柄，该句柄可用于访问对象(object)的属性(attribute)和数据流(data stream)。 3)  可以同时在同一对象(object)上打开多个句柄(handle)，但应明确允许共享。 4）数据流中的初始数据位置设置为 0。
参数介绍	storageID：标识要访问的受信任存储空间。有效值在表 5-2 中定义。 objectID：对象标识符。此缓冲区不能驻留(reside)在共享内存(shared memory)中。 objectIDLen：objectID的长度 flags：用于确定打开对象的设置的标志。有效值在表 5-3 中定义。它是一组标志，用已打开的对象句柄(object handle)的控制访问权限(access rights)和共享权限(sharing permissions)。flags 参数的值由以下列表中标志的按位包含 OR 构造： • 访问控制标志： o TEE_DATA_FLAG_ACCESS_READ：使用读取访问权限打开对象。这允许 TA 调用TEE_ReadObjectData函数。 o TEE_DATA_FLAG_ACCESS_WRITE：使用写入访问权限打开对象。这允许 TA 调用TEE_WriteObjectData和TEE_TruncateObjectData函数。 o TEE_DATA_FLAG_ACCESS_WRITE_META：使用写入元访问权限打开对象。这允许 TA 调用TEE_CloseAndDeletePersistentObject1 和TEE_RenamePersistentObject函数。 • 共享权限控制标志： o TEE_DATA_FLAG_SHARE_READ：调用方允许使用读取访问权限创建对象上的另一个句柄。 o TEE_DATA_FLAG_SHARE_WRITE：调用方允许使用写入访问权限创建对象上的另一个句柄。 • 其他标志保留供将来使用，并应设置为 0。 object：指向句柄(handle)的指针，包含了成功完成时打开的句柄。如果此函数由于任何原因失败，则对象指向的值将设置为TEE_HANDLE_NULL。当不再需要对象句柄时，应调用TEE_CloseObject函数来关闭。
返回值	• TEE_SUCCESS：成功 • TEE_ERROR_ITEM_NOT_FOUND：storageID表示的存储不存在，或者在存储中找不到对象标识符(object identifier) • TEE_ERROR_ACCESS_CONFLICT：在打开对象时检测到访问权限冲突(right conflict) • TEE_ERROR_OUT_OF_MEMORY：没有足够的内存来完成操作 • TEE_ERROR_CORRUPT_OBJECT：当TA 尝试打开某个对象，并且 TEE 确定其内容（或存储本身的内容）已被篡改或回滚 • TEE_ERROR_STORAGE_NOT_AVAILABLE：持久性对象(persistent object)存储在当前无法访问的存储区域中。它可能与设备相关联，但由于其他原因而拔出、繁忙或无法访问。
补充说明	1）产生panic的原因： • objectIDLen大于 TEE_OBJECT_ID_MAX_LEN。 • 实现检测到与此函数关联的任何其他错误，并且该错误未显式显示与此函数的已定义返回代码相关联。

2、TEE_CreatePersistentObject

TEE_Result TEE_CreatePersistentObject(                                                                     uint32_t                      storageID,                              [in(objectIDLength)]       void*                            objectID,                                                                     size_t                          objectIDLen,                                                                     uint32_t                       flags,                                                                     TEE_ObjectHandle*    attribute,                              [inbuf]                             void*                             initialData,                                                                    size_t                           initialDataLen.                              [outopt]                          TEE_ObjectHandle*    object );
函数简介	1）该接口创建一个具有初始属性和初始数据流内容的持久对象(persistent object) 2）新创建的持久性对象(persistent object)的属性取自参数attribute，这些属性可以是另一个持久性对象，也可以是初始化的临时对象(initialized transient object)。对象类型、大小和用法是从属性中复制的。 3）若要创建纯数据对象，参数attribute也可以为 NULL。如果attribute为 NULL，则应将对象(object)类型设置为TEE_TYPE_DATA以创建纯数据对象。 4）可以同时在同一对象上打开多个句柄，但应明确允许共享。 5）数据流中的初始数据位置设置为 0。 6）要将初始化的临时对象转换为持久性对象，请参阅表 5-13 后面的对象参数说明。
参数介绍	storageID：标识要访问的TA空间。有效值在表 5-2 中定义。 objectID：对象标识符。此缓冲区不能驻留(reside)在共享内存(shared memory)中。 objectIDLen：objectID的长度 flags：用于确定打开对象的设置的标志。有效值在表 5-3 中定义。它是一组标志，用已打开的对象句柄控制访问权限和共享权限。flags 参数的值由以下列表中标志的按位包含 OR 构造： • 访问控制标志： o TEE_DATA_FLAG_ACCESS_READ：使用读取访问权限打开对象。这允许 TA 调用TEE_ReadObjectData函数。 o TEE_DATA_FLAG_ACCESS_WRITE：使用写入访问权限打开对象。这允许 TA 调用TEE_WriteObjectData和TEE_TruncateObjectData函数。 o TEE_DATA_FLAG_ACCESS_WRITE_META：使用写入元访问权限打开对象。这允许 TA 调用TEE_CloseAndDeletePersistentObject1 和TEE_RenamePersistentObject函数。 • 共享权限控制标志： o TEE_DATA_FLAG_SHARE_READ：调用方允许使用读取访问权限创建对象上的另一个句柄。 o TEE_DATA_FLAG_SHARE_WRITE：调用方允许使用写入访问权限创建对象上的另一个句柄。 • 其他标志保留供将来使用，并应设置为 0。 attribute：持久性对象或初始化的临时对象的句柄，可从中获取持久性对象属性。如果持久对象不包含任何属性，则可以为 TEE_HANDLE_NULL，例如，如果它是纯数据对象。 initialData：持久对象的初始数据内容 initialDataLen：initialData的长度 object：指向句柄的可选指针。 当对象不为空时： o 包含成功完成时打开的句柄。 o 如果此函数因任何原因失败，则对象指向的值将设置为 TEE_HANDLE_NULL。 o 当不再需要对象句柄时，应使用调用theTEE_CloseObject函数来关闭它。 当对象为空时： o 如果属性是初始化临时对象的句柄，则初始化的临时对象应转换为持久性对象。
返回值	• TEE_SUCCESS：成功 • TEE_ERROR_ITEM_NOT_FOUND：storageID表示的存储不存在，或者在存储中找不到对象标识符 • TEE_ERROR_ACCESS_CONFLICT：在打开对象时检测到访问权限冲突 • TEE_ERROR_OUT_OF_MEMORY：没有足够的内存来完成操作 • TEE_ERROR_STORAGE_NO_SPACE：如果没有足够的空间可用于创建持久性对象 • TEE_ERROR_CORRUPT_OBJECT：当TA 尝试打开某个对象，并且 TEE 确定其内容（或存储本身的内容）已被篡改或回滚 • TEE_ERROR_STORAGE_NOT_AVAILABLE：持久性对象存储在当前无法访问的存储区域中。它可能与设备相关联，但由于其他原因而拔出、繁忙或无法访问。
补充说明	1）产生panic的原因： • objectIDLen大于 TEE_OBJECT_ID_MAX_LEN。 • 属性不是TEE_HANDLE_NULL，并且不是包含要创建的持久性对象的类型和属性的初始化对象的有效句柄。 • 属性不是初始化的临时对象的句柄，并且对象为 NULL。 • 实现检测到与此函数关联的任何其他错误，并且该错误未显式显示与此函数的已定义返回代码相关联。

3、TEE_CloseAndDeletePersistentObject1

TEE_Result TEE_CloseAndDeletePersistentObject1(                                                                                           TEE_ObjectHandle*    object );
函数简介	1）接口替换了TEE_CloseAndDeletePersistentObject函数，后者已被弃用。 2）接口将对象标记为删除并关闭对象句柄(object handle)。 3) 对象句柄已使用写入元访问权限(write-meta access right)打开，即，访问对象是排他性的。 4）删除对象是原子的。一旦此函数返回，该对象将被删除，并且不再存在该对象的打开句柄。即使对象或包含它的存储已损坏，也是如此。 5）此例程可能失败的唯一原因是包含此对象的存储区域变得不可访问（例，用户删除了该对象的媒介），这种情况下，应返回TEE_ERROR_STORAGE_NOT_AVAILABLE。 6)  如果对象是TEE_HANDLE_NULL，则该函数不执行任何操作
参数介绍	object：对象句柄
返回值	• TEE_SUCCESS：成功 • TEE_ERROR_STORAGE_NOT_AVAILABLE：持久性对象(persistent object)存储在当前无法访问的存储区域中。它可能与设备相关联，但由于其他原因而拔出、繁忙或无法访问。
补充说明	1）产生panic的原因： • 持久性对象不是使用写入元访问权限打开的有效对象句柄 • 实现检测到与此函数关联的任何其他错误，并且该错误未显式显示与此函数的已定义返回代码相关联。

4、TEE_RenamePersistentObject

TEE_Result  TEE_RenameObject(                                                            TEE_ObjectHandle    object ,               [in(newObjectIDLen)]         void*                           newObjectID,                                                            size_t                          newObjectIDLen);
函数简介	1）该接口更改对象的标识符。 2）对象句柄应已使用写入元访问权限打开，这意味着对对象的访问是排他性的。 3)  重命名对象是原子的。对象要么被重命名，要么没有任何反应。 4）此例程可能失败的唯一原因是包含此对象的存储区域变得不可访问（例，用户删除了该对象的媒介），这种情况下，应返回TEE_ERROR_STORAGE_NOT_AVAILABLE。 5)  如果对象是TEE_HANDLE_NULL，则该函数不执行任何操作
参数介绍	object：对象句柄 newObjectID：包含新对象标识符的缓冲区。标识符包含任意字节，包括零字节。标识符长度应小于或等于TEE_OBJECT_ID_MAX_LEN，并且可以为0.包含新对象标识符的缓冲区不能驻留在共享内存中。 newObjectIDLen：newObjectIDLen的长度
返回值	• TEE_SUCCESS：成功 • TEE_ERROR_ACCESS_CONFLICT：已存在具有相同标识符的对象 • TEE_ERROR_CORRUPT_OBJECT对象已损坏。对象句柄的行为应基于 “gpd.ta.doesNotCloseHandleOnCorruptObject”属性。 • TEE_ERROR_STORAGE_NOT_AVAILABLE：持久性对象(persistent object)存储在当前无法访问的存储区域中。它可能与设备相关联，但由于其他原因而拔出、繁忙或无法访问。
补充说明	1）产生panic的原因： • 持久性对象不是使用写入元访问权限打开的有效对象句柄 • newObjectID 驻留在共享内存中 • newObjectIDLen 超过 TEE_OBJECT_ID_MAX_LEN • 实现检测到与此函数关联的任何其他错误，并且该错误未显式显示与此函数的已定义返回代码相关联

5、persistent object共享规则

可以使用TEE_OpenPersistentObject 或TEE_CreatePersistentObject函数同时在同一对象上打开多个句柄，但应明确允许共享。更准确地说，在任何时候都适用以下约束：如果在同一对象上打开了多个句柄，并且如果这些对象句柄中的任何一个都是使用TEE_DATA_FLAG_ACCESS_READ标志的，则所有对象句柄应已使用该TEE_DATA_FLAG_SHARE_READ标志打开。

TEE_DATA_FLAG_ACCESS_WRITE和TEE_DATA_FLAG_SHARE_WRITE的标志有相应的约束。使用ACCESS_WRITE_META权限访问对象是排他性的，永远不能共享。

当调用TEE_OpenPersistentObject 或 TEE_CreatePersistentObject 其中一个函数时，如果打开对象会违反这些约束，则该函数会返回TEE_ERROR_ACCESS_CONFLICT错误代码。

表5-3中未定义的标志中的任何位都将保留供将来使用，并应设置成0。

表5-14中的示例说明了在同一对象上调用两次函数TEE_OpenPersistentObject时的行为。请注意，为了便于阅读，表 5-14 中使用的标志名称已通过从其名称中删除 ‘TEE_DATA_FLAG_’前缀进行了缩写，并且通过删除 ‘TEE_ERROR_’ 前缀缩短了任何非TEE_SUCCESS返回代码。

二、Persistent Object Enumeration Functions

1、TEE_AllocatePersistentObjectEnumerator

TEE_Result TEE_AllocatePersistentObjectEnumerator(                                                                   [out]                   TEE_ObjectEnumHandle*   objectEnumerator);
函数简介	1）接口在对象枚举器上分配句柄。 2）分配对象枚举器句柄后，可以将其重用于多个枚举。
参数介绍	objectEnumerator：成功时填充新分配对象枚举器句柄的指针。以防出现错误，将其设为TEE_HANDLE_NULL。
返回值	• TEE_SUCCESS：成功 • TEE_ERROR_OUT_OF_MEMORY：没有足够的内存来分配枚举器句柄
补充说明	1）产生panic的原因： • 实现检测到与此函数关联的任何其他错误，并且该错误未显式显示与此函数的已定义返回代码相关联。

2、TEE_FreePersistentObjectEnumerator

void TEE_FreePersistentObjectEnumerator(                                                                             TEE_ObjectEnumHandle*   objectEnumerator);
函数简介	1）接口解除分配与对象枚举器句柄关联的所有资源。 2）调用此接口后，句柄不再有效。
参数介绍	objectEnumerator：要关闭的句柄。若对象枚举器为TEE_HANDLE_NULL，则此接口不执行任何操作。
返回值	---
补充说明	1）产生panic的原因： • 对象枚举器不是对象枚举器上的有效句柄。 • 实现检测到与此函数关联的任何其他错误，并且该错误未显式显示与此函数的已定义返回代码相关联。

3、TEE_ResetPersistentObjectEnumerator

void TEE_ResetPersistentObjectEnumerator(                                                                               TEE_ObjectEnumHandle   objectEnumerator);
函数简介	1）接口在对象枚举器完成分配后将其重置为初始状态。 2）若枚举已启动，则该枚举将停止。 3）若对象枚举器为TEE_HANDLE_NULL,此接口不执行任何操作。
参数介绍	objectEnumerator：要重置的句柄。
返回值	---
补充说明	1）产生panic的原因： • 对象枚举器不是TEE_HANDLE_NULL且不是对象枚举器上的有效句柄。 • 实现检测到与此函数关联的任何其他错误。

4、TEE_StartPersistentObjectEnumerator

TEE_Result TEE_StartPersistentObjectEnumerator(                                                                                           TEE_ObjectEnumHandle   objectEnumerator，                                                                                           uint_32t                               storageID);
函数简介	1）接口将启动给定的可信存储中所有持久性对象的枚举。 2）可以通过重复调用接口TEE_GetNextPersistentObject来检索对象信息。 3）枚举不一定反应给定存储的一致状态：在枚举期间，其他TA或TA的其他实例可能会创建、删除或重命名对象。若枚举正在进行，则不能保证在枚举过程中创建或销毁对象时将返回所有对象。？？ 4）若要停止枚举，TA可以调用TEE_ResetPersistentObjectEnumerator接口，它会将枚举器从可信存储中分离出来。TA可以调用TEE_FreePersistentObjectEnumerator 接口来完全解除对象枚举器的分配。 5）若在已启动的枚举器上调用此接口，则首先重置(reset)然后启动(start)。
参数介绍	objectEnumerator：对象枚举器上的有效句柄 storageID：存储在枚举对象中的标识符。
返回值	• TEE_SUCCESS：成功。 • TEE_ERROR_ITEM_NOT_FOUND：存储不存在或指定存储中没有对象 • TEE_ERROR_CORRUPT_OBJECT：存储已损坏 • TEE_ERROR_STORAGE_NOT_AVAILABLE：持久性对象存储在当前无法访问的存储区域中。
补充说明	1）产生panic的原因： • 对象枚举器不是对象枚举器上的有效句柄。 • 实现检测到与此函数关联的任何其他错误。

5、TEE_GetNextPersistentObject 

TEE_Result TEE_GetNextPersistentObject(                                                                           TEE_ObjectEnumHandle   objectEnumerator，                                           [out]                        TEE_ObjectInfo*                 objectInfo，                                           [out]                         void*                                    objectID，                                           [out]                         size_t*                                  objectIDLen);
函数简介	1）接口获取枚举中的下一个对象，并返回有关该对象的信息：类型、大小、标识符等。 2）若枚举中没有更多对象，或没有启动枚举，则该接口将返回TEE_ERROR_ITEM_NOT_FOUND。 3）若在枚举对象是检测到损坏的对象，则应以objectID的形式返回其对象ID，且返回错误代码TEE_ERROR_CORRUPT_OBJECT。 4）若在枚举发生时可用对象集发生更改，则可能会多次报告对象或根本不报告对象。
参数介绍	objectEnumerator：对象枚举器上的句柄 objectInfo：指向TEE_ObjectInfo的指针，其中填充了TEE_GetObjectInfo1接口指定的对象信息。它可能为空。 objectID：指向能够保存至少TEE_OBJECT_ID_MAX_LEN字节数组的指针。返回时，对象标识符写入此参数中。 objectIDLen：objectID的长度(从0到TEE_OBJECT_ID_MAX_LEN)
返回值	• TEE_SUCCESS：成功 • TEE_ERROR_ITEM_NOT_FOUND：对象枚举器中没有更多元素，或者没有枚举在此句柄上启动 • TEE_ERROR_CORRUPT_OBJECT：存储或返回的对象已损坏 • TEE_ERROR_STORAGE_NOT_AVAILABLE：持久性对象存储在当前无法访问的存储区域中
补充说明	1）产生panic的原因： • 对象枚举器不是对象枚举器上的有效句柄 • objectID为NULL • objectIDLen为NULL • 实现检测到与此函数关联的任何其他错误