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

  

  To close the session opened by ECM_OpenSession, use the SDF_CloseSession API.

• 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

• Restore factory settings.

  int ECM_FactoryReset();

  Table 15 Return values

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

  

  After factory settings are restored, the ECM password is deleted. You need to create a new password when using the ECM again.

• Import a key in plaintext to the device.

  int ECM_ImportKeyPair_ECC(void* hSessionHandle, unsigned int uiKeyIndex, unsigned char *pucPassword, unsigned int uiPwdLength, ECCrefPublicKey* pucPublicKey, ECCrefPrivateKey* pucPrivateKey);

  Table 16 Parameter description

  Parameter	Description
  void *hSessionHandle[in]	Session handle.
  unsigned int uiKeyIndex[in]	Index of the internal key.
  unsigned char *prePassword[in]	Key password.
  unsigned int prePasswordLen[in]	Password length.
  ECCrefPublicKey* pucPublicKey[in]	Public key structure of the device internal key.
  ECCrefPrivateKey* pucPrivateKey[in]	Private key structure of the device internal key.

  Table 17 Return values

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

  

  1. This API imports the plaintext ECC public and private key structures input by a user to the cryptographic module. The public and private key pairs must match. Otherwise, a failure message is returned.

  2. The key password must meet the strength requirements. For details, see Special Specifications.

  3. Keys with the same index cannot be imported repeatedly.

• Import a KEK in plaintext.

  int ECM_ImportKEK(void* hSessionHandle, unsigned int uiKeyIndex, unsigned char *pucPassword, unsigned int uiPwdLength, unsigned char *KEKBuf, unsigned int KEKLen);

  Table 18 Parameter description

  Parameter	Description
  void *hSessionHandle[in]	Session handle.
  unsigned int uiKeyIndex[in]	Index of the internal key.
  unsigned char *prePassword[in]	Key password.
  unsigned int prePasswordLen[in]	Password length.
  unsigned int *KEKBuf[in]	Imported KEK content.
  unsigned int KEKLen[in]	Length of the imported KEK (16 bytes).

  Table 19 Return values

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

  

  1. The length of plaintext KEKs input by users is fixed at 16 bytes.

  2. The key password must meet the strength requirements. For details, see Special Specifications.

  3. Keys with the same index cannot be imported repeatedly.

• Import a device internal key in the digital envelope format.

  int ECM_ImportKeyWithEnvelop(void *hSessionHandle, unsigned int uiKeyIndex, unsigned char *pucPassword, unsigned int pucPasswordLen, ECCEnvelopedKey *pucEnvelopKey);

  Table 20 Parameter description

  Parameter	Description
  void *hSessionHandle[in]	Session handle.
  unsigned int uiKeyIndex[in]	Index of the internal key to be imported.
  unsigned char *pucPassword[in]	Key password.
  unsigned int pucPasswordLen[in]	Password length.
  ECCEnvelopedKey *pucEnvelopKey[in]	Input parameter for importing a digital envelope. The digital envelope must be encrypted using the public key corresponding to key 0 of the device.

  Table 21 Return values

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

  

  1. This API decrypts the digital envelope input by a user using the private key corresponding to key 0 and imports the decrypted digital envelope to the cryptographic module as the key content at the specified index.

  2. The key password must meet the strength requirements. For details, see Special Specifications.

  3. Keys with the same index cannot be imported repeatedly. If a key corresponding to the index already exists, the import fails.

  Export a device internal key in the digital envelope format.

  int ECM_ExportKeyWithEnvelop(void *hSessionHandle, unsigned int uiKeyIndex, unsignedchar*pucPassword, unsigned int pucPasswordLen, ECCrefPublicKey *pucPublicKey, ECCEnvelopedKey *pucEnvelopKey);

  Table 22 Parameter description

  Parameter	Description
  void *hSessionHandle[in]	Session handle.
  unsigned int uiKeyIndex[in]	Index of the internal key to be exported.
  unsigned char *prePassword[in]	Password of the internal key to be exported.
  unsigned int prePasswordLen[in]	Password length.
  ECCrefPublicKey* pucPublicKey[in]	Public key structure for encrypting the digital envelope.
  ECCEnvelopedKey *pucEnvelopKey[out]	Exported digital envelope.

  Table 23 Return values

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

  

  Before exporting a digital envelope, check whether the entered password matches the specified index. If so, use the input public key to encrypt and generate the digital envelope. If the key corresponding to the index does not exist on the device, a failure message is returned.

  Check whether the ECM password exists.

  int ECM_QueryECMPasswd(void *hSessionHandle);

  Table 24 Parameter description

  Parameter	Description
  void *hSessionHandle[in]	Session handle.

  Table 25 Return values

  Return Value	Description
  0	The password does not exist.
  1	The password exists.

  Check whether the entered ECM password is correct.

  int ECM_CheckECMPasswd(void *hSessionHandle, char *input_ecm_passwd, size_t input_ecm_passwd_len);

  Table 26 Parameter description

  Parameter	Description
  void *hSessionHandle[in]	Session handle.
  char *input_ecm_passwd[in]	Entered ECM password.
  size_t input_ecm_passwd_len[in]	Length of the entered ECM password.

  Table 27 Return values

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

  Change the ECM password.

  int ECM_ChangeECMPasswd(void *hSessionHandle, char *new_password, size_t new_password_len);

  Table 28 Parameter description

  Parameter	Description
  void *hSessionHandle[in]	Session handle.
  char *new_password[in]	New ECM password.
  size_t new_password_len[in]	Length of the new ECM password.

  Table 29 Return values

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

  

  When you use the ECM tool for the first time, an ECM password is required. To enhance security, you are advised to change the password periodically.

  The password must meet the following requirements:

  1. The password must contain at least two types of the following characters:
     • Lowercase letters
     • Uppercase letters
     • Digits
     • Special characters: `~!@#$%^&*()-_=+\|[{}];:'",<.>/? and spaces
  2. The length ranges from 8 bytes to 128 bytes.