# KMS Library

<table><thead><tr><th width="100">AAR Ver.</th><th width="289">Detail</th><th width="121">Date</th><th width="174">Release Version</th><th>BSP Ver.</th></tr></thead><tbody><tr><td>v1.1.0</td><td>• Key check value method added<br>• KBPK key type added.</td><td></td><td></td><td></td></tr><tr><td>v1.1.1</td><td>• Improved binding handling</td><td></td><td></td><td></td></tr><tr><td>v1.1.2</td><td>• DUKPT support added </td><td></td><td></td><td></td></tr><tr><td>v1.1.3</td><td>• TR31 support added</td><td></td><td></td><td></td></tr><tr><td>V1.1.4</td><td>• DUKPT Api set updated</td><td>07.10.2024</td><td>V1360</td><td></td></tr></tbody></table>

{% file src="/files/7wsov4FGR958Ao3nIzYe" %}
Changelog
{% endfile %}

{% file src="/files/pQE34BdAelc5gj04MRip" %}
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

<mark style="color:red;">**Different index must be used for each key.**</mark>

**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

<mark style="color:red;">byte\[] IV Initialization Vector must be null for ECB</mark>&#x20;

• **Data Encryption ECB**

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

**• Data Decryption ECB**&#x20;

<pre class="language-java"><code class="lang-java"><strong>byte[] decryptedData = kms.decryptData(keyIndex,dataArray,TOKENKMS_PROTECTION_MODE_ECB,IV);
</strong></code></pre>

**• Data Encryption CBC**&#x20;

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

**• Data Decryption CBC**&#x20;

<pre class="language-java"><code class="lang-java"><strong>byte[] decryptedData = kms.decryptData(keyIndex,dataArray,TOKENKMS_PROTECTION_MODE_CBC,IV);
</strong></code></pre>

**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&#x20;

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

Size of returning byte array is equal to len parameter

**• Delete key**

<mark style="color:red;">**Note:**</mark> 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 -> <mark style="color:red;">**If ECB is used iv must be null , else initial vector must be given here.**</mark>

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);
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.tokeninc.com/token-developer-portal-1/payment-service/system-and-security-services/kms-library.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.