simple-crypt v3.0.7

simple-crypt   

Note: Things have moved on in cryptography since I wrote this library. While I'm happy to fix bugs in simple-crypt, you're probably better off using libsodium via sodium-native or sodium-plus.

Javascript library for signing and encrypting data.

• Consistent API across Node.js and browser.
• On Node.js wraps crypto.
  • From simple-crypt version 2 onwards, at least Node.js version 8 is required and the dependency on ursa has been removed.
  • From simple-crypt version 3 onwards, at least Node.js version 12 is required and KeyObjects are used internally.
• On browser wraps SlowAES, pbkdf2.js, CryptoJS, jsrsasign, js-rsa-pem and Paul Johnston's SHA scripts.
• Hard-coded to HMAC-SHA-256 for symmetric signing.
• Hard-coded to RSA-SHA-256 with RSASSA-PSS encoding for asymmetric signing.
• Hard-coded to AES-128-CBC for symmetric key encryption (with optional SHA-256 checksum).
• Hard-coded to RSA, RSAES-OAEP encoding and AES-128-CBC for asymmetric encryption (with optional SHA-256 checksum).
• Verification and decryption operations included.
• Support for deriving signing and encryption key from a password using PBKDF2-SHA1.
• JSON encoding of data by default.
• Optional stream API.
• Unit tests, including NIST test vectors and tests for interoperability between Node.js and browser (using PhantomJS).

Example:

var Crypt = require('simple-crypt').Crypt;
var data = { device_id: 'temperature_sensor0', value: 15.765 };

Crypt.make('my signing key', function (err, signer)
{
    signer.sign(data, function (err, signed)
    {
        Crypt.make(this.get_key(), function (err, verifier)
        {
            verifier.verify(signed, function (err, verified)
            {
                assert.deepEqual(verified, data);
            });
        });
    });
});

The API is described here.

Please feel free to make any comments (or pull requests), especially if you notice something wrong!

Installation

Node.js:

npm install simple-crypt

Browser:

<script type="text/javascript" src="dist/simple-crypt-deps.js"></script>
<script type="text/javascript" src="dist/simple-crypt.js"></script>

More Examples

Encryption

Crypt.make(crypto.randomBytes(Crypt.get_key_size()), function (err, encrypter)
{
    encrypter.encrypt(data, function (err, encrypted)
    {
        Crypt.make(this.get_key(), function (err, decrypter)
        {
            decrypter.decrypt(encrypted, function (err, decrypted)
            {
                assert.deepEqual(decrypted, data);
            });
        });
    });
});

Asymmetric operation

var priv_pem = "-----BEGIN RSA PRIVATE KEY-----\nMIIEogIBAAKCAQEA4qiw8PWs7PpnnC2BUEoDRcwXF8pq8XT1/3Hc3cuUJwX/otNe\nfr/Bomr3dtM0ERLN3DrepCXvuzEU5FcJVDUB3sI+pFtjjLBXD/zJmuL3Afg91J9p\n79+Dm+43cR6wuKywVJx5DJIdswF6oQDDzhwu89d2V5x02aXB9LqdXkPwiO0eR5s/\nxHXgASl+hqDdVL9hLod3iGa9nV7cElCbcl8UVXNPJnQAfaiKazF+hCdl/syrIh0K\nCZ5opggsTJibo8qFXBmG4PkT5YbhHE11wYKILwZFSvZ9iddRPQK3CtgFiBnXbVwU\n5t67tn9pMizHgypgsfBoeoyBrpTuc4egSCpjsQIDAQABAoIBAF2sU/wxvHbwAhQE\npnXVMMcO0thtOodxzBz3JM2xThhWnVDgxCPkAhWq2X0NSm5n9BY5ajwyxYH6heTc\np6lagtxaMONiNaE2W7TqxzMw696vhnYyL+kH2e9+owEoKucXz4QYatqsJIQPb2vM\n0h+DfFAgUvNgYNZ2b9NBsLn9oBImDfYueHyqpRGTdX5urEVtmQz029zaC+jFc7BK\nY6qBRSTwFwnVgE+Td8UgdrO3JQ/0Iwk/lkphnhls/BYvdNC5O8oEppozNVmMV8jm\n61K+agOh1KD8ky60iQFjo3VdFpUjI+W0+sYiYpDb4+Z9OLOTK/5J2EBAGim9siyd\ngHspx+UCgYEA9+t5Rs95hG9Q+6mXn95hYduPoxdFCIFhbGl6GBIGLyHUdD8vmgwP\ndHo7Y0hnK0NyXfue0iFBYD94/fuUe7GvcXib93heJlvPx9ykEZoq9DZnhPFBlgIE\nSGeD8hClazcr9O99Fmg3e7NyTuVou+CIublWWlFyN36iamP3a08pChsCgYEA6gvT\npi/ZkYI1JZqxXsTwzAsR1VBwYslZoicwGNjRzhvuqmqwNvK17dnSQfIrsC2VnG2E\nUbE5EIAWbibdoL4hWUpPx5Tl096OjC3qBR6okAxbVtVEY7Rmv7J9RwriXhtD1DYp\neBvo3eQonApFkfI8Lr2kuKGIgwzkZ72QLXsKJiMCgYBZXBCci0/bglwIObqjLv6e\nzQra2BpT1H6PGv2dC3IbLvBq7hN0TQCNFTmusXwuReNFKNq4FrB/xqEPusxsQUFh\nfv2Il2QoI1OjUE364jy1RZ7Odj8TmKp+hoEykPluybYYVPIbT3kgJy/+bAXyIh5m\nAv2zFEQ86HIWMu4NSb0bHQKBgETEZNOXi52tXGBIK4Vk6DuLpRnAIMVl0+hJC2DB\nlCOzIVUBM/VxKvNP5O9rcFq7ihIEO7SlFdc7S1viH4xzUOkjZH2Hyl+OLOQTOYd3\nkp+AgfXpg8an4ujAUP7mu8xaxns7zsNzr+BCgYwXmIlhWz2Aiz2UeL/IsfOpRwuV\n801xAoGADQB84MJe/X8xSUZQzpn2KP/yZ7C517qDJjComGe3mjVxTIT5XAaa1tLy\nT4mvpSeYDJkBD8Hxr3fB1YNDWNbgwrNPGZnUTBNhxIsNLPnV8WySiW57LqVXlggH\nvjFmyDdU5Hh6ma4q+BeAqbXZSJz0cfkBcBLCSe2gIJ/QJ3YJVQI=\n-----END RSA PRIVATE KEY-----";
var pub_pem = "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4qiw8PWs7PpnnC2BUEoD\nRcwXF8pq8XT1/3Hc3cuUJwX/otNefr/Bomr3dtM0ERLN3DrepCXvuzEU5FcJVDUB\n3sI+pFtjjLBXD/zJmuL3Afg91J9p79+Dm+43cR6wuKywVJx5DJIdswF6oQDDzhwu\n89d2V5x02aXB9LqdXkPwiO0eR5s/xHXgASl+hqDdVL9hLod3iGa9nV7cElCbcl8U\nVXNPJnQAfaiKazF+hCdl/syrIh0KCZ5opggsTJibo8qFXBmG4PkT5YbhHE11wYKI\nLwZFSvZ9iddRPQK3CtgFiBnXbVwU5t67tn9pMizHgypgsfBoeoyBrpTuc4egSCpj\nsQIDAQAB\n-----END PUBLIC KEY-----";

Crypt.make(priv_pem, function (err, signer)
{
    signer.sign(data, function (err, signed)
    {
        Crypt.make(pub_pem, function (err, verifier)
        {
            verifier.verify(signed, function (err, verified)
            {
                assert.deepEqual(verified, data);
            });
        });
    });
});

Crypt.make(pub_pem, function (err, encrypter)
{
    encrypter.encrypt(data, function (err, encrypted)
    {
        Crypt.make(priv_pem, function (err, decrypter)
        {
            decrypter.decrypt(encrypted, function (err, decrypted)
            {
                assert.deepEqual(decrypted, data);
            });
        });
    });
});

Passwords

var pw_info = { password: 'P@ssW0rd!', iterations: 10000 };

Crypt.make(pw_info, function (err, signer)
{
    signer.sign(data, function (err, signed)
    {
        var salted = Object.create(pw_info);
        salted.salt = this.get_key().salt;
        Crypt.make(salted, function (err, verifier)
        {
            verifier.verify(signed, function (err, verified)
            {
                assert.deepEqual(verified, data);
            });
        });
    });
});

Crypt.make(pw_info, function (err, encrypter)
{
    encrypter.encrypt(data, function (err, encrypted)
    {
        var salted = Object.create(pw_info);
        salted.salt = this.get_key().salt;
        Crypt.make(salted, function (err, decrypter)
        {
            decrypter.decrypt(encrypted, function (err, decrypted)
            {
                assert.deepEqual(decrypted, data);
            });
        });
    });
});

Conditional operation

Crypt.make('some key', function (err, signer)
{
    signer.maybe_sign(false, data, function (err, signed)
    {
        assert.equal(signed.signed, false);
        Crypt.make(this.get_key(), function (err, verifier)
        {
            verifier.maybe_verify(signed, function (err, verified)
            {
                assert.deepEqual(verified, data);
            });
        });
    });
});

Crypt.make(crypto.randomBytes(Crypt.get_key_size()), function (err, encrypter)
{
    encrypter.maybe_encrypt(true, data, function (err, encrypted)
    {
        assert.equal(encrypted.encrypted, true);
        Crypt.make(this.get_key(), function (err, decrypter)
        {
            decrypter.maybe_decrypt(encrypted, function (err, decrypted)
            {
                assert.deepEqual(decrypted, data);
            });
        });
    });
});

Dynamic key retrieval

var pub_pems = { temperature_sensor0: pub_pem };
var priv_pems = { temperature_sensor0: priv_pem };

Crypt.make().maybe_sign(data, function (err, signed)
{
    assert.equal(signed.signed, true);
    Crypt.make().maybe_verify(signed, function (err, verified)
    {
        assert.deepEqual(verified, data);
    }, function (cb, device_id)
    {
        cb(null, pub_pems[device_id]);
    });
}, function (device_id, cb)
{
    cb(null, priv_pems[device_id], device_id);
}, data.device_id);

Crypt.make().maybe_encrypt(data, function (err, encrypted)
{
    assert.equal(encrypted.encrypted, true);
    Crypt.make().maybe_decrypt(encrypted, function (err, decrypted)
    {
        assert.deepEqual(decrypted, data);
    }, function (cb, device_id)
    {
        cb(null, priv_pems[device_id]);
    });
}, function (device_id, cb)
{
    cb(null, pub_pems[device_id], device_id);
}, data.device_id);

Sign-encrypt-sign

Crypt.sign_encrypt_sign(priv_pem, pub_pem, data, function (err, data_out)
{
    Crypt.verify_decrypt_verify(priv_pem, pub_pem, data_out, function (err, data_in)
    {
        assert.deepEqual(data_in, data);
    });
});

JSON-less encoding

Crypt.make('some signing key', { json: false }, function (err, signer)
{
    signer.sign(Buffer.from('"hello"'), function (err, signed)
    {
        this.verify(signed, function (err, verified)
        {
            assert.equal(verified, '"hello"');
        });
    });
});

Streaming operation

var s = new require('stream').PassThrough();

Crypt.encrypt_stream('some signing key', s, function (err, enc_s)
{
    Crypt.decrypt_stream('some signing key', enc_s, function (err, dec_s)
    {
        var v = '';

        dec_s.on('readable', function ()
        {
            var data = this.read();
            if (data)
            {
                v += data;
            }
        });

        dec_s.on('end', function ()
        {
            assert.equal(v, 'hello world');
        });
    });
});

s.end('hello world');

Licence

MIT

Tests

grunt test

Lint

grunt lint

Code Coverage

grunt coverage

Istanbul results are available here.

Coveralls page is here.

Benchmarks

grunt bench

Here are some results on a laptop with an Intel Core i5-3210M 2.5Ghz CPU and 6Gb RAM running Ubuntu 13.10.

In the tables, fast is the normal simple-crypt Node.js code wrapper and slow is the browser code running on Node.js (not in a browser).

API

Create

• Crypt.make

Key functions

• Crypt.get_key_size
• Crypt.get_iv_size
• Crypt.parse_key
• Crypt.prototype.get_key

Encryption

• Crypt.prototype.encrypt
• Crypt.prototype.decrypt

Signing

• Crypt.prototype.sign
• Crypt.prototype.verify

Sign-encrypt-sign

• Crypt.sign_encrypt_sign
• Crypt.verify_decrypt_verify

Conditional and dynamic key operations

• Crypt.prototype.maybe_encrypt
• Crypt.prototype.maybe_decrypt
• Crypt.prototype.maybe_sign
• Crypt.prototype.maybe_verify

Stream functions

• Crypt.encrypt_stream
• Crypt.decrypt_stream
• Crypt.sign_stream
• Crypt.verify_stream
• Crypt.sign_encrypt_sign_stream
• Crypt.verify_decrypt_verify_stream

Crypt.make(key, options, cb)

Create a new Crypt object which can be used to sign, verify, encrypt and decrypt data.

Parameters:

• {String | Buffer | Object} [key] Optional key to use for operations using this object.

- If you pass a string which looks like it's PEM-encoded then it will be loaded as a RSA key.

- If you pass an object then its `password`, `iterations` and optional `salt` properties will be used to derive a key using PBKDF2-SHA1. If you don't supply a salt then a random one is created. You can also supply an optional `progress` property, which must be a function and is called with the percentage completion as the key is derived.

- Otherwise the key should be a `Buffer` or binary-encoded string, length equal to [get_key_size()](#cryptget_key_size). It will be used as a symmetric key for encryption or signing.

- Omit the key (or pass `undefined`) if you intend to use one of the [dynamic key retrieval](#conditional-and-dynamic-key-operations) methods.

- Note that how you exchange public keys, passwords or symmetric keys with other parties is beyond the scope of this library. You might consider using something like [Diffie-Hellman](http://nodejs.org/api/crypto.html#crypto_crypto_getdiffiehellman_group_name) to exchange symmetric keys but you might also need some kind of public key infrastructure to authenticate the message. That's just an example.

- Note also that if you intend to use the same key for multiple purposes, consider using a key derivation function to derive separate keys and call [Crypt.make](#cryptmakekey-options-cb) separately for each. For examples of key derivation functions, see the following:

  - [Recommendation for Key Derivation Using Pseudorandom Functions](http://csrc.nist.gov/publications/nistpubs/800-108/sp800-108.pdf)

  - [Recommendation for Key Derivation through Extraction-then-Expansion](http://csrc.nist.gov/publications/nistpubs/800-56C/SP-800-56C.pdf)

  - [HMAC-based Extract-and-Expand Key Derivation Function](http://tools.ietf.org/html/rfc5869)

• {Object} [options] Optional settings:

- `{Boolean} json` Whether to JSON encode and decode data. Default is `true`.

- `{Boolean} base64` Whether to Base64-encode generated data and Base64-decode received data.

- `{Boolean} check` Whether to add a checksum to encrypted data and verify it when decrypting data. Default is `true`.

- `{Boolean} pad` Whether to automatically pad encrypted data (using PKCS#7) to a multiple of the AES block size (16 bytes). Default is `true`.

• {Function} [cb] Optional function called with the Crypt object. It's passed the following arguments:

- `{Object} err` If an error occurred then details of the error, otherwise `null`.

- `{Crypt} crypt` The `Crypt` object. `key` (above) is parsed using [parse_key](#cryptparse_keykey-cb) and is available using [get_key](#cryptprototypeget_key).

Return:

{Crypt} The Crypt object. It will have no key until key parsing is complete and cb is called.

Go: TOC | Crypt

Crypt.get_key_size()

Get the size (in bytes) of symmetric encryption keys. Use this value when creating keys for use with Crypt.prototype.encrypt and Crypt.prototype.decrypt.

Return:

{Number} Encryption key size.

Go: TOC | Crypt

Crypt.get_iv_size()

Get the size (in bytes) that Crypt.prototype.encrypt expects (optional) initialisation vectors to be.

Return:

{Number} Initialisation vector size.

Go: TOC | Crypt

Crypt.parse_key(key, cb)

Parse a key. Call this if you want to use the same key for multiple Crypt objects but only incur the cost of parsing it once.

Parameters:

• {String | Buffer | Object} key Key to parse. See the key parameter of Crypt.make.
• {Function} cb Function called with the parsed key. It's passed the following arguments:

- `{Object} err` If an error occurred then details of the error, otherwise `null`.

- `{String|Buffer|Object} key` Parsed key. You can pass this to [Crypt.make](#cryptmakekey-options-cb). If the key looks like a PEM-encoded RSA key then an internal RSA key object is received. If the key is an object (with `password`, `iterations` and optional `salt` properties) then an object with the following properties is received:

  - `{Object} key` An AES encryption key derived using PBKDF2-SHA-1.

  - `{Buffer|String} salt` Binary-encoded salt value which was used to derive `key`.

Go: TOC | Crypt

Crypt.prototype.get_key()

Get the key being used by this Crypt object.

Return:

{Object | Buffer | String} The key. This could be a Buffer, binary-encoded string, internal RSA key object or an object containing a key derived from a password (see parse_key).

Go: TOC | Crypt.prototype

Crypt.prototype.encrypt(data, iv, cb)

Encrypt data using AES-128-CBC and the key you passed to Crypt.make when you created this object. If you passed a (PEM-encoded) RSA public key then a random AES key is created and the public key is used to encrypt it (using RSAES-OAEP). The encrypted AES key is made available along with the encrypted data (see below).

Parameters:

• {Object | Buffer | String} data The data to be encrypted.

- If you didn't pass `options.json` as `false` to [Crypt.make](#cryptmakekey-options-cb) then the data will be JSON-serialized before it's encrypted. Otherwise, it must be a `Buffer` or binary-encoded string.

- If you didn't pass `options.check` as `false` to [Crypt.make](#cryptmakekey-options-cb) then a SHA-256 checksum is prepended to the data before it's encrypted.

- If you didn't pass `options.pad` as `false` to [Crypt.make](#cryptmakekey-options-cb) then the data will be padded to a multiple of 16 bytes.

• {Buffer | String} [iv] Optional initialisation vector (salt) to use for AES encryption. If not supplied, a random one is created. Length must be equal to get_iv_size().
• {Function} cb Function called with the result. It's passed the following arguments:

- `{Object} err` If an error occurred then details of the error, otherwise `null`.
- `{Object} result` Result of the encryption. Typically you would JSON serialize this for transmission, unless you passed `options.base64` as `false` to [Crypt.make](#cryptmakekey-options-cb) in which case `iv`, `data`, and `ekey` won't be Base64-encoded. It has the following properties:

  - `{Buffer|String} iv` Initialisation vector used for the encryption.

  - `{Buffer|String} data` Encrypted data. 

  - `{Buffer|String} ekey` Encrypted AES key (only present when using RSA public key -- see above).

  - `{Number} version` Internal version number for future compatibility checking.

Go: TOC | Crypt.prototype

Crypt.prototype.decrypt(data, cb)

Decrypt data using AES-128-CBC and the key you passed to Crypt.make when you created this object. If you passed a (PEM-encoded) RSA private key then an ekey property is expected to be present on the data parameter (below). The private key is used to decrypt the ekey in order to obtain the AES key.

Parameters:

• {Object} data A result object received from encrypt. You may have received this from another party, for instance.

- If you didn't pass `options.json` as `false` to [Crypt.make](#cryptmakekey-options-cb) then the data will be JSON-parsed after it's decrypted. Otherwise, you'll receive a `Buffer` (on Node.js) or binary-encoded string.

- If you didn't pass `options.base64` as `false` to [Crypt.make](#cryptmakekey-options-cb) then the data will be Base64-decoded before it's decrypted. 

- If you didn't pass `options.check` as `false` to [Crypt.make](#cryptmakekey-options-cb) then a SHA-256 checksum is expected to be prepended to the decrypted data. The checksum is verified against the rest of the decrypted data.

- If you didn't pass `options.pad` as `false` to [Crypt.make](#cryptmakekey-options-cb) then the decrypted data is expected to be padded to a multiple of 16 bytes and will be unpadded automatically.

• {Function} cb Function called with the result. It's passed the following arguments:

- `{Object} err` If an error occurred then details of the error, otherwise `null`.

- `{Object|Buffer|String} data` The decrypted data.

Go: TOC | Crypt.prototype

Crypt.prototype.sign(data, cb)

Sign a SHA-256 hash of some data using the key you passed to Crypt.make when you created this object. If you passed a (PEM-encoded) RSA private key then the hash is signed using RSASSA-PSS. Otherwise, HMAC-SHA-256 is used to sign the data.

Parameters:

• {Object | Buffer | String} data The data to be signed.

- If you didn't pass `options.json` as `false` to [Crypt.make](#cryptmakekey-options-cb) then the data will be JSON-serialized before it's encrypted. Otherwise, it must be a `Buffer` or binary-encoded string.

• {Function} cb Function called with the result. It's passed the following arguments:

- `{Object} err` If an error occurred then details of the error, otherwise `null`.
- `{Object} result` Result of signing the data. Typically you would JSON serialize this for transmission, unless you passed `options.base64` as `false` to [Crypt.make](#cryptmakekey-options-cb) in which case `data` and `signature` won't be Base64-encoded. It has the following properties:

  - `{Buffer|String} data` The data that was signed.

  - `{Buffer|String} signature` Signed hash of the data.

  - `{Number} version` Internal version number for future compatibility checking.

Go: TOC | Crypt.prototype

Crypt.prototype.verify(data, cb)

Verify a signature by comparing it to a signed SHA-256 hash of some data. The signed hash is generated using the key you passed to Crypt.make when you created this object. If you passed a (PEM-encoded) RSA public key then the hash is signed using RSASSA-PSS. Otherwise HMAC is used.

Parameters:

• {Object} data A result object received from sign. You may have received this from another party, for instance.

- If you didn't pass `options.json` as `false` to [Crypt.make](#cryptmakekey-options-cb) then the data will be JSON-parsed after it's verified. Otherwise, you'll receive a  `Buffer` (on Node.js) or binary-encoded string.

- If you didn't pass `options.base64` as `false` to [Crypt.make](#cryptmakekey-options-cb) then the data will be Base64-decoded before it's verified.

• {Function} cb Function called with the result. It's passed the following arguments:

- `{Object} err` If an error occurred then details of the error, otherwise `null`.

- `{Object|Buffer|String} data` The verified data.

Go: TOC | Crypt.prototype

Crypt.sign_encrypt_sign(signing_key, encryption_key, data, iv, cb)

Sign then encrypt then sign data. Convenience function which creates two Crypt objects, calls sign on the first, plumbs the result into encrypt on the second and then plumbs the result from that into sign on the first again. See this article for a discussion of why just sign then encrypt isn't good enough.

Parameters:

• {Buffer | String | Object} signing_key Key to use for signing the data.
• {Buffer | String | Object} encryption_key Key to use for encrypting the data and signature.
• {Object | Buffer | String} data The data to be signed and encrypted.
• {Buffer | String} [iv] Optional initialisation vector (salt) to use for encryption. If not supplied, a random one is created.
• {Function} cb Function called with the result. It's passed the following arguments:

- `{Object} err` If an error occurred then details of the error, otherwise `null`.
- `{Object} result` Result of signing and encrypting the data. See the description of `cb` for [sign](#cryptprototypesigndata-cb).

Go: TOC | Crypt

Crypt.verify_decrypt_verify(decryption_key, verifying_key, data, cb)

Verify then decrypt then verify data. Convenience function which creates two Crypt objects, calls verify on the first, plumbs the result into decrypt on the second and then plumbs the result from that into verify on the first again.

Parameters:

• {Buffer | String | Object} decryption_key Key to use for decrypting the data and signature.
• {Buffer | String | Object} verifying_key Key to use for verifying the signature.
• {Object} data A result object received from sign_encrypt_sign.
• {Function} cb Function called with the result. It's passed the following arguments:

- `{Object} err` If an error occurred then details of the error, otherwise `null`.

- `{Object|Buffer|String} data` The decrypted and verified data.

Go: TOC | Crypt

Crypt.prototype.maybe_encrypt(encrypt, data, cb, get_key)

Conditionally encrypt data using encrypt.

Parameters:

• {Boolean} encrypt Whether to encrypt the data.
• {Object | Buffer | String} data The data to encrypt.
• {Function} cb Function called with the result. It's passed the following arguments:

- `{Object} err` If an error occurred then details of the error, otherwise `null`.

- `{Object} result` Result object with the following properties:

  - `{Boolean} encrypted` Whether the data was encrypted.

  - `{Object} data` Encryption result (data, initialisation vector etc) if the data was encrypted, otherwise the data.

  - `{Object} [key_data]` If the data was encrypted and `get_key` was called (see below) then this is the key data received from `get_key`.

• {Function} [get_key] Optional function to call in order to get the encryption key. You must supply this if you didn't supply a key when creating the Crypt object. get_key is called with the following arguments:

- The arguments to `maybe_encrypt` that follow `get_key` (if any).

- `{Function} got_key` Function to call with the key. You should call it with the following arguments:

  - `{Object} err` If an error occurred then details of the error, otherwise `null`.

  - `{Object|Buffer|String} key` The encryption key. If this is a falsey value then the data won't be encrypted.

  - `{Object} [key_data]` Optional metadata for the key. This is included in the result (see above).

  - `{Buffer|String} [iv]` Optional initialisation vector.

Go: TOC | Crypt.prototype

Crypt.prototype.maybe_decrypt(data, cb, get_key)

Conditionally decrypt data using decrypt.

Parameters:

• {Object} data A result object received from maybe_encrypt.
• {Function} cb Function called with the result. It's passed the following arguments:

- `{Object} err` If an error occurred then details of the error, otherwise `null`.

- `{Object|Buffer|String} data` If the data was encrypted then the decrypted data otherwise the data.

• {Function} [get_key] Optional function to call in order to get the encryption key. You must supply this if you didn't supply a key when creating the Crypt object. get_key is called with the following arguments:

- The arguments to `maybe_decrypt` that follow `get_key` (if any).

- `{Function} got_key` Function to call with the key. You should call it with the following arguments:

  - `{Object} err` If an error occurred then details of the error, otherwise `null`.

  - `{Object|Buffer|String} key` The decryption key.

- `{Object} [key_data]` Metadata for the key which was supplied in [maybe_encrypt](#cryptprototypemaybe_encryptencrypt-data-cb-get_key) (if any).

Go: TOC | Crypt.prototype

Crypt.prototype.maybe_sign(sign, data, cb, get_key)

Conditionally sign data using sign.

Parameters:

• {Boolean} sign Whether to sign the data.
• {Object | Buffer | String} data The data to sign.
• {Function} cb Function called with the result. It's passed the following arguments:

- `{Object} err` If an error occurred then details of the error, otherwise `null`.

- `{Object} result` Result object with the following properties:

  - `{Boolean} signed` Whether the data was signed.

  - `{Object} data` Signing result (data, signature etc) if the data was signed, otherwise the data.

  - `{Object} [key_data]` If the data was signed and `get_key` was called (see below) then this is the key data received from `get_key`.

• {Function} [get_key] Optional function to call in order to get the signing key. You must supply this if you didn't supply a key when creating the Crypt object. get_key is called with the following arguments:

- The arguments to `maybe_sign` that follow `get_key` (if any).

- `{Function} got_key` Function to call with the key. You should call it with the following arguments:

  - `{Object} err` If an error occurred then details of the error, otherwise `null`.

  - `{Object|Buffer|String} key` The signing key. If this is a falsey value then the data won't be signed.

  - `{Object} [key_data]` Optional metadata for the key. This is included in the result (see above).

Go: TOC | Crypt.prototype

Crypt.prototype.maybe_verify(data, cb, get_key)

Conditionally verify data using verify.

Parameters:

• {Object} data A result object received from maybe_sign.
• {Function} cb Function called with the result. It's passed the following arguments:

- `{Object} err` If an error occurred then details of the error, otherwise `null`.

- `{Object|Buffer|String} data` If the data was signed then the verified data otherwise the data.

• {Function} [get_key] Optional function to call in order to get the verifying key. You must supply this if you didn't supply a key when creating the Crypt object. get_key is called with the following arguments:

- The arguments to `maybe_verify` that follow `get_key` (if any).

- `{Function} got_key` Function to call with the key. You should call it with the following arguments:

  - `{Object} err` If an error occurred then details of the error, otherwise `null`.

  - `{Object|Buffer|String} key` The verifying key.

- `{Object} [key_data]` Metadata for the key which was supplied in [maybe_sign](#cryptprototypemaybe_signsign-data-cb-get_key) (if any).

Go: TOC | Crypt.prototype

Crypt.encrypt_stream(key, s, options, cb)

Encrypt a stream of data.

Each chunk in the stream is encrypted separately, along with the hash of the preceding chunk.

Parameters:

• {Buffer | String | Object} key Key to use for encryping the data in the stream.
• {Readable} s The stream.Readable to encrypt.
• {Object} [options] Options for frame.encode.
• {Function} cb Function called with the encrypted stream. It's passed the following arguments:

- `{Object} err` If an error occurred then details of the error, otherwise `null`.

- `{Readable} enc_s` The encrypted data stream. Any encryption errors will be emitted as `error` events on `enc_s`.

Go: TOC | Crypt

Crypt.decrypt_stream(key, s, options, cb)

Decrypt a stream of data.

Parameters:

• {Buffer | String | Object} key Key to use for decrypting the data in the stream.
• {Readable} s The encrypted stream.Readable to decrypt.
• {Object} [options] Options for frame.decode.
• {Function} cb Function called with the decrypted stream. It's passed the following arguments:

- `{Object} err` If an error occurred then details of the error, otherwise `null`.

- `{Readable} dec_s` The decrypted data stream. Any decryption errors will be emitted as `error` events on `dec_s`.

Go: TOC | Crypt

Crypt.sign_stream(key, s, options, cb)

Sign a stream of data.

Each chunk in the stream is signed separately, along with the hash of the preceding chunk.

Parameters:

• {Buffer | String | Object} key Key to use for signing the data in the stream.
• {Readable} s The stream.Readable to sign.
• {Object} [options] Options for frame.encode.
• {Function} cb Function called with the signed stream. It's passed the following arguments:

- `{Object} err` If an error occurred then details of the error, otherwise `null`.

- `{Readable} sig_s` The signed data stream. Any signing errors will be emitted as `error` events on `sig_s`.

Go: TOC | Crypt

Crypt.verify_stream(key, s, options, cb)

Verify a stream of data.

Parameters:

• {Buffer | String | Object} key Key to use for verifying the data in the stream.
• {Readable} s The signed stream.Readable to verify.
• {Object} [options] Options for frame.decode.
• {Function} cb Function called with the verified stream. It's passed the following arguments:

- `{Object} err` If an error occurred then details of the error, otherwise `null`.

- `{Readable} ver_s` The verified data stream. Any verification errors will be emitted as `error` events on `ver_s`.

Go: TOC | Crypt

Crypt.sign_encrypt_sign_stream(signing_key, encryption_key, s, options, cb)

Sign then encrypt then sign a stream of data.

Parameters:

• {Buffer | String | Object} signing_key Key to use for signing the data in the stream.
• {Buffer | String | Object} encryption_key Key to use for encryping the data in the stream.
• {Readable} s The stream.Readable to sign and encrypt.
• {Object} [options] Options for frame.encode.
• {Function} cb Function called with the signed and encrypted stream. It's passed the following arguments:

- `{Object} err` If an error occurred then details of the error, otherwise `null`.

- `{Readable} sig_enc_s` The signed and encrypted data stream. Any signing or encryption errors will be emitted as `error` events on `sig_enc_s`.

Go: TOC | Crypt

Crypt.verify_decrypt_verify_stream(decryption_key, verifying_key, s, options, cb)

Verify then decrypt then verify a stream of data.

Parameters:

• {Buffer | String | Object} decryption_key Key to use for decrypting the data in the stream.
• {Buffer | String | Object} verifying_key Key to use for verifying the data in the stream.
• {Readable} s The signed and encrypted stream.Readable to verify and decrypt.
• {Object} [options] Options for frame.decode.
• {Function} cb Function called with the verified and decrypted stream. It's passed the following arguments:

- `{Object} err` If an error occurred then details of the error, otherwise `null`.

- `{Readable} ver_dec_s` The verified and decrypted data stream. Any verification or decryption errors will be emitted as `error` events on `ver_dec_s`.

Go: TOC | Crypt

—generated by apidox—