crypto module
The crypto module offers a set of APIs for cryptographic usage. It provides the hash, HMAC, cipher, decipher, sign, and verify methods.
To access the functions in the crypto
module, use the
require('crypto')
statement.
crypto.createHash()
Creates and returns a hash
object, a cryptographic hash with the
algorithm that is used to generate hash digests.
Syntax
crypto.createHash(algorithm)
algorithm | The case-sensitive name of the algorithm to use. |
sha1
sha256
sha512
sha224
sha384
ripemd160
md5
Example
sha256
algorithm to hash the data read from the input context. The
hash result is 'base64'
encoded.var crypto = require('crypto');
session.input.readAsBuffer(function(error, data) {
if (error) {
console.error("readAsBuffer error "+error);
} else {
var hash = crypto.createHash('sha256');
var result = hash.update(data).digest('base64');
session.output.write(result);
}
});
crypto.getHashes()
Returns an array with the names of the supported hash algorithms.
Syntax
crypto.getHashes()
hash.digest()
Calculates the digest of all of the passed data to be hashed.
Syntax
hash.digest([output_encoding])
output_encoding | The encoding of the digested result. |
'hex'
or 'base64'
. If no encoding is
provided, then a Buffer is returned. The hash
object cannot be used after the
digest() method is called.hash.update()
Updates the hash content with the data, the encoding of which is given in input encoding. This method can be called several times.
Syntax
hash.update(data[, input_encoding])
data | The data that is being digested. |
input_encoding | The encoding of the data. |
'utf8'
or
'ascii'
. If no encoding is provided and the input is a string, an encoding of
'utf8'
is enforced. If data is a Buffer or Buffers, then input encoding is
ignored.crypto.createHmac()
Creates and returns a hmac
object, which is a cryptographic HMAC with
the algorithm and key.
Syntax
crypto.createHmac(algorithm, key)
algorithm | The case-sensitive name of the algorithm to use. |
key | The shared secret key that is used by the algorithm to encrypt text. |
hmac-
prefix-naming
is the same as the one without the prefix. In other words, hmac-sha1
is the same as
sha1
.hmac-sha1
orsha1
hmac-sha256
orsha256
hmac-sha512
orsha512
hmac-sha224
orsha224
hmac-sha384
orsha384
hmac-ripemd160
orripemd160
hmac-md5
ormd5
- A string object that refers to a configured object that also supports prefix usage in XSLT.
- A Buffer or Buffers object that contains base64 encoded data of a key.
- An Object.
- A symmetric key whose JWK
'kty'
member value is'oct'
.
For more information about formats when defining a key object, see Key object usage.
Example
hmac-sha256
algorithm and the shared secret key object that is named
Alice
to do the HMAC. The result is 'base64'
encoded.var crypto = require('crypto');
var key = "Alice";
var hmac = crypto.createHmac('hmac-sha256', key);
var input = "This is plaintext to hash";
var result = hmac.update(input).digest('base64');
session.output.write(result);
hmac.digest()
Calculates the digest of all of the passed data to the HMAC.
Syntax
hmac.digest([output_encoding])
output_encoding | The encoding of the digested result. |
'hex'
or 'base64'
. If no encoding is
provided, then a Buffer is returned. The hmac
object cannot be used after the
digest() method is called.hmac.update()
Updates the content of the hmac
object with the data, the encoding of
which is given in input encoding. This method can be called several times.
Syntax
hmac.update(data[, input_encoding])
data | The data that is being digested. |
input_encoding | The encoding of the data. |
'utf8'
or
'ascii'
. If no encoding is provided and the input is a string, an encoding of
'utf8'
is enforced. If data is a Buffer or Buffers, then input encoding is
ignored.cipher.final()
Returns the enciphered contents.
Syntax
cipher.final([encoding])
encoding | The encoding of the data. |
'base64'
or
'hex'
. If no encoding is provided, then a Buffer is returned. The cipher object
cannot be used after the final()
method is called.cipher.getAuthTag()
Returns a Buffer object that represents the authentication tag that is computed from the data.
Syntax
cipher.getAuthTag()
cipher.getIV()
Returns the IV for the cipher object.
Syntax
cipher.getIV()
createCipheriv()
, then the returning IV is
identical. The returned value is a Buffer object.cipher.setAAD()
Sets the value that is used for the additional authenticated data (AAD) input parameter.
Syntax
cipher.setAAD(buffer)
cipher.setAutoPadding()
The automatic padding of the input data.
Syntax
cipher.setAutoPadding(auto_padding=true)
final()
fails. You must call this method before
cipher.final().cipher.update()
Updates the cipher with data.
Syntax
cipher.update(data[, encoding])
data | The data that is being updated. |
encoding | The encoding of the data. |
'utf8'
or 'ascii'
.
If no encoding is provided, then a Buffer is expected. If data is a Buffer, then
encoding is ignored.crypto.createCipheriv()
Creates and returns a cipher object, with the selected algorithm, key, and initialization vector.
Syntax
crypto.createCipheriv(algorithm, key, iv)
algorithm | The case-sensitive name of the algorithm to use. |
key | The shared secret key that is used by the algorithm to encrypt text. |
iv | The initialization vector (IV). |
aes128-cbc
aes192-cbc
aes256-cbc
tripledes-cbc
A128CBC-HS256
A192CBC-HS384
A256CBC-HS512
A128GCM
A192GCM
A256GCM
The A128CBC-HS256
, A192CBC-HS384
, and
A256CBC-HS512
algorithms need to be Encrypt-then-MAC.
- A string object that refers to a configured object that also supports prefix usage in XSLT.
- A Buffer or Buffers object that contains the base64 encoded data of a key.
- An Object.
- A symmetric key whose JWK
'kty'
member value is'oct'
.
For more information about formats when defining a key object, see Key object usage.
The iv must be a Buffer and is optional. If it does not present, an auto-generated IV is used. In this case, getIV() returns an auto-generated IV.
A128CBC-HS256
Encrypt-then-MAC algorithm to do a cipher. The IV is
auto-generated and needed when you are doing the
decipher.var crypto = require('crypto');
var cipher = crypto.createCipheriv('A128CBC-HS256', 'alice');
var aad = new Buffer('additional authentication data');
cipher.setAAD(aad);
cipher.update('this is the plaintext that needs to be encrypted');
cipher.update('second part');
var encipherData = cipher.final();
var authTag = cipher.getAuthTag();
var iv = cipher.getIV();
crypto.getCiphers()
Returns an array with the names of the supported ciphers.
Syntax
crypto.getCiphers()
crypto.createDecipheriv()
Creates and returns a decipher object with the selected algorithm, key, and initialization vector.
Syntax
crypto.createDecipheriv(algorithm, key, iv)
algorithm | The case-sensitive name of the algorithm to use. |
key | The shared secret key that is used by the algorithm to encrypt text. |
iv | The initialization vector. |
aes128-cbc
aes192-cbc
aes256-cbc
tripledes-cbc
A128CBC-HS256
A192CBC-HS384
A256CBC-HS512
A128GCM
A192GCM
A256GCM
The A128CBC-HS256
, A192CBC-HS384
, and
A256CBC-HS512
algorithms need to be Encrypt-then-MAC.
- A string object that refers to a configured object that also supports prefix usage in XSLT.
- A Buffer or Buffers object that contains the base64 encoded data of a key.
- An Object.
- A symmetric key whose JWK
'kty'
member value is'oct'
.
For more information about formats when defining a key object, see Key object usage.
The iv must be a Buffer.
Using the aes192-cbc
algorithm to decipher data.
var decipher = crypto.createDecipheriv('aes192-cbc', 'alice', iv);
decipher.update(encipherData);
var originalPlainText = decipher.final();
decipher.final()
Returns the deciphered plaintext.
Syntax
decipher.final([encoding])
encoding | The encoding of the data. |
'ascii'
or
'utf8'
. If no encoding is provided, then a Buffer is returned.Note: The decipher object cannot be used after the final() method is called.
decipher.setAAD()
Sets the value that is used for the AAD input parameter.
Syntax
decipher.setAAD(buffer)
decipher.setAuthTag()
Passes in the received authentication tag.
Syntax
decipher.setAuthTag(buffer)
decipher.setAutoPadding()
The automatic padding of the input data.
Syntax
decipher.setAutoPadding(auto_padding=true)
decipher.update()
Updates the decipher with data.
Syntax
decipher.update(data[, encoding])
data | The data that is being updated. |
encoding | The encoding of the data. |
'base64'
or
'hex'
. If no encoding is provided, then a Buffer is expected. If
data is a Buffer, then encoding is ignored.crypto.createSign()
Creates and returns a signing object, with the selected algorithm.
Syntax
crypto.createSign(algorithm)
algorithm | The case-sensitive name of the algorithm to use. |
dsa-sha1
rsa-sha1
rsa-sha256
rsa-sha512
rsa-sha384
rsa-ripemd160
rsa-md5
ecdsa-sha1
ecdsa-sha256
ecdsa-sha384
ecdsa-sha512
rsassa-pss-ps256
orPS256
rsassa-pss-ps384
orPS384
rsassa-pss-ps512
orPS512
The crypto sign API is general purpose and uses an asymmetric key (public/private) mechanism to generate the signature. It does not include a symmetric key sign.
Example
rsa-sha256
algorithm and the private key object that is named Alice to
generate a
signature.var crypto = require('crypto');
var key = "Alice";
var sign = crypto.createSign('rsa-sha256');
sign.update('This is text to sign').sign(key, function(error, signature) {
if (error) {
console.error("sign error "+error);
} else {
console.log("signature with rsa-sha256 is "+signature.toString('base64'));
session.output.write(signature);
}
});
sign.sign()
Calculates the signature on all the updated data that is passed through the sign object.
Syntax
sign.sign(key[, output_encoding], function(error, signature) {...})
key | The private key that is used to encrypt the data to generate the digital signature. |
output_encoding | The encoding of the signature. |
error | The error information if an error occurs. |
signature | The final result of digital signature. |
- A string object that refers to a configured object that also supports prefix usage in XSLT.
- A Buffer or Buffers object that contains the PEM formatted base64 encoded data of a key.
- An Object.
- An RSA private key in JWK form whose
'kty'
member value is'RSA'
. - An elliptic curve private key in JWK form whose
'kty'
member value is'EC'
.
For more information about formats when defining a key object, see Key object usage.
The output_encoding can 'hex'
or 'base64'
.
If no encoding is provided, then a Buffer is returned.
The error is an instance of the GatewayScript error object. If no error occurs, the error variable is null.
The signature is the final result of the digital signature. The signature type must be string or Buffer, which is based on the output_encoding value. If no encoding is provided, then a Buffer is returned. If an error occurs, the signature is null.
The sign object cannot be used after the sign() method is called.
sign.update()
Updates the sign object with the data. This method can be called several times.
Syntax
sign.update(data[, input_encoding])
data | The data that is being signed. |
input_encoding | The encoding of the data. |
'utf8'
is enforced. If data is a
Buffer or Buffers, then input encoding is ignored. The input_encoding must be
'utf8'
or 'ascii'
.crypto.createVerify()
Creates and returns a verification object, with the selected algorithm.
Syntax
crypto.createVerify(algorithm)
algorithm | The case-sensitive name of the algorithm to use. |
dsa-sha1
rsa-sha1
rsa-sha256
rsa-sha512
rsa-sha384
rsa-ripemd160
rsa-md5
ecdsa-sha1
ecdsa-sha256
ecdsa-sha384
ecdsa-sha512
rsassa-pss-ps256
orPS256
rsassa-pss-ps384
orPS384
rsassa-pss-ps512
orPS512
The crypto verify API is general purpose and is using an asymmetric key (public/private) mechanism to verify the signature. It does not include a symmetric key verify.
Example
rsa-sha256
algorithm and the certificate object that is named Alice to
verify the signature that is read from the input
context.var crypto = require('crypto');
var key = "Alice";
session.input.readAsBuffer(function(error, buffer) {
if (error) {
console.error("readAsBuffer error: "+error);
} else {
var verify = crypto.createVerify('rsa-sha256');
verify.update('This is text to sign').verify(key, buffer, function(error) {
if (error) {
console.error("verification fail: "+error);
}
});
}
});
verify.update()
Updates the verification object with the data. This method can be called several times.
Syntax
verify.update(data[, input_encoding])
data | The data that is being verified. |
input_encoding | The encoding of the data. |
'utf8'
is enforced. If data is a
Buffer or Buffers, then input encoding is ignored. The input_encoding must be
'utf8'
or 'ascii'
. verify.verify()
Verifies the digital signature.
Syntax
verify.verify(key, signature[, signature_encoding], function(error) {...})
key | The key object that is used to verify the signature. |
signature | The previously calculated signature for the data. |
signature_encoding | The encoding of the signature. |
error | The error information if an error occurs. |
- A string object that refers to a configured object that also supports prefix usage in XSLT.
- A Buffer or Buffers object that contains base64 encoded data of a key.
- An Object.
- An RSA public key in JWK form whose
'kty'
member value is'RSA'
. - An elliptic curve public key in JWK form whose
'kty'
member value is'EC'
.
For more information about formats when defining a key object, see Key object usage.
The signature must be a string, Buffer, or Buffers. If no encoding is provided
and the signature is a string, an encoding of 'base64'
is enforced. If signature is
a Buffer or Buffers, then signature encoding is ignored.
The signature_encoding must be 'hex'
or
'base64'
.
The error is an instance of the GatewayScript error object. If the
verify()
call succeeds, the error variable is null.
The verify object cannot be used after the verify() method is called.
crypto.randomBytes()
Generates random cryptographic bytes
Syntax
crypto.randomBytes(size[, function (error, buffer)])
size | The number of bytes of the generated bits. |
function | An asynchronous callback function. This is optional |
error | The error information if an error occurs. |
buffer | The generated random cryptographic bytes. |
The size must be a value in the range 1 - 2000000000.
The function passes random bytes in an asynchronous way. Otherwise, the random bytes are the function's return value.
The error happens if random byte generation is not able to perform. If callback does not present, an exception is thrown. Otherwise, the error is passed into callback function.
Examples
- Asynchronous
crypto.randomBytes(256, function(ex, buf) { if (ex) throw ex; console.log('Have %d bytes of random data: %s', buf.length, buf); });
- Synchronous
try { var buf = crypto.randomBytes(256); console.log('Have %d bytes of random data: %s', buf.length, buf); } catch (ex) { // handle error }