Key Management Tool APIs

To help users customize key management, the key management tool APIs are provided.

• Create a session user.

  int ECM_OpenSession(void *hDeviceHandle, void **phSessionHandle);

  Table 1 Parameter description

  Parameter	Description
  hDeviceHandle[in]	Handle of the device that has been started.
  phSessionHandle[out]	Handle of the session established with the cryptographic device.

  Table 2 Return values

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

• Create a device internal key and set the password.

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

  Table 3 Parameter description

  Parameter	Description
  hSessionHandle[in]	Handle of the session established with the device.
  uiKeyIndex[in]	Index value of the private key stored in the cryptographic device. The value includes the key type and index.
  pucPassword[in]	Password for accessing the private key.
  uiPwdLength[in]	Length of the password for accessing the private key. The value ranges from 8 to 128 bytes.

  Table 4 Return values

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

  

  • uiKeyIndex[in]: 32-bit internal key index information, with the high-order 12 bits indicating the key type and the low-order 20 bits indicating the key index.

    The key types include:

    • SDF_SM2_SIGN: signature key pair
    • SDF_SM2_ENC: encryption key pair
    • SDF_SM4: SM4 encryption key
  • A user key includes an encryption key pair and a signature key pair. Therefore, this API needs to be called twice to generate a user key.

• Delete a specified internal key.

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

  Table 5 Parameter description

  Parameter	Description
  hSessionHandle[in]	Handle of the session established with the device.
  uiKeyIndex[in]	Index value of the private key stored in the cryptographic device. The value includes the key type and index.

  Table 6 Return values

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

• Query internal key status.

  int ECM_QueryKey(void *hSessionHandle, unsigned int uiKeyIndex, unsigned int *uiKeyInfo);

  Table 7 Parameter description

  Parameter	Description
  hSessionHandle[in]	Handle of the session established with the device.
  uiKeyIndex[in]	Index value of the private key stored in the cryptographic device. The value includes the key type and index.
  uiKeyInfo[out]	Internal key information of the cryptographic device. 0: Keys exist. Other values: Keys do not exist.

  Table 8 Return values

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

• Change the password for accessing a specified private key.

  int ECM_ChangePassword(void *hSessionHandle, unsigned int uiKeyIndex, unsigned char *prePassword, unsigned int prePasswordLen, unsigned char *newPassword, unsigned int newPasswordLen);

  Table 9 Parameter description

  Parameter	Description
  hSessionHandle[in]	Handle of the session established with the device.
  uiKeyIndex[in]	Index value of the private key stored in the cryptographic device. The value includes the key type and index.
  prePassword[in]	Current password for accessing the private key.
  prePasswordLen[in]	Length of the current password for accessing the private key. The value ranges from 8 to 128 bytes.
  newPassword[in]	New password for accessing the private key.
  newPasswordLen[in]	Length of the new password for accessing the private key. The value ranges from 8 to 128 bytes.

  Table 10 Return values

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

• Export the corresponding internal key.

  int ECM_ExportKey(void *hSessionHandle, unsigned int uiKeyIndex, unsigned char *keyFileBuffer, unsigned int *keyBufferLength, unsigned char *keySalt);

  Table 11 Parameter description

  Parameter	Description
  hSessionHandle[in]	Handle of the session established with the device.
  uiKeyIndex[in]	Index value of the private key stored in the cryptographic device. The value includes the key type and index.
  keyFileBuffer[out]	Pointer to the buffer for storing the exported internal key ciphertext.
  keyBufferLength[out]	Length of the exported internal key ciphertext.
  keySalt[in]	Encryption salt value. The length of the value cannot exceed 16 bytes.

  Table 12 Return values

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

• Import a key to the specified index.

  int ECM_ImportKey(void *hSessionHandle, unsigned int uiKeyIndex, unsigned char *keyFileBuffer, unsigned int keyBufferLength, unsigned char *keySalt);

  Table 13 Parameter description

  Parameter	Description
  hSessionHandle[in]	Handle of the session established with the device.
  uiKeyIndex[in]	Index value of the private key stored in the cryptographic device. The value includes the key type and index.
  keyFileBuffer[in]	Pointer to the buffer for storing the key ciphertext to be imported.
  keyBufferLength[out]	Length of the key ciphertext to be imported.
  keySalt[in]	Decryption salt value. The length of the value cannot exceed 16 bytes.

  Table 14 Return values

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

• Set the path of the application that can access internal keys.

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

  Table 15 Parameter description

  Parameter	Description
  hSessionHandle[in]	Handle of the session established with the device.
  uiKeyIndex[in]	Index value of the private key stored in the cryptographic device. The value includes the key type and index.
  pucAccessInfo[in]	Pointer to the buffer for storing the hash value of the application allowed for access. The length is fixed at 32 bytes.
  pucPassword[out]	Password for accessing the private key.
  uiPwdLength[in]	Length of the password for accessing the private key. The value ranges from 8 to 128 bytes.

  Table 16 Return values

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

  

  The CA hash value is calculated as follows: SHA256 (CA path||User name). That is, perform the SHA256 calculation on the concatenated value of the CA path and user name. Note that the user name must be 256 bytes. If the user name is shorter than 256 bytes, pad it with zeros.

• Delete the path of the application that can access internal keys.

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

  Table 17 Parameter description

  Parameter	Description
  hSessionHandle[in]	Handle of the session established with the device.
  uiKeyIndex[in]	Index value of the private key stored in the cryptographic device. The value includes the key type and index.
  pucAccessInfo[in]	Pointer to the buffer for storing the hash value of the application allowed for access. The length is fixed at 32 bytes.
  pucPassword[out]	Password for accessing the private key.
  uiPwdLength[in]	Length of the password for accessing the private key. The value ranges from 8 to 128 bytes.

  Table 18 Return values

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

• Restore factory settings.

  int ECM_FactoryReset();

  Table 19 Return values

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