Asymmetric Algorithm Operation APIs

This section describes the functions and specification restrictions of security device management APIs, including device and session management, random number generation, and private key access control.

Asymmetric algorithm operation 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_ExternalVerify_ECC(void *hSessionHandle, unsigned int uiAlgID, ECCrefPublicKey *pucPublicKey, unsigned char *pucDataInput, unsigned int uiInputLength, ECCSignature *pucSignature);
int SDF_InternalSign_ECC(void *hSessionHandle, unsigned int uiISKIndex, unsigned char *pucData, unsigned int uiDataLength, ECCSignature *pucSignature);
int SDF_InternalVerify_ECC(void *hSessionHandle, unsigned int uiISKIndex, unsigned char *pucData, unsigned int uiDataLength, ECCSignature *pucSignature);
int SDF_ExternalEncrypt_ECC(void *hSessionHandle, unsigned int uiAlgID, ECCrefPublicKey *pucPublicKey, unsigned char *pucData, unsigned int uiDataLength, ECCCipher *pucEncature);

User-defined APIs

Verify ECC signature using the external ECC public key.

int SDF_ExternalSign_ECC(void *hSessionHandle, unsigned int uiAlgID, ECCrefPrivateKey *pucPrivateKey, unsigned char *pucData, unsigned int uiDataLength, ECCSignature *pucSignature);

**Table 1** Parameter description
Parameter	Description
hSessionHandle[in]	Handle of the session established with the device.
uiAlgID[in]	Algorithm identifier, which specifies the ECC algorithm to be used. No restriction is imposed.
pucPrivateKey[in]	Structure of the external ECC private key. The key length cannot exceed 256 bits.
pucData[in]	Pointer to the buffer for storing the externally input data.
uiDataLength[in]	Length of the input data, which is fixed at 32 bytes.
pucSignature[out]	Pointer to the buffer for storing the input signature value (the length of the encryption result buffer is greater than or equal to the length of the input data plaintext).

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

Decrypt data using the external ECC private key.

int SDF_ExternalDecrypt_ECC(void *hSessionHandle, unsigned int uiAlgID, ECCrefPrivateKey *pucPrivateKey, ECCCipher *pucEncData, unsigned char *pucData, unsigned int *puiDataLength);

**Table 3** Parameter description
Parameter	Description
hSessionHandle[in]	Handle of the session established with the device.
uiAlgID[in]	Algorithm identifier, which specifies the ECC algorithm to be used. No restriction is imposed.
pucPrivateKey[in]	Structure of the external ECC private key. The key length cannot exceed 256 bits.
pucEncData[in]	Pointer to the buffer for storing the externally input data ciphertext. The data length cannot exceed 20 KB.
pucData[out]	Pointer to the buffer for storing the decryption result.
puiDataLength[out]	Length of the decryption result. The input value cannot exceed 500 KB and is greater than or equal to the length of the input data ciphertext.

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

Encrypt data using the internal ECC public key.

int SDF_InternalEncrypt_ECC(void *hSessionHandle, unsigned int uiISKIndex, unsigned char *pucData, unsigned int uiDataLength, ECCCipher *pucEncData);

**Table 5** Parameter description
Parameter	Description
hSessionHandle[in]	Handle of the session established with the device.
uiISKIndex[in]	Internal key index. The value ranges from 0 to 1000.
pucData[in]	Pointer to the buffer for storing the input data.
uiDataLength[in]	Length of the input data, which cannot exceed 20 KB.
pucEncData[out]	Pointer to the buffer for storing the output data ciphertext (the length of the encryption result buffer is greater than or equal to the length of the input data plaintext).

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

Decrypt data using the internal ECC private key.

int SDF_InternalDecrypt_ECC(void *hSessionHandle, unsigned int uiISKIndex, unsigned int ECCKeyType, ECCCipher *pucEncData, unsigned char *pucData, unsigned int *puiDataLength);

**Table 7** Parameter description
Parameter	Description
hSessionHandle[in]	Handle of the session established with the device.
uiISKIndex[in]	Internal key index. The value ranges from 0 to 1000.
ECCKeyType[in]	Internal key type. SGD_SM2_3 indicates the encryption private key, and SGD_SM2_1 indicates the signature private key.
pucEncData[in]	Pointer to the buffer for storing the externally input data ciphertext. The data length cannot exceed 20 KB.
pucData[out]	Pointer to the buffer for storing the decryption result.
puiDataLength[out]	Length of the decryption result. The input value cannot exceed 500 KB and is greater than or equal to the length of the input data ciphertext.

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

Specification Restrictions

The length of the externally input ECC public key can only be 256 bits.
The input data for signature verification is the hash value of the data to be signed. The data length cannot exceed 32 bytes.
The length of the data to be encrypted or decrypted cannot exceed 20 KB. The length of the decryption result cannot exceed 500 KB.

Parent topic: API Description