Key Management APIs

This section describes the functions and specification restrictions of key management APIs and their extended APIs.

Key management APIs comply with GM/T 0018-2012. For details about the API parameters and return values, see GM/T 0018-2012. For details about the algorithm identifier description, see GM/T 0006-2012.

int SDF_ExportSignPublicKey_ECC(void *hSessionHandle, unsigned int uiKeyIndex, ECCrefPublicKey *pucPublicKey);
int SDF_ExportEncPublicKey_ECC(void *hSessionHandle, unsigned int uiKeyIndex, ECCrefPublicKey *pucPublicKey);
int SDF_GenerateKeyPair_ECC(void *hSessionHandle, unsigned int uiAlgID, unsigned int uiKeyBits, ECCrefPublicKey *pucPublicKey, ECCrefPrivateKey *pucPrivateKey);
int SDF_GenerateKeyWithIPK_ECC(void *hSessionHandle, unsigned int uiIPKIndex, unsigned int uiKeyBits, ECCCipher *pucKey, void **phKeyHandle);
int SDF_GenerateKeyWithEPK_ECC(void *hSessionHandle, unsigned int uiKeyBits, unsigned int uiAlgID, ECCrefPublicKey *pucPublicKey, ECCCipher *pucKey, void **phKeyHandle);
int SDF_ImportKeyWithISK_ECC(void *hSessionHandle, unsigned int uiISKIndex, ECCCipher *pucKey, void **phKeyHandle);
int SDF_ExchangeDigitEnvelopeBaseOnECC(void *hSessionHandle, unsigned int uiKeyIndex, unsigned int uiAlgID, ECCrefPublicKey *pucPublicKey, ECCCipher *pucEncDataIn, ECCCipher *pucEncDataOut);
int SDF_GenerateAgreementDataWithECC(void *hSessionHandle, unsigned int uiISKIndex, unsigned int uiKeyBits, unsigned char *pucSponsorID, unsigned int uiSponsorIDLength, ECCrefPublicKey *pucSponsorPublicKey, ECCrefPublicKey *pucSponsorTmpPublicKey, void **phAgreementHandle);
int SDF_GenerateKeyWithECC(void *hSessionHandle, unsigned char *pucResponseID, unsigned int uiResponseIDLength, ECCrefPublicKey *pucResponsePublicKey, ECCrefPublicKey *pucResponseTmpPublicKey, void *hAgreementHandle, void **phKeyHandle);
int SDF_GenerateAgreementDataAndKeyWithECC(void *hSessionHandle, unsigned int uiISKIndex, unsigned int uiKeyBits, unsigned char *pucResponseID, unsigned int uiResponseIDLength, unsigned char *pucSponsorID, unsigned int uiSponsorIDLength, ECCrefPublicKey *pucSponsorPublicKey, ECCrefPublicKey *pucSponsorTmpPublicKey, ECCrefPublicKey *pucResponsePublicKey, ECCrefPublicKey *pucResponseTmpPublicKey, void **phKeyHandle);
int SDF_ExchangeDigitEnvelopeBaseOnECC(void *hSessionHandle, unsigned int uiKeyIndex, unsigned int uiAlgID, ECCrefPublicKey *pucPublicKey, ECCCipher *pucEncDataIn, ECCCipher *pucEncDataOut);
int SDF_GenerateKeyWithKEK(void *hSessionHandle, unsigned int uiKeyBits, unsigned int uiAlgID, unsigned int uiKEKIndex, unsigned char *pucKey, unsigned int *puiKeyLength, void **phKeyHandle);
int SDF_ImportKeyWithKEK(void *hSessionHandle, unsigned int uiAlgID, unsigned int uiKEKIndex, unsigned char *pucKey, unsigned int puiKeyLength, void **phKeyHandle);
int SDF_DestroyKey(void *hSessionHandle, void *hKeyHandle);

Specification Restrictions

SDF_GenerateKeyPair_ECC supports only SGD_SM2_3, SGD_SM2_1, and SGD_SM2.
Only SM2 ECC keys are supported. Therefore, the public key length can only be 256 bits, that is, the bits values in the public key and private key structures can only be 256.
The length of the generated session key can only be 128 bits.
SDF_GenerateKeyWithEPK_ECC supports only SGD_SM2_3 and SGD_SM2_1.
The ciphertext length of the ECCCipher structure is less than or equal to 20 KB.
The length of a negotiated key ranges from 8 to 128 bits, and the user ID length cannot exceed 64 bytes.
SDF_ExchangeDigitEnvelopeBaseOnECC supports only SGD_SM2_3.
The index of a KEK ranges from 1 to 1000. The KEK API supports only SGD_SM4_CBC and SGD_SM4_ECB. The length of the input ciphertext cannot exceed 256 bytes.
The maximum number of key handles is 1000.
SDF_DestroyKey automatically releases hKeyHandle. You do not need to release it again.

The electronic code book (ECB) mode is insecure. The cipher block chaining (CBC) mode is recommended as it can be used with the message authentication code (MAC) to ensure the integrity and confidentiality of the transport layer cryptography protocol (TLCP).

User-defined APIs

An extended API, which is used to set a session key into a session key handle.

int SDF_ImportKey(void *hSessionHandle, unsigned char *pucKey, unsigned int uiKeyLength, void **phKeyHandle)

**Table 1** Parameter description
Parameter	Description
hSessionHandle[in]	Handle of the session established with the device.
pucKey[in]	Pointer to the buffer for storing the input session key plaintext.
uiKeyLength[in]	Length of the entered session key (less than or equal to 256 bytes).
phKeyHandle[out]	Pointer to the buffer for storing the output session handle.

**Table 2** Return values
Return Value	Description
0	Success
Other values	Failure: returning an error code

An extended API, which can be used to open or initialize a device.

int SDF_OpenDeviceWithConf(void **phDeviceHandle, const char* configFile)

**Table 3** Parameter description
Parameter	Description
phDeviceHandle[in]	Handle of the session established with the device.
configFile[in]	Pointer to the configuration file. If the value is NULL, the default configuration is used. If the specified configuration file does not exist or cannot be opened, the function returns a failure.

**Table 4** Return values
Return Value	Description
0	Success
Other values	Failure: returning an error code

The following is an example of the configuration file format.

workers:0 
timeout:1000

workers indicates the number of TEE worker threads that the current device pre-applies for. The valid value ranges from 0 to 3. The default value is 0. If the value is invalid, the system sets the value to 0.
timeout indicates the time (in ms) that a TEE worker thread waits before going to sleep if no new task is received. The value must be greater than 0. The default value is 1000.
Other invalid fields will be ignored. If multiple valid values are configured for workers or timeout, the last one takes effect.

Parent topic: API Description