# Dashmachine crypto utility library

Cryptographic helper functions for use in Dash Platform Web Dapp Sample Messaging.

> Note: this is an experimental library to support the web dapp sample investigation of Dash Platform usage - not for production use.

> **Breaking Changes** From v1.0.0 DashJS is required as an external dependency in both browser and node.js versions

## Prerequisites

To utilise the encryption & decryption by username The library requires DashJS as an external dependency, so this must be referenced BEFORE the Dashmachine Crypto library.
In Node.js:
```
const Dash = require('dash');
const DashmachineCrypto = require('dashmachine-crypto');
```
In the browser:
```
<script src="https://unpkg.com/dash"></script>
<script src="dashmachine-crypto-lib.js" type="text/javascript"></script>
```

**Please see the examples below for sample usage**

## Browser usage

Include the `dashmachine-crypto-lib.js` script file available from the [releases page](https://github.com/dashmachine/dashmachine-crypto/releases).

## Nodejs usage

    npm i dashmachine-crypto

### Documentation

<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

##### Table of Contents

-   [DashmachineCrypto](#dashmachinecrypto)
    -   [Examples](#examples)
-   [encrypt](#encrypt)
    -   [Parameters](#parameters)
-   [decrypt](#decrypt)
    -   [Parameters](#parameters-1)
-   [hash](#hash)
    -   [Parameters](#parameters-2)
-   [verify](#verify)
    -   [Parameters](#parameters-3)
-   [generateEntropy](#generateentropy)
-   [encryptForUsername](#encryptforusername)
    -   [Parameters](#parameters-4)
-   [decryptForUsername](#decryptforusername)
    -   [Parameters](#parameters-5)

#### DashmachineCrypto

DashmachineCrypto performs ECIES encryption & decryption and Double SHA256 Hashing. Note the class contains only static methods so you do not have to call the contructor, i.e. use DashmachineCrypto.encrypt, not new DashmachineCrypto()

##### Examples

```javascript
<!-- Usage in HTML file -->
<script src="https://unpkg.com/dash"></script>
<script src="dashmachine-crypto-lib.js" type="text/javascript"></script>
<script>
const vendorPrivateKey = '40148175614f062fb0b4e5c519be7b6f57b872ebb55ea719376322fd12547bff'
const message = 'hello';
const userPublicKey = 'A7GGInyvn7ExXkSVg+OFhbhVjEMhIFv0oyeJl03gFDRo'
const userPrivateKey = '219c8a8f9376750cee9f06e0409718f2a1b88df4acc61bf9ed9cf252c8602768'
const vendorPublicKey = 'A0/qSE6tis4l6BtQlTXB2PHW+WV+Iy0rpF5hAvX8hDRz'
console.log(`Encrypting message "${message}"...`);
const encrypted = DashmachineCrypto.encrypt(vendorPrivateKey, message, userPublicKey);
console.dir(encrypted.data);
console.log(`Decrypting result message "${message}"...`);
const decrypted = DashmachineCrypto.decrypt(userPrivateKey, encrypted.data, vendorPublicKey);
console.dir(decrypted);
console.log(`Hashing message "${message}"...`);
const digest = DashmachineCrypto.hash(message);
console.dir(digest.data);
console.log(`Verifying hash...`);
const verifies = DashmachineCrypto.verify(message, digest.data);
console.dir(verifies.success)
const entropy = DashmachineCrypto.generateEntropy();
console.log(`entropy: ${entropy}`);

const senderName = 'alice';
const senderMnemonic = 'uniform analyst paper father soldier toe lesson fetch exhaust jazz swim response';
const recipientName = 'bob';
const recipientMnemonic = 'liar fee island situate deal exotic flat direct save bag fiscal news';
const userMessage = `Hello ${recipientName}!`;
const dpnsContractId = '295xRRRMGYyAruG39XdAibaU9jMAzxhknkkAxFE7uVkW'

async function testUsernameEncryption() {
try {
console.log(`send message \"${userMessage}\" to user: ${recipientName}`)
const encrypted = await DashmachineCrypto.encryptForUsername(userMessage, senderName, recipientName, senderMnemonic, dpnsContractId);
console.log('encrypted:', encrypted.data);
const decrypted = await DashmachineCrypto.decryptForUsername(encrypted.data, recipientName, senderName, recipientMnemonic, dpnsContractId)
console.log('decrypted:', decrypted.data);
}
catch (e) {
console.log('error :', e);

}

}

(async () => { await testUsernameEncryption() })()
</script>
```

```javascript
//use in nodejs
const Dash = require('dash');
const DashmachineCrypto = require("dashmachine-crypto")

const vendorPrivateKey = '40148175614f062fb0b4e5c519be7b6f57b872ebb55ea719376322fd12547bff'
const message = 'hello';
const userPublicKey = 'A7GGInyvn7ExXkSVg+OFhbhVjEMhIFv0oyeJl03gFDRo'
const userPrivateKey = '219c8a8f9376750cee9f06e0409718f2a1b88df4acc61bf9ed9cf252c8602768'
const vendorPublicKey = 'A0/qSE6tis4l6BtQlTXB2PHW+WV+Iy0rpF5hAvX8hDRz'
console.log(`Encrypting message "${message}"...`);
const encrypted = DashmachineCrypto.encrypt(vendorPrivateKey, message, userPublicKey);
console.dir(encrypted.data);
console.log(`Decrypting result message "${message}"...`);
const decrypted = DashmachineCrypto.decrypt(userPrivateKey, encrypted.data, vendorPublicKey);
console.dir(decrypted);
console.log('decrypted', decrypted.data);
const entropy = DashmachineCrypto.generateEntropy();
console.log(`entropy: ${entropy}`);

const senderName = 'alice';
const senderMnemonic = 'uniform analyst paper father soldier toe lesson fetch exhaust jazz swim response';
const recipientName = 'bob';
const recipientMnemonic = 'liar fee island situate deal exotic flat direct save bag fiscal news';
const userMessage = `Hello ${recipientName}!`;
const dpnsContractId = '295xRRRMGYyAruG39XdAibaU9jMAzxhknkkAxFE7uVkW'

async function testUsernameEncryption() {
try {
console.log(`send message \"${userMessage}\" to user: ${recipientName}`)
const encrypted = await DashmachineCrypto.encryptForUsername(userMessage, senderName, recipientName, senderMnemonic, dpnsContractId);
console.log('encrypted:', encrypted.data);
const decrypted = await DashmachineCrypto.decryptForUsername(encrypted.data, recipientName, senderName, recipientMnemonic, dpnsContractId)
console.log('decrypted:', decrypted.data);
}
catch (e) {
console.log('error :', e);

}

}

(async () => { await testUsernameEncryption() })()
```

#### encrypt

##### Parameters

-   `senderPrivateKey` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The base64 repesentation of the HD private key of the Dash User sending the message, the result of calling client.account.getIdentityHDKey(0, 'user').privateKey where client is an instance of Dash.Client
-   `message` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** message to encrypt
-   `recipientPublicKey` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** The base64 repesentation of the public key for the Identity of the Dash User receiveing the message

Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Either {success: true, data: [encrypted message]} or {error: true, message: [error message]}

#### decrypt

##### Parameters

-   `recipientPrivateKey` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The base64 repesentation of the HD private key of the Dash User receiving the message, the result of calling client.account.getIdentityHDKey(0, 'user').privateKey where client is an instance of Dash.Client
-   `encryptedMessage` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** message to decrypt as a hex representation of the stringified JSON of the encryption result buffer
-   `senderPublicKey` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** The base64 repesentation of the public key for the Identity of the Dash User sending the message

Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Either {success: true, data: [decrypted message]} or {error: true, message: [error message]}

#### hash

##### Parameters

-   `message` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** full message to be hashed

Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Either {success: true, data: [digest]} or {error: true, message: [error message]}

#### verify

##### Parameters

-   `message` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** full message to be hashed
-   `digest` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** digest to compare

#### generateEntropy

Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Either {success: true, data: [generated entropy]} or {error: true, message: [error message]}

#### encryptForUsername

##### Parameters

-   `message` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The message to encrypt
-   `senderName` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** DPNS username of sender
-   `recipientName` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** DPNS username of recipient
-   `senderMnemonic` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Account mnemonic of sender
-   `dpnsContractId` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** contractId for DPNS contract

Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** {success: true, data: encryptedMessage} | {Error}

#### decryptForUsername

##### Parameters

-   `message` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The message to decrypt
-   `recipientName` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** DPNS username of recipient
-   `senderName` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** DPNS username of sender
-   `recipientMnemonic` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Account mnemonic of recipient
-   `dpnsContractId` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** contractId for DPNS contract

Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** {success: true, data: encryptedMessage} or {Error}


### License

[MIT License](LICENSE)

# Development

To develop this library:

-   clone the repository and change to project directory 


    git clone  https://github.com/dashmachine/dashmachine-crypto.git && cd dashmachine-crypto

The source file is `src/crypto.service.js`

-   build output


    npm run build

-   test with webpack dev server


    npm start

-   update documentation (requires npm documentation package installed globally:  `npm i -g documentation`)

Update the Documentation section of the README.md file  

    npm run docs:readme