npm package: @jorveld/jsoncrypt
Description: Collection of functions that can be used to encrypt, sign and hash json objects
Author: Jorien van Veldhoven
Latest version: 1.1.0

# jsoncrypt

## Purpose

The jsoncrypt javascript (nodejs) library contains a number of functions that can be used to encrypt, decrypt, sign and hash json objects. The library was created to simplify the use of cryptocraphic operations on json objects.

## Getting started

In order to use jsoncrypt use the following steps
1) Create a directory in which you want to create a nodejs (Javascipt) application.
2) Go to this directory and install jsoncrypt with: 'npm install @jorveld/jsoncrypt'
3) Create a javascript file in which you want to use the library and add the following line:
const JSONCrypt = require('@jorveld/jsoncrypt');
next call the available functions, for example:
RSAPair = JSONCrypt.getRSAPair();

## available functionss
jsoncrypt implements the following functions:

Utilty functions:
==> getRSAPair() --> This function returns a 2048 bit RSA public and private key. The function returns a JSON object with two properties:
- publicKey
- privateKey

==> createSyncEncryptionKey() --> This function returns a 32 byte random string, that can be used as key in the 'synchronous' encryption functions.

==> createSyncEncryptionKeyAndIv() --> This function returns a 32 byte random string, to be used as the key and a 16 byte initialisation vector for the 'synchronous' encryption functions


Synchronous encryption functions:

==> cryptSync(inputJSONObjectToBeEncrypted, inputEncryptionKey, inputIv="") --> this function takes a JSONObject and encrypts it using the inputEncryptionKey (using AES). If the inputIv=="", a new initialisation vector is creared. If not, the provied vector is used. 

It returns a JSON object with two properties:
-iv: this is the random initialisation vector used for the encryption. Please mind: the iv is not secret, it nevertheless needs to be provided to decrypt.
-encryptedContent: the encrypted content
==> deCryptSync(inputEncryptedContent, inputEncryptionKey, inputIv) --> this function is used to decrypt a JSON object crypted with cryptSync. The function takes the following parameters:
- inputEncryptedContent. This is the 'encryptedContent' from the cryptSync function.
- inputEncryptionKey. The secret synchronous encryption key used.
- inputIv. The initalisation vector generated by cryptSync. 

Example:
const JSONCrypt = require('jsoncrypt');


console.log("crypt test");

key=JSONCrypt.createSyncEncryptionKey();

var toBeEncryptedObject = {
    name: "John Johnson", 
    gender: "male",
    age: 32
}


console.log("SyncCrypt");
syncCryptResult=JSONCrypt.cryptSync(toBeEncryptedObject, key);
console.log("syncCryptResult:"+JSON.stringify(syncCryptResult));
console.log("SyncUncrypt");
syncUnencryptResult=JSONCrypt.deCryptSync(syncCryptResult.encryptedContent,key,syncCryptResult.iv);
console.log("syncUnencryptResult:"+JSON.stringify(syncUnencryptResult));


Asynchronous encryption functions:
==>cryptAsync(inputJSONObjectToBeEncrypted, inputPublicKey) --> this function will RSA-encrypt the JSONObject 'inputJSONObjectToBeEncrypted' using the public key 'inputPublicKey'. The function returns the encrypted content as a string. 
==>deCryptAsync(inputEncryptedContent, inputPrivateKey) --> this function will decrypt 'inputEncryptedContent' (string) (output of cryptAsync) using the private key 'inputPrivateKey'.

Example:

const JSONCrypt = require('jsoncrypt');

console.log("crypt test");


var toBeEncryptedObject = {
    name: "John Johnson", 
    gender: "male",
    age: 32
}


console.log("create RSA Keys");
RSAPair = JSONCrypt.getRSAPair();
console.log("RSAPair:");
console.log(RSAPair);

console.log("AsyncCrypt");
asyncCryptResult=JSONCrypt.cryptAsync(toBeEncryptedObject, RSAPair.publicKey);
console.log("asyncCryptResult="+asyncCryptResult);

console.log("AsyncUncrypt");
asyncDecryptResult=JSONCrypt.deCryptAsync(asyncCryptResult, RSAPair.privateKey);
console.log("asyncDecryptResult="+asyncDecryptResult);

Hash functions:
==>hash(inputJSONObjectToBeHashed) --> this function will md5-hash the JSON object 'inputJSONObjectToBeHashed'. The funcntions the hash as an output.  
==>verifyHash(inputHash, inputJSONObjectToBeVerified) --> This function will check if 'inputJSONObjectToBeVerified' is hashed to 'inputHash'. This function can be used to verify a hash. It returns 'true' if the hash is valid.

Example:
const JSONCrypt = require('jsoncrypt');

console.log("crypt test");


var toBeEncryptedObject = {
    name: "John Johnson", 
    gender: "male",
    age: 32
}

console.log("Hash");
hashResult=JSONCrypt.hash(toBeEncryptedObject);
console.log(hashResult);
console.log("Hash verification:"+JSONCrypt.verifyHash(hashResult, toBeEncryptedObject));

sign functions:
==>sign(inputJSONObjectToBeSigned, inputPrivateKey) --> this function is used to aes-256-cbc sign JSON object inputJSONObjectToBeSigned' using RSA private key 'inputPrivateKey'. The output of the function is the signature (as a string). 
==>verifySignature(inputSignature, inputPublicKey, inputJSONObjectToBeVerified) --> this function is used to verify if 'inputSignature' was used to sign JSON Object 'inputJSONObjectToBeVerified' using RSA key 'inputPublicKey'. If the signature is valid, 'true' is returned.

Example:
const JSONCrypt = require('jsoncrypt');

console.log("crypt test");


var toBeEncryptedObject = {
    name: "John Johnson", 
    gender: "male",
    age: 32
}

console.log("Sign");
signature=JSONCrypt.sign(toBeEncryptedObject, RSAPair.privateKey);
console.log("signature:"+ signature);
console.log("Signature verification:"+JSONCrypt.verifySignature(signature, RSAPair.publicKey, toBeEncryptedObject));


## Author 
Jorien van Veldhoven

## License
MIT license