String-Cipher

Simple set of crypto function for encrypting and decrypting UTF-8/ACSII strings. The module uses AES-GCM (128, 192 and 256) bases on Node crypto module. Solution used is based on this gist. By using AES-GCM encryption chiper text is authenticated as well. Base of this module are the make functions that generate desired encrypt and decrypt functions.

Written in Typescript as an ES6 module, all functions are provided in Sync and Async versions. In order to imporve over all security scheme, user supplied Password and random Salt is used to drive a key using pbkdf2 (with default iterations of 1, for speed but this can be changed using options). The key length depends on the AES-GCM version (128/192/256 use 16/24/32 bit keys) other values are defaulted to values specified by RFC 5288

Contents

• Installation and Usage
• Customization
• Make functions Option

Installation and Usage

npm install --save string-cipher

Async Api usage

Using async api for string inputs

import { encryptString, decryptString } from 'string-cipher';

const fetchedPassword = 'password'; // fetched from secure location not to placed in code like this 
const plainText = 'test string'; // utf-8 strings
const cipherText = await encryptString(plainText, fetchedPassword);
const retrivedText = await decryptString(cipherText, fetchedPassword);

Using async api for JSON inputs

import { encryptJson, decryptJson } from 'string-cipher';

const fetchedPassword = 'password'; // fetched from secure location not to placed in code like this 
const plainJson = { "field": "value" }; // any object that can be stringifed by JSON.stringify
const cipherJson = await encryptJson(plainJson, fetchedPassword);
const retrivedJson = await decryptJson(cipherJson, fetchedPassword);

Sync Api usage

Using sync api for string inputs

import { encryptStringSync, decryptStringSync } from 'string-cipher';

const fetchedPassword = 'password'; // fetched from secure location not to placed in code like this 
const plainText = 'test string'; // utf-8 strings
const cipherText = encryptStringSync(plainText, fetchedPassword);
const retrivedText = decryptStringSync(cipherText, fetchedPassword);

Using sync api for JSON inputs

import { encryptJsonSync, decryptJsonSync } from 'string-cipher';

const fetchedPassword = 'password'; // fetched from secure location not to placed in code like this 
const plainJson = { "field": "value" }; // any object that can be stringifed by JSON.stringify
const cipherJson = encryptJsonSync(plainJson, fetchedPassword);
const retrivedJson = decryptJsonSync(cipherJson, fetchedPassword);

Customization

With the help of make functions provided by the module you can customize the encryption and decrption setting. Note that same configuration should be appiled to both makeStringEncrypter and makeStringDecrypter

import { makeStringEncrypter, makeStringDecrypter } from 'string-cipher';

const commonOptions = {
  algorithm: 'aes-128-gcm',
  stringEncoding = 'ascii',
  authTagLength = 8,
  ivLength = 8,
  saltLength = 8,
  iterations = 10,
  digest = 'sha256'
}

const customEncrypt = makeStringEncrypter({
  outputEncoding = 'hex',
  ...commonOptions
});
const customEncryptJson = (payload, password) => customEncrypt(JSON.stringify(payload), password);

const customDecrypt = makeStringDecrypter({
  inputEncoding = 'hex',
  ...commonOptions
});
const customDecryptJson = async (payload, password) => JSON.parse(await customDecrypt(payload, password));

const fetchedPassword = 'password'; // fetched from secure location not to placed in code like this 
const plainText = 'test string';
const cipherText = await customEncrypt(plainText, fetchedPassword);
const retrivedText = await customDecrypt(cipherText, fetchedPassword);

makeStringEncrypterSync and makeStringDecrypterSync functions can used to generate Sync versions of cutomized encrypt and decrypt functions.

Make Functions Option

Option	Type	Required	Values	Default	Notes
algorithm	CipherGCMTypes	Yes	aes-256-gcm,aes-128-gcm,aes-192-gcm	none
stringEncoding	string	No	utf8,ascii	utf8	encoding format of the input string
outputEncoding	string	No	base64,hex	base64	only for encryption function output format
inputEncoding	string	No	base64,hex	base64	only for decryption function input format
ivLength	number	No	any number	12	Security of encryption depends on this 12 is recomemded
authTagLength	number	No	any number	16	Security of encryption depends on this 16 is recomemded
saltLength	number	No	any number	32	Used for password generation
iterations	number	No	any number	1	Used by pbkdf2 to drive key, main factor is speed
digest	string	No	sha25,sha512	sha256	Used by pbkdf2 to drive key