# KMS Library

AAR Ver.	Detail	Date	Release Version
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

{% file src="" %} Changelog {% endfile %} {% file src="" %} libTokenKMS v1.1.4 {% endfile %} 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. ```java 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** ```java 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** ```java 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 ```java 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 ```java 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. ```java try { TokenUSDKManager.getInstance().kmsService.deleteKey(keyIndex) }catch (e: TokenKMSException){ Log.i("", "$e") } ``` **• Check key exists** Throws exception if key does not exists. ```kotlin try { kms.checkKeyExist(keyIndex) }catch (e: TokenKMSException){ Log.i("", "$e") } ``` **• Delete ALL keys (NOT SUPPORTED ON 330TR)** ```java 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 ```java kms.injectDUKPTKeyByKEK(keyIndex, keyIndex_KEK, TokenKMSKeyType, TokenKMSKeyAlgorithm, encKeyData, KCV, ksn, TokenKMSProtectionMode, initialVector); ``` **DUKPT Key Check Value** ```java byte[] DUKPTKeyCheckValue = kms.getDUKPTKeyCheckValue3DES(keyIndex,len); ``` **DUKPT Check Key Exists** ```java kms.checkDUKPTKeyExist3DES(keyIndex); ``` **DUKPT Delete Key** ```java kms.deleteDUKPTKey3DES(keyIndex); ``` #### TR31 Save Key ```java kms.saveTR31Key(byte[] TR31Block, int kbpkIndex, int keyIndex); ```