@caido/quickjs-types / caido/crypto

caido/crypto

Classes

Cipheriv

Instances of the Cipheriv class are used to encrypt data. The class can be used in one way:

• Using the cipher.update() and cipher.final() methods to produce the encrypted data.

The createCipheriv method is used to create Cipheriv instances. Cipheriv objects are not to be created directly using the new keyword.

Extended by

• CipherCCM
• CipherGCM
• CipherOCB
• CipherChaCha20Poly1305

Methods

final()

final(): Buffer

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

Returns

Buffer

Any remaining enciphered contents.

update()

update(data: BinaryLike): Buffer

Updates the cipher with data.

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

Parameters

Parameter	Type
data	BinaryLike

Returns

Buffer

---

Decipheriv

Instances of the Decipheriv class are used to decrypt data. The class can be used in one way:

• Using the decipher.update() and decipher.final() methods to produce the unencrypted data.

The createDecipheriv method is used to create Decipheriv instances. Decipheriv objects are not to be created directly using the new keyword.

Extended by

• DecipherCCM
• DecipherGCM
• DecipherOCB
• DecipherChaCha20Poly1305

Methods

final()

final(): Buffer

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

Returns

Buffer

update()

update(data: ArrayBufferView): Buffer

Updates the decipher with data.

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

Parameters

Parameter	Type
data	ArrayBufferView

Returns

Buffer

---

Hash

The Hash class is a utility for creating hash digests of data.

Using the hash.update() and hash.digest() methods to produce the computed hash.

The createHash method is used to create Hash instances. Hashobjects are not to be created directly using the new keyword.

Example: Using the hash.update() and hash.digest() methods:

import { createHash } from 'crypto';

const hash = createHash('sha256');

hash.update('some data to hash');
console.log(hash.digest('hex'));
// Prints:
//   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50

Methods

digest()

Call Signature

digest(): Buffer

Calculates the digest of all of the data passed to be hashed (using the hash.update() method). If encoding is provided a string will be returned; otherwise a Buffer is returned.

The Hash object can not be used again after hash.digest() method has been called. Multiple calls will cause an error to be thrown.

Returns

Buffer

Call Signature

digest(encoding: BinaryToTextEncoding): string

Calculates the digest of all of the data passed to be hashed (using the hash.update() method). If encoding is provided a string will be returned; otherwise a Buffer is returned.

The Hash object can not be used again after hash.digest() method has been called. Multiple calls will cause an error to be thrown.

Parameters

Parameter	Type	Description
encoding	BinaryToTextEncoding	The encoding of the return value.

Returns

string

update()

Call Signature

update(data: BinaryLike): Hash

Updates the hash content with the given data, the encoding of which is given in inputEncoding. If encoding is not provided, and the data is a string, an encoding of 'utf8' is enforced. If data is a Buffer, TypedArray, orDataView, then inputEncoding is ignored.

This can be called many times with new data as it is streamed.

Parameters

Parameter	Type
data	BinaryLike

Returns

Hash

Call Signature

update(data: string, inputEncoding: Encoding): Hash

Updates the hash content with the given data, the encoding of which is given in inputEncoding. If encoding is not provided, and the data is a string, an encoding of 'utf8' is enforced. If data is a Buffer, TypedArray, orDataView, then inputEncoding is ignored.

This can be called many times with new data as it is streamed.

Parameters

Parameter	Type	Description
data	string	-
inputEncoding	Encoding	The encoding of the data string.

Returns

Hash

---

Hmac

The Hmac class is a utility for creating cryptographic HMAC digests.

Using the hmac.update() and hmac.digest() methods to produce the computed HMAC digest.

The createHmac method is used to create Hmac instances. Hmacobjects are not to be created directly using the new keyword.

Example: Using the hmac.update() and hmac.digest() methods:

import { createHmac } from 'crypto';

const hmac = createHmac('sha256', 'a secret');

hmac.update('some data to hash');
console.log(hmac.digest('hex'));
// Prints:
//   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e

Methods

digest()

Call Signature

digest(): Buffer

Calculates the HMAC digest of all of the data passed using hmac.update(). If encoding is provided a string is returned; otherwise a Buffer is returned;

The Hmac object can not be used again after hmac.digest() has been called. Multiple calls to hmac.digest() will result in an error being thrown.

Returns

Buffer

Call Signature

digest(encoding: BinaryToTextEncoding): string

Calculates the HMAC digest of all of the data passed using hmac.update(). If encoding is provided a string is returned; otherwise a Buffer is returned;

The Hmac object can not be used again after hmac.digest() has been called. Multiple calls to hmac.digest() will result in an error being thrown.

Parameters

Parameter	Type	Description
encoding	BinaryToTextEncoding	The encoding of the return value.

Returns

string

update()

Call Signature

update(data: BinaryLike): Hmac

Updates the Hmac content with the given data, the encoding of which is given in inputEncoding. If encoding is not provided, and the data is a string, an encoding of 'utf8' is enforced. If data is a Buffer, TypedArray, orDataView, then inputEncoding is ignored.

This can be called many times with new data as it is streamed.

Parameters

Parameter	Type
data	BinaryLike

Returns

Hmac

Call Signature

update(data: string, inputEncoding: Encoding): Hmac

Updates the Hmac content with the given data, the encoding of which is given in inputEncoding. If encoding is not provided, and the data is a string, an encoding of 'utf8' is enforced. If data is a Buffer, TypedArray, orDataView, then inputEncoding is ignored.

This can be called many times with new data as it is streamed.

Parameters

Parameter	Type	Description
data	string	-
inputEncoding	Encoding	The encoding of the data string.

Returns

Hmac

Interfaces

CipherCCM

Instances of the Cipheriv class are used to encrypt data. The class can be used in one way:

• Using the cipher.update() and cipher.final() methods to produce the encrypted data.

The createCipheriv method is used to create Cipheriv instances. Cipheriv objects are not to be created directly using the new keyword.

Extends

• Cipheriv

Methods

final()

final(): Buffer

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

Returns

Buffer

Any remaining enciphered contents.

Inherited from

Cipheriv.final

getAuthTag()

getAuthTag(): Buffer

Returns

Buffer

setAAD()

setAAD(buffer: ArrayBufferView): this

Parameters

Parameter	Type
buffer	ArrayBufferView

Returns

this

update()

update(data: BinaryLike): Buffer

Updates the cipher with data.

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

Parameters

Parameter	Type
data	BinaryLike

Returns

Buffer

Inherited from

Cipheriv.update

---

CipherCCMOptions

Properties

authTagLength

authTagLength: number

---

CipherChaCha20Poly1305

Instances of the Cipheriv class are used to encrypt data. The class can be used in one way:

• Using the cipher.update() and cipher.final() methods to produce the encrypted data.

The createCipheriv method is used to create Cipheriv instances. Cipheriv objects are not to be created directly using the new keyword.

Extends

• Cipheriv

Methods

final()

final(): Buffer

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

Returns

Buffer

Any remaining enciphered contents.

Inherited from

Cipheriv.final

getAuthTag()

getAuthTag(): Buffer

Returns

Buffer

setAAD()

setAAD(buffer: ArrayBufferView): this

Parameters

Parameter	Type
buffer	ArrayBufferView

Returns

this

update()

update(data: BinaryLike): Buffer

Updates the cipher with data.

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

Parameters

Parameter	Type
data	BinaryLike

Returns

Buffer

Inherited from

Cipheriv.update

---

CipherChaCha20Poly1305Options

Properties

authTagLength?

optional authTagLength: number

Default

16

---

CipherGCM

Instances of the Cipheriv class are used to encrypt data. The class can be used in one way:

• Using the cipher.update() and cipher.final() methods to produce the encrypted data.

The createCipheriv method is used to create Cipheriv instances. Cipheriv objects are not to be created directly using the new keyword.

Extends

• Cipheriv

Methods

final()

final(): Buffer

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

Returns

Buffer

Any remaining enciphered contents.

Inherited from

Cipheriv.final

getAuthTag()

getAuthTag(): Buffer

Returns

Buffer

setAAD()

setAAD(buffer: ArrayBufferView): this

Parameters

Parameter	Type
buffer	ArrayBufferView

Returns

this

update()

update(data: BinaryLike): Buffer

Updates the cipher with data.

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

Parameters

Parameter	Type
data	BinaryLike

Returns

Buffer

Inherited from

Cipheriv.update

---

CipherGCMOptions

Properties

authTagLength?

optional authTagLength: number

---

CipherOCB

Instances of the Cipheriv class are used to encrypt data. The class can be used in one way:

• Using the cipher.update() and cipher.final() methods to produce the encrypted data.

The createCipheriv method is used to create Cipheriv instances. Cipheriv objects are not to be created directly using the new keyword.

Extends

• Cipheriv

Methods

final()

final(): Buffer

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

Returns

Buffer

Any remaining enciphered contents.

Inherited from

Cipheriv.final

getAuthTag()

getAuthTag(): Buffer

Returns

Buffer

setAAD()

setAAD(buffer: ArrayBufferView): this

Parameters

Parameter	Type
buffer	ArrayBufferView

Returns

this

update()

update(data: BinaryLike): Buffer

Updates the cipher with data.

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

Parameters

Parameter	Type
data	BinaryLike

Returns

Buffer

Inherited from

Cipheriv.update

---

CipherOCBOptions

Properties

authTagLength

authTagLength: number

---

DecipherCCM

Instances of the Decipheriv class are used to decrypt data. The class can be used in one way:

• Using the decipher.update() and decipher.final() methods to produce the unencrypted data.

The createDecipheriv method is used to create Decipheriv instances. Decipheriv objects are not to be created directly using the new keyword.

Extends

• Decipheriv

Methods

final()

final(): Buffer

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

Returns

Buffer

Inherited from

Decipheriv.final

setAAD()

setAAD(buffer: ArrayBufferView): this

Parameters

Parameter	Type
buffer	ArrayBufferView

Returns

this

setAuthTag()

setAuthTag(buffer: ArrayBufferView): this

Parameters

Parameter	Type
buffer	ArrayBufferView

Returns

this

update()

update(data: ArrayBufferView): Buffer

Updates the decipher with data.

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

Parameters

Parameter	Type
data	ArrayBufferView

Returns

Buffer

Inherited from

Decipheriv.update

---

DecipherChaCha20Poly1305

Instances of the Decipheriv class are used to decrypt data. The class can be used in one way:

• Using the decipher.update() and decipher.final() methods to produce the unencrypted data.

The createDecipheriv method is used to create Decipheriv instances. Decipheriv objects are not to be created directly using the new keyword.

Extends

• Decipheriv

Methods

final()

final(): Buffer

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

Returns

Buffer

Inherited from

Decipheriv.final

setAAD()

setAAD(buffer: ArrayBufferView): this

Parameters

Parameter	Type
buffer	ArrayBufferView

Returns

this

setAuthTag()

setAuthTag(buffer: ArrayBufferView): this

Parameters

Parameter	Type
buffer	ArrayBufferView

Returns

this

update()

update(data: ArrayBufferView): Buffer

Updates the decipher with data.

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

Parameters

Parameter	Type
data	ArrayBufferView

Returns

Buffer

Inherited from

Decipheriv.update

---

DecipherGCM

Instances of the Decipheriv class are used to decrypt data. The class can be used in one way:

• Using the decipher.update() and decipher.final() methods to produce the unencrypted data.

The createDecipheriv method is used to create Decipheriv instances. Decipheriv objects are not to be created directly using the new keyword.

Extends

• Decipheriv

Methods

final()

final(): Buffer

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

Returns

Buffer

Inherited from

Decipheriv.final

setAAD()

setAAD(buffer: ArrayBufferView): this

Parameters

Parameter	Type
buffer	ArrayBufferView

Returns

this

setAuthTag()

setAuthTag(buffer: ArrayBufferView): this

Parameters

Parameter	Type
buffer	ArrayBufferView

Returns

this

update()

update(data: ArrayBufferView): Buffer

Updates the decipher with data.

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

Parameters

Parameter	Type
data	ArrayBufferView

Returns

Buffer

Inherited from

Decipheriv.update

---

DecipherOCB

Instances of the Decipheriv class are used to decrypt data. The class can be used in one way:

• Using the decipher.update() and decipher.final() methods to produce the unencrypted data.

The createDecipheriv method is used to create Decipheriv instances. Decipheriv objects are not to be created directly using the new keyword.

Extends

• Decipheriv

Methods

final()

final(): Buffer

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

Returns

Buffer

Inherited from

Decipheriv.final

setAAD()

setAAD(buffer: ArrayBufferView): this

Parameters

Parameter	Type
buffer	ArrayBufferView

Returns

this

setAuthTag()

setAuthTag(buffer: ArrayBufferView): this

Parameters

Parameter	Type
buffer	ArrayBufferView

Returns

this

update()

update(data: ArrayBufferView): Buffer

Updates the decipher with data.

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

Parameters

Parameter	Type
data	ArrayBufferView

Returns

Buffer

Inherited from

Decipheriv.update

Type Aliases

BinaryLike

BinaryLike = string | ArrayBufferView

---

BinaryToTextEncoding

BinaryToTextEncoding = "base64" | "hex"

---

CharacterEncoding

CharacterEncoding = "utf8" | "utf-8" | "utf16le" | "utf-16le" | "latin1"

---

CipherCCMTypes

CipherCCMTypes = "aes-128-ccm" | "aes-192-ccm" | "aes-256-ccm"

---

CipherChaCha20Poly1305Types

CipherChaCha20Poly1305Types = "chacha20-poly1305"

---

CipherGCMTypes

CipherGCMTypes = "aes-128-gcm" | "aes-192-gcm" | "aes-256-gcm"

---

CipherKey

CipherKey = BinaryLike

---

CipherOCBTypes

CipherOCBTypes = "aes-128-ocb" | "aes-192-ocb" | "aes-256-ocb"

---

Encoding

Encoding = BinaryToTextEncoding | CharacterEncoding | LegacyCharacterEncoding

---

LegacyCharacterEncoding

LegacyCharacterEncoding = "ascii"

---

UUID

UUID = `${string}-${string}-${string}-${string}-${string}`

Functions

createCipheriv()

Call Signature

createCipheriv(algorithm: CipherCCMTypes, key: BinaryLike, iv: BinaryLike, options: CipherCCMOptions): Cipheriv

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, theauthTagLength option is required and specifies the length of the authentication tag in bytes, see CCM mode. In GCM mode, the authTagLengthoption is not required but can be used to set the length of the authentication tag and defaults to 16 bytes. For chacha20-poly1305, the authTagLength option defaults to 16 bytes.

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.

Parameters

Parameter	Type
algorithm	CipherCCMTypes
key	BinaryLike
iv	BinaryLike
options	CipherCCMOptions

Returns

Cipheriv

Call Signature

createCipheriv(algorithm: CipherOCBTypes, key: BinaryLike, iv: BinaryLike, options: CipherOCBOptions): CipherOCB

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, theauthTagLength option is required and specifies the length of the authentication tag in bytes, see CCM mode. In GCM mode, the authTagLengthoption is not required but can be used to set the length of the authentication tag and defaults to 16 bytes. For chacha20-poly1305, the authTagLength option defaults to 16 bytes.

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.

Parameters

Parameter	Type
algorithm	CipherOCBTypes
key	BinaryLike
iv	BinaryLike
options	CipherOCBOptions

Returns

CipherOCB

Call Signature

createCipheriv(algorithm: CipherGCMTypes, key: BinaryLike, iv: BinaryLike, options?: CipherGCMOptions): CipherGCM

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, theauthTagLength option is required and specifies the length of the authentication tag in bytes, see CCM mode. In GCM mode, the authTagLengthoption is not required but can be used to set the length of the authentication tag and defaults to 16 bytes. For chacha20-poly1305, the authTagLength option defaults to 16 bytes.

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.

Parameters

Parameter	Type
algorithm	CipherGCMTypes
key	BinaryLike
iv	BinaryLike
options?	CipherGCMOptions

Returns

CipherGCM

Call Signature

createCipheriv(algorithm: "chacha20-poly1305", key: BinaryLike, iv: BinaryLike, options?: CipherChaCha20Poly1305Options): CipherChaCha20Poly1305

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, theauthTagLength option is required and specifies the length of the authentication tag in bytes, see CCM mode. In GCM mode, the authTagLengthoption is not required but can be used to set the length of the authentication tag and defaults to 16 bytes. For chacha20-poly1305, the authTagLength option defaults to 16 bytes.

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.

Parameters

Parameter	Type
algorithm	"chacha20-poly1305"
key	BinaryLike
iv	BinaryLike
options?	CipherChaCha20Poly1305Options

Returns

CipherChaCha20Poly1305

Call Signature

createCipheriv(algorithm: string, key: BinaryLike, iv: BinaryLike | null): Cipheriv

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, theauthTagLength option is required and specifies the length of the authentication tag in bytes, see CCM mode. In GCM mode, the authTagLengthoption is not required but can be used to set the length of the authentication tag and defaults to 16 bytes. For chacha20-poly1305, the authTagLength option defaults to 16 bytes.

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.

Parameters

Parameter	Type
algorithm	string
key	BinaryLike
iv	BinaryLike | null

Returns

Cipheriv

---

createDecipheriv()

Call Signature

createDecipheriv(algorithm: CipherCCMTypes, key: BinaryLike, iv: BinaryLike, options: CipherCCMOptions): DecipherCCM

Creates and returns a Decipheriv 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 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.

Parameters

Parameter	Type
algorithm	CipherCCMTypes
key	BinaryLike
iv	BinaryLike
options	CipherCCMOptions

Returns

DecipherCCM

Call Signature

createDecipheriv(algorithm: CipherOCBTypes, key: BinaryLike, iv: BinaryLike, options: CipherOCBOptions): DecipherOCB

Creates and returns a Decipheriv 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 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.

Parameters

Parameter	Type
algorithm	CipherOCBTypes
key	BinaryLike
iv	BinaryLike
options	CipherOCBOptions

Returns

DecipherOCB

Call Signature

createDecipheriv(algorithm: CipherGCMTypes, key: BinaryLike, iv: BinaryLike, options?: CipherGCMOptions): DecipherGCM

Creates and returns a Decipheriv 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 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.

Parameters

Parameter	Type
algorithm	CipherGCMTypes
key	BinaryLike
iv	BinaryLike
options?	CipherGCMOptions

Returns

DecipherGCM

Call Signature

createDecipheriv(algorithm: "chacha20-poly1305", key: BinaryLike, iv: BinaryLike, options?: CipherChaCha20Poly1305Options): DecipherChaCha20Poly1305

Creates and returns a Decipheriv 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 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.

Parameters

Parameter	Type
algorithm	"chacha20-poly1305"
key	BinaryLike
iv	BinaryLike
options?	CipherChaCha20Poly1305Options

Returns

DecipherChaCha20Poly1305

Call Signature

createDecipheriv(algorithm: string, key: BinaryLike, iv: BinaryLike | null): Decipheriv

Creates and returns a Decipheriv 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 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.

Parameters

Parameter	Type
algorithm	string
key	BinaryLike
iv	BinaryLike | null

Returns

Decipheriv

---

createHash()

createHash(algorithm: string): Hash

Creates and returns a Hash object that can be used to generate hash digests using the given algorithm.

The algorithm is supported by 'md4', 'md5', 'sha1', 'sha256','sha384' and 'sha512'.

Parameters

Parameter	Type
algorithm	string

Returns

Hash

---

createHmac()

createHmac(algorithm: string, key: BinaryLike): Hmac

Creates and returns an Hmac object that uses the given algorithm and key.

The algorithm is supported by 'md4', 'md5', 'sha1', 'sha256','sha384' and 'sha512'.

The key is the HMAC key used to generate the cryptographic HMAC hash. 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 randomBytes or generateKey, its length should not exceed the block size of algorithm (e.g., 512 bits for SHA-256).

Parameters

Parameter	Type
algorithm	string
key	BinaryLike

Returns

Hmac

---

getRandomValues()

getRandomValues<T>(typedArray: T): T

A convenient alias for webcrypto.getRandomValues. This implementation is not compliant with the Web Crypto spec, to write web-compatible code use webcrypto.getRandomValues instead.

Type Parameters

Type Parameter
T extends ArrayBufferView

Parameters

Parameter	Type
typedArray	T

Returns

T

Returns typedArray.

---

randomBytes()

randomBytes(size: number): Buffer

Generates cryptographically strong pseudorandom data. The size argument is a number indicating the number of bytes to generate.

the random bytes are generated synchronously and returned as a Buffer. An error will be thrown if there is a problem generating the bytes.

// Synchronous
import { randomBytes } from '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.

Parameters

Parameter	Type	Description
size	number	The number of bytes to generate. The size must not be larger than 2**31 - 1.

Returns

Buffer

---

randomFill()

Call Signature

randomFill<T>(buffer: T, callback: (err: Error | null, buf: T) => void): void

This function is similar to 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 'buffer';
import { randomFill } from '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'));
});

// The above is equivalent to the following:
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 'buffer';
import { randomFill } from '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'));
});

Type Parameters

Type Parameter
T extends ArrayBufferView

Parameters

Parameter	Type	Description
buffer	T	Must be supplied. The size of the provided buffer must not be larger than 2**31 - 1.
callback	(err: Error | null, buf: T) => void	function(err, buf) {}.

Returns

void

Call Signature

randomFill<T>(buffer: T, offset: number, callback: (err: Error | null, buf: T) => void): void

This function is similar to 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 'buffer';
import { randomFill } from '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'));
});

// The above is equivalent to the following:
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 'buffer';
import { randomFill } from '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'));
});

Type Parameters

Type Parameter
T extends ArrayBufferView

Parameters

Parameter	Type	Description
buffer	T	Must be supplied. The size of the provided buffer must not be larger than 2**31 - 1.
offset	number
callback	(err: Error | null, buf: T) => void	function(err, buf) {}.

Returns

void

Call Signature

randomFill<T>(buffer: T, offset: number, size: number, callback: (err: Error | null, buf: T) => void): void

This function is similar to 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 'buffer';
import { randomFill } from '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'));
});

// The above is equivalent to the following:
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 'buffer';
import { randomFill } from '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'));
});

Type Parameters

Type Parameter
T extends ArrayBufferView

Parameters

Parameter	Type	Description
buffer	T	Must be supplied. The size of the provided buffer must not be larger than 2**31 - 1.
offset	number
size	number
callback	(err: Error | null, buf: T) => void	function(err, buf) {}.

Returns

void

---

randomFillSync()

randomFillSync<T>(buffer: T, offset?: number, size?: number): T

Synchronous version of randomFill.

import { Buffer } from 'buffer';
import { randomFillSync } from 'crypto';

const buf = Buffer.alloc(10);
console.log(randomFillSync(buf).toString('hex'));

randomFillSync(buf, 5);
console.log(buf.toString('hex'));

// The above is equivalent to the following:
randomFillSync(buf, 5, 5);
console.log(buf.toString('hex'));

Any ArrayBuffer, TypedArray or DataView instance may be passed asbuffer.

import { Buffer } from 'buffer';
import { randomFillSync } from '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'));

Type Parameters

Type Parameter
T extends ArrayBufferView

Parameters

Parameter	Type	Description
buffer	T	Must be supplied. The size of the provided buffer must not be larger than 2**31 - 1.
offset?	number
size?	number

Returns

T

The object passed as buffer argument.

---

randomInt()

Call Signature

randomInt(max: number): number

Return a random integer n such that min <= n < max. This implementation avoids modulo bias.

The range (max - min) must be less than 2**48. min and max must be safe integers.

// Synchronous
import { randomInt } from 'crypto';

const n = randomInt(3);
console.log(`Random number chosen from (0, 1, 2): ${n}`);

// With `min` argument
import { randomInt } from 'crypto';

const n = randomInt(1, 7);
console.log(`The dice rolled: ${n}`);

Parameters

Parameter	Type	Description
max	number	End of random range (exclusive).

Returns

number

Call Signature

randomInt(min: number, max: number): number

Return a random integer n such that min <= n < max. This implementation avoids modulo bias.

The range (max - min) must be less than 2**48. min and max must be safe integers.

// Synchronous
import { randomInt } from 'crypto';

const n = randomInt(3);
console.log(`Random number chosen from (0, 1, 2): ${n}`);

// With `min` argument
import { randomInt } from 'crypto';

const n = randomInt(1, 7);
console.log(`The dice rolled: ${n}`);

Parameters

Parameter	Type	Description
min	number	Start of random range (inclusive).
max	number	End of random range (exclusive).

Returns

number

---

randomUUID()

randomUUID(): `${string}-${string}-${string}-${string}-${string}`

Generates a random RFC 4122 version 4 UUID. The UUID is generated using a cryptographic pseudorandom number generator.

Returns

`${string}-${string}-${string}-${string}-${string}`