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-2023. For details about the API parameters and return values, see GM/T 0018-2023. For details about the algorithm identifier description, see GM/T 0006-2023.

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_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 2048. 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 session key handles is 300000.
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 key 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: 16
timeout: 1000
ta_cpu_set: 0,2-4,6 
ca_cpu_set: 0-15
selftest:true
key_access:true

workers indicates the number of TEE worker threads that the current device applies for. The valid value ranges from 1 to 32. The default value is 16. If the value is invalid, the system sets the value to 16.
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.
ta_cpu_set specifies the CPU cores to which a TA is bound. By default, CPU cores 16 to 31 on NUMA node 0 are bound. The value of this configuration item can be a comma-separated list of CPU core IDs. Each element can be in one of the following formats:
- Individual CPU core: a non-negative integer, indicating a single CPU core (for example, 0, 1, or 5).
- CPU core range: two integers separated by a hyphen (-), indicating a continuous CPU core range (including both ends. For example, 0-3 indicates CPU cores 0, 1, 2, and 3).
- Hybrid format: any combination of individual CPU cores and core ranges (for example, 0,2-4,6,8-10).
ca_cpu_set specifies the CPU cores bound to a CA. For details about the format, see ta_cpu_set. By default, CPU cores 0 to 15 on NUMA node 0 are bound.
selftest indicates whether to perform a self-test. The default value is false. For details, see Algorithm Self-Test in section "Special Specifications."
key_access indicates whether to obtain the SM4 key usage permission by calling SDF_GetKEKAccessRight. The default value is true. If this parameter is set to false, the SM4 key can be used without calling the API. Set this parameter as required. The affected APIs include SDF_GenerateKeyWithKEK and SDF_ImportKeyWithKEK.

Spaces between numbers and separators are allowed for the core-binding configuration items and will be ignored during parsing. Invalid values and characters will cause core binding failures. In this case, the default core binding policy is used.

If configFile is NULL, the default configuration file /etc/sdf.conf will be parsed. If the default configuration file does not exist, all configurations will be set to the system default values.

Obtaining the permission for accessing the KEK stored at the specified index in the cryptographic device.

int SDF_GetKEKAccessRight(void *hSessionHandle, unsigned int uiKeyIndex, unsigned char *pucPassword,unsigned int uiPwdLength);

**Table 5** Parameter description
Parameter	Description
void *hSessionHandle[in]	Handle of the session established with the cryptographic device.
unsigned int uiKeyIndex[in]	Index of the KEK stored in the cryptographic device.
unsigned char *pucPassword[in]	Password for accessing the KEK.
unsigned int uiPwdLength[in]	Length of the password for accessing the KEK.

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

In this document, the key index of the cryptographic device ranges from 1 to n. n is limited by the actual storage capacity. Its default value is 2048.
No error is returned if the same index is successfully called for multiple times.
If a non-root user fails to obtain the permission due to 500 consecutive incorrect password inputs, the system will delete the permission for accessing the key.
The length of the password for accessing the KEK must be at least 8 bytes.

Revoking the access of the key stored at the specified index in the cryptographic device.

int SDF_ReleasePrivateKeyAccessRight(void *hSessionHandle, unsigned int uiKeyIndex);

**Table 7** Parameter description
Parameter	Description
void *hSessionHandle[in]	Handle of the session established with the cryptographic device.
unsigned int uiKeyIndex[in]	Index of the key stored in the cryptographic device.

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

Parent topic: API Description