vault-cipher

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'

Settings

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