node package manager

vault-cipher

High-level authenticated encryption API used by Vault

vault-cipher

Provides a high-level authenticated encryption API that Vault uses to encrypt its stored settings. On Node, it's backed by the crypto module, while in the browser it uses crypto-js. Random values are generated with crypto.randomBytes() or crypto.getRandomValues() where available.

The encryption algorithm is an encrypt-then-MAC scheme based on AES and HMAC.

  • The given secret is used to derive an encryption key and a signing key using PBKDF2
  • The plaintext is padded to a multiple of the AES block size using PKCS#7
  • A random iv is selected using crypto.randomBytes()
  • The plaintext is encrypted using AES-256-CBC with the encryption key and iv to produce ciphertext
  • iv and ciphertext are concatenated and signed using HMAC-SHA-256 with the signing key to produce mac
  • The result is the concatenation of iv, ciphertext and mac
+--------+      +--------+      +----------------+----------------+
| secret |----->| PBKDF2 |----->| encryption key |  signing key   |
+--------+      +--------+      +----------------+----------------+
                                    |                     |
+---------+                         V                     |
| message |------------------>+-------------+             |
+---------+     +----+        | AES-256-CBC |             |
                | iv |------->+-------------+             |
                +----+              |                     |
                   |                |                     |
                   V                V                     V
              +----------+------------------+     +--------------+
              |    iv    |    ciphertext    |---->| HMAC-SHA-256 |
              +----------+------------------+     +--------------+
                      |               |                 |
                      V               V                 V
                  +----------+------------------+-----------+
                  |    iv    |    ciphertext    |    mac    |
                  +----------+------------------+-----------+

Its high-level API provides a simple way to encrypt and decrypt text:

var Cipher = require('vault-cipher'),
    cipher = new Cipher('your secret key');
 
var ciphertext = cipher.encrypt('some text');
 
cipher.decrypt(ciphertext) // -> 'some text' 

The cipher is configurable by passing options to the constructor, for example:

var cipher = new Cipher('secret key', {format: 'hex', work: 1000})

The available options are:

  • format: the output format of the ciphertext, either base64 (default) or hex
  • salt: a salt string used during PBKDF2 key derivation, defaults to a GUID embedded in the library
  • work: the number of PBKDF2 iterations used to derive the encryption and signing keys, default is 10,000