Class ydn.crypto.Cipher

Cipher provide encryption, decryption and hashing using master keys.

Constructor
ydn.crypto.Cipher(options)
Cipher supporting key rotation.

If multiple master keys are provided, the first secret of the key is used for encryption. All keys are used on decryption depending on the given encryption package.

var options = {
    method: 'rc4',
    secrets: [{
      name: 'aaaa',
      key: 'aYHF6vfuGHpfWS*eRLrPQxZjSó~É5c6HjCscqDqRtZasp¡JWSMGaW'
    }]
};
var cipher = new ydn.crypto.Cipher(options);
var package = cipher.encrypt({msg: 'Keep this secret.', 'msg1'});
// db.put('messages', package, 'msg1');
// db.put('messages', package, cipher.hash('msg1'));
var msg = cipher.decrypt(package, 'msg1');
Parameters:
{Object} options
Define encryption options in JSON.
Fields:
{number=} expiration
Optional. expiration time in ms.
{boolean=} encryptKey
Optional. Encrypt record key. By default only record value is encrypted.
{string|boolean=} exposeKey
Optional. If set, the result of encryption package from encrypt has set encryption key in attribute name key. If exposeKey is a string, it is served as key extraction path in encrypt.
{string=} method
Optional. Cipher algorithms, either 'aes-cbc' or 'rc4', representing Advanced Encryption Standard with Cipher Block Chaining Mod or Rivest Cipher 4 respectively. Default to 'aes-cbc'.
{Array<Object>} secrets
List of master key name and secret.
{boolean=} unsafeParse
Optional. During deserialization with JSON.parse fail, use eval for deserialization. Default to false. Note: using eval to parse untrusted record value invite security issue.
Method
decrypt(package, key)
Decrypt the encryption package.

When expiration is used and encryption package is expired, i.e, expiration < new Date().getTime(), result is set to undefined.

Parameters:
{Object} package
The encryption package as return from encrypt method.
{string} key
Optional. The encryption key for the package. Optional if exposeKey is used.
Returns:
{*} Result from decryption
Throws:
{Error} MasterKeyNotProvidedError
The master key name as specify in the package is not available. The error object has attributes of name and code for "MasterKeyNotProvidedError" string value and master key name, respectively.

encrypt(value, key)
Encrypt given value with given key.

The first master key, a 64-bit random salt and the key are digested with SHA256 to get a hash key. Given value is converted into string by `JSON.stringify`. The resulting message is encrypted using selected algorithm with the hash key.

The output encryption package contains the master key name used and salt for decryption.

Parameters:
{Object} value
The value to be encrypted.
{string=} key
Optional. The encryption key. If key is not provided and exposeKey is string, a key will be extracted from the value object by exposeKey as keyPath. If a string key is not yield and exposeKey is set, a key will be generated by timestamp and a random number.
Returns:
{Object} The encryption package. For example:
{
  "salt": [2, 255, 63, 177, 0, 67, 229, 159, 60, 253, 109, 195, 81, 25, 21, 238],
  "data": "ÛÉe)/T¸LžPš˜PÑ šî×Èzç´¤õĪ\u001eìÎ\u0006‹Ü",
  "expiration": 1434996338405, // only present if expiration is set
  "creation": 1434996323405,
  "key" "id1", // only present if exposeKey is set true
  "keyName": "aaaa" // master key name
}

hash(value, key_name)
Hash with secret.
Parameters:
{string} value
The value to be hashed.
{string|number=} Optional. key_name
The encryption key name or index of the master keys to be used in hashing, default to the first key, 0.
Returns:
{string} The resulting hash.