Documentation
Rate This Document
Findability
Accuracy
Completeness
Readability
SubmitClose

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 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 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
ta_cpu_set:0,2-4,6
    • workers indicates the number of TEE worker threads that the current device pre-applies for. The valid value ranges from 0 to 99. 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.

    • ta_cpu_set specifies the CPU cores to which the TA is 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).

      Spaces between numbers and separators are allowed and will be ignored during parsing. The valid values of the CPU core IDs are the first 32 CPU cores of each NUMA node. If the value is invalid or contains invalid characters, core binding fails and the default core binding policy is used. By default, the first half of the valid CPU cores are bound.

  • 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
    1. 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.
    2. No error is returned if the same index is successfully called for multiple times.
    3. If the permission fails to be obtained due to 500 consecutive incorrect password inputs, the system will delete the permission for accessing the key.
    4. 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