crypto module

The crypto module offers a set of APIs for cryptographic usage. It provides the hash, HMAC, cipher, decipher, sign, and verify APIs.

To access the functions in the crypto module, use the require('crypto') statement.

APIs to create hash digests.
APIs to create cryptographic HMAC content.
APIs to encrypt data.
APIs to decrypt data.
APIs to generate signatures.
APIs to verify signatures.
Utility APIs.

cipher.final()

Returns the enciphered contents.

Syntax
cipher.final([encoding])
Parameters
encoding
The encoding of the data. The encoding must be '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()
Guidelines
This API is for authenticated encryption modes. The encryption mode must be Encrypt-then-MAC and called after the encryption from the final() API is complete.

cipher.getIV()

Returns the IV for the cipher object.

Syntax
cipher.getIV()
Guidelines
If the IV is passed in createCipheriv(), the returned 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)
Guidelines
This API is for authenticated encryption modes. The encryption mode must be Encrypt-then-MAC. The data type can be a Buffer or Buffers object.

cipher.setAutoPadding()

The automatic padding of the input data.

Syntax
cipher.setAutoPadding(auto_padding=true)
cipher.setAutoPadding(auto_padding=false)
Guidelines
You can disable automatic padding of the input data to block size. If auto_padding=false, the length of the entire input data must be a multiple of the cipher's block size or final() fails. You must call this API before cipher.final().

cipher.update()

Updates the cipher with data.

Syntax
cipher.update(data[,encoding])
Parameters
data
The data to update.
encoding
The encoding of the data. The encoding must be '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)
Parameters
algorithm
The case-sensitive name of the algorithm to use. The following values for the algorithm are supported.
  • 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.

key
The shared secret key to encrypt text. The key must be.
  • 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'.

To create a key object, see Key object usage.

iv
The initialization vector (IV). The IV must be a Buffer. If it does not present, an auto-generated IV is used. In this case, getIV() returns an auto-generated IV.
Example
Use the A128CBC-HS256 Encrypt-then-MAC algorithm to do a cipher. The IV is auto-generated and needed for the decipher object.
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.createDecipheriv()

Creates and returns a decipher object with the selected algorithm, key, and initialization vector.

Syntax
crypto.createDecipheriv(algorithm,key,iv)
Parameters
algorithm
The case-sensitive name of the algorithm to use. The following values for the algorithm are supported.
  • 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.

key
The shared secret key to encrypt text. The key must be.
  • 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'.

To create a key object, see Key object usage.

iv
The initialization vector (IV). The IV must be a Buffer. If it does not present, an auto-generated IV is used. In this case, getIV() returns an auto-generated IV.
Example
Use the aes192-cbc algorithm to decipher data.
var decipher = crypto.createDecipheriv('aes192-cbc', 'alice', iv); 
decipher.update(encipherData);
var originalPlainText = decipher.final();

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)
Parameters
algorithm
The case-sensitive name of the algorithm to use.
The following values for the algorithm are supported.
  • sha1
  • sha256
  • sha512
  • sha224
  • sha384
  • ripemd160
  • md5
Example
Using the 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.createHmac()

Creates and returns a hmac object, which is a cryptographic HMAC with the algorithm and key.

Syntax
crypto.createHmac(algorithm,key)
Parameters
algorithm
The case-sensitive name of the algorithm to use. The following values for the algorithm are supported. The hmac- prefix-naming is the same as the one without the prefix. In other words, hmac-sha1 is the same as sha1.
  • hmac-sha1 or sha1.
  • hmac-sha256 or sha256.
  • hmac-sha512 or sha512.
  • hmac-sha224 or sha224.
  • hmac-sha384 or sha384.
  • hmac-ripemd160 or ripemd160.
  • hmac-md5 or md5.
key
The shared secret key that to encrypt text. The key must be.
  • 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, see Key object usage.
Example
Use the hmac-sha256 algorithm and the Alice shared secret key object 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);

crypto.createSign()

Creates and returns a signing object, with the selected algorithm.

Syntax
crypto.createSign(algorithm)
Parameters
algorithm
The case-sensitive name of the algorithm to use. The following values for the algorithm are supported.
  • 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 or PS256.
  • rsassa-pss-ps384 or PS384.
  • rsassa-pss-ps512 or PS512.
Guidelines
This API is general purpose and uses an asymmetric key (public-private) mechanism to generate the signature. This API does not include a symmetric key sign.
Example
Use 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);
  }
});

crypto.createVerify()

Creates and returns a verification object, with the selected algorithm.

Syntax
crypto.createVerify(algorithm)
Parameters
algorithm
The case-sensitive name of the algorithm to use. The following values for the algorithm are supported.
  • 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 or PS256.
  • rsassa-pss-ps384 or PS384.
  • rsassa-pss-ps512 or PS512.
Guidelines
The 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 to verify.
Example
Use the 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);
      }
    });
  }
});

crypto.getCiphers()

Returns an array with the names of the supported ciphers.

Syntax
crypto.getCiphers()

crypto.getHashes()

Returns an array with the names of the supported hash algorithms.

Syntax
crypto.getHashes()

crypto.randomBytes()

Generates random cryptographic bytes.

Syntax
crypto.randomBytes(size[,function(error,buffer)])
Parameters
size
The number of bytes of the generated bits. Use a value in the range 1 - 2000000000.
error
The error information if an error occurs. An error occurs if random byte generation fails. If the callback does not present, an exception is raised. Otherwise, the error is passed into callback function.
buffer
The generated random cryptographic bytes.
Examples
  • Asynchronously generate random bytes.
    crypto.randomBytes(256,function(ex,buf){
  if (ex) throw ex;
  console.log('Have %d bytes of random data: %s', buf.length, buf);
});
  • Synchronously generate random bytes.
    try {
  var buf = crypto.randomBytes(256);
  console.log('Have %d bytes of random data: %s', buf.length, buf);
} catch (ex) {
  // handle error
}

crypto.randomUUID()

Generates a 128-bit UUID.

Syntax
crypto.randomBytes()
Guidelines
This method generates a random version 4 UUID (Universal Unique Identifier) per RFC 4122.

decipher.final()

Returns the deciphered plain text.

Syntax
decipher.final([encoding])
Parameters
encoding
The encoding of the data. The encoding must be 'ascii' or 'utf8'. If no encoding is provided, a Buffer is returned.
Guidelines
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)
Guidelines
Use for authenticated encryption modes. The encryption mode must be Encrypt-then-MAC. The data type can be a Buffer or Buffers object.

decipher.setAuthTag()

Passes in the received authentication tag.

Syntax
decipher.setAuthTag(buffer)
Guidelines
Use for authenticated encryption modes. The encryption mode must be Encrypt-then-MAC. If no tag is provided or if the ciphertext is tampered with, final() raises an exception that indicates that the ciphertext is to be discarded due to failed authentication. The data type must be a Buffer.

decipher.setAutoPadding()

The automatic padding of the input data.

Syntax
decipher.setAutoPadding(auto_padding=true)
decipher.setAutoPadding(auto_padding=false)
Guidelines
You can disable automatic padding if the data is encrypted without standard block padding to prevent decipher.final() from checking and removing it. It works only if the length of the input data is a multiple of the ciphers block size. You must call this method before you stream data to decipher.update().

decipher.update()

Updates the decipher object with data.

Syntax
decipher.update(data[,encoding])
Parameters
data
The data to update.
encoding
The encoding of the data. The encoding must be 'base64' or 'hex'. If no encoding is provided, a Buffer is expected. If data is a Buffer, then encoding is ignored.

hash.digest()

Calculates the digest of all of the passed data to be hashed.

Syntax
hash.digest([encoding])
Parameters
encoding
The encoding of the digested result. The encoding must be 'hex' or 'base64'. If no encoding is provided, 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[,encoding])
Parameters
data
The data to digest.
encoding
The encoding of the data. The input_encoding must be '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, input encoding is ignored.

hmac.digest()

Calculates the digest of all of the passed data to the HMAC.

Syntax
hmac.digest([encoding])
Parameters
encoding
The encoding of the resultant digest. The encoding can be 'hex' or 'base64'. If no encoding is provided, 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[,encoding])
Parameters
data
The data to update in the digest.
encoding
The encoding of the data. The input_encoding can be '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, input encoding is ignored.

sign.sign()

Calculates the signature on all the updated data that is passed through the sign object.

Syntax
sign.sign(key[,encoding],function(error,signature,){})
Parameters
key
The private key to encrypt the data to generate the digital signature. The key must be.
  • 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'.
To create a key object, see Key object usage.
encoding
The encoding of the signature. The encoding can 'hex' or 'base64'. If no encoding is provided, then a Buffer is returned.
error
The error information if an error occurs. The error is an instance of the GatewayScript error object. If no error occurs, the error variable is null.
signature
The final result of digital signature. The signature type must be string or Buffer, which is based on the encoding. If no encoding is provided, a Buffer is returned. If an error occurs, the signature is null.
Guidelines
The sign object cannot be used after the sign() method is called.

sign.update()

Updates the sign object with the data. This API can be called several times.

Syntax
sign.update(data[,encoding])
Parameters
data
The data to sign. The data type must be string, Buffer, or Buffers. If no encoding is provided and the input is a string, an encoding of 'utf8' is enforced. If data is a Buffer or Buffers, the encoding is ignored.
encoding
The encoding of the data. The encoding must be 'utf8' or 'ascii'.

verify.update()

Updates the verification object with the data. This method can be called several times.

Syntax
verify.update(data[,encoding])
Parameters
data
The data to verify. The data type must be a string, Buffer, or Buffers. If no encoding is provided and the input is a string, an encoding of 'utf8' is enforced. If data is a Buffer or Buffers, input encoding is ignored.
encoding
The encoding of the data. The input encoding must be 'utf8' or 'ascii'.

verify.verify()

Verifies the digital signature.

Syntax
verify.verify(key,signature[,encoding],function(error){})
Parameters
key
The key object to verify the signature. The key must be.
  • 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'.
To create a key, see Key object usage.
signature
The previously calculated signature for the data. 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, signature-encoding is ignored.
encoding
The encoding of the signature. The signature encoding must be 'hex' or 'base64'.
error
The error information if an error occurs. The error is an instance of the GatewayScript error object. If the verify() call succeeds, the error variable is null.
Guidelines
The verify object cannot be used after the verify() method is called.