Crypto

Hash, HMAC, encrypt, and decrypt inside the sandbox.

D.crypto.Cipher.final

Returns any remaining enciphered contents.
If no encoding is provided, then a Buffer is returned.

Once the cipher.final() method has been called, the Cipher object can no longer be used to encrypt data.
Attempts to call cipher.final() more than once will result in an error being thrown.

Signature

D.crypto.Cipher.final([outputEncoding])

Parameters

outputEncoding · `binary` | `base64` | `hex` · optional: The encoding of the return value.
Can be 'binary', 'base64' or 'hex'.
If no encoding is provided, then a buffer is returned.

Returns

string | Buffer — - Any remaining enciphered contents

Example

D.crypto.createCipher('sha1', 'key', 'initialization vector').final('binary')

D.crypto.Cipher.setAutoPadding

When using block encryption algorithms, the Cipher class will automatically add padding to the input data to the appropriate block size.

To disable the default padding call cipher.setAutoPadding(false).
When autoPadding is false, the length of the entire input data must be a multiple of the cipher’s block size or cipher.final() will throw an error.
Disabling automatic padding is useful for non-standard padding, for instance using 0x0 instead of PKCS padding.

The cipher.setAutoPadding() method must be called before cipher.final().

Signature

D.crypto.Cipher.setAutoPadding([autoPadding])

Parameters

autoPadding · `bool` · optional, default `true`: The auto padding boolean flag.

Returns

void

Example

D.crypto.createCipher('sha1', 'key', 'initialization vector').setAutoPadding(false)

D.crypto.Cipher.update

Updates the cipher with data.
The cipher.update() method can be called multiple times with new data until cipher.final() is called.
Calling cipher.update() after cipher.final() will result in an error being thrown.

Input Encoding options:

If the inputEncoding argument is given, the data argument is a string using the specified encoding.
If the inputEncoding argument is not given, data must be a Buffer.

Output Encoding options:

If the outputEncoding is specified, a string using the specified encoding is returned.
If no outputEncoding is provided, a Buffer is returned.

Signature

D.crypto.Cipher.update(data, [inputEncoding], [outputEncoding])

Parameters

data · `string` | `Buffer`: The data object.
inputEncoding · `binary` | `ascii` | `utf8` · optional: The encoding of the data.
If data is a Buffer this argument is ignored.
outputEncoding · `binary` | `base64` | `hex` · optional: The encoding of the return value.
The output encoding specifies the output format of the enciphered data, and can be 'binary', 'base64' or 'hex'.
If no encoding is provided, then a buffer is returned.

Returns

string | Buffer — - Returns the enciphered contents, and can be called many times with new data as it is streamed.

Example

D.crypto.createCipher('sha1', 'key', 'initialization vector').update('data', 'binary', 'binary')

D.crypto.Decipher.final

Returns any remaining plaintext which is deciphered.
If outputEncoding is specified, a string is returned. If an outputEncoding is not provided, a Buffer is returned.

Once the decipher.final() method has been called, the Decipher object can no longer be used to decrypt data.
Attempts to call decipher.final() more than once will result in an error being thrown.

Signature

D.crypto.Decipher.final([outputEncoding])

Parameters

outputEncoding · `binary` | `base64` | `hex` · optional: The outputEncoding specifies the output format of the enciphered data, and can be 'binary', 'base64' or 'hex'.
If no encoding is provided, then a buffer is returned.

Returns

string | Buffer — - Any remaining deciphered data

Example

D.crypto.createDecipher('sha1', 'key', 'initialization vector').final('binary')

D.crypto.Decipher.setAutoPadding

When data has been encrypted without standard block padding, calling decipher.setAutoPadding(false) will disable automatic padding to prevent decipher.final() from checking for and removing padding.
Turning auto padding off will only work if the input data’s length is a multiple of the cipher’s block size.

The decipher.setAutoPadding() method must be called before decipher.final().

Signature

D.crypto.Decipher.setAutoPadding([autoPadding])

Parameters

autoPadding · `bool` · optional, default `true`: The auto padding boolean flag.

Returns

void

Example

D.crypto.createDecipher('sha1', 'key', 'initialization vector').setAutoPadding(false)

D.crypto.Decipher.update

Updates the decipher with data.
The decipher.update() method can be called multiple times with new data until decipher.final() is called.
Calling decipher.update() after decipher.final() will result in an error being thrown.

Input Encoding options:

If the inputEncoding argument is given, the data argument is a string using the specified encoding.
If the inputEncoding argument is not given, data must be a Buffer.
If data is a Buffer then inputEncoding is ignored.

Output Encoding options:

If the outputEncoding is specified, a string using the specified encoding is returned.
If no outputEncoding is provided, a Buffer is returned.

Signature

D.crypto.Decipher.update(data, [inputEncoding], [outputEncoding])

Parameters

data · `string` | `Buffer`: The data object.
inputEncoding · `binary` | `ascii` | `utf8` · optional: The encoding of the data string.
If data is a Buffer this argument is ignored.
outputEncoding · `binary` | `base64` | `hex` · optional: The encoding of the return value.
The output encoding specifies the output format of the enciphered data, and can be 'binary', 'base64' or 'hex'.
If no encoding is provided, then a buffer is returned.

Returns

string | Buffer — - Returns the deciphered data

Example

D.crypto.createDecipher('sha1', 'key', 'initialization vector').update('data', 'binary', 'binary')

D.crypto.createCipher

Creates a Cipher object using the given algorithm and a raw key. The returned object implements the Cipher contract — repeated update() calls followed by a single final() call produce the ciphertext. For passphrase-derived keys prefer pbkdf2Sync over passing the passphrase directly. This is a wrapper of the node’s crypto library ‘crypto.createCipheriv’.
For more information check the official node documentation:
https://nodejs.org/docs/latest-v14.x/api/crypto.html#crypto_crypto_createcipheriv_algorithm_key_iv_options

Signature

D.crypto.createCipher(algorithm, key, initializationVector)

Parameters

algorithm · `string`: The algorithm is dependent on the available algorithms supported by the version of OpenSSL on the agent's host platform. Examples are 'sha1', 'md5', 'sha256', 'sha512', 'aes192', etc
key · `string` | `Buffer`: The key to be used. Must be 'binary' encoded strings or buffers.
initializationVector · `string` | `Buffer`: The initialization vector. Must be 'binary' encoded strings or buffers.

Returns

Cipher

Example

// returns the Cipher object
D.crypto.createCipher('aes-128-ecb', 'the key', 'the initialization vector')

D.crypto.createDecipher

Creates a Decipher object using the given algorithm and raw key. Mirror of createCipher. Inputs are the ciphertext buffer via repeated update() calls and one final(); outputs are the decrypted plaintext. This is a wrapper of the node’s crypto library ‘crypto.createDecipheriv’.
For more information check the official node documentation:
https://nodejs.org/docs/latest-v14.x/api/crypto.html#crypto_crypto_createdecipheriv_algorithm_key_iv_options

Signature

D.crypto.createDecipher(algorithm, key, initializationVector)

Parameters

algorithm · `string`: The algorithm is dependent on the available algorithms supported by the version of OpenSSL on the agent's host platform. Examples are 'sha1', 'md5', 'sha256', 'sha512', 'aes192', etc
key · `string` | `Buffer`: The key to be used. Must be 'binary' encoded strings or buffers.
initializationVector · `string` | `Buffer`: The initialization vector. Must be 'binary' encoded strings or buffers.

Returns

Decipher

Example

// returns the Decipher object
D.crypto.createDecipher('aes-128-ecb', 'the key', 'the initialization vector')

D.crypto.hash

Computes a one-shot cryptographic hash of a string with the named algorithm (for example sha256, sha1, md5) and returns the digest hex-encoded.

Signature

D.crypto.hash(data, algorithm, [inputEncoding], [outputEncoding])

Parameters

data · `string` | `Buffer`: The data object.
If data is a Buffer then inputEncoding is ignored.
algorithm · `string`: The cipher algorithm is dependent on the available algorithms supported by the version of OpenSSL on the agent's host platform.
Examples are 'sha1', 'md5', 'sha256', 'sha512', 'aes192', etc
inputEncoding · `binary` | `ascii` | `utf8` · optional: The encoding of the data string.
outputEncoding · `binary` | `base64` | `hex` · optional: The encoding of the return value.
If no encoding is provided, then a buffer is returned.

Returns

string | Buffer

Example

// returns '4130d2b39ca35eaf4cb95fc846c21ee6a39af698154a83a586ee270a0d372139' for the generated hash digest with 'utf8' input encoding and 'hex' output encoding.
D.crypto.hash('my data', 'sha256', 'utf8', 'hex')

D.crypto.hmac

Computes a one-shot HMAC of a string with the named algorithm and key. Returns the digest hex-encoded. Use HMAC (not raw hash) when you need integrity guarantees against an attacker who can modify the message.

Signature

D.crypto.hmac(data, key, algorithm, [outputEncoding])

Parameters

data · `string`: The data string
key · `string`: The HMAC key to be used.
algorithm · `string`: The cipher algorithm is dependent on the available algorithms supported by the version of OpenSSL on the agent's host platform.
Examples are 'sha1', 'md5', 'sha256', 'sha512', 'aes192', etc
outputEncoding · `binary` | `base64` | `hex` · optional: The output encoding.
If no encoding is provided, then a buffer is returned.

Returns

string | Buffer

Example

// returns '049f32be4f33a698204529818c1b676d460c9cb2f6901457d012a6646127ae31' for the generated HMAC digest with hex output encoding
D.crypto.hmac('my data', 'my secret', 'sha256', 'hex')

D.crypto.pbkdf2Sync

Synchronous PBKDF2 (Password-Based Key Derivation Function). Returns the derived key as a Buffer or throws an error.

Note: the sandbox wrapper always uses HMAC-SHA1 as the underlying digest. Node’s digest argument is not exposed.

Signature

D.crypto.pbkdf2Sync(password, salt, iterations, keyLength)

Parameters

password · `string`: The password
salt · `string`: The random bit of data added to the password before it is run through the hashing algorithm.
iterations · `integer`: The number of iterations for the key and salt mixing. Higher iteration counts make guessing the key harder.
keyLength · `integer`: The number of output bytes to be used for the algorithm.

Returns

Buffer — - Derived key

Example

var key = D.crypto.pbkdf2Sync('my-password', 'salt-bytes', 10000, 32);