# Cryptography API

## Connector functions JS API guide for crypto utility

This file provides methods for different crypto utilities using `crypt` global object.

### Encrypt and decrypt messages with AES algorithms

The `crypt.aes` global object provides all the functions for encryption and decryption using the AES algorithm.

These JavaScript functions use the cipher algorithm identifier required by the Java method `javax.crypto.Cipher.getInstance(algorithm)`, composed of `{CipherName}/{cipherMode}/{CipherPadding}`. Some examples are:

  - AES/CBC/NoPadding
  - AES/CBC/PKCS5Padding
  - AES/ECB/NoPadding
  - AES/ECB/PKCS5Padding
  - AES/GCM/NoPadding

### Data hashing

The `crypt.hmac` global object provides functions for hashing data. 


### AES JS API

#### crypt.aes.encrypt(algorithm, key, ivParameterSpec, data)

Encrypt the `data` using the selected AES `algorithm` with the provided shared `key`. 

**Kind**: global function  
**Returns**: <code>Uint8Array</code>


| Param     | Type                                                | Description                                                                                                                                                                                                         |
|-----------|-----------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| algorithm | <code>string</code>                                 | algorithm identifier, as required in java `javax.crypto.Cipher.getInstance(algorithm)`. For example: `AES/CBC/PKCS5Padding`                                                                                         |
| key       | <code>Uint8Array</code> | key used to encrypt the data. In `AES` algorithms. The key size must match the selected algorithm. For example, AES algorithms support keys of 16 bytes (`AES-128`), 24 bytes (`AES-192`), or 32 bytes (`AES-256`). |
| ivParam | <code>Uint8Array</code>           | Initialization vector (IV) used in encryption. Only allowed or required depending on the selected algorithm.                                                                                                         |
| data | <code>Uint8Array</code>           | data to be encoded                                                                                                                                                                                                  |

```javascript
var key128 = utils.bytes.fromText('012345678902345a'); /* 128 bits for AES-128 */
var ivParam = utils.bytes.fromText('0123456789023452');

var inputData = [104, 111, 108, 97, 32, 99, 97, 114, 97, 108, 99, 111, 108, 52, 53, 54];
var encriptedData = crypt.aes.encrypt("AES/CBC/NoPadding", key128, ivParam, inputData); 

log(encriptedData) // Expected output: [178,19,136,33,80,100,25,183,126,178,19,125,139,24,212,253]
```

#### crypt.aes.decrypt(algorithm, key, ivParameterSpec, data)

Decrypt the `data` using the selected AES `algorithm` with the provided shared `key`.

**Kind**: global function  
**Returns**: <code>Uint8Array</code>


| Param     | Type                                      | Description                                                                                                                                                                                                         |
|-----------|-------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| algorithm | <code>string</code>                       | algorithm identifier, as required in java `javax.crypto.Cipher.getInstance(algorithm)`. For example: `AES/CBC/PKCS5Padding`                                                                                         |
| key       | <code>Uint8Array</code> | key used to decrypt the data. In `AES` algorithms. The key size must match the selected algorithm. For example, AES algorithms support keys of 16 bytes (`AES-128`), 24 bytes (`AES-192`), or 32 bytes (`AES-256`). |
| ivParam | <code>Uint8Array</code> | Initialization vector (IV) used in encryption. Only allowed or required depending on the selected algorithm.                                                                                                         |
| data | <code>Uint8Array</code> | encoded data to be decrypted                                                                                                                                                                                        |

```javascript
var key128 = utils.bytes.fromText('012345678902345a'); /* 128 bits for AES-128 */
var ivParam = utils.bytes.fromText('0123456789023452');

var inputEncrypted = [178,19,136,33,80,100,25,183,126,178,19,125,139,24,212,253]
var data = crypt.aes.decrypt("AES/CBC/NoPadding", key128, ivParam, inputEncrypted);

log(data) // Expected output: [104, 111, 108, 97, 32, 99, 97, 114, 97, 108, 99, 111, 108, 52, 53, 54] 

```

### HMAC JS API

Following functions apply some hashing function with specified key to specified data.
In all cases, the result is a JSON with following structure:

| Param     | Type                      | Description                                                                                                                                          |
|-----------|-------------------------- |--------------------------                                                                                                                            |
| error     | <code>string</code>       | It will be null if hashing finishes correctly. If hashing fails, exception message will be indicated.                                                |
| result    | <code>Uint8Array</code>   | Obtained hash. If the hash function is applied correctly, byte array with hashed data will be returned. If some error occurs, null will be returned  |


Correct hashing result:

``` json
{
 "error": null,
 "result": [-102, 54, -66, -103, -25, 112, 1, 118, -65, 122, -22, 27, 88, 106, -54, 122, -11, -109, -63, 99, -127, -23, -15, -43, 28, 109, -22, -65, 25, 45, -85, 9, 39, 44, 39, 75, -95, -47, -61, -103, 101, -80, -62, -35, -102, 74, -76, 45, 94, -7, -35, 8, -80, -80, -65, -103, 127, 104, 75, -65, -89, 111, -34, 109]
}
```

Result with some error
``` json
{
 "error": "Algorithm HmacSHA999 not available",
 "result": null
}
```

#### crypt.hmac.sha256(data, key)

Create a hash from provided string using sha256. 

**Kind**: global function  
**Returns**: <code>Object</code>

| Param     | Type                      | Description               |
|-----------|-------------------------- |-------------------------- |
| data      | <code>string</code>       | Data to be hashed         |
| key       | <code>Uint8Array</code>   | key to be used for hashing |

```javascript
var hashResult = crypt.hmac.sha256("Some data to be hashed", "hashingKey");
log(hashResult) 
/* Expected output: 
{
 "error": null,
 "result": [-56, -6, 82, -104, -74, -100, -103, 112, 80, -89, -61, 85, -63, 58, -102, -54, -68, 15, 70, 60, 44, 85, 110, -100, -108, -95, -48, -3, 8, -25, 33, -4]
}
*/
```

#### crypt.hmac.sha512(data, key)

Create a hash from provided string using sha512. 

**Kind**: global function  
**Returns**: <code>Object</code>

| Param     | Type                                      | Description                                                                                                                                                                                                         |
|-----------|-------------------------------------------|-------------------------- |
| data      | <code>string</code>                       | Data to be hashed         |
| key       | <code>Uint8Array</code>                   | key to be used for hashing |

```javascript
var hashResult = crypt.hmac.sha512("Some data to be hashed", "hashingKey");
log(hashResult) ;
/* Expected output: 
{
 "error": null,
 "result": [-102, 54, -66, -103, -25, 112, 1, 118, -65, 122, -22, 27, 88, 106, -54, 122, -11, -109, -63, 99, -127, -23, -15, -43, 28, 109, -22, -65, 25, 45, -85, 9, 39, 44, 39, 75, -95, -47, -61, -103, 101, -80, -62, -35, -102, 74, -76, 45, 94, -7, -35, 8, -80, -80, -65, -103, 127, 104, 75, -65, -89, 111, -34, 109]
}
*/
```