README.md

A TypeScript library for widely used crypto standards.

Features

• Generate a random key for IV (24-byte long) or salt (32-byte long) using CSPRNG (Cryptographically-secure PRNG)
• HMAC-SHA256 encryption
• SHAKE256 (SHA-3) encryption
• AES256-GCM encryption and decryption
• Argon2i key derivation and hash verification

Installation

This is a Node.js package available through the npm registry. Before installing this package, download and install Node.js. Node.js v10.0.0 or higher is required.

Installation is done by using npm:

npm install @empo/encryption

Usage

Generate a random key

This provides CSPRNG, to be used as a cryptographic function (e.g. AES, SHA, Argon2) backend. The length of the output value is determined by its type (IV or salt). You could also add an encoding option behind the type.

import { generateRandomBytes } from '@empo/encryption'

// Generate random iv (24-byte String)
const buffer = generateRandomBytes({ type: 'iv' })

// Generate random base64 encoded salt (32-byte String)
const salt = generateRandomBytes({ type: 'salt', encoding: 'base64' })

Encryption

This provides a basic API for block cipher encryption using AES256-GCM.

import { AES } from '@empo/encryption'

const plaintext = 'password'

// Secret used for encryption/decryption and
// it has to be cryptographic safe - this means randomBytes or derived by PBKDF2 (for example)
const secret = generateRandomBytes({ type: 'salt', encoding: 'base64' })

const aes = new AES(secret)

// Generate base64 encoded cipher text
const encrypted = aes.encrypt(plaintext)

Decryption

This provides a basic API for block cipher decryption using AES256-GCM.

import { AES } from '@empo/encryption'

const plaintext = 'password'

// Secret used for encryption/decryption and
// it has to be cryptographic safe - this means randomBytes or derived by PBKDF2 (for example)
const secret = generateRandomBytes({ type: 'salt', encoding: 'base64' })

const aes = new AES(secret)
const encrypted = aes.encrypt(plaintext)

// Generate utf8 encoded plain text
const decrypted = aes.decrypt(encrypted)

Secure hash function

This provides a secure hash function using HMAC with SHA256. A hash function is deterministic — meaning that for a given input value it must always generate the same hash value, and the function can't be reversible.

import { SHA } from '@empo/encryption'

const plaintext = 'password'

// Pepper used for the cryptographic function
const pepper = generateRandomBytes({ type: 'salt', encoding: 'base64' })

const sha = new SHA(pepper)

// Generate base64 encoded hash
const encrypted = sha.encrypt(plaintext)

This provides a generalization of a cryptographic hash function using SHAKE256. SHAKE256 is an extensible-output function (XOF) in the SHA-3 family, as specified in FIPS 202. The 256 in its name indicates its maximum security level (in bits), as described in Sections A.1 and A.2 of FIPS 202. Unlike HMAC with SHA256, SHAKE256 doesn't need a pepper.

import { SHAKE256 } from '@empo/encryption'

const plaintext = 'password'

const sha3 = new SHAKE256()

// Generate base64 encoded hash
const encrypted = sha3.encrypt(plaintext)

This provides a key derivation function using Argon2 algorithm. A key derivation function is a cryptographic hash function that derives one or more secret keys such as a password, or a passphrase using pseudorandom function — meaning that for a given input value it must always generate different hash value, and the function can't be reversible.

import { Argon2 } from '@empo/encryption'

const plaintext = 'password'

// Pepper is similar to salt but stored in the application environment variables, not in DB
const pepper = generateRandomBytes({ type: 'salt', encoding: 'base64' })
const salt = generateRandomBytes({ type: 'salt', encoding: 'base64' })

const argon2 = new Argon2(pepper, salt)

// Generate hash
const encrypted = await argon2.encrypt(text)

// Verify hashed value with given text (outputs True or False)
const match = await argon2.match(encrypted, text)

FAQ

See FAQ.md.

License

This package is freely distributable under the terms of the MIT license. When required, please check P-H-C/phc-winner-argon2 for license over Argon2 and the reference implementation.