HSMDevice (CloudPOSSDK)

All Superinterfaces:

Device
```
public interface HSMDevice
extends Device
```
The HSMDevice interface represents an interface for interacting with a Hardware Security Module (HSM). This interface provides essential security services related to the HSM. An instance of HSMDevice is obtained as follows:
```
 HSMDevice hsmDevice = (HSMDevice) POSTerminal.getInstance().getDevice("com.cloudpos.device.hsm");
 
```
The HSM device supports concurrent use by multiple applications. However, some operations may require exclusive access.
To use this device, applications must request permission:
```
 <uses-permission android:name="android.permission.CLOUDPOS_SAFE_MODULE" /> 
```
See Also:

Device

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`CERT_FORMAT_DER` DER format
`static int`	`CERT_FORMAT_PEM` PEM format
`static int`	`CERT_TYPE_APP_ROOT` Terminal application root certificate
`static int`	`CERT_TYPE_COMM_ROOT` Terminal SSL communication root certificate
`static int`	`CERT_TYPE_KEYLOADER_ROOT` Terminal Keyloader root certificate
`static int`	`CERT_TYPE_PUBLIC_KEY` Terminal public key certificate
`static int`	`CERT_TYPE_TERMINAL_OWNER` Terminal owner root certificate

Method Summary

All Methods Instance Methods Abstract Methods Deprecated Methods
Modifier and Type	Method and Description
`byte[]`	`decrypt(int algorithm, java.lang.String aliasPrivateKey, byte[] bufCipher)` Decrypts data using the specified private key.
`boolean`	`deleteCertificate(int certType, java.lang.String alias)` Deletes a specified certificate from the HSM.
`boolean`	`deleteKeyPair(java.lang.String aliasPrivateKey)` Deletes a key pair from the HSM based on the provided alias.
`byte[]`	`encrypt(int algorithm, java.lang.String aliasPrivateKey, byte[] bufPlain)` Encrypts data using the specified private key.
`byte[]`	`generateCSR(java.lang.String aliasPrivateKey, javax.security.auth.x500.X500Principal subject)` Generates a Certificate Signing Request (CSR) for a given private key.
`void`	`generateKeyPair(java.lang.String aliasPrivateKey, int algorithm, int keySize)` Requests the HSM to generate a new key pair.
`byte[]`	`generateRandom(int length)` Generates a random buffer from the HSM.
`byte[]`	`getCertificate(int certType, java.lang.String alias, int dataFormat)` Retrieves the specified certificate from the HSM.
`java.lang.String`	`getEncryptedUniqueCode(java.lang.String uniqueCode, java.lang.String randomFactor)` Retrieves the encrypted unique code, a feature primarily used in China.
`long`	`getFreeSpace()` Determines the available free space within the HSM.
`boolean`	`injectPublicKeyCertificate(java.lang.String alias, java.lang.String aliasPrivateKey, byte[] bufCert, int dataFormat)` Injects a public key certificate associated with an existing key pair into the HSM.
`boolean`	`injectRootCertificate(int certType, java.lang.String alias, byte[] bufCert, int dataFormat)` Injects root certificates into the HSM.
`boolean`	`isKeyExist(int keyID)` Checks if a specified key exists in the HSM.
`boolean`	`isKeyExist(int keyID, int algorithm)` Deprecated. Use `isKeyExist(int)` instead.
`boolean`	`isTampered()` Checks if the HSM is tampered with.
`byte[]`	`keyDecrypt_v1(int keyID, int algorithm, int mode, byte[] byteData, byte[] IV)` Decrypts data using a specified key stored in the HSM (version 1).
`int`	`keyDecrypt(int keyID, int algorithm, int mode, byte[] byteData, byte[] IV)` Deprecated. Use `keyDecrypt_v1(int, int, int, byte[], byte[])` instead.
`byte[]`	`keyEncrypt_v1(int keyID, int algorithm, int mode, byte[] byteData, byte[] IV)` Encrypts data using a specified key stored in the HSM (version 1).
`int`	`keyEncrypt(int keyID, int algorithm, int mode, byte[] byteData, byte[] IV)` Deprecated. Use `keyEncrypt_v1(int, int, int, byte[], byte[])` instead.
`void`	`open(int logicalID)` Opens the hardware security module for use.
`java.lang.String[]`	`queryCertificates(int certType)` Queries the HSM for certificates of a specific type.
`boolean`	`resetSensorStatus()` Resets the sensor status, useful for small batteries.
`int`	`updateKey(int keyID, int algorithm, byte[] byteData)` Updates a key in the HSM.
`int`	`updateSM4Key(int keyID, byte[] keyBuffer, byte[] signature)` Updates an SM4 key.

Methods inherited from interface com.cloudpos.Device
cancelRequest, close, getFailCount, getUsageCount, open

- Field Detail
  - CERT_FORMAT_PEM
```
static final int CERT_FORMAT_PEM
```
    PEM format
    
    See Also:
    
    Constant Field Values
  - CERT_FORMAT_DER
```
static final int CERT_FORMAT_DER
```
    DER format
    
    See Also:
    
    Constant Field Values
  - CERT_TYPE_TERMINAL_OWNER
```
static final int CERT_TYPE_TERMINAL_OWNER
```
    Terminal owner root certificate
    
    See Also:
    
    Constant Field Values
  - CERT_TYPE_PUBLIC_KEY
```
static final int CERT_TYPE_PUBLIC_KEY
```
    Terminal public key certificate
    
    See Also:
    
    Constant Field Values
  - CERT_TYPE_APP_ROOT
```
static final int CERT_TYPE_APP_ROOT
```
    Terminal application root certificate
    
    See Also:
    
    Constant Field Values
  - CERT_TYPE_COMM_ROOT
```
static final int CERT_TYPE_COMM_ROOT
```
    Terminal SSL communication root certificate
    
    See Also:
    
    Constant Field Values
  - CERT_TYPE_KEYLOADER_ROOT
```
static final int CERT_TYPE_KEYLOADER_ROOT
```
    Terminal Keyloader root certificate
    
    See Also:
    
    Constant Field Values
- Method Detail
  - open
```
void open(int logicalID)
   throws DeviceException
```
    Opens the hardware security module for use.
    
    Parameters:
    
    logicalID - The logical ID of the HSM device.
    
    Throws:
    
    DeviceException - for standard reasons as documented in DeviceException。
  - isTampered
```
boolean isTampered()
            throws DeviceException
```
    Checks if the HSM is tampered with. The operation is not exclusive. The HSM with automatic protection will self-destruct to protect sensitive data in case of tampering.
    
    Returns:
    
    true if tampered, false otherwise.
    
    Throws:
    
    DeviceException - for standard reasons as documented in DeviceException.
  - generateRandom
```
byte[] generateRandom(int length)
               throws DeviceException
```
    Generates a random buffer from the HSM. The operation is not exclusive.
    
    Parameters:
    
    length - The length of the buffer (less than 64).
    
    Returns:
    
    Random buffer.
    
    Throws:
    
    DeviceException - for standard reasons as documented in DeviceException.
  - generateKeyPair
```
void generateKeyPair(java.lang.String aliasPrivateKey,
                     int algorithm,
                     int keySize)
              throws DeviceException
```
    Requests the HSM to generate a new key pair. This operation requires exclusive access to the HSM.
    
    Parameters:
    
    aliasPrivateKey - Alias for the private key.
    
    algorithm - The algorithm for the key pair (currently supports "RSA").
    
    keySize - Bit size of the key (currently supports 2048 bits).
    
    Throws:
    
    DeviceException - for standard reasons as documented in DeviceException.
  - injectPublicKeyCertificate
```
boolean injectPublicKeyCertificate(java.lang.String alias,
                                   java.lang.String aliasPrivateKey,
                                   byte[] bufCert,
                                   int dataFormat)
                            throws DeviceException
```
    Injects a public key certificate associated with an existing key pair into the HSM. This operation requires exclusive access to the HSM.
    
    Parameters:
    
    alias - Alias for the certificate.
    
    aliasPrivateKey - Alias for the key pair, usually the private key's alias.
    
    bufCert - Certificate data.
    
    dataFormat - Format of the certificate data (currently only PEM format is supported).
    
    Returns:
    
    true if successful, false otherwise.
    
    Throws:
    
    DeviceException - for standard reasons as documented in DeviceException.
  - injectRootCertificate
```
boolean injectRootCertificate(int certType,
                              java.lang.String alias,
                              byte[] bufCert,
                              int dataFormat)
                       throws DeviceException
```
    Injects root certificates into the HSM. All certificates must be signed by the terminal's owner certificate. The keyUsage flag must be set as define:
    - CERT_TYPE_TERMINAL_OWNER certificate's keyUsage flag must be set as critical, and the KeyEncipherment, CertificateSign and CRLSign must be set, other flags are cleared.
    - CERT_TYPE_APP_ROOT certificate's keyUsage flag must be set as critical, and the DigitalSignature, CertificateSign must be set, other flags are cleared.
    - CERT_TYPE_COMM_ROOT certificate's keyUsage flag must be set as non-critical and DigitalSignature, KeyEncipherment, DataEncipherment must be set, other flags are cleared.
    - CERT_TYPE_KEYLOADER_ROOT certificate's keyUsage flag must be set as critical and NonRepudiation, CertificateSign must be set, other flags are cleared.
    This operation requires exclusive access to the HSM.
    Parameters:
    
    certType - Type of the certificate. CERT_TYPE_TERMINAL_OWNER, CERT_TYPE_APP_ROOT ,CERT_TYPE_COMM_ROOT or CERT_TYPE_KEYLOADER_ROOT.
    
    alias - Alias for the certificate.
    
    bufCert - Certificate data.
    
    dataFormat - Format of the certificate data (currently only PEM format （CERT_FORMAT_PEM）is supported).
    
    Returns:
    
    true if successful, false otherwise.
    
    Throws:
    
    DeviceException - for standard reasons as documented in DeviceException.
  - getCertificate
```
byte[] getCertificate(int certType,
                      java.lang.String alias,
                      int dataFormat)
               throws DeviceException
```
    Retrieves the specified certificate from the HSM. This operation does not require exclusive access.
    
    Parameters:
    
    certType - Type of the certificate (e.g., CERT_TYPE_PUBLIC_KEY, CERT_TYPE_TERMINAL_OWNER, CERT_TYPE_APP_ROOT , CERT_TYPE_COMM_ROOT or CERT_TYPE_KEYLOADER_ROOT).
    
    alias - Alias of the certificate.
    
    dataFormat - Format of the certificate data (currently only CERT_FORMAT_PEM is supported).
    
    Returns:
    
    Certificate data buffer.
    
    Throws:
    
    DeviceException - for standard reasons as documented in DeviceException.
  - deleteCertificate
```
boolean deleteCertificate(int certType,
                          java.lang.String alias)
                   throws DeviceException
```
    Deletes a specified certificate from the HSM. This operation requires exclusive access and cannot delete the OWNER certificate.
    
    Parameters:
    
    certType - Type of the certificate (e.g., CERT_TYPE_PUBLIC_KEY, CERT_TYPE_APP_ROOT , CERT_TYPE_COMM_ROOT or CERT_TYPE_KEYLOADER_ROOT).
    
    alias - Alias of the certificate.
    
    Returns:
    
    true if deletion is successful, false otherwise.
    
    Throws:
    
    DeviceException - for standard reasons as documented in DeviceException.
  - queryCertificates
```
java.lang.String[] queryCertificates(int certType)
                              throws DeviceException
```
    Queries the HSM for certificates of a specific type. This operation does not require exclusive access.
    
    Parameters:
    
    certType - Type of the certificates to query.
    
    Returns:
    
    Array of certificate aliases stored in the HSM.
    
    Throws:
    
    DeviceException - for standard reasons as documented in DeviceException.
  - deleteKeyPair
```
boolean deleteKeyPair(java.lang.String aliasPrivateKey)
               throws DeviceException
```
    Deletes a key pair from the HSM based on the provided alias. This operation requires exclusive access to the HSM.
    
    Parameters:
    
    aliasPrivateKey - Alias of the private key.
    
    Returns:
    
    true if successful, false otherwise.
    
    Throws:
    
    DeviceException - for standard reasons as documented in DeviceException.
  - generateCSR
```
byte[] generateCSR(java.lang.String aliasPrivateKey,
                   javax.security.auth.x500.X500Principal subject)
            throws DeviceException
```
    Generates a Certificate Signing Request (CSR) for a given private key. The operation is exclusive. Only the CN (Common Name) is extracted from the X500Principal subject parameter.
    
    Parameters:
    
    aliasPrivateKey - The alias of the private key.
    
    subject - X500Principal containing the subject information.
    
    Returns:
    
    PEM-formatted CSR buffer.
    
    Throws:
    
    DeviceException - for standard reasons as documented in DeviceException.
  - encrypt
```
byte[] encrypt(int algorithm,
               java.lang.String aliasPrivateKey,
               byte[] bufPlain)
        throws DeviceException
```
    Encrypts data using the specified private key. Padding data, if required, should be applied before calling this method. This operation does not require exclusive access.
    
    Parameters:
    
    algorithm - Encryption algorithm.
    
    aliasPrivateKey - Alias of the private key.
    
    bufPlain - Data buffer to encrypt.
    
    Returns:
    
    Encrypted data buffer.
    
    Throws:
    
    DeviceException - for standard reasons as documented in DeviceException.
  - decrypt
```
byte[] decrypt(int algorithm,
               java.lang.String aliasPrivateKey,
               byte[] bufCipher)
        throws DeviceException
```
    Decrypts data using the specified private key. Padding data, if required, should be applied before calling this method. This operation does not require exclusive access.
    
    Parameters:
    
    algorithm - Decryption algorithm.
    
    aliasPrivateKey - Alias of the private key.
    
    bufCipher - Data buffer to decrypt.
    
    Returns:
    
    Decrypted data buffer.
    
    Throws:
    
    DeviceException - for standard reasons as documented in DeviceException.
  - getFreeSpace
```
long getFreeSpace()
           throws DeviceException
```
    Determines the available free space within the HSM. This operation does not require exclusive access.
    
    Returns:
    
    The amount of free space in the HSM.
    
    Throws:
    
    DeviceException - for standard reasons as documented in DeviceException.
  - getEncryptedUniqueCode
```
java.lang.String getEncryptedUniqueCode(java.lang.String uniqueCode,
                                        java.lang.String randomFactor)
                                 throws DeviceException
```
    Retrieves the encrypted unique code, a feature primarily used in China. This operation does not require exclusive access.
    
    Parameters:
    
    uniqueCode - The unique code to be encrypted.
    
    randomFactor - A random factor for the encryption process.
    
    Returns:
    
    The encrypted unique code.
    
    Throws:
    
    DeviceException - for standard reasons as documented in DeviceException.
  - resetSensorStatus
```
boolean resetSensorStatus()
                   throws DeviceException
```
    Resets the sensor status, useful for small batteries. The operation is not exclusive.
    
    Returns:
    
    true if reset is successful, false otherwise.
    
    Throws:
    
    DeviceException - for standard reasons as documented in DeviceException.
  - updateKey
```
int updateKey(int keyID,
              int algorithm,
              byte[] byteData)
       throws DeviceException
```
    Updates a key in the HSM.
    
    Parameters:
    
    keyID - Key index (range 0-49, with 0-2 reserved, third-party apps should use 3-49).
    
    algorithm - Key type (SM4, DES, 3DES, or AES).
    
    byteData - Key data.
    
    Returns:
    
    Non-negative on success, negative on failure.
    
    Throws:
    
    DeviceException - for standard reasons as documented in DeviceException.
  - keyEncrypt
```
int keyEncrypt(int keyID,
               int algorithm,
               int mode,
               byte[] byteData,
               byte[] IV)
        throws DeviceException
```
    Deprecated. Use keyEncrypt_v1(int, int, int, byte[], byte[]) instead.
    
    Encrypts data using a specified key stored in the HSM. This method is deprecated and should be replaced with keyEncrypt_v1(int, int, int, byte[], byte[]).
    
    Parameters:
    
    keyID - Key index (range 0-49, with 0-2 reserved).
    
    algorithm - Encryption algorithm (e.g., SM4, DES, 3DES, AES).
    
    mode - Encryption mode (e.g., 0: ECB 1: CBC 2:CFB 3:OFB).
    
    byteData - Data to encrypt.
    
    IV - Initialization vector.
    
    Returns:
    
    Length of the encrypted data, or a negative value on failure.
    
    Throws:
    
    DeviceException - for standard reasons as documented in DeviceException.
  - keyEncrypt_v1
```
byte[] keyEncrypt_v1(int keyID,
                     int algorithm,
                     int mode,
                     byte[] byteData,
                     byte[] IV)
              throws DeviceException
```
    Encrypts data using a specified key stored in the HSM (version 1). This operation does not require exclusive access.
    
    Parameters:
    
    keyID - Key index (range 0-49, with 0-2 reserved).
    
    algorithm - Encryption algorithm (e.g., SM4, DES, 3DES, AES).
    
    mode - Encryption mode (e.g., 0: ECB 1: CBC 2:CFB 3:OFB).
    
    byteData - Data to encrypt.
    
    IV - Initialization vector.
    
    Returns:
    
    The encrypted data, or null on failure.
    
    Throws:
    
    DeviceException - for standard reasons as documented in DeviceException.
  - keyDecrypt
```
int keyDecrypt(int keyID,
               int algorithm,
               int mode,
               byte[] byteData,
               byte[] IV)
        throws DeviceException
```
    Deprecated. Use keyDecrypt_v1(int, int, int, byte[], byte[]) instead.
    
    Decrypts data using a specified key stored in the HSM. This method is deprecated and should be replaced with keyDecrypt_v1(int, int, int, byte[], byte[]).
    
    Parameters:
    
    keyID - Key index (range 0-49, with 0-2 reserved).
    
    algorithm - Decryption algorithm (e.g., SM4, DES, 3DES, AES).
    
    mode - Decryption mode (e.g., 0: ECB 1: CBC 2:CFB 3:OFB).
    
    byteData - Data to decrypt.
    
    IV - Initialization vector.
    
    Returns:
    
    Length of the decrypted data, or a negative value on failure.
    
    Throws:
    
    DeviceException - for standard reasons as documented in DeviceException.
  - keyDecrypt_v1
```
byte[] keyDecrypt_v1(int keyID,
                     int algorithm,
                     int mode,
                     byte[] byteData,
                     byte[] IV)
              throws DeviceException
```
    Decrypts data using a specified key stored in the HSM (version 1). This operation does not require exclusive access.
    
    Parameters:
    
    keyID - Key index (range 0-49, with 0-2 reserved).
    
    algorithm - Decryption algorithm (e.g., SM4, DES, 3DES, AES).
    
    mode - Decryption mode (e.g., 0: ECB 1: CBC 2:CFB 3:OFB).
    
    byteData - Data to decrypt.
    
    IV - Initialization vector.
    
    Returns:
    
    The decrypted data, or null on failure.
    
    Throws:
    
    DeviceException - for standard reasons as documented in DeviceException.
  - isKeyExist
```
boolean isKeyExist(int keyID,
                   int algorithm)
            throws DeviceException
```
    Deprecated. Use isKeyExist(int) instead.
    
    Checks if a specified key exists in the HSM. This method is deprecated and should be replaced with isKeyExist(int).
    
    Parameters:
    
    keyID - Key index (range 0-49, with 0-2 reserved).
    
    algorithm - Key type (e.g., SM4, DES, 3DES, AES).
    
    Returns:
    
    true if the key exists, false otherwise.
    
    Throws:
    
    DeviceException - for standard reasons as documented in DeviceException.
  - isKeyExist
```
boolean isKeyExist(int keyID)
            throws DeviceException
```
    Checks if a specified key exists in the HSM. This operation does not require exclusive access.
    
    Parameters:
    
    keyID - Key index (range 0-49, with 0-2 reserved).
    
    Returns:
    
    true if the key exists, false otherwise.
    
    Throws:
    
    DeviceException - for standard reasons as documented in DeviceException.
  - updateSM4Key
```
int updateSM4Key(int keyID,
                 byte[] keyBuffer,
                 byte[] signature)
          throws DeviceException
```
    Updates an SM4 key.
    
    Parameters:
    
    keyID - Key index (range 0-2).
    
    keyBuffer - Key data.
    
    signature - Signature data.
    
    Returns:
    
    Non-negative on success, negative on failure.
    
    Throws:
    
    DeviceException - for standard reasons as documented in DeviceException.

Interface HSMDevice

Field Summary

Method Summary

Methods inherited from interface com.cloudpos.Device

Field Detail

CERT_FORMAT_PEM

CERT_FORMAT_DER

CERT_TYPE_TERMINAL_OWNER

CERT_TYPE_PUBLIC_KEY

CERT_TYPE_APP_ROOT

CERT_TYPE_COMM_ROOT

CERT_TYPE_KEYLOADER_ROOT

Method Detail

open

isTampered

generateRandom

generateKeyPair

injectPublicKeyCertificate

injectRootCertificate

getCertificate

deleteCertificate

queryCertificates

deleteKeyPair

generateCSR

encrypt

decrypt

getFreeSpace

getEncryptedUniqueCode

resetSensorStatus

updateKey

keyEncrypt

keyEncrypt_v1

keyDecrypt

keyDecrypt_v1

isKeyExist

isKeyExist

updateSM4Key