密码运算API(GP Internal API)

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

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

密码运算API(GP Internal API)

 

 

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

密码运算API(GP Internal API)

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

 

 

数据结构

密码运算API(GP Internal API)

 

  

 

通用运算函数 

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

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:无合适的算法

 

 

 

上一篇:Contains函数应用 IEqualityComparer 示例


下一篇:Mapped Statements collection already contains value for