data-at-rest

Stability: 1 - Experimental

Encryption utilities for data at rest.

Contributors

@tristanls

Contents

• Overview
• Installation
• Tests
• Usage
• Documentation
• Releases

Overview

This module encodes a way to store secret data at rest given an encryption key. It is intended to guide the user by providing default algorithm selection (DataAtRest.ALGORITHM), asking for additional authenticated data, specifying appropriate initialization vector length (DataAtRest.IV_LENGTH_IN_BYTES), and using crypto.createCipheriv() instead of crypto.createCipher().

Generation and management of encryption key is beyond the scope of this module, however Envelope encryption may be of interest.

For more insight into additional authenticated data and its uses, see How to Protect the Integrity of Your Encrypted Data by Using AWS Key Management Service and EncryptionContext.

Installation

npm install data-at-rest

Tests

npm test

Usage

const DataAtRest = require("data-at-rest");
 
// secret key from somewhere
const key = crypto.randomBytes(32); // 256 bits (aes-256-gcm)
 
// data to store
const data = {
    id: "some-id",
    secretData: "some secret data",
    notSecretData: "not secret data"
};
 
// encryption
const additionalAuthenticatedData = {
    id: data.id,
    notSecretData: data.notSecretData
};
const cipherBundle =
            DataAtRest.encrypt(
                Buffer.from(data.secretData, "utf8"),
                DataAtRest.aad(additionalAuthenticatedData),
                key
            );
const dataStoredAtRest = {
    id: data.id,
    secretData: JSON.stringify(DataAtRest.cipherBundleToBase64(cipherBundle)),
    notSecretData: data.notSecretData
};
 
// decryption
const plaintext =
            DataAtRest.decrypt(
                DataAtRest.cipherBundleFromBase64(JSON.parse(dataStoredAtRest.secretData)),
                DataAtRest.aad(additionalAuthenticatedData),
                key
            );
const retrievedData = {
    id: dataStoredAtRest.id,
    secretData: plaintext.toString("utf8"),
    notSecretData: dataStoredAtRest.notSecretData
};

Documentation

DataAtRest

Public API

• DataAtRest.ALGORITHM
• DataAtRest.IV_LENGTH_IN_BYTES
• DataAtRest.aad(obj)
• DataAtRest.cipherBundleFromBase64(cipherBundle)
• DataAtRest.cipherBundleToBase64(cipherBundle)
• DataAtRest.decrypt(cipherBundle, aad, key)
• DataAtRest.encrypt(plaintext, aad, key)
• DataAtRest.normalizeAad(obj)

DataAtRest.ALGORITHM

• aes-256-gcm

Default algorithm to use.

DataAtRest.IV_LENGTH_IN_BYTES

• 12

Default initialization vector length in bytes.

DataAtRest.aad(obj)

• obj: Object An object representing string-to-string map of additional authenticated data.
• Return: Buffer Normalized additional authenticated data.

Normalizes given additional authenticated data by sorting it in order to generate the same buffer regardless of property ordering within the passed in object.

DataAtRest.cipherBundleFromBase64(cipherBundle)

• cipherBundle: Object Cipher bundle generated by DataAtRest.cipherBundleToBase64(cipherBundle).
  • authTag: String Base64 encoded string authentication tag.
  • ciphertext: String Base64 encoded string ciphertext.
  • iv: String Base64 encoded string initialization vector.
• Return: Object Cipher bundle with Base64 encoded strings converted to Buffers.
  • authTag: Buffer Authentication tag.
  • ciphertext: Buffer Ciphertext.
  • iv: Buffer Initialization vector.

Converts a cipher bundle with Base64 encoded string properties into a cipher bundle with Buffer properties.

DataAtRest.cipherBundleToBase64(cipherBundle)

• cipherBundle: Object Cipher bundle generated by DataAtRest.encrypt(plaintext, aad, key).
  • authTag: Buffer Authentication tag.
  • ciphertext: Buffer Ciphertext.
  • iv: Buffer Initialization vector.
• Return: Object Cipher bundle with Buffers converted to Base64 encoded strings.
  • authTag: String Base64 encoded string authentication tag.
  • ciphertext: String Base64 encoded string ciphertext.
  • iv: String Base64 encoded string initialization vector.

Converts a cipher bundle with Buffer properties into a cipher bundle with Base64 encoded string properties.

DataAtRest.decrypt(cipherBundle, aad, key)

• cipherBundle: Object Cipher bundle generated by DataAtRest.encrypt(plaintext, aad, key).
  • authTag: Buffer Authentication tag.
  • ciphertext: Buffer Ciphertext.
  • iv: Buffer Initialization vector.
• aad: Buffer Additional authenticated data generated by DataAtRest.aad(obj).
• key: Buffer Encryption key.
• Return: Buffer Decrypted plaintext.

Decrypts previously encrypted cipherBundle into plaintext.

DataAtRest.encrypt(plaintext, aad, key)

• plaintext: Buffer Plaintext to encrypt.
• aad: Buffer Additional authenticated data generated by DataAtRest.aad(obj).
• key: Buffer Encryption key.
• Return: Object Cipher bundle.
  • authTag: Buffer Authentication tag.
  • ciphertext: Buffer Ciphertext.
  • iv: Buffer Initialization vector.

Encrypts the plaintext using specified additional authenticated data (aad) and the encryption key.

DataAtRest.normalizeAad(obj)

• obj: Object An object representing string-to-string map of additional authenticated data.
• Return: Array Normalized object in form of sorted array.

Normalizes given additional authenticated data object by sorting it by key and returning an array (the order of which should be preserved by JSON.stringify implementations).

Releases

Current releases.

Policy

We follow the semantic versioning policy (semver.org) with a caveat:

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.

caveat: Major version zero is a special case indicating development version that may make incompatible API changes without incrementing MAJOR version.