SEManager

##
android.device
Class SEManager

    java.lang.Object
      android.device.SEManager

    public class SEManager

extends java.lang.Object

The SEManager class is used to initialize and control the security processor hardware.

To control the security processor hardware with this class, use the following steps:

1. You can obtain an instance of this class by calling `SEManager`.

   SEManager manager = new SEManager();

2. initialize the security processor with `open`.
3. delete the key on the specified index before download new key with `deleteKey`.
4. download Keys in security processor RAM with `downloadKey`.
5. using the downloaded key to encrypt the Data `encryptData`.
6. Call `close` to close the security processor.

For more information about the smart card reader, read SEManager sample.

Nested Class Summary
`static interface` | `SEManager.OperationPedInputListener` The application has to implement the appropriate listener.
`static interface` | `SEManager.PedInputListener` The application has to implement the appropriate listener.

Field Summary
`static int` | `ECRC16_DATA` Data crc16 error.
`static int` | `EENCRYPTKEYS_NOTDOWLOAD` The encryption key for the key is not downloaded.
`static int` | `EHEAD_CMD` Command head (CB) error.
`static int` | `EKEYS_DOWNLOAD` Keys download.
`static int` | `EKEYS_EXISTS` Keys exists or cant't be overwrite.
`static int` | `EKEYS_NOTDOWNLOAD` Keys not download.
`static int` | `EKEYS_OUTOFSPACE` Keys out of space.
`static int` | `EKEYS_RDORINIT` Keys not ready or init.
`static int` | `EKEYSNO_NOTFOUND` Keys number not found.
`static int` | `EKEYSNO_OVERRANGE` Keys number out of range.
`static int` | `ELENGTH_CMD` Command length error.
`static int` | `EMSG_FORMAT` Message format error.
`static int` | `EMSG_MAC` Message mac error.
`static int` | `ENOTSUP_ALGORITHM` Unsupported algorithm.
`static int` | `ENOTSUP_CMD` Unsupported command.
`static int` | `ENOTSUP_FORMAT` Unsupported format.
`static int` | `ENOTSUP_KEYSLENGTH` Unsupported keys length.
`static int` | `ENOTSUP_MODE` Unsupported mode.
`static int` | `ENOTSUP_PINBLOCK_FORMAT` Unsupported pinblock format.
`static int` | `ENOTSUP_SEPUSE` Keys unsupported specified use.
`static int` | `EPINBLOCK_CHAR` Pinblock char error.
`static int` | `ERESERVED_0X1D` Parameters temporarily reserved.
`static int` | `ESEPARATOR_CMD` Command separator error.
`static int` | `ESEPARATORLEN_CMD` Command separator length error.
`static int` | `EUSER_PINBLOCK_LENGTH` User pinblock length error.
`static int` | `EUSER_PINBLOCK_VALUE` User pinblock value error.
`static int` | `EUSERNAME_LENGTH` Username length error.
`static int` | `EUSERNAME_VALUE` Username value error.
`static int` | `S_OK` Command execute Success

Constructor Summary
`SEManager()` The SEManager class is used to initialize and control the security processor hardware.

Method Summary
`int` | `open()` Open security processor.
`int` | `close()` Close security processor.
`int` | `decryptData(int KeyUsage, int KeyNo, int Algorithm, byte[] StartValue, int StartValueLen, int PaddingChar, byte[] DecryptData, int DecryptDataLen, byte[] ResponseData, byte[] ResLen)` Decryption data.
`int` | `deleteKey(int KeyUsage, int KeyNo, byte[] ResponseData, byte[] ResLen)` Delete keys.
`int` | `downloadKey(int KeyUsage, int KeyNo, int ParentKeyNo, byte[] KeyData, int KeyDataLen, byte[] ResponseData, byte[] ResLen)` Download Keys in security processor RAM.
`int` | `downloadKeyDukpt(int keyType, byte[] Bdk, int BdkLen, byte[] Ksn, int KsnLen, byte[] bsIpek, int bsIpekLength)` Download Dukpt keys in security processor RAM. Keys length is 16 bytes. Bdk and Ipek, pick one of two.
`int` | `enableSuspend(int enable, byte[] ResponseData, byte[] ResLen)` Enable the security processor timeout before automatic suspension.
`int` | `encryptData(int KeyUsage, int KeyNo, int Algorithm, byte[] StartValue, int StartValueLen, int PaddingChar, byte[] EncryptData, int EncryptDataLen, byte[] ResponseData, byte[] ResLen)` Encryption data.
`int` | `generateRandomData(byte[] ResponseData, byte[] ResLen)` Generate a 8 bytes random number.
`int` | `getFirmwareVersion(byte[] ResponseData, byte[] ResLen)` Get security processor firmware version.
`int` | `getPinBlock(int KeyUsage, int PINKeyNo, byte[] CustomerData, int CustomerDataLen, java.lang.String message, long timeOut, SEManager.PedInputListener listener)` Get the pin block.
`int` | `getPinBlockEx(android.os.Bundle bundle, SEManager.PedInputListener listener)` Get the pin block.
`int` | `getPinBlockEx(int KeyUsage, int PINKeyNo, byte[] CustomerData, int CustomerDataLen, java.lang.String message, long timeOut, java.lang.String supportPinLen, SEManager.PedInputListener listener)` Get the pin block.
`int` | `getStatus(byte[] ResponseData, byte[] ResLen)` Get security processor hardware status.
`int` | `setSuspendTimeout(int timeout, byte[] ResponseData, byte[] ResLen)` Allows to set the security processor timeout before automatic suspension.
`int` | `calculateMACOfDUKPTExtend(int keySetNum, byte[] rawData, int rawDataLen, byte[] outData, int[] outDataLen, byte[] outKsn, int[] KsnLen)` Calculate MAC use dukpt. Only supports Android 8.1.
`int` | `encryptWithPEK(int keyType, int keyType, byte[] rawData, int rawDataLen, byte[] outData, int[] outDataLen, byte[] outKsn, int[] KsnLen)` Data encryption use dukpt. Only supports Android 8.1.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

FIELD DETAIL

### S_OK

    public static final int S_OK

  command execute Success

  See Also:
    Constant Field Values

### ENOTSUP_CMD

    public static final int ENOTSUP_CMD

  unsupported command

  See Also:
    Constant Field Values

### ELENGTH_CMD

    public static final int ELENGTH_CMD

  command length error

  See Also:
    Constant Field Values

### ESEPARATOR_CMD

    public static final int ESEPARATOR_CMD

  command separator error

  See Also:
    Constant Field Values

### ESEPARATORLEN_CMD

    public static final int ESEPARATORLEN_CMD

  command separator length error

  See Also:
    Constant Field Values

### EHEAD_CMD

    public static final int EHEAD_CMD

  command head (CB) error

  See Also:
    Constant Field Values

### ECRC16_DATA

    public static final int ECRC16_DATA

  data crc16 error

  See Also:
    Constant Field Values

### EMSG_MAC

    public static final int EMSG_MAC

  message mac error

  See Also:
    Constant Field Values

### EMSG_FORMAT

    public static final int EMSG_FORMAT

  message format error

  See Also:
    Constant Field Values

### ENOTSUP_ALGORITHM

    public static final int ENOTSUP_ALGORITHM

  unsupported algorithm

  See Also:
    Constant Field Values

### ENOTSUP_FORMAT

    public static final int ENOTSUP_FORMAT

  unsupported format

  See Also:
    Constant Field Values

### ENOTSUP_MODE

    public static final int ENOTSUP_MODE

  unsupported mode

  See Also:
    Constant Field Values

### EKEYS_RDORINIT

    public static final int EKEYS_RDORINIT

  keys not ready or init

  See Also:
    Constant Field Values

### EKEYSNO_NOTFOUND

    public static final int EKEYSNO_NOTFOUND

  keys number not found

  See Also:
    Constant Field Values

### EKEYSNO_OVERRANGE

    public static final int EKEYSNO_OVERRANGE

  keys number out of range

  See Also:
    Constant Field Values

### EKEYS_DOWNLOAD

    public static final int EKEYS_DOWNLOAD

  keys download

  See Also:
    Constant Field Values

### EKEYS_NOTDOWNLOAD

    public static final int EKEYS_NOTDOWNLOAD

  keys not download

  See Also:
    Constant Field Values

### EKEYS_OUTOFSPACE

    public static final int EKEYS_OUTOFSPACE

  keys out of space

  See Also:
    Constant Field Values

### EKEYS_EXISTS

    public static final int EKEYS_EXISTS

  keys exists or cant't be overwrite

  See Also:
    Constant Field Values

### EENCRYPTKEYS_NOTDOWLOAD

    public static final int EENCRYPTKEYS_NOTDOWLOAD

  The encryption key for the key is not downloaded.

  See Also:
    Constant Field Values

### ENOTSUP_SEPUSE

    public static final int ENOTSUP_SEPUSE

  keys unsupported specified use

  See Also:
    Constant Field Values

### ENOTSUP_KEYSLENGTH

    public static final int ENOTSUP_KEYSLENGTH

  unsupported keys length

  See Also:
    Constant Field Values

### ERESERVED_0X1D

    public static final int ERESERVED_0X1D

  Reserved

  See Also:
    Constant Field Values

### ENOTSUP_PINBLOCK_FORMAT

    public static final int ENOTSUP_PINBLOCK_FORMAT

  unsupported pinblock format

  See Also:
    Constant Field Values

### EUSERNAME_LENGTH

    public static final int EUSERNAME_LENGTH

  username length error

  See Also:
    Constant Field Values

### EUSERNAME_VALUE

    public static final int EUSERNAME_VALUE

  username value error

  See Also:
    Constant Field Values

### EUSER_PINBLOCK_LENGTH

    public static final int EUSER_PINBLOCK_LENGTH

  user pinblock length error

  See Also:
    Constant Field Values

### EUSER_PINBLOCK_VALUE

    public static final int EUSER_PINBLOCK_VALUE

  user pinblock value error

  See Also:
    Constant Field Values

### EPINBLOCK_CHAR

    public static final int EPINBLOCK_CHAR

  pinblock char error

  See Also:
    Constant Field Values

Constructor Detail

### SEManager

    public SEManager()

Method Detail

### open

    public int open()

  Open security processor.

  Parameters:
    none
  Returns:
    0 if successful, negative number if failed.

### close

    public int close()

  Close security processor.

  Parameters:
    none
  Returns:
    0 if successful, negative number if failed.

### getFirmwareVersion

    public int getFirmwareVersion(byte[] ResponseData,
                                  byte[] ResLen)

  Get security processor firmware version.

  Parameters:
    `ResponseData` - Output data, processor response data.
    `ResLen` - Output data, processor response data length.
  Returns:
    Error Code. See Constant Field Values.

### getStatus

    public int getStatus(byte[] ResponseData,
                         byte[] ResLen)

  Get security processor hardware status.

  Parameters:
    `ResponseData` - Output data, 5 Bytes device status:
    Byte[0] : maxium storage num of keys we support(The sum of all keys)
    Byte[1] : used for mag strip info encryption(TDK)
    Byte[2] : used for counting PIN keys
    Byte[3] : num of MAC keys
    Byte[4] : num of Master keys
    `ResLen` - Output data, length of ResponseData, 5 Bytes.
  Returns:
    Error Code. See Constant Field Values.

### downloadKey

    public int downloadKey(int KeyUsage,
                           int KeyNo,
                           int ParentKeyNo,
                           byte[] KeyData,
                           int KeyDataLen,
                           byte[] ResponseData,
                           byte[] ResLen)

  Download keys in security processor RAM. Keys length is 8 bytes (DES), 16 bytes or 24 Bytes(3DES).

  Parameters:
    `KeyUsage` - Input data, Key Usage:
    0x01 : used for Mag strip info encryption(TDK)
    0x02 : used for PIN encryption
    0x03 : used for MAC calculation
    0x04 : Parent(Master) key
    0x05 : Reserved
    0x06 : Reserved
    0x07 : used for message transportation encryption
    `KeyNo` - Input data, Key number,value is 0 to 149.
    `ParentKeyNo` - Input data, parent Key Number. When DownloadKey is used to load parent key, this parameter can be ignore. Parent(Master) key have no parent key.
    `KeyData` - Input data, key data, this parameter have 8 bytes(DES), 16 bytes or 24 bytes(3DES).
    `KeyDataLen` - Input data, Key Data length.
    `ResponseData` - Output data, security processor response data, output KCV (with clear key encryption 8 0x00 return value, get first 4 bytes).
    `ResLen` - Output data, security processor response data length.
  Returns:
    Error Code. See Constant Field Values.
  Note:Parent keys or encryption keys unsupported 8 bytes length, that must be 16 bytes.

### downloadKeyDukpt

    public int downloadKeyDukpt(int keyType,
                                byte[] Bdk,
                                int BdkLen,
                                byte[] Ksn,
                                int KsnLen,
                                byte[] bsIpek,
                                int bsIpekLength)

  Download Dukpt keys in security processor RAM. Keys length is 16 bytes. Bdk and Ipek, pick one of two.

  Parameters:
    `keyType` - Input data, key usage:
    0x01 : MSR_KEY
    0x03 : PIN_KEY
    `Bdk` - Input data, Bdk.
    `BdkLen` - The Bdk data length.
    `Ksn` - Input data, Ksn.
    `KsnLen` - The Ksn data length.
    `bsIpek` - Input data, Ipek.
    `bsIpekLength` - The bsIpek data length.
  Returns:
    Error Code. See Constant Field Values.
  Note:Parent keys or encryption keys unsupported 8 bytes length, that must be 16 bytes.

### deleteKey

    public int deleteKey(int KeyUsage,
                         int KeyNo,
                         byte[] ResponseData,
                         byte[] ResLen)

  Delete keys.

  Parameters:
    `KeyUsage` - Input data, Key Usage;
    0x01 : used for Mag strip info encryption(TDK)
    0x02 : used for PIN encryption
    0x03 : used for MAC calculation
    0x04 : Parent(Master) key
    0x05 : Reserved
    0x06 : Reserved
    0x07 : used for message transportation encryption
    `KeyNo` - Input data, Key index, value is 0 to 149.
    `ResponseData` - Output data, security processor response data, this function return data is NULL.
    `ResLen` - Output data, security processor response data length, this function return data length is 0.
  Returns:
    Error Code. See Constant Field Values.

### encryptData

    public int encryptData(int KeyUsage,
                           int KeyNo,
                           int Algorithm,
                           byte[] StartValue,
                           int StartValueLen,
                           int PaddingChar,
                           byte[] EncryptData,
                           int EncryptDataLen,
                           byte[] ResponseData,
                           byte[] ResLen)

  Encryption data.

  Parameters:
    `KeyUsage` - Input data, Key Usage:
    0x01 : used for Mag strip info encryption(TDK)
    0x02 : used for PIN encryption
    0x03 : used for MAC calculation
    0x04 : Parent(Master) key
    0x05 : Reserved
    0x06 : Reserved
    0x07 : used for message transportation encryption
    `KeyNo` - Input data, Key index, value is 0 to 149.
    `Algorithm` - Input data, algorithm define:
    0x01 : ECB
    0x02 : CBC
    `StartValue` - Input data, initialization vector, this value is NULL(Algorithm = 0x01) or 8 bytes (Algorithm = 0x02).
    `StartValueLen` - Input data, initialization vector length.
    `PaddingChar` - Input data, padding character, value is 0x0 to 0xF.
    `EncryptData` - Input data, encryption data, length is 0 to 128 bytes.
    `EncryptDataLen` - Input data, encryption data length.
    `ResponseData` - Output data, encrypted data return form security processor.
    `ResLen` - Output data, security processor response data length.
  Returns:
    Error Code. See Constant Field Values.

### decryptData

    public int decryptData(int KeyUsage,
                           int KeyNo,
                           int Algorithm,
                           byte[] StartValue,
                           int StartValueLen,
                           int PaddingChar,
                           byte[] DecryptData,
                           int DecryptDataLen,
                           byte[] ResponseData,
                           byte[] ResLen)

  Decryption data.

  Parameters:
    `KeyUsage` - Input data, key usage:
    0x01 : used for Mag strip info encryption(TDK)
    0x02 : used for PIN encryption
    0x03 : used for MAC calculation
    0x04 : Parent(Master) key
    0x05 : Reserved
    0x06 : Reserved
    0x07 : used for message transportation encryption
    `KeyNo` - Input data, Key index is 0 to 149.
    `Algorithm` - Input data, Algorithm define:
    0x01 : ECB
    0x02 : CBC
    `StartValue` - Input data, initialization vector, this value is NULL(Algorithm = 0x01) or 8 bytes (Algorithm = 0x02).
    `StartValueLen` - Input data, initialization vector length.
    `PaddingChar` - Input data, padding character, value is 0x0 to 0xF.
    `DecryptData` - Input data, dencryption data, 0 to 128 Bytes.
    `DecryptDataLen` - Input data, dencryption data length.
    `ResponseData` - Output data, dencrypted data returned from security processor.
    `ResLen` - Output data, security processor response data length.
  Returns:
    Error Code. See Constant Field Values.

### getPinBlock

    public int getPinBlock(int KeyUsage,
                           int PINKeyNo,
                           byte[] CustomerData,
                           int CustomerDataLen,
                           java.lang.String message,
                           long timeOut,
                           SEManager.PedInputListener listener)

  Get the pin block.

  Parameters:
    `KeyUsage` - Input data, key usage:
    0x01 : used for Mag strip info encryption(TDK)
    0x02 : used for PIN encryption
    0x03 : used for MAC calculation
    0x04 : Parent(Master) key
    0x05 : Reserved
    0x06 : Reserved
    0x07 : used for message transportation encryption
    `PINKeyNo` - Input data, Key index is 0 to 149.
    `CustomerData` - Input data, ASCII format Customer account, 0 to 24 Bytes.
    `CustomerDataLen` - Input data, the length of CustomerData.
    `message` - Enter prompt information.
    `timeOut` - Set the input key timeout.
    `listener` - The `PedInputListener` that will be called when a input key event is fired.
  Returns:
    0 if successful, negative number if fail.

### getPinBlockEx

    public int getPinBlockEx(int KeyUsage,
                             int PINKeyNo,
                             byte[] CustomerData,
                             int CustomerDataLen,
                             java.lang.String message,
                             long timeOut,
                             java.lang.String supportPinLen,
                             SEManager.PedInputListener listener)

  Get the pin block.

  Parameters:
    `KeyUsage` - Input data, key usage:
    0x01 : used for Mag strip info encryption(TDK)
    0x02 : used for PIN encryption
    0x03 : used for MAC calculation
    0x04 : Parent(Master) key
    0x05 : Reserved
    0x06 : Reserved
    0x07 : used for message transportation encryption
    `PINKeyNo` - Input data, Key index is 0 to 149.
    `CustomerData` - Input data, ASCII format Customer account, 0 to 24 Bytes.
    `CustomerDataLen` - Input data, the length of CustomerData.
    `message` - Enter prompt information.
    `timeOut` - Set the input key timeout.
    `supportPinLen` - Set the input key support length, default format: "0,4,6,8,10,12".
    `listener` - The `PedInputListener` that will be called when a input key event is fired.
  Returns:
    0 if successful, negative number if fail.

### getPinBlockEx

    public int getPinBlockEx(android.os.Bundle bundle,
                             SEManager.PedInputListener listener)

  Get the pin block.

  Parameters:
    `bundle` - Is a Bundle obejct. The bundle support parameters are as follows:

    Key | Type | Remark
    cardNo | String | Card number.
    sound | boolean | Play the key prompt tone.
    timeOutMS | long | Timeout.
    supportPinLen | String | Password length supported.
    FullScreen | boolean | Full screen or half screen display.
    ShowLine | boolean | Show lines.
    numberText | StringArray | Display type of number.
    cancelText | String | Cancel key display content.
    deleteText | String | Delete key display.
    okText | String | Confirm key display content.
    title | String | Title display content.
    message | String | Prompt display content.
    textSize | ShortArray | Set text size, top, bottom, left and right margins, background color.
    inputBySP | boolean | Touch screen input mode, true indicates TP control

    inputType

    int

    Type of input online / offline / Admin.
    0x00:onLine
    0x01:admin_A
    0x02:admin_B
    0x03:offLine_plain
    0x04:offLine_cipher

    bypass | boolean | Bypass mode supports to exit directly by pressing the confirm key without input.
    checkAdminMode | int | Use verification input type in admin mode. 0x01:verify password input 0x02:set password for the first time 0x03:set password to confirm input

    KeyUsage

    int

    Use of secret key use of pinpad 0x02.
    0x01:used for magnetic stripe information encryption (TDK)
    0x02:for pin encryption
    0x03:for Mac calculation
    0x04:parent (Master) key
    0x05:reserved
    0x06:reserved
    0x07:used for message transmission encryption

    PINKeyNo | int | Key index, values 0 to 149.

    pinAlgMode

    int

    Define using encryption algorithms.
    0x00:mk/sk
    0x01:fixed key
    0x02:format4 key
    0x03/0x04:des or sm4
    0x10:dukpt

    `listener` - The `PedInputListener` that will be called when a input key event is fired. It can also be used IInputActionListener, but need import android.os.IInputActionListener.
  Returns:
    0 if successful, negative number if fail.

### generateRandomData

    public int generateRandomData(byte[] ResponseData,
                                  byte[] ResLen)

  Generate a 8 bytes random number.

  Parameters:
    `ResponseData` - Output data, to store the generated 8 bytes random number.
    `ResLen` - Bytes indicating the length of response data.
  Returns:
    0 if successful, negative number if fail.

### enableSuspend

    public int enableSuspend(int enable,
                             byte[] ResponseData,
                             byte[] ResLen)

  Enable the security processor timeout before automatic suspension.

  Parameters:
    `enable` - Indicates to enable or to disable the security processor suspend.
    `ResponseData` - Output data, security processor response data.
    `ResLen` - Output data, security processor response data length.
  Returns:
    0 if successful, negative number if fail.

### setSuspendTimeout

    public int setSuspendTimeout(int timeout,
                                 byte[] ResponseData,
                                 byte[] ResLen)

  Allow to set the security processor timeout before automatic suspension.

  Parameters:
    `timeout` - The value of the timeout (in seconds) or 0 for infinite.
    `ResponseData` - Output data, security processor response data.
    `ResLen` - Output data, security processor response data length.
  Returns:
    0 if successful, negative number if fail.

### calculateMACOfDUKPTExtend

    public int calculateMACOfDUKPTExtend(int keySetNum,
    				     byte[] rawData,
    				     int rawDataLen,
    				     byte[] outData,
    				     int[] outDataLen,
    				     byte[] outKsn,
    				     int[] KsnLen)

  Calculate MAC use dukpt. Only supports Android 8.1.

  Parameters:
    `keySetNum` - Key index of dukpt, range from 0x01 to 0x04.
    `rawData` - Input data, plain data.
    `rawDataLen` - Input data length.
    `outData` - Output data, MAC data.
    `outDataLen` - Output data, MAC data length.
    `outKsn` - Output data, Ksn.
    `KsnLen` - Output data, Ksn length.
  Returns:
    0 if successful, negative number if fail.

### encryptWithPEK

    public int encryptWithPEK(int keyType,
    			  int keySetNum,
    			  byte[] rawData,
    			  int rawDataLen,
    			  byte[] outData,
    			  int[] outDataLen,
    			  byte[] outKsn,
    			  int[] KsnLen)

  Data encryption use dukpt. Only supports Android 8.1.

  Parameters:
    `keyType` - Dukpt key type, set 0x03 for data encryption.
    `keySetNum` - Key index of dukpt, range from 0x01 to 0x04.
    `rawData` - Input data, plain data.
    `rawDataLen` - Input data length.
    `outData` - Output data, encrypted data.
    `outDataLen` - Output data, encrypted data length.
    `outKsn` - Output data, Ksn.
    `KsnLen` - Output data, Ksn length.
  Returns:
    0 if successful, negative number if fail.