npm package: @particle/device-control-crypto
Description: Elliptic Curve J-PAKE and AES CCM for Node.js and browsers
Author: Particle Industries, Inc.
Latest version: 1.1.5

# @particle/device-control-crypto

Elliptic Curve J-PAKE and AES CCM for Node.js and browsers.


## Installation

```shell
npm install @particle/device-control-crypto --save
```
<!-- private-module-note-start -->

<!-- private-module-note-end -->

## API
<!-- api-docs-start -->
<a name="Ccm"></a>

### Ccm
A class implementing the CCM mode of operation for a block cipher.

**Kind**: global class  

* [Ccm](#Ccm)
    * [new Ccm(options)](#new_Ccm_new)
    * [.encrypt(data, nonce, [addData])](#Ccm+encrypt) ⇒ <code>Promise.&lt;Uint8Array&gt;</code>
    * [.decrypt(data, nonce, [addData])](#Ccm+decrypt) ⇒ <code>Promise.&lt;Uint8Array&gt;</code>


* * *

<a name="new_Ccm_new"></a>

#### new Ccm(options)
Constructor.


| Param | Type | Default | Description |
| --- | --- | --- | --- |
| options | <code>Object</code> |  | Options. |
| options.encrypt | [<code>EncryptFunction</code>](#EncryptFunction) |  | Encryption function. |
| options.nonceLength | <code>Number</code> |  | Nonce length in bytes. The value must be in the range [7, 13]. |
| [options.tagLength] | <code>Number</code> | <code>16</code> | Length of the authentication tag in bytes: 4, 6, 8, 10, 12,        14 or 16. |


* * *

<a name="Ccm+encrypt"></a>

#### ccm.encrypt(data, nonce, [addData]) ⇒ <code>Promise.&lt;Uint8Array&gt;</code>
Encrypt a message.

**Kind**: instance method of [<code>Ccm</code>](#Ccm)  
**Returns**: <code>Promise.&lt;Uint8Array&gt;</code> - Encrypted data. The authentication tag is appended to the encrypted data.  

| Param | Type | Description |
| --- | --- | --- |
| data | <code>Uint8Array</code> | Data to encrypt. |
| nonce | <code>Uint8Array</code> | Nonce. |
| [addData] | <code>Uint8Array</code> | Additional authenticated data. |


* * *

<a name="Ccm+decrypt"></a>

#### ccm.decrypt(data, nonce, [addData]) ⇒ <code>Promise.&lt;Uint8Array&gt;</code>
Decrypt a message.

**Kind**: instance method of [<code>Ccm</code>](#Ccm)  
**Returns**: <code>Promise.&lt;Uint8Array&gt;</code> - Decrypted data.  
**Throws**:

- Throws an error if decryption fails.


| Param | Type | Description |
| --- | --- | --- |
| data | <code>Uint8Array</code> | Data to decrypt. The authentication tag must be appended to the encrypted data. |
| nonce | <code>Uint8Array</code> | Nonce. |
| [addData] | <code>Uint8Array</code> | Additional authenticated data. |


* * *

<a name="EcJpake"></a>

### EcJpake
A class implementing the EC J-PAKE protocol as defined by the Thread specification.

**Kind**: global class  

* [EcJpake](#EcJpake)
    * [.getRound1()](#EcJpake+getRound1) ⇒ <code>Promise.&lt;Uint8Array&gt;</code>
    * [.readRound1(buf)](#EcJpake+readRound1) ⇒ <code>Number</code>
    * [.getRound2()](#EcJpake+getRound2) ⇒ <code>Promise.&lt;Uint8Array&gt;</code>
    * [.readRound2(buf)](#EcJpake+readRound2) ⇒ <code>Number</code>
    * [.deriveSecret()](#EcJpake+deriveSecret) ⇒ <code>Promise.&lt;Uint8Array&gt;</code>


* * *

<a name="EcJpake+getRound1"></a>

#### ecJpake.getRound1() ⇒ <code>Promise.&lt;Uint8Array&gt;</code>
Generate a message for the first round of the protocol.

**Kind**: instance method of [<code>EcJpake</code>](#EcJpake)  
**Returns**: <code>Promise.&lt;Uint8Array&gt;</code> - Message data.  

* * *

<a name="EcJpake+readRound1"></a>

#### ecJpake.readRound1(buf) ⇒ <code>Number</code>
Read a message generated by the peer for the first round of the protocol.

**Kind**: instance method of [<code>EcJpake</code>](#EcJpake)  
**Returns**: <code>Number</code> - Number of bytes read.  

| Param | Type | Description |
| --- | --- | --- |
| buf | <code>Uint8Array</code> | Message data. |


* * *

<a name="EcJpake+getRound2"></a>

#### ecJpake.getRound2() ⇒ <code>Promise.&lt;Uint8Array&gt;</code>
Generate a message for the second round of the protocol.

**Kind**: instance method of [<code>EcJpake</code>](#EcJpake)  
**Returns**: <code>Promise.&lt;Uint8Array&gt;</code> - Message data.  

* * *

<a name="EcJpake+readRound2"></a>

#### ecJpake.readRound2(buf) ⇒ <code>Number</code>
Read a message generated by the peer for the second round of the protocol.

**Kind**: instance method of [<code>EcJpake</code>](#EcJpake)  
**Returns**: <code>Number</code> - Number of bytes read.  

| Param | Type | Description |
| --- | --- | --- |
| buf | <code>Uint8Array</code> | Message data. |


* * *

<a name="EcJpake+deriveSecret"></a>

#### ecJpake.deriveSecret() ⇒ <code>Promise.&lt;Uint8Array&gt;</code>
Derive the shared secret.

**Kind**: instance method of [<code>EcJpake</code>](#EcJpake)  
**Returns**: <code>Promise.&lt;Uint8Array&gt;</code> - Shared secret.  

* * *

<a name="createAes128Cipher"></a>

### createAes128Cipher(key) ⇒ [<code>EncryptFunction</code>](#EncryptFunction)
Create an AES-128 cipher operating in ECB mode.

**Kind**: global function  
**Returns**: [<code>EncryptFunction</code>](#EncryptFunction) - Encryption function.  

| Param | Type | Description |
| --- | --- | --- |
| key | <code>Uint8Array</code> | Encryption key. The key must be 16 bytes long. |


* * *

<a name="getRandomBytes"></a>

### getRandomBytes(size) ⇒ <code>Promise.&lt;Uint8Array&gt;</code>
Generate cryptographically strong random data.

**Kind**: global function  
**Returns**: <code>Promise.&lt;Uint8Array&gt;</code> - Random data.  

| Param | Type | Description |
| --- | --- | --- |
| size | <code>Number</code> | Number of bytes to generate. |


* * *

<a name="EncryptFunction"></a>

### EncryptFunction ⇒ <code>Promise.&lt;Uint8Array&gt;</code>
Encrypt a single block of data.

**Kind**: global typedef  
**Returns**: <code>Promise.&lt;Uint8Array&gt;</code> - Ciphertext block.  

| Param | Type | Description |
| --- | --- | --- |
| block | <code>Uint8Array</code> | Plaintext block. The block must be 16 bytes long. |


* * *

<a name="RandomFunction"></a>

### RandomFunction ⇒ <code>Promise.&lt;Uint8Array&gt;</code>
Constructor.

**Kind**: global typedef  
**Returns**: <code>Promise.&lt;Uint8Array&gt;</code> - Random bytes.  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| size | <code>Number</code> |  | Number of random bytes to generate. |
| options | <code>Object</code> |  | Options. |
| options.role | <code>String</code> |  | Role of this peer: `client` or `server`. |
| options.secret | <code>String</code> \| <code>Uint8Array</code> |  | Pre-shared secret. |
| [options.randomBytes] | [<code>RandomFunction</code>](#RandomFunction) | <code>getRandomBytes</code> | Cryptographically strong random generator function. |
| [options.curve] | <code>String</code> | <code>p256</code> | Curve name. |
| [options.clientId] | <code>String</code> \| <code>Uint8Array</code> | <code>client</code> | Client identity. |
| [options.serverId] | <code>String</code> \| <code>Uint8Array</code> | <code>server</code> | Server identity. |


* * *


<!-- api-docs-end -->

_NOTE: Unfortunately, docs have a nasty habit of falling out of date. When in doubt, check usage in [tests](./src/index.test.js)_