这部分API定义了如何实际执行密码运算：

• 可以为给定的操作类型，算法和密钥大小预先分配密码操作，生成的密码操作句柄可以重复用于多个操作。
• 当操作需要时，可以独立设置密码操作密钥，并将其重新用于多个操作。请注意，某些加密算法（例如AES-XTS）需要两个密钥。
• 一个操作可能处于两种状态：初始状态，什么都没有进行；活动状态，正在进行操作。
• 本规范支持的加密算法有：

 

 

• tee.cryptography.ecc属性如果是true，则支持下列算法：

• 摘要，对称加密，MAC和AE操作始终是多阶段的，即可以按连续的块将数据提供给API。另一方面，非对称操作始终是单阶段的。请注意，签名和验证操作是对调用方计算的摘要进行操作。
• 可以将操作状态从一个操作句柄复制到未初始化的操作句柄中，这允许TA复制或派生多阶段操作。

 

 

数据结构

 

  

 

通用运算函数 

这些函数是所有类型的密码操作所共有的，包括：摘要、对称加密、消息认证码、非对称加密、密钥派生、认证加密……

1、TEE_Result TEE_AllocateOperation(TEE_OperationHandle* operation, uint32_t algorithm, uint32_t mode, uint32_t maxKeySize);

该函数为新的加密操作分配一个句柄，并设置模式和算法类型。如果此函数未返回TEE_SUCCESS，则没有有效的句柄值。

一旦创建了加密操作，GP实现必须保证分配了该操作所需的所有资源，并且可以执行任何密钥最大为maxKeySize位的操作。如果算法需要多个密钥，由GP实现来为其分配合适的内存。

参数algorithm、mode、maxKeySize请参考相关表格。 

 

2、void TEE_FreeOperation(TEE_OperationHandle operation);

取消分配与操作句柄关联的所有资源。调用此函数后，操作句柄不再有效，且该操作中的所有加密材料均被销毁。 

 

3、void TEE_GetOperationInfo(TEE_OperationHandle operation, [out] TEE_OperationInfo* operationInfo);

该函数返回有关操作句柄的信息，填充数据结构operationInfo的下列字段：

• algorithm, mode, maxKeySize：传递给函数TEE_AllocateOperation的参数
• operationClass：描述操作种类，有TEE_OPERATION_CIPHER、TEE_OPERATION_MAC、TEE_OPERATION_AE、TEE_OPERATION_DIGEST、TEE_OPERATION_ASYMMETRIC_CIPHER、TEE_OPERATION_ASYMMETRIC_SIGNATURE、TEE_OPERATION_KEY_DERIVATION等
• keySize：如果操作中编有一个密钥，则为密钥实际大小。如果该操作需要多个密钥，则该值应该被设置为0
• requiredKeyUsage：一个位向量，描述了TEE_SetOperationKey、TEE_SetOperationKey2函数中使用对象时必须要存在的位。如果是摘要操作则设置为0。如果该类操作需要多个密钥，也设置为0。
• digestLength：对于MAC，AE或Digest，描述摘要或标记中的字节数
• handleState：描述操作当前状态的位向量，包含如下标志的组合或为0（没有合适的标志），TEE_HANDLE_FLAG_EXPECT_TWO_KEYS——如果算法期望设置两个密钥，则使用TEE_SetOperationKey2设置该标志位。只有当参数algorithm为TEE_ALG_AES_XTS时才会发生，此时keySize、requiredKeyUsage均被设置为0；TEE_HANDLE_FLAG_KEY_SET——如果操作密钥已经被设置，则设置该标志位。对于摘要操作该标志常设；TEE_HANDLE_FLAG_INITIALIZED——多阶段操作和摘要操作设置该标志位。

 

4、TEE_Result TEE_GetOperationInfoMultiple(TEE_OperationHandle operation, [outbuf] TEE_OperationInfoMultiple* operationInfoMultiple, size_t* operationSize);

该函数返回有关操作句柄的信息，填充数据结构operationInfoMultiple中的字段。

• operationState：如果该操作为激活状态，填充OPERATION_STATE_ACTIVE；如果为初始状态，填充OPERATION_STATE_INITIAL。
• numberOfKeys：设置为此操作所需要的密钥数，代表了后续的TEE_OperationInfoKey结构的个数，如果操作不需要密钥则设置为0。
• keyInformation： 

 

5、void TEE_ResetOperation(TEE_OperationHandle operation);

对于多阶段操作，该函数将操作重置为初始化之前、已设置密钥之后的初始状态。

可以在设置密钥后的任何时间和任何操作调用此函数，但是仅对多阶段操作（即对称密码，MAC，AE和摘要）有意义。 

当此类多阶段操作处于活动状态时，即已初始化但尚未成功完成时，则将操作重置为初始状态，不清除操作密钥。

 

6、TEE_Result TEE_SetOperationKey(TEE_OperationHandle operation, TEE_ObjectHandle key);

该函数编程一个操作的密钥，即它将某个操作关联一个密钥。

密钥材料从密钥对象句柄复制到操作中， 密钥设置之后，操作和密钥对象之间不再有任何联系。对象句柄可以被关闭或重置对，这不会影响操作。 

该复制的密钥材料一直存在，直到使用TEE_FreeOperation释放该操作或在该操作中设置了另一个密钥为止。此函数接受临时密钥对象和持久密钥对象上的句柄，密钥对象的类型和大小必须与操作的类型和大小兼容。

 

7、TEE_Result TEE_SetOperationKey2(TEE_OperationHandle operation, TEE_ObjectHandle key1,TEE_ObjectHandle key2);

该函数用两个密钥初始化一个现有的操作，只在TEE_ALG_AES_XTS算法中使用到。

该函数类似于TEE_SetOperationKey，除了设置了两个密钥。key1和key2必须同时是NULL，或同时为非NULL。

 

8、void TEE_CopyOperation(TEE_OperationHandle dstOperation,TEE_OperationHandle srcOperation);

该函数将操作状态从源操作句柄拷贝到目的操作句柄，同时拷贝源操作句柄的密钥材料。

 

 

消息摘要函数

1、void TEE_DigestUpdate(TEE_OperationHandle operation, [inbuf] void* chunk, size_t chunkSize);

该函数积累消息数据以进行哈希处理，消息数据不必是块对齐的。

 

2、TEE_Result TEE_DigestDoFinal(TEE_OperationHandle operation, [inbuf] void* chunk, size_t chunkLen, [outbuf] void* hash, size_t* hashLen);

该消息完成消息摘要操作并生成消息哈希。之后，“消息摘要”操作将重置为初始状态，并且可以重复使用。

 

 

对称密码函数

这些函数定义了执行对称密码操作（例如AES）的方式，涵盖分组密码和流密码。

1、void TEE_CipherInit(TEE_OperationHandle operation, [inbuf] void* IV, size_t IVLen);

该函数启动对称密码操作，操作必须关联一个密钥。

 

2、TEE_Result TEE_CipherUpdate(TEE_OperationHandle operation, [inbuf] void* srcData, size_t srcLen, [outbuf] void* destData, size_t* destLen);

该函数用来加密或解密输入数据，输入数据不必是块大小的倍数，除非对此函数的一个或多个调用提供了足够的输入数据，否则不会生成任何输出。

 

3、TEE_Result TEE_CipherDoFinal(TEE_OperationHandle operation, [inbuf] void* srcData, size_t srcLen, [outbufopt] void* destData, size_t* destLen);

完成密码操作，处理以前未通过调用TEE_CipherUpdate函数处理的数据以及insrcData中提供的数据。随后操作句柄可以重用或重新初始化。

 

 

MAC函数

这些函数用于执行MAC（消息身份验证代码）操作，例如HMAC或AES-CMAC操作。 

1、void TEE_MACInit(TEE_OperationHandle operation, [inbuf] void* IV, size_t IVLen);

该函数初始化一个MAC操作，操作必须关联一个密钥。如果MAC算法不需要IV，则忽略IV、IVLen参数。

 

2、void TEE_MACUpdate(TEE_OperationHandle operation, [inbuf] void* chunk, size_t chunkSize);

该函数积累用于MAC计算的数据。输入数据不必是块大小的倍数，随后可以继续调用该函数。

 

3、TEE_Result TEE_MACComputeFinal(TEE_OperationHandle operation, [inbuf] void* message, size_t messageLen, [outbuf] void* mac, size_t*macLen);

该函数用最后一条消息完成MAC操作，然后计算MAC。之后，可以重复使用操作句柄或使用新的密钥重新初始化操作句柄。

 

4、TEE_Result TEE_MACCompareFinal(TEE_OperationHandle operation, [inbuf] void* message, size_t messageLen, [inbuf] void* mac, size_t macLen);

完成MAC操作并将MAC与传递给函数的缓冲区进行比较。之后，可以重复使用操作句柄或使用新的密钥对其进行初始化。

该操作必须处于活动状态，随后移至初始状态。

 

 

认证加密函数

这些函数用于身份验证加密操作，如TEE_ALG_AES_CCM和TEE_ALG_AES_GCM算法。

1、TEE_Result TEE_AEInit(TEE_OperationHandle operation, [inbuf] void* nonce, size_tnonceLen, uint32_t tagLen, uint32_t AADLen, uint32_t payloadLen);

 该函数初始化身份验证加密操作。

 

2、void TEE_AEUpdateAAD(TEE_OperationHandle operation, [inbuf] void* AADdata, size_t AADdataLen);

该函数向AE操作提供新的附加身份验证数据（AAD）。

 

3、TEE_Result TEE_AEUpdate(TEE_OperationHandle operation, [inbuf] void* srcData, size_t srcLen, [outbuf] void* destData, size_t*destLen);

该函数积累用于身份验证加密操作的数据。

 

4、TEE_Result TEE_AEEncryptFinal(TEE_OperationHandle operation, [inbuf] void* srcData, size_t srcLen, [outbuf] void* destData, size_t* destLen, [outbuf] void* tag,  size_t* tagLen);

该函数处理先前调用TEE_AEUpdate函数尚未处理的数据以及insrcData中提供的数据，它完成AE操作并计算标签。

操作句柄可以重用或新初始化。

 

5、TEE_Result TEE_AEDecryptFinal(TEE_OperationHandle operation, [inbuf] void* srcData, size_t srcLen, [outbuf] void* destData, size_t* destLen, [in] void* tag, size_t tagLen);

该函数处理先前调用TEE_AEUpdate函数尚未处理的数据以及insrcData中提供的数据，它完成AE操作并将计算出的标签与参数tag中提供的标签进行比较。

 

 

非对称密码函数

这些函数使用非对称算法，摘要签名和签名验证来加密和解密数据。注意，非对称加密始终是“单阶段”，这与始终是“多阶段”的对称密码不同。

1、TEE_Result TEE_AsymmetricEncrypt(TEE_OperationHandle operation, [in] TEE_Attribute* params, uint32_t paramCount, [inbuf] void* srcData, size_tsrcLen, [outbuf] void* destData, size_t* destLen);

TEE_Result TEE_AsymmetricDecrypt(TEE_OperationHandle operation, [in] TEE_Attribute* params, uint32_t paramCount, [inbuf] void* srcData, size_t srcLen, [outbuf] void* destData, size_t* destLen);

TEE_AsymmetricEncrypt函数在非对称操作中加密消息，TEE_AsymmetricDecrypt用于解密。这两个函数仅能调用下列算法的操作：TEE_ALG_RSAES_PKCS1_V1_5、

TEE_ALG_RSAES_PKCS1_OAEP_MGF1_SHA1、TEE_ALG_RSAES_PKCS1_OAEP_MGF1_SHA224、TEE_ALG_RSAES_PKCS1_OAEP_MGF1_SHA256、TEE_ALG_RSAES_PKCS1_OAEP_MGF1_SHA384、

TEE_ALG_RSAES_PKCS1_OAEP_MGF1_SHA512、TEE_ALG_RSA_NOPAD

 

2、TEE_Result TEE_AsymmetricSignDigest(TEE_OperationHandle operation, [in] TEE_Attribute* params, uint32_t paramCount, [inbuf] void* digest, size_t digestLen, [outbuf] void* signature, size_t* signatureLen);

该函数在非对称操作中对消息摘要进行签名。注意只能对已经散列的消息进行签名。

如果在算法中指定了哈希算法，则参数digestLen应该等于此哈希算法的摘要长度。

 

3、TEE_Result TEE_AsymmetricVerifyDigest(TEE_OperationHandle operation, [in] TEE_Attribute* params, uint32_t paramCount, [inbuf] void* digest, size_t digestLen, [inbuf] void* signature, size_t signatureLen);

该函数在非对称操作中验证消息摘要签名。

 

 

密钥派生函数

1、void TEE_DeriveKey(TEE_OperationHandle operation, [in] TEE_Attribute* params, uint32_t paramCount, TEE_ObjectHandle derivedKey);

 

 

随机数生成函数

1、void TEE_GenerateRandom([out] void* randomBuffer, size_t randomBufferLen);

该函数用于生成一个随机数。

 

 

 

加密算法规范

本节指定了加解密操作API支持的加密算法，密钥类型和密钥部分。注意，对于“ NOPAD”对称算法，TA负责执行填充。

算法标识符列表：

算法标识符数据结构：

Bits	Function	Values
Bits[31:28]	指定算法类别，决定哪些加密函数可以被调用	0x1：块加密 0x3：MAC 0x4：AE 0x5：摘要 0x6：非对称加密 0x7：非对称签名 0x8：密钥派生 0xA：对象句柄 （算法标识符该域不等于0xA，对象标识符该域为0xA）
Bits[27:25]	保留	0x0
Bit[24]	对象类型密钥对指示符	如果是算法标识符，这里为0。 如果是对象标识符，密钥对对象为1，否则为0。
Bits[23:20]	定义MGF用于RSA OAEP的内部哈希	如果bits[19:16]指示使用MGF，则这里指定摘要模式，否则为0。
Bits[19:16]	指示算法是否使用MGF	如果算法使用MGF则为1，否则为0。
Bits[15:12]	为非对称签名算法定义消息摘要	如果bits[31:28]是0x7，且bits[7:0]是0x42，则是ECC算法。 密钥材料指定曲线类型，算法ID指定需求的hash大小：   0x1：SHA-1，0x2：SHA-224，0x3：SHA-256，0x4：SHA-384，0x5：SHA-512 否则，该域定义摘要模式：   0x1: MD5，0x2: SHA-1，0x3: SHA-224，0x4: SHA-256，0x5: SHA-384，0x6: SHA-512
Bits[11:8]	可以指定链模式或填充模式
Bits[7:0]	识别基本的主要算法	0x00：通用密钥对象 0x01：MD5 0x02：SHA-1 0x03：SHA-224 0x04：SHA-256 0x05：SHA-384 0x06：SHA-512 0x10：AES 0x11：DES 0x13：DES3 0x30：RSA 0x31：DSA 0x32：DH 0xBE：非法对象 0xBF：无合适的算法