Class: Cipher#
Added in: v0.1.94
Instances of the Cipher class are used to encrypt data. The class can be
used in one of two ways:
- As a stream that is both readable and writable, where plain unencrypted
data is written to produce encrypted data on the readable side, or
- Using the
cipher.update() and cipher.final() methods to produce
the encrypted data.
The crypto.createCipheriv() method is
used to create Cipher instances. Cipher objects are not to be created
directly using the new keyword.
Example: Using Cipher objects as streams:
const {
scrypt,
randomFill,
createCipheriv,
} = await import('node:crypto');
const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';
scrypt(password, 'salt', 24, (err, key) => {
if (err) throw err;
randomFill(new Uint8Array(16), (err, iv) => {
if (err) throw err;
const cipher = createCipheriv(algorithm, key, iv);
let encrypted = '';
cipher.setEncoding('hex');
cipher.on('data', (chunk) => encrypted += chunk);
cipher.on('end', () => console.log(encrypted));
cipher.write('some clear text data');
cipher.end();
});
});const {
scrypt,
randomFill,
createCipheriv,
} = require('node:crypto');
const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';
scrypt(password, 'salt', 24, (err, key) => {
if (err) throw err;
randomFill(new Uint8Array(16), (err, iv) => {
if (err) throw err;
const cipher = createCipheriv(algorithm, key, iv);
let encrypted = '';
cipher.setEncoding('hex');
cipher.on('data', (chunk) => encrypted += chunk);
cipher.on('end', () => console.log(encrypted));
cipher.write('some clear text data');
cipher.end();
});
});
Example: Using Cipher and piped streams:
import {
createReadStream,
createWriteStream,
} from 'node:fs';
import {
pipeline,
} from 'node:stream';
const {
scrypt,
randomFill,
createCipheriv,
} = await import('node:crypto');
const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';
scrypt(password, 'salt', 24, (err, key) => {
if (err) throw err;
randomFill(new Uint8Array(16), (err, iv) => {
if (err) throw err;
const cipher = createCipheriv(algorithm, key, iv);
const input = createReadStream('test.js');
const output = createWriteStream('test.enc');
pipeline(input, cipher, output, (err) => {
if (err) throw err;
});
});
});const {
createReadStream,
createWriteStream,
} = require('node:fs');
const {
pipeline,
} = require('node:stream');
const {
scrypt,
randomFill,
createCipheriv,
} = require('node:crypto');
const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';
scrypt(password, 'salt', 24, (err, key) => {
if (err) throw err;
randomFill(new Uint8Array(16), (err, iv) => {
if (err) throw err;
const cipher = createCipheriv(algorithm, key, iv);
const input = createReadStream('test.js');
const output = createWriteStream('test.enc');
pipeline(input, cipher, output, (err) => {
if (err) throw err;
});
});
});
Example: Using the cipher.update() and cipher.final() methods:
const {
scrypt,
randomFill,
createCipheriv,
} = await import('node:crypto');
const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';
scrypt(password, 'salt', 24, (err, key) => {
if (err) throw err;
randomFill(new Uint8Array(16), (err, iv) => {
if (err) throw err;
const cipher = createCipheriv(algorithm, key, iv);
let encrypted = cipher.update('some clear text data', 'utf8', 'hex');
encrypted += cipher.final('hex');
console.log(encrypted);
});
});const {
scrypt,
randomFill,
createCipheriv,
} = require('node:crypto');
const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';
scrypt(password, 'salt', 24, (err, key) => {
if (err) throw err;
randomFill(new Uint8Array(16), (err, iv) => {
if (err) throw err;
const cipher = createCipheriv(algorithm, key, iv);
let encrypted = cipher.update('some clear text data', 'utf8', 'hex');
encrypted += cipher.final('hex');
console.log(encrypted);
});
});
cipher.final([outputEncoding])#
Added in: v0.1.94
outputEncoding <string> The encoding of the return value.
- Returns: <Buffer> | <string> Any remaining enciphered contents.
If
outputEncoding is specified, a string is
returned. If an outputEncoding is not provided, 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.
cipher.getAuthTag()#
Added in: v1.0.0
- Returns: <Buffer> When using an authenticated encryption mode (
GCM, CCM,
OCB, and chacha20-poly1305 are currently supported), the
cipher.getAuthTag() method returns a
Buffer containing the authentication tag that has been computed from
the given data.
The cipher.getAuthTag() method should only be called after encryption has
been completed using the cipher.final() method.
If the authTagLength option was set during the cipher instance's creation,
this function will return exactly authTagLength bytes.
cipher.setAAD(buffer[, options])#
Added in: v1.0.0
When using an authenticated encryption mode (GCM, CCM, OCB, and
chacha20-poly1305 are
currently supported), the cipher.setAAD() method sets the value used for the
additional authenticated data (AAD) input parameter.
The plaintextLength option is optional for GCM and OCB. When using CCM,
the plaintextLength option must be specified and its value must match the
length of the plaintext in bytes. See CCM mode.
The cipher.setAAD() method must be called before cipher.update().
cipher.setAutoPadding([autoPadding])#
Added in: v0.7.1
autoPadding <boolean> Default: true
- Returns: <Cipher> The same
Cipher instance for method chaining.
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().
cipher.update(data[, inputEncoding][, outputEncoding])#
Updates the cipher with data. 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, TypedArray, or
DataView. If data is a Buffer, TypedArray, or DataView, then
inputEncoding is ignored.
The outputEncoding specifies the output format of the enciphered
data. If the outputEncoding
is specified, a string using the specified encoding is returned. If no
outputEncoding is provided, a Buffer is returned.
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.
Class: Decipher#
Added in: v0.1.94
Instances of the Decipher class are used to decrypt data. The class can be
used in one of two ways:
- As a stream that is both readable and writable, where plain encrypted
data is written to produce unencrypted data on the readable side, or
- Using the
decipher.update() and decipher.final() methods to
produce the unencrypted data.
The crypto.createDecipheriv() method is
used to create Decipher instances. Decipher objects are not to be created
directly using the new keyword.
Example: Using Decipher objects as streams:
import { Buffer } from 'node:buffer';
const {
scryptSync,
createDecipheriv,
} = await import('node:crypto');
const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';
const key = scryptSync(password, 'salt', 24);
const iv = Buffer.alloc(16, 0);
const decipher = createDecipheriv(algorithm, key, iv);
let decrypted = '';
decipher.on('readable', () => {
let chunk;
while (null !== (chunk = decipher.read())) {
decrypted += chunk.toString('utf8');
}
});
decipher.on('end', () => {
console.log(decrypted);
});
const encrypted =
'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa';
decipher.write(encrypted, 'hex');
decipher.end();const {
scryptSync,
createDecipheriv,
} = require('node:crypto');
const { Buffer } = require('node:buffer');
const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';
const key = scryptSync(password, 'salt', 24);
const iv = Buffer.alloc(16, 0);
const decipher = createDecipheriv(algorithm, key, iv);
let decrypted = '';
decipher.on('readable', () => {
let chunk;
while (null !== (chunk = decipher.read())) {
decrypted += chunk.toString('utf8');
}
});
decipher.on('end', () => {
console.log(decrypted);
});
const encrypted =
'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa';
decipher.write(encrypted, 'hex');
decipher.end();
Example: Using Decipher and piped streams:
import {
createReadStream,
createWriteStream,
} from 'node:fs';
import { Buffer } from 'node:buffer';
const {
scryptSync,
createDecipheriv,
} = await import('node:crypto');
const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';
const key = scryptSync(password, 'salt', 24);
const iv = Buffer.alloc(16, 0);
const decipher = createDecipheriv(algorithm, key, iv);
const input = createReadStream('test.enc');
const output = createWriteStream('test.js');
input.pipe(decipher).pipe(output);const {
createReadStream,
createWriteStream,
} = require('node:fs');
const {
scryptSync,
createDecipheriv,
} = require('node:crypto');
const { Buffer } = require('node:buffer');
const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';
const key = scryptSync(password, 'salt', 24);
const iv = Buffer.alloc(16, 0);
const decipher = createDecipheriv(algorithm, key, iv);
const input = createReadStream('test.enc');
const output = createWriteStream('test.js');
input.pipe(decipher).pipe(output);
Example: Using the decipher.update() and decipher.final() methods:
import { Buffer } from 'node:buffer';
const {
scryptSync,
createDecipheriv,
} = await import('node:crypto');
const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';
const key = scryptSync(password, 'salt', 24);
const iv = Buffer.alloc(16, 0);
const decipher = createDecipheriv(algorithm, key, iv);
const encrypted =
'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa';
let decrypted = decipher.update(encrypted, 'hex', 'utf8');
decrypted += decipher.final('utf8');
console.log(decrypted);
const {
scryptSync,
createDecipheriv,
} = require('node:crypto');
const { Buffer } = require('node:buffer');
const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';
const key = scryptSync(password, 'salt', 24);
const iv = Buffer.alloc(16, 0);
const decipher = createDecipheriv(algorithm, key, iv);
const encrypted =
'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa';
let decrypted = decipher.update(encrypted, 'hex', 'utf8');
decrypted += decipher.final('utf8');
console.log(decrypted);
decipher.final([outputEncoding])#
Added in: v0.1.94
outputEncoding <string> The encoding of the return value.
- Returns: <Buffer> | <string> Any remaining deciphered contents.
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.
decipher.setAAD(buffer[, options])#
When using an authenticated encryption mode (GCM, CCM, OCB, and
chacha20-poly1305 are
currently supported), the decipher.setAAD() method sets the value used for the
additional authenticated data (AAD) input parameter.
The options argument is optional for GCM. When using CCM, the
plaintextLength option must be specified and its value must match the length
of the ciphertext in bytes. See CCM mode.
The decipher.setAAD() method must be called before decipher.update().
When passing a string as the buffer, please consider
caveats when using strings as inputs to cryptographic APIs.
decipher.setAuthTag(buffer[, encoding])#
When using an authenticated encryption mode (GCM, CCM, OCB, and
chacha20-poly1305 are
currently supported), the decipher.setAuthTag() method is used to pass in the
received authentication tag. If no tag is provided, or if the cipher text
has been tampered with, decipher.final() will throw, indicating that the
cipher text should be discarded due to failed authentication. If the tag length
is invalid according to NIST SP 800-38D or does not match the value of the
authTagLength option, decipher.setAuthTag() will throw an error.
The decipher.setAuthTag() method must be called before decipher.update()
for CCM mode or before decipher.final() for GCM and OCB modes and
chacha20-poly1305.
decipher.setAuthTag() can only be called once.
When passing a string as the authentication tag, please consider
caveats when using strings as inputs to cryptographic APIs.
decipher.setAutoPadding([autoPadding])#
Added in: v0.7.1
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 ciphers block size.
The decipher.setAutoPadding() method must be called before
decipher.final().
decipher.update(data[, inputEncoding][, outputEncoding])#
Updates the decipher with data. 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.
The outputEncoding specifies the output format of the enciphered
data. If the outputEncoding
is specified, a string using the specified encoding is returned. If no
outputEncoding is provided, a Buffer is returned.
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.
Even if the underlying cipher implements authentication, the authenticity and
integrity of the plaintext returned from this function may be uncertain at this
time. For authenticated encryption algorithms, authenticity is generally only
established when the application calls decipher.final().
node:crypto module methods and properties#
crypto.checkPrime(candidate[, options], callback)#
candidate <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Buffer> | <DataView> | <bigint>
A possible prime encoded as a sequence of big endian octets of arbitrary
length.
options <Object>
checks <number> The number of Miller-Rabin probabilistic primality
iterations to perform. When the value is 0 (zero), a number of checks
is used that yields a false positive rate of at most 2-64 for
random input. Care must be used when selecting a number of checks. Refer
to the OpenSSL documentation for the BN_is_prime_ex function nchecks
options for more details. Default: 0
callback <Function>
err <Error> Set to an <Error> object if an error occurred during check.
result <boolean> true if the candidate is a prime with an error
probability less than 0.25 ** options.checks.
Checks the primality of the candidate.
crypto.checkPrimeSync(candidate[, options])#
Added in: v15.8.0
candidate <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Buffer> | <DataView> | <bigint>
A possible prime encoded as a sequence of big endian octets of arbitrary
length.
options <Object>
checks <number> The number of Miller-Rabin probabilistic primality
iterations to perform. When the value is 0 (zero), a number of checks
is used that yields a false positive rate of at most 2-64 for
random input. Care must be used when selecting a number of checks. Refer
to the OpenSSL documentation for the BN_is_prime_ex function nchecks
options for more details. Default: 0
- Returns: <boolean>
true if the candidate is a prime with an error
probability less than 0.25 ** options.checks.
Checks the primality of the candidate.
crypto.constants#
Added in: v6.3.0
An object containing commonly used constants for crypto and security related
operations. The specific constants currently defined are described in
Crypto constants.
crypto.createCipheriv(algorithm, key, iv[, options])#
Creates and returns a Cipher object, with the given algorithm, key and
initialization vector (iv).
The options argument controls stream behavior and is optional except when a
cipher in CCM or OCB mode (e.g. 'aes-128-ccm') is used. In that case, the
authTagLength option is required and specifies the length of the
authentication tag in bytes, see CCM mode. In GCM mode, the authTagLength
option is not required but can be used to set the length of the authentication
tag that will be returned by getAuthTag() and defaults to 16 bytes.
For chacha20-poly1305, the authTagLength option defaults to 16 bytes.
The algorithm is dependent on OpenSSL, examples are 'aes192', etc. On
recent OpenSSL releases, openssl list -cipher-algorithms will
display the available cipher algorithms.
The key is the raw key used by the algorithm and iv is an
initialization vector. Both arguments must be 'utf8' encoded strings,
Buffers, TypedArray, or DataViews. The key may optionally be
a KeyObject of type secret. If the cipher does not need
an initialization vector, iv may be null.
When passing strings for key or iv, please consider
caveats when using strings as inputs to cryptographic APIs.
Initialization vectors should be unpredictable and unique; ideally, they will be
cryptographically random. They do not have to be secret: IVs are typically just
added to ciphertext messages unencrypted. It may sound contradictory that
something has to be unpredictable and unique, but does not have to be secret;
remember that an attacker must not be able to predict ahead of time what a
given IV will be.
crypto.createDecipheriv(algorithm, key, iv[, options])#
Creates and returns a Decipher object that uses the given algorithm, key
and initialization vector (iv).
The options argument controls stream behavior and is optional except when a
cipher in CCM or OCB mode (e.g. 'aes-128-ccm') is used. In that case, the
authTagLength option is required and specifies the length of the
authentication tag in bytes, see CCM mode. In GCM mode, the authTagLength
option is not required but can be used to restrict accepted authentication tags
to those with the specified length.
For chacha20-poly1305, the authTagLength option defaults to 16 bytes.
The algorithm is dependent on OpenSSL, examples are 'aes192', etc. On
recent OpenSSL releases, openssl list -cipher-algorithms will
display the available cipher algorithms.
The key is the raw key used by the algorithm and iv is an
initialization vector. Both arguments must be 'utf8' encoded strings,
Buffers, TypedArray, or DataViews. The key may optionally be
a KeyObject of type secret. If the cipher does not need
an initialization vector, iv may be null.
When passing strings for key or iv, please consider
caveats when using strings as inputs to cryptographic APIs.
Initialization vectors should be unpredictable and unique; ideally, they will be
cryptographically random. They do not have to be secret: IVs are typically just
added to ciphertext messages unencrypted. It may sound contradictory that
something has to be unpredictable and unique, but does not have to be secret;
remember that an attacker must not be able to predict ahead of time what a given
IV will be.
crypto.createDiffieHellman(prime[, primeEncoding][, generator][, generatorEncoding])#
Creates a DiffieHellman key exchange object using the supplied prime and an
optional specific generator.
The generator argument can be a number, string, or Buffer. If
generator is not specified, the value 2 is used.
If primeEncoding is specified, prime is expected to be a string; otherwise
a Buffer, TypedArray, or DataView is expected.
If generatorEncoding is specified, generator is expected to be a string;
otherwise a number, Buffer, TypedArray, or DataView is expected.
crypto.createDiffieHellman(primeLength[, generator])#
Added in: v0.5.0
Creates a DiffieHellman key exchange object and generates a prime of
primeLength bits using an optional specific numeric generator.
If generator is not specified, the value 2 is used.
crypto.createECDH(curveName)#
Added in: v0.11.14
Creates an Elliptic Curve Diffie-Hellman (ECDH) key exchange object using a
predefined curve specified by the curveName string. Use
crypto.getCurves() to obtain a list of available curve names. On recent
OpenSSL releases, openssl ecparam -list_curves will also display the name
and description of each available elliptic curve.
crypto.createHash(algorithm[, options])#
Creates and returns a Hash object that can be used to generate hash digests
using the given algorithm. Optional options argument controls stream
behavior. For XOF hash functions such as 'shake256', the outputLength option
can be used to specify the desired output length in bytes.
The algorithm is dependent on the available algorithms supported by the
version of OpenSSL on the platform. Examples are 'sha256', 'sha512', etc.
On recent releases of OpenSSL, openssl list -digest-algorithms will
display the available digest algorithms.
Example: generating the sha256 sum of a file
import {
createReadStream,
} from 'node:fs';
import { argv } from 'node:process';
const {
createHash,
} = await import('node:crypto');
const filename = argv[2];
const hash = createHash('sha256');
const input = createReadStream(filename);
input.on('readable', () => {
const data = input.read();
if (data)
hash.update(data);
else {
console.log(`${hash.digest('hex')} ${filename}`);
}
});const {
createReadStream,
} = require('node:fs');
const {
createHash,
} = require('node:crypto');
const { argv } = require('node:process');
const filename = argv[2];
const hash = createHash('sha256');
const input = createReadStream(filename);
input.on('readable', () => {
const data = input.read();
if (data)
hash.update(data);
else {
console.log(`${hash.digest('hex')} ${filename}`);
}
});
crypto.createHmac(algorithm, key[, options])#
Creates and returns an Hmac object that uses the given algorithm and key.
Optional options argument controls stream behavior.
The algorithm is dependent on the available algorithms supported by the
version of OpenSSL on the platform. Examples are 'sha256', 'sha512', etc.
On recent releases of OpenSSL, openssl list -digest-algorithms will
display the available digest algorithms.
The key is the HMAC key used to generate the cryptographic HMAC hash. If it is
a KeyObject, its type must be secret. If it is a string, please consider
caveats when using strings as inputs to cryptographic APIs. If it was
obtained from a cryptographically secure source of entropy, such as
crypto.randomBytes() or crypto.generateKey(), its length should not
exceed the block size of algorithm (e.g., 512 bits for SHA-256).
Example: generating the sha256 HMAC of a file
import {
createReadStream,
} from 'node:fs';
import { argv } from 'node:process';
const {
createHmac,
} = await import('node:crypto');
const filename = argv[2];
const hmac = createHmac('sha256', 'a secret');
const input = createReadStream(filename);
input.on('readable', () => {
const data = input.read();
if (data)
hmac.update(data);
else {
console.log(`${hmac.digest('hex')} ${filename}`);
}
});const {
createReadStream,
} = require('node:fs');
const {
createHmac,
} = require('node:crypto');
const { argv } = require('node:process');
const filename = argv[2];
const hmac = createHmac('sha256', 'a secret');
const input = createReadStream(filename);
input.on('readable', () => {
const data = input.read();
if (data)
hmac.update(data);
else {
console.log(`${hmac.digest('hex')} ${filename}`);
}
});
crypto.createPrivateKey(key)#
Creates and returns a new key object containing a private key. If key is a
string or Buffer, format is assumed to be 'pem'; otherwise, key
must be an object with the properties described above.
If the private key is encrypted, a passphrase must be specified. The length
of the passphrase is limited to 1024 bytes.
crypto.createPublicKey(key)#
Creates and returns a new key object containing a public key. If key is a
string or Buffer, format is assumed to be 'pem'; if key is a KeyObject
with type 'private', the public key is derived from the given private key;
otherwise, key must be an object with the properties described above.
If the format is 'pem', the 'key' may also be an X.509 certificate.
Because public keys can be derived from private keys, a private key may be
passed instead of a public key. In that case, this function behaves as if
crypto.createPrivateKey() had been called, except that the type of the
returned KeyObject will be 'public' and that the private key cannot be
extracted from the returned KeyObject. Similarly, if a KeyObject with type
'private' is given, a new KeyObject with type 'public' will be returned
and it will be impossible to extract the private key from the returned object.
crypto.createSecretKey(key[, encoding])#
Creates and returns a new key object containing a secret key for symmetric
encryption or Hmac.
crypto.createSign(algorithm[, options])#
Added in: v0.1.92
Creates and returns a Sign object that uses the given algorithm. Use
crypto.getHashes() to obtain the names of the available digest algorithms.
Optional options argument controls the stream.Writable behavior.
In some cases, a Sign instance can be created using the name of a signature
algorithm, such as 'RSA-SHA256', instead of a digest algorithm. This will use
the corresponding digest algorithm. This does not work for all signature
algorithms, such as 'ecdsa-with-SHA256', so it is best to always use digest
algorithm names.
crypto.createVerify(algorithm[, options])#
Added in: v0.1.92
Creates and returns a Verify object that uses the given algorithm.
Use crypto.getHashes() to obtain an array of names of the available
signing algorithms. Optional options argument controls the
stream.Writable behavior.
In some cases, a Verify instance can be created using the name of a signature
algorithm, such as 'RSA-SHA256', instead of a digest algorithm. This will use
the corresponding digest algorithm. This does not work for all signature
algorithms, such as 'ecdsa-with-SHA256', so it is best to always use digest
algorithm names.
crypto.diffieHellman(options)#
Added in: v13.9.0, v12.17.0
Computes the Diffie-Hellman secret based on a privateKey and a publicKey.
Both keys must have the same asymmetricKeyType, which must be one of 'dh'
(for Diffie-Hellman), 'ec', 'x448', or 'x25519' (for ECDH).
crypto.fips#
Added in: v6.0.0Deprecated since: v10.0.0
Property for checking and controlling whether a FIPS compliant crypto provider
is currently in use. Setting to true requires a FIPS build of Node.js.
This property is deprecated. Please use crypto.setFips() and
crypto.getFips() instead.
crypto.generateKey(type, options, callback)#
type <string> The intended use of the generated secret key. Currently
accepted values are 'hmac' and 'aes'.
options <Object>
length <number> The bit length of the key to generate. This must be a
value greater than 0.
- If
type is 'hmac', the minimum is 8, and the maximum length is
231-1. If the value is not a multiple of 8, the generated
key will be truncated to Math.floor(length / 8).
- If
type is 'aes', the length must be one of 128, 192, or 256.
callback <Function>
Asynchronously generates a new random secret key of the given length. The
type will determine which validations will be performed on the length.
const {
generateKey,
} = await import('node:crypto');
generateKey('hmac', { length: 512 }, (err, key) => {
if (err) throw err;
console.log(key.export().toString('hex'));
});const {
generateKey,
} = require('node:crypto');
generateKey('hmac', { length: 512 }, (err, key) => {
if (err) throw err;
console.log(key.export().toString('hex'));
});
The size of a generated HMAC key should not exceed the block size of the
underlying hash function. See crypto.createHmac() for more information.
crypto.generateKeyPair(type, options, callback)#
type <string> Must be 'rsa', 'rsa-pss', 'dsa', 'ec', 'ed25519',
'ed448', 'x25519', 'x448', or 'dh'.
options <Object>
callback <Function>
Generates a new asymmetric key pair of the given type. RSA, RSA-PSS, DSA, EC,
Ed25519, Ed448, X25519, X448, and DH are currently supported.
If a publicKeyEncoding or privateKeyEncoding was specified, this function
behaves as if keyObject.export() had been called on its result. Otherwise,
the respective part of the key is returned as a KeyObject.
It is recommended to encode public keys as 'spki' and private keys as
'pkcs8' with encryption for long-term storage:
const {
generateKeyPair,
} = await import('node:crypto');
generateKeyPair('rsa', {
modulusLength: 4096,
publicKeyEncoding: {
type: 'spki',
format: 'pem',
},
privateKeyEncoding: {
type: 'pkcs8',
format: 'pem',
cipher: 'aes-256-cbc',
passphrase: 'top secret',
},
}, (err, publicKey, privateKey) => {
});const {
generateKeyPair,
} = require('node:crypto');
generateKeyPair('rsa', {
modulusLength: 4096,
publicKeyEncoding: {
type: 'spki',
format: 'pem',
},
privateKeyEncoding: {
type: 'pkcs8',
format: 'pem',
cipher: 'aes-256-cbc',
passphrase: 'top secret',
},
}, (err, publicKey, privateKey) => {
});
On completion, callback will be called with err set to undefined and
publicKey / privateKey representing the generated key pair.
If this method is invoked as its util.promisify()ed version, it returns
a Promise for an Object with publicKey and privateKey properties.
crypto.generateKeyPairSync(type, options)#
type <string> Must be 'rsa', 'rsa-pss', 'dsa', 'ec', 'ed25519',
'ed448', 'x25519', 'x448', or 'dh'.
options <Object>
- Returns: <Object>
Generates a new asymmetric key pair of the given type. RSA, RSA-PSS, DSA, EC,
Ed25519, Ed448, X25519, X448, and DH are currently supported.
If a publicKeyEncoding or privateKeyEncoding was specified, this function
behaves as if keyObject.export() had been called on its result. Otherwise,
the respective part of the key is returned as a KeyObject.
When encoding public keys, it is recommended to use 'spki'. When encoding
private keys, it is recommended to use 'pkcs8' with a strong passphrase,
and to keep the passphrase confidential.
const {
generateKeyPairSync,
} = await import('node:crypto');
const {
publicKey,
privateKey,
} = generateKeyPairSync('rsa', {
modulusLength: 4096,
publicKeyEncoding: {
type: 'spki',
format: 'pem',
},
privateKeyEncoding: {
type: 'pkcs8',
format: 'pem',
cipher: 'aes-256-cbc',
passphrase: 'top secret',
},
});const {
generateKeyPairSync,
} = require('node:crypto');
const {
publicKey,
privateKey,
} = generateKeyPairSync('rsa', {
modulusLength: 4096,
publicKeyEncoding: {
type: 'spki',
format: 'pem',
},
privateKeyEncoding: {
type: 'pkcs8',
format: 'pem',
cipher: 'aes-256-cbc',
passphrase: 'top secret',
},
});
The return value { publicKey, privateKey } represents the generated key pair.
When PEM encoding was selected, the respective key will be a string, otherwise
it will be a buffer containing the data encoded as DER.
crypto.generateKeySync(type, options)#
Added in: v15.0.0
type <string> The intended use of the generated secret key. Currently
accepted values are 'hmac' and 'aes'.
options <Object>
length <number> The bit length of the key to generate.
- If
type is 'hmac', the minimum is 8, and the maximum length is
231-1. If the value is not a multiple of 8, the generated
key will be truncated to Math.floor(length / 8).
- If
type is 'aes', the length must be one of 128, 192, or 256.
- Returns: <KeyObject>
Synchronously generates a new random secret key of the given length. The
type will determine which validations will be performed on the length.
const {
generateKeySync,
} = await import('node:crypto');
const key = generateKeySync('hmac', { length: 512 });
console.log(key.export().toString('hex')); const {
generateKeySync,
} = require('node:crypto');
const key = generateKeySync('hmac', { length: 512 });
console.log(key.export().toString('hex'));
The size of a generated HMAC key should not exceed the block size of the
underlying hash function. See crypto.createHmac() for more information.
crypto.generatePrime(size[, options], callback)#
Generates a pseudorandom prime of size bits.
If options.safe is true, the prime will be a safe prime -- that is,
(prime - 1) / 2 will also be a prime.
The options.add and options.rem parameters can be used to enforce additional
requirements, e.g., for Diffie-Hellman:
- If
options.add and options.rem are both set, the prime will satisfy the
condition that prime % add = rem.
- If only
options.add is set and options.safe is not true, the prime will
satisfy the condition that prime % add = 1.
- If only
options.add is set and options.safe is set to true, the prime
will instead satisfy the condition that prime % add = 3. This is necessary
because prime % add = 1 for options.add > 2 would contradict the condition
enforced by options.safe.
options.rem is ignored if options.add is not given.
Both options.add and options.rem must be encoded as big-endian sequences
if given as an ArrayBuffer, SharedArrayBuffer, TypedArray, Buffer, or
DataView.
By default, the prime is encoded as a big-endian sequence of octets
in an <ArrayBuffer>. If the bigint option is true, then a <bigint>
is provided.
The size of the prime will have a direct impact on how long it takes to
generate the prime. The larger the size, the longer it will take. Because
we use OpenSSL's BN_generate_prime_ex function, which provides only
minimal control over our ability to interrupt the generation process,
it is not recommended to generate overly large primes, as doing so may make
the process unresponsive.
crypto.generatePrimeSync(size[, options])#
Added in: v15.8.0
Generates a pseudorandom prime of size bits.
If options.safe is true, the prime will be a safe prime -- that is,
(prime - 1) / 2 will also be a prime.
The options.add and options.rem parameters can be used to enforce additional
requirements, e.g., for Diffie-Hellman:
- If
options.add and options.rem are both set, the prime will satisfy the
condition that prime % add = rem.
- If only
options.add is set and options.safe is not true, the prime will
satisfy the condition that prime % add = 1.
- If only
options.add is set and options.safe is set to true, the prime
will instead satisfy the condition that prime % add = 3. This is necessary
because prime % add = 1 for options.add > 2 would contradict the condition
enforced by options.safe.
options.rem is ignored if options.add is not given.
Both options.add and options.rem must be encoded as big-endian sequences
if given as an ArrayBuffer, SharedArrayBuffer, TypedArray, Buffer, or
DataView.
By default, the prime is encoded as a big-endian sequence of octets
in an <ArrayBuffer>. If the bigint option is true, then a <bigint>
is provided.
The size of the prime will have a direct impact on how long it takes to
generate the prime. The larger the size, the longer it will take. Because
we use OpenSSL's BN_generate_prime_ex function, which provides only
minimal control over our ability to interrupt the generation process,
it is not recommended to generate overly large primes, as doing so may make
the process unresponsive.
crypto.getCipherInfo(nameOrNid[, options])#
Added in: v15.0.0
nameOrNid <string> | <number> The name or nid of the cipher to query.
options <Object>
- Returns: <Object>
name <string> The name of the cipher
nid <number> The nid of the cipher
blockSize <number> The block size of the cipher in bytes. This property
is omitted when mode is 'stream'.
ivLength <number> The expected or default initialization vector length in
bytes. This property is omitted if the cipher does not use an initialization
vector.
keyLength <number> The expected or default key length in bytes.
mode <string> The cipher mode. One of 'cbc', 'ccm', 'cfb', 'ctr',
'ecb', 'gcm', 'ocb', 'ofb', 'stream', 'wrap', 'xts'.
Returns information about a given cipher.
Some ciphers accept variable length keys and initialization vectors. By default,
the crypto.getCipherInfo() method will return the default values for these
ciphers. To test if a given key length or iv length is acceptable for given
cipher, use the keyLength and ivLength options. If the given values are
unacceptable, undefined will be returned.
crypto.getDiffieHellman(groupName)#
Added in: v0.7.5
Creates a predefined DiffieHellmanGroup key exchange object. The
supported groups are listed in the documentation for DiffieHellmanGroup.
The returned object mimics the interface of objects created by
crypto.createDiffieHellman(), but will not allow changing
the keys (with diffieHellman.setPublicKey(), for example). The
advantage of using this method is that the parties do not have to
generate nor exchange a group modulus beforehand, saving both processor
and communication time.
Example (obtaining a shared secret):
const {
getDiffieHellman,
} = await import('node:crypto');
const alice = getDiffieHellman('modp14');
const bob = getDiffieHellman('modp14');
alice.generateKeys();
bob.generateKeys();
const aliceSecret = alice.computeSecret(bob.getPublicKey(), null, 'hex');
const bobSecret = bob.computeSecret(alice.getPublicKey(), null, 'hex');
console.log(aliceSecret === bobSecret);const {
getDiffieHellman,
} = require('node:crypto');
const alice = getDiffieHellman('modp14');
const bob = getDiffieHellman('modp14');
alice.generateKeys();
bob.generateKeys();
const aliceSecret = alice.computeSecret(bob.getPublicKey(), null, 'hex');
const bobSecret = bob.computeSecret(alice.getPublicKey(), null, 'hex');
console.log(aliceSecret === bobSecret);
crypto.getFips()#
Added in: v10.0.0
- Returns: <number>
1 if and only if a FIPS compliant crypto provider is
currently in use, 0 otherwise. A future semver-major release may change
the return type of this API to a <boolean>.
crypto.hash(algorithm, data[, outputEncoding])#
Added in: v21.7.0, v20.12.0
A utility for creating one-shot hash digests of data. It can be faster than
the object-based crypto.createHash() when hashing a smaller amount of data
(<= 5MB) that's readily available. If the data can be big or if it is streamed,
it's still recommended to use crypto.createHash() instead.
The algorithm is dependent on the available algorithms supported by the
version of OpenSSL on the platform. Examples are 'sha256', 'sha512', etc.
On recent releases of OpenSSL, openssl list -digest-algorithms will
display the available digest algorithms.
Example:
const crypto = require('node:crypto');
const { Buffer } = require('node:buffer');
const string = 'Node.js';
console.log(crypto.hash('sha1', string));
const base64 = 'Tm9kZS5qcw==';
console.log(crypto.hash('sha1', Buffer.from(base64, 'base64'), 'buffer'));import crypto from 'node:crypto';
import { Buffer } from 'node:buffer';
const string = 'Node.js';
console.log(crypto.hash('sha1', string));
const base64 = 'Tm9kZS5qcw==';
console.log(crypto.hash('sha1', Buffer.from(base64, 'base64'), 'buffer'));
crypto.hkdf(digest, ikm, salt, info, keylen, callback)#
HKDF is a simple key derivation function defined in RFC 5869. The given ikm,
salt and info are used with the digest to derive a key of keylen bytes.
The supplied callback function is called with two arguments: err and
derivedKey. If an errors occurs while deriving the key, err will be set;
otherwise err will be null. The successfully generated derivedKey will
be passed to the callback as an <ArrayBuffer>. An error will be thrown if any
of the input arguments specify invalid values or types.
import { Buffer } from 'node:buffer';
const {
hkdf,
} = await import('node:crypto');
hkdf('sha512', 'key', 'salt', 'info', 64, (err, derivedKey) => {
if (err) throw err;
console.log(Buffer.from(derivedKey).toString('hex'));
});const {
hkdf,
} = require('node:crypto');
const { Buffer } = require('node:buffer');
hkdf('sha512', 'key', 'salt', 'info', 64, (err, derivedKey) => {
if (err) throw err;
console.log(Buffer.from(derivedKey).toString('hex'));
});
crypto.hkdfSync(digest, ikm, salt, info, keylen)#
Provides a synchronous HKDF key derivation function as defined in RFC 5869. The
given ikm, salt and info are used with the digest to derive a key of
keylen bytes.
The successfully generated derivedKey will be returned as an <ArrayBuffer>.
An error will be thrown if any of the input arguments specify invalid values or
types, or if the derived key cannot be generated.
import { Buffer } from 'node:buffer';
const {
hkdfSync,
} = await import('node:crypto');
const derivedKey = hkdfSync('sha512', 'key', 'salt', 'info', 64);
console.log(Buffer.from(derivedKey).toString('hex')); const {
hkdfSync,
} = require('node:crypto');
const { Buffer } = require('node:buffer');
const derivedKey = hkdfSync('sha512', 'key', 'salt', 'info', 64);
console.log(Buffer.from(derivedKey).toString('hex'));
crypto.pbkdf2(password, salt, iterations, keylen, digest, callback)#
Provides an asynchronous Password-Based Key Derivation Function 2 (PBKDF2)
implementation. A selected HMAC digest algorithm specified by digest is
applied to derive a key of the requested byte length (keylen) from the
password, salt and iterations.
The supplied callback function is called with two arguments: err and
derivedKey. If an error occurs while deriving the key, err will be set;
otherwise err will be null. By default, the successfully generated
derivedKey will be passed to the callback as a Buffer. An error will be
thrown if any of the input arguments specify invalid values or types.
The iterations argument must be a number set as high as possible. The
higher the number of iterations, the more secure the derived key will be,
but will take a longer amount of time to complete.
The salt should be as unique as possible. It is recommended that a salt is
random and at least 16 bytes long. See NIST SP 800-132 for details.
When passing strings for password or salt, please consider
caveats when using strings as inputs to cryptographic APIs.
const {
pbkdf2,
} = await import('node:crypto');
pbkdf2('secret', 'salt', 100000, 64, 'sha512', (err, derivedKey) => {
if (err) throw err;
console.log(derivedKey.toString('hex'));
});const {
pbkdf2,
} = require('node:crypto');
pbkdf2('secret', 'salt', 100000, 64, 'sha512', (err, derivedKey) => {
if (err) throw err;
console.log(derivedKey.toString('hex'));
});
An array of supported digest functions can be retrieved using
crypto.getHashes().
This API uses libuv's threadpool, which can have surprising and
negative performance implications for some applications; see the
UV_THREADPOOL_SIZE documentation for more information.
crypto.pbkdf2Sync(password, salt, iterations, keylen, digest)#
Provides a synchronous Password-Based Key Derivation Function 2 (PBKDF2)
implementation. A selected HMAC digest algorithm specified by digest is
applied to derive a key of the requested byte length (keylen) from the
password, salt and iterations.
If an error occurs an Error will be thrown, otherwise the derived key will be
returned as a Buffer.
The iterations argument must be a number set as high as possible. The
higher the number of iterations, the more secure the derived key will be,
but will take a longer amount of time to complete.
The salt should be as unique as possible. It is recommended that a salt is
random and at least 16 bytes long. See NIST SP 800-132 for details.
When passing strings for password or salt, please consider
caveats when using strings as inputs to cryptographic APIs.
const {
pbkdf2Sync,
} = await import('node:crypto');
const key = pbkdf2Sync('secret', 'salt', 100000, 64, 'sha512');
console.log(key.toString('hex')); const {
pbkdf2Sync,
} = require('node:crypto');
const key = pbkdf2Sync('secret', 'salt', 100000, 64, 'sha512');
console.log(key.toString('hex'));
An array of supported digest functions can be retrieved using
crypto.getHashes().
crypto.privateDecrypt(privateKey, buffer)#
Decrypts buffer with privateKey. buffer was previously encrypted using
the corresponding public key, for example using crypto.publicEncrypt().
If privateKey is not a KeyObject, this function behaves as if
privateKey had been passed to crypto.createPrivateKey(). If it is an
object, the padding property can be passed. Otherwise, this function uses
RSA_PKCS1_OAEP_PADDING.
Using crypto.constants.RSA_PKCS1_PADDING in crypto.privateDecrypt()
requires OpenSSL to support implicit rejection (rsa_pkcs1_implicit_rejection).
If the version of OpenSSL used by Node.js does not support this feature,
attempting to use RSA_PKCS1_PADDING will fail.
crypto.privateEncrypt(privateKey, buffer)#
Encrypts buffer with privateKey. The returned data can be decrypted using
the corresponding public key, for example using crypto.publicDecrypt().
If privateKey is not a KeyObject, this function behaves as if
privateKey had been passed to crypto.createPrivateKey(). If it is an
object, the padding property can be passed. Otherwise, this function uses
RSA_PKCS1_PADDING.
crypto.publicDecrypt(key, buffer)#
Decrypts buffer with key.buffer was previously encrypted using
the corresponding private key, for example using crypto.privateEncrypt().
If key is not a KeyObject, this function behaves as if
key had been passed to crypto.createPublicKey(). If it is an
object, the padding property can be passed. Otherwise, this function uses
RSA_PKCS1_PADDING.
Because RSA public keys can be derived from private keys, a private key may
be passed instead of a public key.
crypto.publicEncrypt(key, buffer)#
Encrypts the content of buffer with key and returns a new
Buffer with encrypted content. The returned data can be decrypted using
the corresponding private key, for example using crypto.privateDecrypt().
If key is not a KeyObject, this function behaves as if
key had been passed to crypto.createPublicKey(). If it is an
object, the padding property can be passed. Otherwise, this function uses
RSA_PKCS1_OAEP_PADDING.
Because RSA public keys can be derived from private keys, a private key may
be passed instead of a public key.
crypto.randomBytes(size[, callback])#
size <number> The number of bytes to generate. The size must
not be larger than 2**31 - 1.
callback <Function>
- Returns: <Buffer> if the
callback function is not provided.
Generates cryptographically strong pseudorandom data. The size argument
is a number indicating the number of bytes to generate.
If a callback function is provided, the bytes are generated asynchronously
and the callback function is invoked with two arguments: err and buf.
If an error occurs, err will be an Error object; otherwise it is null. The
buf argument is a Buffer containing the generated bytes.
const {
randomBytes,
} = await import('node:crypto');
randomBytes(256, (err, buf) => {
if (err) throw err;
console.log(`${buf.length} bytes of random data: ${buf.toString('hex')}`);
});
const {
randomBytes,
} = require('node:crypto');
randomBytes(256, (err, buf) => {
if (err) throw err;
console.log(`${buf.length} bytes of random data: ${buf.toString('hex')}`);
});
If the callback function is not provided, the random bytes are generated
synchronously and returned as a Buffer. An error will be thrown if
there is a problem generating the bytes.
const {
randomBytes,
} = await import('node:crypto');
const buf = randomBytes(256);
console.log(
`${buf.length} bytes of random data: ${buf.toString('hex')}`);
const {
randomBytes,
} = require('node:crypto');
const buf = randomBytes(256);
console.log(
`${buf.length} bytes of random data: ${buf.toString('hex')}`);
The crypto.randomBytes() method will not complete until there is
sufficient entropy available.
This should normally never take longer than a few milliseconds. The only time
when generating the random bytes may conceivably block for a longer period of
time is right after boot, when the whole system is still low on entropy.
This API uses libuv's threadpool, which can have surprising and
negative performance implications for some applications; see the
UV_THREADPOOL_SIZE documentation for more information.
The asynchronous version of crypto.randomBytes() is carried out in a single
threadpool request. To minimize threadpool task length variation, partition
large randomBytes requests when doing so as part of fulfilling a client
request.
crypto.randomFill(buffer[, offset][, size], callback)#
This function is similar to crypto.randomBytes() but requires the first
argument to be a Buffer that will be filled. It also
requires that a callback is passed in.
If the callback function is not provided, an error will be thrown.
import { Buffer } from 'node:buffer';
const { randomFill } = await import('node:crypto');
const buf = Buffer.alloc(10);
randomFill(buf, (err, buf) => {
if (err) throw err;
console.log(buf.toString('hex'));
});
randomFill(buf, 5, (err, buf) => {
if (err) throw err;
console.log(buf.toString('hex'));
});
randomFill(buf, 5, 5, (err, buf) => {
if (err) throw err;
console.log(buf.toString('hex'));
});const { randomFill } = require('node:crypto');
const { Buffer } = require('node:buffer');
const buf = Buffer.alloc(10);
randomFill(buf, (err, buf) => {
if (err) throw err;
console.log(buf.toString('hex'));
});
randomFill(buf, 5, (err, buf) => {
if (err) throw err;
console.log(buf.toString('hex'));
});
randomFill(buf, 5, 5, (err, buf) => {
if (err) throw err;
console.log(buf.toString('hex'));
});
Any ArrayBuffer, TypedArray, or DataView instance may be passed as
buffer.
While this includes instances of Float32Array and Float64Array, this
function should not be used to generate random floating-point numbers. The
result may contain +Infinity, -Infinity, and NaN, and even if the array
contains finite numbers only, they are not drawn from a uniform random
distribution and have no meaningful lower or upper bounds.
import { Buffer } from 'node:buffer';
const { randomFill } = await import('node:crypto');
const a = new Uint32Array(10);
randomFill(a, (err, buf) => {
if (err) throw err;
console.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength)
.toString('hex'));
});
const b = new DataView(new ArrayBuffer(10));
randomFill(b, (err, buf) => {
if (err) throw err;
console.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength)
.toString('hex'));
});
const c = new ArrayBuffer(10);
randomFill(c, (err, buf) => {
if (err) throw err;
console.log(Buffer.from(buf).toString('hex'));
});const { randomFill } = require('node:crypto');
const { Buffer } = require('node:buffer');
const a = new Uint32Array(10);
randomFill(a, (err, buf) => {
if (err) throw err;
console.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength)
.toString('hex'));
});
const b = new DataView(new ArrayBuffer(10));
randomFill(b, (err, buf) => {
if (err) throw err;
console.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength)
.toString('hex'));
});
const c = new ArrayBuffer(10);
randomFill(c, (err, buf) => {
if (err) throw err;
console.log(Buffer.from(buf).toString('hex'));
});
This API uses libuv's threadpool, which can have surprising and
negative performance implications for some applications; see the
UV_THREADPOOL_SIZE documentation for more information.
The asynchronous version of crypto.randomFill() is carried out in a single
threadpool request. To minimize threadpool task length variation, partition
large randomFill requests when doing so as part of fulfilling a client
request.
crypto.randomFillSync(buffer[, offset][, size])#
Synchronous version of crypto.randomFill().
import { Buffer } from 'node:buffer';
const { randomFillSync } = await import('node:crypto');
const buf = Buffer.alloc(10);
console.log(randomFillSync(buf).toString('hex'));
randomFillSync(buf, 5);
console.log(buf.toString('hex'));
randomFillSync(buf, 5, 5);
console.log(buf.toString('hex'));const { randomFillSync } = require('node:crypto');
const { Buffer } = require('node:buffer');
const buf = Buffer.alloc(10);
console.log(randomFillSync(buf).toString('hex'));
randomFillSync(buf, 5);
console.log(buf.toString('hex'));
randomFillSync(buf, 5, 5);
console.log(buf.toString('hex'));
Any ArrayBuffer, TypedArray or DataView instance may be passed as
buffer.
import { Buffer } from 'node:buffer';
const { randomFillSync } = await import('node:crypto');
const a = new Uint32Array(10);
console.log(Buffer.from(randomFillSync(a).buffer,
a.byteOffset, a.byteLength).toString('hex'));
const b = new DataView(new ArrayBuffer(10));
console.log(Buffer.from(randomFillSync(b).buffer,
b.byteOffset, b.byteLength).toString('hex'));
const c = new ArrayBuffer(10);
console.log(Buffer.from(randomFillSync(c)).toString('hex'));const { randomFillSync } = require('node:crypto');
const { Buffer } = require('node:buffer');
const a = new Uint32Array(10);
console.log(Buffer.from(randomFillSync(a).buffer,
a.byteOffset, a.byteLength).toString('hex'));
const b = new DataView(new ArrayBuffer(10));
console.log(Buffer.from(randomFillSync(b).buffer,
b.byteOffset, b.byteLength).toString('hex'));
const c = new ArrayBuffer(10);
console.log(Buffer.from(randomFillSync(c)).toString('hex'));
crypto.randomInt([min, ]max[, callback])#
min <integer> Start of random range (inclusive). Default: 0.
max <integer> End of random range (exclusive).
callback <Function> function(err, n) {}.
Return a random integer n such that min <= n < max. This
implementation avoids modulo bias.
The range (max - min) must be less than 248. min and max must
be safe integers.
If the callback function is not provided, the random integer is
generated synchronously.
const {
randomInt,
} = await import('node:crypto');
randomInt(3, (err, n) => {
if (err) throw err;
console.log(`Random number chosen from (0, 1, 2): ${n}`);
});
const {
randomInt,
} = require('node:crypto');
randomInt(3, (err, n) => {
if (err) throw err;
console.log(`Random number chosen from (0, 1, 2): ${n}`);
});
const {
randomInt,
} = await import('node:crypto');
const n = randomInt(3);
console.log(`Random number chosen from (0, 1, 2): ${n}`);
const {
randomInt,
} = require('node:crypto');
const n = randomInt(3);
console.log(`Random number chosen from (0, 1, 2): ${n}`);
const {
randomInt,
} = await import('node:crypto');
const n = randomInt(1, 7);
console.log(`The dice rolled: ${n}`);
const {
randomInt,
} = require('node:crypto');
const n = randomInt(1, 7);
console.log(`The dice rolled: ${n}`);
crypto.randomUUID([options])#
Added in: v15.6.0, v14.17.0
options <Object>
disableEntropyCache <boolean> By default, to improve performance,
Node.js generates and caches enough
random data to generate up to 128 random UUIDs. To generate a UUID
without using the cache, set disableEntropyCache to true.
Default: false.
- Returns: <string>
Generates a random RFC 4122 version 4 UUID. The UUID is generated using a
cryptographic pseudorandom number generator.
crypto.scrypt(password, salt, keylen[, options], callback)#
Provides an asynchronous scrypt implementation. Scrypt is a password-based
key derivation function that is designed to be expensive computationally and
memory-wise in order to make brute-force attacks unrewarding.
The salt should be as unique as possible. It is recommended that a salt is
random and at least 16 bytes long. See NIST SP 800-132 for details.
When passing strings for password or salt, please consider
caveats when using strings as inputs to cryptographic APIs.
The callback function is called with two arguments: err and derivedKey.
err is an exception object when key derivation fails, otherwise err is
null. derivedKey is passed to the callback as a Buffer.
An exception is thrown when any of the input arguments specify invalid values
or types.
const {
scrypt,
} = await import('node:crypto');
scrypt('password', 'salt', 64, (err, derivedKey) => {
if (err) throw err;
console.log(derivedKey.toString('hex'));
});
scrypt('password', 'salt', 64, { N: 1024 }, (err, derivedKey) => {
if (err) throw err;
console.log(derivedKey.toString('hex'));
});const {
scrypt,
} = require('node:crypto');
scrypt('password', 'salt', 64, (err, derivedKey) => {
if (err) throw err;
console.log(derivedKey.toString('hex'));
});
scrypt('password', 'salt', 64, { N: 1024 }, (err, derivedKey) => {
if (err) throw err;
console.log(derivedKey.toString('hex'));
});
crypto.scryptSync(password, salt, keylen[, options])#
Provides a synchronous scrypt implementation. Scrypt is a password-based
key derivation function that is designed to be expensive computationally and
memory-wise in order to make brute-force attacks unrewarding.
The salt should be as unique as possible. It is recommended that a salt is
random and at least 16 bytes long. See NIST SP 800-132 for details.
When passing strings for password or salt, please consider
caveats when using strings as inputs to cryptographic APIs.
An exception is thrown when key derivation fails, otherwise the derived key is
returned as a Buffer.
An exception is thrown when any of the input arguments specify invalid values
or types.
const {
scryptSync,
} = await import('node:crypto');
const key1 = scryptSync('password', 'salt', 64);
console.log(key1.toString('hex'));
const key2 = scryptSync('password', 'salt', 64, { N: 1024 });
console.log(key2.toString('hex')); const {
scryptSync,
} = require('node:crypto');
const key1 = scryptSync('password', 'salt', 64);
console.log(key1.toString('hex'));
const key2 = scryptSync('password', 'salt', 64, { N: 1024 });
console.log(key2.toString('hex'));
crypto.secureHeapUsed()#
Added in: v15.6.0
- Returns: <Object>
total <number> The total allocated secure heap size as specified
using the --secure-heap=n command-line flag.
min <number> The minimum allocation from the secure heap as
specified using the --secure-heap-min command-line flag.
used <number> The total number of bytes currently allocated from
the secure heap.
utilization <number> The calculated ratio of used to total
allocated bytes.
crypto.setEngine(engine[, flags])#
Load and set the engine for some or all OpenSSL functions (selected by flags).
Support for custom engines in OpenSSL is deprecated from OpenSSL 3.
engine could be either an id or a path to the engine's shared library.
The optional flags argument uses ENGINE_METHOD_ALL by default. The flags
is a bit field taking one of or a mix of the following flags (defined in
crypto.constants):
crypto.constants.ENGINE_METHOD_RSA
crypto.constants.ENGINE_METHOD_DSA
crypto.constants.ENGINE_METHOD_DH
crypto.constants.ENGINE_METHOD_RAND
crypto.constants.ENGINE_METHOD_EC
crypto.constants.ENGINE_METHOD_CIPHERS
crypto.constants.ENGINE_METHOD_DIGESTS
crypto.constants.ENGINE_METHOD_PKEY_METHS
crypto.constants.ENGINE_METHOD_PKEY_ASN1_METHS
crypto.constants.ENGINE_METHOD_ALL
crypto.constants.ENGINE_METHOD_NONE
crypto.setFips(bool)#
Added in: v10.0.0
Enables the FIPS compliant crypto provider in a FIPS-enabled Node.js build.
Throws an error if FIPS mode is not available.
crypto.sign(algorithm, data, key[, callback])#
Calculates and returns the signature for data using the given private key and
algorithm. If algorithm is null or undefined, then the algorithm is
dependent upon the key type (especially Ed25519 and Ed448).
If key is not a KeyObject, this function behaves as if key had been
passed to crypto.createPrivateKey(). If it is an object, the following
additional properties can be passed:
-
dsaEncoding <string> For DSA and ECDSA, this option specifies the
format of the generated signature. It can be one of the following:
'der' (default): DER-encoded ASN.1 signature structure encoding (r, s).
'ieee-p1363': Signature format r || s as proposed in IEEE-P1363.
-
padding <integer> Optional padding value for RSA, one of the following:
crypto.constants.RSA_PKCS1_PADDING (default)
crypto.constants.RSA_PKCS1_PSS_PADDING
RSA_PKCS1_PSS_PADDING will use MGF1 with the same hash function
used to sign the message as specified in section 3.1 of RFC 4055.
-
saltLength <integer> Salt length for when padding is
RSA_PKCS1_PSS_PADDING. The special value
crypto.constants.RSA_PSS_SALTLEN_DIGEST sets the salt length to the digest
size, crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN (default) sets it to the
maximum permissible value.
If the callback function is provided this function uses libuv's threadpool.
crypto.timingSafeEqual(a, b)#
This function compares the underlying bytes that represent the given
ArrayBuffer, TypedArray, or DataView instances using a constant-time
algorithm.
This function does not leak timing information that
would allow an attacker to guess one of the values. This is suitable for
comparing HMAC digests or secret values like authentication cookies or
capability urls.
a and b must both be Buffers, TypedArrays, or DataViews, and they
must have the same byte length. An error is thrown if a and b have
different byte lengths.
If at least one of a and b is a TypedArray with more than one byte per
entry, such as Uint16Array, the result will be computed using the platform
byte order.
When both of the inputs are Float32Arrays or
Float64Arrays, this function might return unexpected results due to IEEE 754
encoding of floating-point numbers. In particular, neither x === y nor
Object.is(x, y) implies that the byte representations of two floating-point
numbers x and y are equal.
Use of crypto.timingSafeEqual does not guarantee that the surrounding code
is timing-safe. Care should be taken to ensure that the surrounding code does
not introduce timing vulnerabilities.
crypto.verify(algorithm, data, key, signature[, callback])#
Verifies the given signature for data using the given key and algorithm. If
algorithm is null or undefined, then the algorithm is dependent upon the
key type (especially Ed25519 and Ed448).
If key is not a KeyObject, this function behaves as if key had been
passed to crypto.createPublicKey(). If it is an object, the following
additional properties can be passed:
-
dsaEncoding <string> For DSA and ECDSA, this option specifies the
format of the signature. It can be one of the following:
'der' (default): DER-encoded ASN.1 signature structure encoding (r, s).
'ieee-p1363': Signature format r || s as proposed in IEEE-P1363.
-
padding <integer> Optional padding value for RSA, one of the following:
crypto.constants.RSA_PKCS1_PADDING (default)
crypto.constants.RSA_PKCS1_PSS_PADDING
RSA_PKCS1_PSS_PADDING will use MGF1 with the same hash function
used to sign the message as specified in section 3.1 of RFC 4055.
-
saltLength <integer> Salt length for when padding is
RSA_PKCS1_PSS_PADDING. The special value
crypto.constants.RSA_PSS_SALTLEN_DIGEST sets the salt length to the digest
size, crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN (default) sets it to the
maximum permissible value.
The signature argument is the previously calculated signature for the data.
Because public keys can be derived from private keys, a private key or a public
key may be passed for key.
If the callback function is provided this function uses libuv's threadpool.