SEManager

android.device
Class SEManager

java.lang.Object
  android.device.SEManager

public class SEManager
extends java.lang.Object
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:

You can obtain an instance of this class by calling SEManager.
SEManager manager = new SEManager();
initialize the security processor with open.
delete the key on the specified index before download new key with deleteKey.
download Keys in security processor RAM with downloadKey.
using the downloaded key to encrypt the Data encryptData.
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.

android.device Class SEManager

S_OK

ENOTSUP_CMD

ELENGTH_CMD

ESEPARATOR_CMD

ESEPARATORLEN_CMD

EHEAD_CMD

ECRC16_DATA

EMSG_MAC

EMSG_FORMAT

ENOTSUP_ALGORITHM

ENOTSUP_FORMAT

ENOTSUP_MODE

EKEYS_RDORINIT

EKEYSNO_NOTFOUND

EKEYSNO_OVERRANGE

EKEYS_DOWNLOAD

EKEYS_NOTDOWNLOAD

EKEYS_OUTOFSPACE

EKEYS_EXISTS

EENCRYPTKEYS_NOTDOWLOAD

ENOTSUP_SEPUSE

ENOTSUP_KEYSLENGTH

ERESERVED_0X1D

ENOTSUP_PINBLOCK_FORMAT

EUSERNAME_LENGTH

EUSERNAME_VALUE

EUSER_PINBLOCK_LENGTH

EUSER_PINBLOCK_VALUE

EPINBLOCK_CHAR

SEManager

open

close

getFirmwareVersion

getStatus

downloadKey

downloadKeyDukpt

deleteKey

encryptData

decryptData

getPinBlock

getPinBlockEx

getPinBlockEx

generateRandomData

enableSuspend

setSuspendTimeout

calculateMACOfDUKPTExtend

encryptWithPEK

android.device
Class SEManager