KMS Library

AAR Ver.	Detail	Date	Release Version	BSP Ver.
v1.1.0	• Key check value method added • KBPK key type added.
v1.1.1	• Improved binding handling
v1.1.2	• DUKPT support added
v1.1.3	• TR31 support added
V1.1.4	• DUKPT Api set updated	07.10.2024	V1360

47KB

Token KMS Library Changelog.pdf

PDF

Open

Changelog

162KB

libTokenKMS_release_v1.1.4.aar

Open

libTokenKMS v1.1.4

Our terminals possess a secure processor and a secure memory implemented onboard. All kinds of key operations such as encryption, decryption, signing and more run on this secure processor. Fundamentally, KMS is a service that provides functions to developers for carrying out crypto operations on this secure hardware.

TokenKMS kms = new TokenKMS();
kms.init(context, new KMSWrapperInterface.InitCallbacks() {
    @Override
    public void onInitSuccess() {
        
    }
    @Override
    public void onInitFailed() {
    
    } 
});

Key Index

Key Index should be between 0 and 39

For DUKPT Keys index should be between 0 and 24

Different index must be used for each key.

Key Types

TOKENKMS_KEYTYPE_TMK -> Terminal Master Key TOKENKMS_KEYTYPE_KPK -> Key Protection Key (Key Encryption Key(KEK)) TOKENKMS_KEYTYPE_PIN -> PIN Key TOKENKMS_KEYTYPE_MAC -> MAC Key TOKENKMS_KEYTYPE_TDK TOKENKMS_KEYTYPE_KBPK -> Key Block Protection Key

Key Algorithms

TOKENKMS_KEY_ALG_TYPE_3DES
TOKENKMS_KEY_ALG_TYPE_AES

Protection Modes

TOKENKMS_PROTECTION_MODE_ECB
TOKENKMS_PROTECTION_MODE_CBC

Encryption/Decryption

int keyIndex Index of key that is going to be used in encryption and decryption byte[] dataArray Data to be encrypted or decrypted

byte[] IV Initialization Vector must be null for ECB

• Data Encryption ECB

byte[] encryptedData = kms.encryptData(keyIndex,dataArray,TOKENKMS_PROTECTION_MODE_ECB,IV);

• Data Decryption ECB

byte[] decryptedData = kms.decryptData(keyIndex,dataArray,TOKENKMS_PROTECTION_MODE_ECB,IV);

• Data Encryption CBC

byte[] encryptedData = kms.encryptData(keyIndex,dataArray,TOKENKMS_PROTECTION_MODE_CBC,IV);

• Data Decryption CBC

byte[] decryptedData = kms.decryptData(keyIndex,dataArray,TOKENKMS_PROTECTION_MODE_CBC,IV);

Key Injection

int keyIndex Index of Key that is going to be injected

int keyIndex_KEK Index of KEK(Key Encryption Key) that is going to be used for injection

byte[] encKeydata Encrypted key data

byte[] KCV Key Check Value

kms.injectKeybyKEK(keyIndex,keyIndex_KEK,TokenKMSKeyType,TokenKMSKeyAlgorithm ,encKeyData,KCV);

• Get Key Check Value

int keyIndex Index of Key to get Key check Value

int len Length of Key Check Value

byte[] keyCheckValue = kms.getKeyCheckValue(keyIndex,len);

Size of returning byte array is equal to len parameter

• Delete key

Note: You must use this function with try catch.

try {
    TokenUSDKManager.getInstance().kmsService.deleteKey(keyIndex)  
}catch (e: TokenKMSException){
    Log.i("", "$e")
}

• Check key exists

Throws exception if key does not exists.

try {
    kms.checkKeyExist(keyIndex)  
}catch (e: TokenKMSException){
    Log.i("", "$e")
}

• Delete ALL keys (NOT SUPPORTED ON 330TR)

kms.deleteAllKey();

DUKPT Methods

DUKPT Key Injection

int keyIndex Index of Key that is going to be injected

int keyIndex_KEK Index of KEK(Key Encryption Key) that is going to be used for injection

byte[] encKeydata Encrypted key data

byte[] KCV Key Check Value

byte[] ksn Key Serial Number

TokenKMSProtectionMode -> TOKENKMS_PROTECTION_MODE_ECB or TOKENKMS_PROTECTION_MODE_CBC

byte[] initialVector IV -> If ECB is used iv must be null , else initial vector must be given here.

TokenKMSKeyType -> TOKENKMS_KEYTYPE_PIN

TokenKMSKeyAlgoirthm -> TOKENKMS_KEY_ALG_TYPE_3DES_DUKPT

kms.injectDUKPTKeyByKEK(keyIndex, keyIndex_KEK, TokenKMSKeyType, TokenKMSKeyAlgorithm, encKeyData, KCV, ksn, TokenKMSProtectionMode, initialVector);

DUKPT Key Check Value

byte[] DUKPTKeyCheckValue = kms.getDUKPTKeyCheckValue3DES(keyIndex,len);

DUKPT Check Key Exists

kms.checkDUKPTKeyExist3DES(keyIndex);

DUKPT Delete Key

kms.deleteDUKPTKey3DES(keyIndex);

TR31 Save Key

kms.saveTR31Key(byte[] TR31Block, int kbpkIndex, int keyIndex);