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 thefinal()
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)
- 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 orfinal()
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
, andA256CBC-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
, andA256CBC-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.
- 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 assha1
.hmac-sha1
orsha1
.hmac-sha256
orsha256
.hmac-sha512
orsha512
.hmac-sha224
orsha224
.hmac-sha384
orsha384
.hmac-ripemd160
orripemd160
.hmac-md5
ormd5
.
- 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'
.
- Example
-
Use the
hmac-sha256
algorithm and theAlice
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
orPS256
.rsassa-pss-ps384
orPS384
.rsassa-pss-ps512
orPS512
.
- 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
orPS256
.rsassa-pss-ps384
orPS384
.rsassa-pss-ps512
orPS512
.
- 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 }
- Asynchronously generate random bytes.
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)
- 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. Thehash
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. Thehmac
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'
.
- 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'
.
- 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.