Crypto — Node.js 22 LTS

Криптография

Исходный код: lib/crypto.js

Модуль node:crypto предоставляет криптографические функции, включающие набор обёрток для функций хеширования, HMAC, шифрования, расшифрования, подписания и проверки OpenSSL.

Модули JavaScript

const { createHmac } = await import('node:crypto');

const secret = 'abcdefg';
const hash = createHmac('sha256', secret)
               .update('I love cupcakes')
               .digest('hex');
console.log(hash);
// Prints:
//   c0fa1bc00531bd78ef38c628449c5102aeabd49b5dc3a2a516ea6ea959d6658e

CommonJS

const { createHmac } = require('node:crypto');

const secret = 'abcdefg';
const hash = createHmac('sha256', secret)
               .update('I love cupcakes')
               .digest('hex');
console.log(hash);
// Prints:
//   c0fa1bc00531bd78ef38c628449c5102aeabd49b5dc3a2a516ea6ea959d6658e

Определение отсутствия поддержки криптографии

Node.js может быть собран без поддержки модуля node:crypto. В таких случаях попытка выполнить import из crypto или вызов require('node:crypto') приведёт к возникновению ошибки.

При использовании CommonJS возникшую ошибку можно перехватить с помощью try/catch:

let crypto;
try {
  crypto = require('node:crypto');
} catch (err) {
  console.error('crypto support is disabled!');
} copy

При использовании лексического ключевого слова ESM import ошибку можно перехватить, только если обработчик для process.on('uncaughtException') зарегистрирован до любой попытки загрузить модуль (например, с помощью модуля предварительной загрузки).

При использовании ESM, если существует вероятность, что код будет запущен в сборке Node.js без поддержки криптографии, рассмотрите возможность использования функции import() вместо лексического ключевого слова import:

let crypto;
try {
  crypto = await import('node:crypto');
} catch (err) {
  console.error('crypto support is disabled!');
} copy

Класс: `Certificate`

Добавлено в: v0.11.8

SPKAC — механизм запроса на подпись сертификата, первоначально реализованный Netscape и официально определённый в качестве части элемента keygen в HTML5.

<keygen> объявлен устаревшим начиная с HTML 5.2, и новые проекты больше не должны использовать этот элемент.

Модуль node:crypto предоставляет класс Certificate для работы с данными SPKAC. Чаще всего он используется для обработки данных, созданных элементом <keygen> HTML5. Внутри Node.js использует реализацию SPKAC в OpenSSL.

Статический метод: `Certificate.exportChallenge(spkac[, encoding])`

История

Версия	Изменения
v15.0.0	Аргумент spkac может иметь тип ArrayBuffer. Максимальный размер аргумента spkac ограничен 2**31 - 1 байтами.
v9.0.0	Добавлено в: v9.0.0

spkac <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
encoding <string> Кодировка строки spkac.
Возвращает: <Buffer> Компонент challenge структуры данных spkac, которая включает открытый ключ и challenge.

Модули JavaScript

const { Certificate } = await import('node:crypto');
const spkac = getSpkacSomehow();
const challenge = Certificate.exportChallenge(spkac);
console.log(challenge.toString('utf8'));
// Prints: the challenge as a UTF8 string

CommonJS

const { Certificate } = require('node:crypto');
const spkac = getSpkacSomehow();
const challenge = Certificate.exportChallenge(spkac);
console.log(challenge.toString('utf8'));
// Prints: the challenge as a UTF8 string

Статический метод: `Certificate.exportPublicKey(spkac[, encoding])`

История

Версия	Изменения
v15.0.0	Аргумент spkac может иметь тип ArrayBuffer. Максимальный размер аргумента spkac ограничен 2**31 - 1 байтами.
v9.0.0	Добавлено в: v9.0.0

spkac <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
encoding <string> Кодировка строки spkac.
Возвращает: <Buffer> Компонент открытого ключа структуры данных spkac, которая включает открытый ключ и challenge.

Модули JavaScript

const { Certificate } = await import('node:crypto');
const spkac = getSpkacSomehow();
const publicKey = Certificate.exportPublicKey(spkac);
console.log(publicKey);
// Prints: the public key as <Buffer ...>

CommonJS

const { Certificate } = require('node:crypto');
const spkac = getSpkacSomehow();
const publicKey = Certificate.exportPublicKey(spkac);
console.log(publicKey);
// Prints: the public key as <Buffer ...>

Статический метод: `Certificate.verifySpkac(spkac[, encoding])`

История

Версия	Изменения
v15.0.0	Аргумент spkac может иметь тип ArrayBuffer. Добавлена кодировка. Максимальный размер аргумента spkac ограничен 2**31 - 1 байтами.
v9.0.0	Добавлено в: v9.0.0

spkac <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
encoding <string> Кодировка строки spkac.
Возвращает: <boolean> true, если указанная структура данных spkac действительна, и false в противном случае.

Модули JavaScript

import { Buffer } from 'node:buffer';
const { Certificate } = await import('node:crypto');

const spkac = getSpkacSomehow();
console.log(Certificate.verifySpkac(Buffer.from(spkac)));
// Prints: true or false

CommonJS

const { Buffer } = require('node:buffer');
const { Certificate } = require('node:crypto');

const spkac = getSpkacSomehow();
console.log(Certificate.verifySpkac(Buffer.from(spkac)));
// Prints: true or false

Устаревший API

Стабильность: 0 - Устаревший

В рамках устаревшего интерфейса можно создавать экземпляры класса crypto.Certificate, как показано в примерах ниже.

`new crypto.Certificate()`

Экземпляры класса Certificate можно создавать с помощью ключевого слова new или вызывая crypto.Certificate() как функцию:

Модули JavaScript

const { Certificate } = await import('node:crypto');

const cert1 = new Certificate();
const cert2 = Certificate();

CommonJS

const { Certificate } = require('node:crypto');

const cert1 = new Certificate();
const cert2 = Certificate();

`certificate.exportChallenge(spkac[, encoding])`

Добавлено в: v0.11.8

spkac <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
encoding <string> Кодировка строки spkac.
Возвращает: <Buffer> Компонент challenge структуры данных spkac, которая включает открытый ключ и challenge.

Модули JavaScript

const { Certificate } = await import('node:crypto');
const cert = Certificate();
const spkac = getSpkacSomehow();
const challenge = cert.exportChallenge(spkac);
console.log(challenge.toString('utf8'));
// Prints: the challenge as a UTF8 string

CommonJS

const { Certificate } = require('node:crypto');
const cert = Certificate();
const spkac = getSpkacSomehow();
const challenge = cert.exportChallenge(spkac);
console.log(challenge.toString('utf8'));
// Prints: the challenge as a UTF8 string

`certificate.exportPublicKey(spkac[, encoding])`

Добавлено в: v0.11.8

spkac <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
encoding <string> Кодировка строки spkac.
Возвращает: <Buffer> Компонент открытого ключа структуры данных spkac, которая включает открытый ключ и challenge.

Модули JavaScript

const { Certificate } = await import('node:crypto');
const cert = Certificate();
const spkac = getSpkacSomehow();
const publicKey = cert.exportPublicKey(spkac);
console.log(publicKey);
// Prints: the public key as <Buffer ...>

CommonJS

const { Certificate } = require('node:crypto');
const cert = Certificate();
const spkac = getSpkacSomehow();
const publicKey = cert.exportPublicKey(spkac);
console.log(publicKey);
// Prints: the public key as <Buffer ...>

`certificate.verifySpkac(spkac[, encoding])`

Добавлено в: v0.11.8

spkac <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
encoding <string> Кодировка строки spkac.
Возвращает: <boolean> true, если указанная структура данных spkac действительна, и false в противном случае.

Модули JavaScript

import { Buffer } from 'node:buffer';
const { Certificate } = await import('node:crypto');

const cert = Certificate();
const spkac = getSpkacSomehow();
console.log(cert.verifySpkac(Buffer.from(spkac)));
// Prints: true or false

CommonJS

const { Buffer } = require('node:buffer');
const { Certificate } = require('node:crypto');

const cert = Certificate();
const spkac = getSpkacSomehow();
console.log(cert.verifySpkac(Buffer.from(spkac)));
// Prints: true or false

Класс: `Cipher`

Добавлено в: v0.1.94

Расширяет: <stream.Transform>

Экземпляры класса Cipher используются для шифрования данных. Класс можно использовать одним из двух способов:

Как поток для чтения и записи: незашифрованные данные записываются, а зашифрованные данные считываются, или
С помощью методов cipher.update() и cipher.final() для получения зашифрованных данных.

Для создания экземпляров Cipher используется метод crypto.createCipheriv(). Объекты Cipher нельзя создавать напрямую с помощью ключевого слова new.

Пример: использование объектов Cipher в качестве потоков:

Модули JavaScript

const {
  scrypt,
  randomFill,
  createCipheriv,
} = await import('node:crypto');

const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';

// First, we'll generate the key. The key length is dependent on the algorithm.
// In this case for aes192, it is 24 bytes (192 bits).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err;
  // Then, we'll generate a random initialization vector
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err;

    // Once we have the key and iv, we can create and use the cipher...
    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();
  });
});

CommonJS

const {
  scrypt,
  randomFill,
  createCipheriv,
} = require('node:crypto');

const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';

// First, we'll generate the key. The key length is dependent on the algorithm.
// In this case for aes192, it is 24 bytes (192 bits).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err;
  // Then, we'll generate a random initialization vector
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err;

    // Once we have the key and iv, we can create and use the cipher...
    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();
  });
});

Пример: использование Cipher и связанных потоков:

Модули JavaScript

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';

// First, we'll generate the key. The key length is dependent on the algorithm.
// In this case for aes192, it is 24 bytes (192 bits).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err;
  // Then, we'll generate a random initialization vector
  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;
    });
  });
});

CommonJS

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';

// First, we'll generate the key. The key length is dependent on the algorithm.
// In this case for aes192, it is 24 bytes (192 bits).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err;
  // Then, we'll generate a random initialization vector
  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;
    });
  });
});

Пример: использование методов cipher.update() и cipher.final():

Модули JavaScript

const {
  scrypt,
  randomFill,
  createCipheriv,
} = await import('node:crypto');

const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';

// First, we'll generate the key. The key length is dependent on the algorithm.
// In this case for aes192, it is 24 bytes (192 bits).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err;
  // Then, we'll generate a random initialization vector
  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);
  });
});

CommonJS

const {
  scrypt,
  randomFill,
  createCipheriv,
} = require('node:crypto');

const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';

// First, we'll generate the key. The key length is dependent on the algorithm.
// In this case for aes192, it is 24 bytes (192 bits).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err;
  // Then, we'll generate a random initialization vector
  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])`

Добавлено в: v0.1.94

outputEncoding <string> Кодировка возвращаемого значения.
Возвращает: <Buffer> | <string> Любые оставшиеся зашифрованные данные. Если указано outputEncoding, возвращается строка. Если outputEncoding не указан, возвращается Buffer.

После вызова метода cipher.final() объект Cipher больше нельзя использовать для шифрования данных. Повторный вызов cipher.final() приведёт к возникновению ошибки.

`cipher.getAuthTag()`

Добавлено в: v1.0.0

Возвращает: <Buffer> При использовании режима аутентифицированного шифрования (в настоящее время поддерживаются GCM, CCM, OCB и chacha20-poly1305) метод cipher.getAuthTag() возвращает Buffer, содержащий тег аутентификации, вычисленный на основе заданных данных.

Метод cipher.getAuthTag() следует вызывать только после завершения шифрования с помощью метода cipher.final().

Если при создании экземпляра cipher был задан параметр authTagLength, эта функция вернёт ровно authTagLength байт.

`cipher.setAAD(buffer[, options])`

Добавлено в: v1.0.0

buffer <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
options <Object> Параметры stream.transform
- plaintextLength <number>
- encoding <string> Кодировка строки, используемая, если buffer является строкой.
Возвращает: <Cipher> Тот же экземпляр Cipher для цепочки вызовов.

При использовании режима аутентифицированного шифрования (в настоящее время поддерживаются GCM, CCM, OCB и chacha20-poly1305) метод cipher.setAAD() задаёт значение для входного параметра дополнительных аутентифицированных данных (AAD).

Параметр plaintextLength необязателен для GCM и OCB. При использовании CCM параметр plaintextLength необходимо указать, а его значение должно соответствовать длине открытого текста в байтах. См. режим CCM.

Метод cipher.setAAD() необходимо вызвать до cipher.update().

`cipher.setAutoPadding([autoPadding])`

Добавлено в: v0.7.1

autoPadding <boolean> По умолчанию: true
Возвращает: <Cipher> Тот же экземпляр Cipher для цепочки вызовов.

При использовании блочных алгоритмов шифрования класс Cipher автоматически добавляет к входным данным заполнение до соответствующего размера блока. Чтобы отключить заполнение по умолчанию, вызовите cipher.setAutoPadding(false).

Когда autoPadding имеет значение false, длина всех входных данных должна быть кратна размеру блока шифра, иначе cipher.final() вызовет ошибку. Отключение автоматического заполнения полезно для нестандартных схем заполнения, например при использовании 0x0 вместо заполнения PKCS.

Метод cipher.setAutoPadding() необходимо вызвать до cipher.final().

`cipher.update(data[, inputEncoding][, outputEncoding])`

История

Версия	Изменения
v6.0.0	Значение `inputEncoding` по умолчанию изменено с `binary` на `utf8`.
v0.1.94	Добавлено в: v0.1.94

data <string> | <Buffer> | <TypedArray> | <DataView>
inputEncoding <string> Кодировка данных.
outputEncoding <string> Кодировка возвращаемого значения.
Возвращает: <Buffer> | <string>

Обновляет шифр, используя data. Если указан аргумент inputEncoding, аргумент data представляет собой строку в указанной кодировке. Если аргумент inputEncoding не указан, data должен иметь тип Buffer, TypedArray или DataView. Если data имеет тип Buffer, TypedArray или DataView, то inputEncoding игнорируется.

Параметр outputEncoding задаёт формат вывода зашифрованных данных. Если указан outputEncoding, возвращается строка в указанной кодировке. Если outputEncoding не задан, возвращается Buffer.

Метод cipher.update() можно вызывать несколько раз с новыми данными до вызова cipher.final(). Вызов cipher.update() после cipher.final() приведёт к возникновению ошибки.

Класс: `Decipher`

Добавлено в: v0.1.94

Наследует: <stream.Transform>

Экземпляры класса Decipher используются для расшифровки данных. Класс можно использовать одним из двух способов:

Как поток с возможностью чтения и записи, в который записываются зашифрованные данные, чтобы получить незашифрованные данные на стороне чтения, или
С помощью методов decipher.update() и decipher.final() для получения незашифрованных данных.

Метод crypto.createDecipheriv() используется для создания экземпляров Decipher. Объекты Decipher не следует создавать напрямую с помощью ключевого слова new.

Пример: использование объектов Decipher в качестве потоков:

Модули JavaScript

import { Buffer } from 'node:buffer';
const {
  scryptSync,
  createDecipheriv,
} = await import('node:crypto');

const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';
// Key length is dependent on the algorithm. In this case for aes192, it is
// 24 bytes (192 bits).
// Use the async `crypto.scrypt()` instead.
const key = scryptSync(password, 'salt', 24);
// The IV is usually passed along with the ciphertext.
const iv = Buffer.alloc(16, 0); // Initialization vector.

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);
  // Prints: some clear text data
});

// Encrypted with same algorithm, key and iv.
const encrypted =
  'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa';
decipher.write(encrypted, 'hex');
decipher.end();

CommonJS

const {
  scryptSync,
  createDecipheriv,
} = require('node:crypto');
const { Buffer } = require('node:buffer');

const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';
// Key length is dependent on the algorithm. In this case for aes192, it is
// 24 bytes (192 bits).
// Use the async `crypto.scrypt()` instead.
const key = scryptSync(password, 'salt', 24);
// The IV is usually passed along with the ciphertext.
const iv = Buffer.alloc(16, 0); // Initialization vector.

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);
  // Prints: some clear text data
});

// Encrypted with same algorithm, key and iv.
const encrypted =
  'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa';
decipher.write(encrypted, 'hex');
decipher.end();

Пример: использование Decipher и потоков с передачей данных:

Модули JavaScript

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';
// Use the async `crypto.scrypt()` instead.
const key = scryptSync(password, 'salt', 24);
// The IV is usually passed along with the ciphertext.
const iv = Buffer.alloc(16, 0); // Initialization vector.

const decipher = createDecipheriv(algorithm, key, iv);

const input = createReadStream('test.enc');
const output = createWriteStream('test.js');

input.pipe(decipher).pipe(output);

CommonJS

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';
// Use the async `crypto.scrypt()` instead.
const key = scryptSync(password, 'salt', 24);
// The IV is usually passed along with the ciphertext.
const iv = Buffer.alloc(16, 0); // Initialization vector.

const decipher = createDecipheriv(algorithm, key, iv);

const input = createReadStream('test.enc');
const output = createWriteStream('test.js');

input.pipe(decipher).pipe(output);

Пример: использование методов decipher.update() и decipher.final():

Модули JavaScript

import { Buffer } from 'node:buffer';
const {
  scryptSync,
  createDecipheriv,
} = await import('node:crypto');

const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';
// Use the async `crypto.scrypt()` instead.
const key = scryptSync(password, 'salt', 24);
// The IV is usually passed along with the ciphertext.
const iv = Buffer.alloc(16, 0); // Initialization vector.

const decipher = createDecipheriv(algorithm, key, iv);

// Encrypted using same algorithm, key and iv.
const encrypted =
  'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa';
let decrypted = decipher.update(encrypted, 'hex', 'utf8');
decrypted += decipher.final('utf8');
console.log(decrypted);
// Prints: some clear text data

CommonJS

const {
  scryptSync,
  createDecipheriv,
} = require('node:crypto');
const { Buffer } = require('node:buffer');

const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';
// Use the async `crypto.scrypt()` instead.
const key = scryptSync(password, 'salt', 24);
// The IV is usually passed along with the ciphertext.
const iv = Buffer.alloc(16, 0); // Initialization vector.

const decipher = createDecipheriv(algorithm, key, iv);

// Encrypted using same algorithm, key and iv.
const encrypted =
  'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa';
let decrypted = decipher.update(encrypted, 'hex', 'utf8');
decrypted += decipher.final('utf8');
console.log(decrypted);
// Prints: some clear text data

`decipher.final([outputEncoding])`

Добавлено в: v0.1.94

outputEncoding <string> Кодировка возвращаемого значения.
Возвращает: <Buffer> | <string> Любые оставшиеся расшифрованные данные. Если указано outputEncoding, возвращается строка. Если outputEncoding не задан, возвращается Buffer.

После вызова метода decipher.final() объект Decipher больше нельзя использовать для расшифровки данных. Повторный вызов decipher.final() приведёт к ошибке.

`decipher.setAAD(buffer[, options])`

История

Версия	Изменения
v15.0.0	Аргумент buffer может быть строкой или ArrayBuffer и ограничен размером не более 2 ** 31 - 1 байт.
v7.2.0	Теперь этот метод возвращает ссылку на `decipher`.
v1.0.0	Добавлено в: v1.0.0

buffer <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
options <Object> параметры stream.transform
- plaintextLength <number>
- encoding <string> Кодировка строки, используемая, если buffer является строкой.
Возвращает: <Decipher> Тот же объект Decipher для цепочки вызовов методов.

При использовании режима аутентифицированного шифрования (в настоящее время поддерживаются GCM, CCM, OCB и chacha20-poly1305) метод decipher.setAAD() задаёт значение параметра дополнительных аутентифицированных данных (AAD).

Аргумент options является необязательным для GCM. При использовании CCM необходимо указать параметр plaintextLength, значение которого должно совпадать с длиной зашифрованного текста в байтах. См. режим CCM.

Метод decipher.setAAD() необходимо вызвать до decipher.update().

При передаче строки в качестве buffer учитывайте особенности использования строк в качестве входных данных для криптографических API.

`decipher.setAuthTag(buffer[, encoding])`

История

Версия	Изменения
v22.0.0	Использование тегов GCM длиной, отличной от 128 бит, без указания параметра `authTagLength` при создании `decipher` объявлено устаревшим.
v15.0.0	Аргумент buffer может быть строкой или ArrayBuffer и ограничен размером не более 2 ** 31 - 1 байт.
v11.0.0	Теперь этот метод выбрасывает исключение, если длина тега GCM недопустима.
v7.2.0	Теперь этот метод возвращает ссылку на `decipher`.
v1.0.0	Добавлено в: v1.0.0

buffer <string> | <Buffer> | <ArrayBuffer> | <TypedArray> | <DataView>
encoding <string> Кодировка строки, используемая, если buffer является строкой.
Возвращает: <Decipher> Тот же объект Decipher для цепочки вызовов методов.

При использовании режима аутентифицированного шифрования (в настоящее время поддерживаются GCM, CCM, OCB и chacha20-poly1305) метод decipher.setAuthTag() используется для передачи полученного тега аутентификации. Если тег не предоставлен или зашифрованный текст был изменён, decipher.final() выбросит исключение, указывающее на то, что зашифрованный текст следует отбросить из-за неудачной проверки подлинности. Если длина тега недопустима согласно NIST SP 800-38D или не совпадает со значением параметра authTagLength, decipher.setAuthTag() выбросит ошибку.

Метод decipher.setAuthTag() необходимо вызвать до decipher.update() для режима CCM или до decipher.final() для режимов GCM и OCB, а также для chacha20-poly1305. decipher.setAuthTag() можно вызвать только один раз.

При передаче строки в качестве тега аутентификации учитывайте особенности использования строк в качестве входных данных для криптографических API.

`decipher.setAutoPadding([autoPadding])`

Добавлено в: v0.7.1

autoPadding <boolean> По умолчанию: true
Возвращает: <Decipher> Тот же объект Decipher для цепочки вызовов методов.

Если данные были зашифрованы без стандартного заполнения блоков, вызов decipher.setAutoPadding(false) отключит автоматическое заполнение, чтобы decipher.final() не выполнял проверку и удаление заполнения.

Отключение автоматического заполнения работает только в том случае, если длина входных данных кратна размеру блока шифра.

Метод decipher.setAutoPadding() необходимо вызвать до decipher.final().

`decipher.update(data[, inputEncoding][, outputEncoding])`

История

Версия	Изменения
v6.0.0	Значение `inputEncoding` по умолчанию изменено с `binary` на `utf8`.
v0.1.94	Добавлено в: v0.1.94

data <string> | <Buffer> | <TypedArray> | <DataView>
inputEncoding <string> Кодировка строки data.
outputEncoding <string> Кодировка возвращаемого значения.
Возвращает: <Buffer> | <string>

Обновляет объект decipher, используя data. Если указан аргумент inputEncoding, аргумент data является строкой в заданной кодировке. Если аргумент inputEncoding не указан, data должен быть Buffer. Если data является Buffer, то inputEncoding игнорируется.

Параметр outputEncoding задаёт формат вывода зашифрованных данных. Если указан outputEncoding, возвращается строка в заданной кодировке. Если outputEncoding не задан, возвращается Buffer.

Метод decipher.update() можно вызывать несколько раз с новыми данными до вызова decipher.final(). Вызов decipher.update() после decipher.final() приведёт к ошибке.

Даже если базовый шифр реализует аутентификацию, подлинность и целостность открытого текста, возвращённого этой функцией, на данном этапе могут быть не подтверждены. Для алгоритмов аутентифицированного шифрования подлинность обычно подтверждается только после вызова приложением decipher.final().

Класс: `DiffieHellman`

Добавлено в: v0.5.0

Класс DiffieHellman предназначен для создания обмена ключами Диффи — Хеллмана.

Экземпляры класса DiffieHellman можно создать с помощью функции crypto.createDiffieHellman().

Модули JavaScript

import assert from 'node:assert';

const {
  createDiffieHellman,
} = await import('node:crypto');

// Generate Alice's keys...
const alice = createDiffieHellman(2048);
const aliceKey = alice.generateKeys();

// Generate Bob's keys...
const bob = createDiffieHellman(alice.getPrime(), alice.getGenerator());
const bobKey = bob.generateKeys();

// Exchange and generate the secret...
const aliceSecret = alice.computeSecret(bobKey);
const bobSecret = bob.computeSecret(aliceKey);

// OK
assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex'));

CommonJS

const assert = require('node:assert');

const {
  createDiffieHellman,
} = require('node:crypto');

// Generate Alice's keys...
const alice = createDiffieHellman(2048);
const aliceKey = alice.generateKeys();

// Generate Bob's keys...
const bob = createDiffieHellman(alice.getPrime(), alice.getGenerator());
const bobKey = bob.generateKeys();

// Exchange and generate the secret...
const aliceSecret = alice.computeSecret(bobKey);
const bobSecret = bob.computeSecret(aliceKey);

// OK
assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex'));

`diffieHellman.computeSecret(otherPublicKey[, inputEncoding][, outputEncoding])`

Добавлено в: v0.5.0

otherPublicKey <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
inputEncoding <string> Кодировка строки otherPublicKey.
outputEncoding <string> Кодировка возвращаемого значения.
Возвращает: <Buffer> | <string>

Вычисляет общий секрет, используя otherPublicKey в качестве открытого ключа другой стороны, и возвращает вычисленный общий секрет. Переданный ключ интерпретируется с использованием указанной inputEncoding, а секрет кодируется с использованием указанной outputEncoding. Если inputEncoding не задан, ожидается, что otherPublicKey будет объектом Buffer, TypedArray или DataView.

Если задан outputEncoding, возвращается строка; в противном случае возвращается Buffer.

`diffieHellman.generateKeys([encoding])`

Добавлено в: v0.5.0

encoding <string> Кодировка возвращаемого значения.
Возвращает: <Buffer> | <string>

Генерирует закрытый и открытый ключи Диффи — Хеллмана, если они ещё не были сгенерированы или вычислены, и возвращает открытый ключ в указанной encoding. Этот ключ следует передать другой стороне. Если задан encoding, возвращается строка; в противном случае возвращается Buffer.

Эта функция представляет собой тонкую обёртку над DH_generate_key(). В частности, после генерации или установки закрытого ключа вызов этой функции только обновляет открытый ключ, но не генерирует новый закрытый ключ.

`diffieHellman.getGenerator([encoding])`

Добавлено в: v0.5.0

encoding <string> Кодировка возвращаемого значения.
Возвращает: <Buffer> | <string>

Возвращает генератор Диффи — Хеллмана в указанной encoding. Если задан encoding, возвращается строка; в противном случае возвращается Buffer.

`diffieHellman.getPrime([encoding])`

Добавлено в: v0.5.0

encoding <string> Кодировка возвращаемого значения.
Возвращает: <Buffer> | <string>

Возвращает простое число Диффи — Хеллмана в указанной encoding. Если задан encoding, возвращается строка; в противном случае возвращается Buffer.

`diffieHellman.getPrivateKey([encoding])`

Добавлено в: v0.5.0

encoding <string> Кодировка возвращаемого значения.
Возвращает: <Buffer> | <string>

Возвращает закрытый ключ Диффи — Хеллмана в указанной encoding. Если задан encoding, возвращается строка; в противном случае возвращается Buffer.

`diffieHellman.getPublicKey([encoding])`

Добавлено в: v0.5.0

encoding <string> Кодировка возвращаемого значения.
Возвращает: <Buffer> | <string>

Возвращает открытый ключ Диффи — Хеллмана в указанной encoding. Если задан encoding, возвращается строка; в противном случае возвращается Buffer.

`diffieHellman.setPrivateKey(privateKey[, encoding])`

Добавлено в: v0.5.0

privateKey <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
encoding <string> Кодировка строки privateKey.

Устанавливает закрытый ключ Диффи — Хеллмана. Если указан аргумент encoding, ожидается, что privateKey будет строкой. Если encoding не задан, ожидается, что privateKey будет объектом Buffer, TypedArray или DataView.

Эта функция не вычисляет автоматически соответствующий открытый ключ. Чтобы вручную задать открытый ключ или автоматически вычислить его, можно использовать diffieHellman.setPublicKey() или diffieHellman.generateKeys().

`diffieHellman.setPublicKey(publicKey[, encoding])`

Добавлено в: v0.5.0

publicKey <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
encoding <string> Кодировка строки publicKey.

Устанавливает открытый ключ Диффи — Хеллмана. Если указан аргумент encoding, ожидается, что publicKey будет строкой. Если encoding не задан, ожидается, что publicKey будет объектом Buffer, TypedArray или DataView.

`diffieHellman.verifyError`

Добавлено в: v0.11.12

Битовое поле, содержащее предупреждения и/или ошибки, возникшие в результате проверки, выполненной при инициализации объекта DiffieHellman.

Для этого свойства допустимы следующие значения (определённые в модуле node:constants):

DH_CHECK_P_NOT_SAFE_PRIME
DH_CHECK_P_NOT_PRIME
DH_UNABLE_TO_CHECK_GENERATOR
DH_NOT_SUITABLE_GENERATOR

Класс: `DiffieHellmanGroup`

Добавлено в: v0.7.5

Класс DiffieHellmanGroup принимает в качестве аргумента общеизвестную группу modp. Он работает так же, как DiffieHellman, за исключением того, что не позволяет изменять ключи после создания. Иными словами, он не реализует методы setPublicKey() или setPrivateKey().

Модули JavaScript

const { createDiffieHellmanGroup } = await import('node:crypto');
const dh = createDiffieHellmanGroup('modp16');

CommonJS

const { createDiffieHellmanGroup } = require('node:crypto');
const dh = createDiffieHellmanGroup('modp16');

Поддерживаются следующие группы:

'modp14' (2048 бит, RFC 3526, раздел 3)
'modp15' (3072 бита, RFC 3526, раздел 4)
'modp16' (4096 бит, RFC 3526, раздел 5)
'modp17' (6144 бита, RFC 3526, раздел 6)
'modp18' (8192 бита, RFC 3526, раздел 7)

Следующие группы по-прежнему поддерживаются, но считаются устаревшими (см. Предостережения):

'modp1' (768 бит, RFC 2409, раздел 6.1)
'modp2' (1024 бита, RFC 2409, раздел 6.2)
'modp5' (1536 бит, RFC 3526, раздел 2)

Эти устаревшие группы могут быть удалены в будущих версиях Node.js.

Класс: `ECDH`

Добавлено в: v0.11.14

Класс ECDH — это утилита для создания обмена ключами Диффи — Хеллмана на эллиптических кривых (ECDH).

Экземпляры класса ECDH можно создавать с помощью функции crypto.createECDH().

Модули JavaScript

import assert from 'node:assert';

const {
  createECDH,
} = await import('node:crypto');

// Generate Alice's keys...
const alice = createECDH('secp521r1');
const aliceKey = alice.generateKeys();

// Generate Bob's keys...
const bob = createECDH('secp521r1');
const bobKey = bob.generateKeys();

// Exchange and generate the secret...
const aliceSecret = alice.computeSecret(bobKey);
const bobSecret = bob.computeSecret(aliceKey);

assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex'));
// OK

CommonJS

const assert = require('node:assert');

const {
  createECDH,
} = require('node:crypto');

// Generate Alice's keys...
const alice = createECDH('secp521r1');
const aliceKey = alice.generateKeys();

// Generate Bob's keys...
const bob = createECDH('secp521r1');
const bobKey = bob.generateKeys();

// Exchange and generate the secret...
const aliceSecret = alice.computeSecret(bobKey);
const bobSecret = bob.computeSecret(aliceKey);

assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex'));
// OK

Статический метод: `ECDH.convertKey(key, curve[, inputEncoding[, outputEncoding[, format]]])`

Добавлено в: v10.0.0

key <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
curve <string>
inputEncoding <string> Кодировка строки key.
outputEncoding <string> Кодировка возвращаемого значения.
format <string> По умолчанию: 'uncompressed'
Возвращает: <Buffer> | <string>

Преобразует открытый ключ Диффи — Хеллмана на эллиптической кривой, заданный параметрами key и curve, в формат, заданный параметром format. Аргумент format задаёт кодирование точки и может иметь значение 'compressed', 'uncompressed' или 'hybrid'. Переданный ключ интерпретируется с использованием указанного inputEncoding, а возвращаемый ключ кодируется с использованием указанного outputEncoding.

Чтобы получить список доступных имён кривых, используйте crypto.getCurves(). В последних выпусках OpenSSL команда openssl ecparam -list_curves также отображает имя и описание каждой доступной эллиптической кривой.

Если format не указан, точка будет возвращена в формате 'uncompressed'.

Если inputEncoding не задан, ожидается, что key будет объектом Buffer, TypedArray или DataView.

Пример (распаковка ключа):

Модули JavaScript

const {
  createECDH,
  ECDH,
} = await import('node:crypto');

const ecdh = createECDH('secp256k1');
ecdh.generateKeys();

const compressedKey = ecdh.getPublicKey('hex', 'compressed');

const uncompressedKey = ECDH.convertKey(compressedKey,
                                        'secp256k1',
                                        'hex',
                                        'hex',
                                        'uncompressed');

// The converted key and the uncompressed public key should be the same
console.log(uncompressedKey === ecdh.getPublicKey('hex'));

CommonJS

const {
  createECDH,
  ECDH,
} = require('node:crypto');

const ecdh = createECDH('secp256k1');
ecdh.generateKeys();

const compressedKey = ecdh.getPublicKey('hex', 'compressed');

const uncompressedKey = ECDH.convertKey(compressedKey,
                                        'secp256k1',
                                        'hex',
                                        'hex',
                                        'uncompressed');

// The converted key and the uncompressed public key should be the same
console.log(uncompressedKey === ecdh.getPublicKey('hex'));

`ecdh.computeSecret(otherPublicKey[, inputEncoding][, outputEncoding])`

История

Версия	Изменения
v10.0.0	Формат ошибки изменён для более удобной обработки ошибки, связанной с недопустимым открытым ключом.
v6.0.0	Значение `inputEncoding` по умолчанию изменено с `binary` на `utf8`.
v0.11.14	Добавлено в: v0.11.14

otherPublicKey <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
inputEncoding <string> Кодировка строки otherPublicKey.
outputEncoding <string> Кодировка возвращаемого значения.
Возвращает: <Buffer> | <string>

Вычисляет общий секрет, используя otherPublicKey в качестве открытого ключа другой стороны, и возвращает вычисленный общий секрет. Переданный ключ интерпретируется с использованием указанного inputEncoding, а возвращаемый секрет кодируется с использованием указанного outputEncoding. Если inputEncoding не задан, ожидается, что otherPublicKey будет объектом Buffer, TypedArray или DataView.

Если outputEncoding задан, возвращается строка; в противном случае возвращается Buffer.

ecdh.computeSecret выдаст ошибку ERR_CRYPTO_ECDH_INVALID_PUBLIC_KEY, если otherPublicKey находится за пределами эллиптической кривой. Поскольку otherPublicKey обычно передаётся удалённым пользователем по незащищённой сети, обязательно предусмотрите надлежащую обработку этого исключения.

`ecdh.generateKeys([encoding[, format]])`

Добавлено в: v0.11.14

encoding <string> Кодировка возвращаемого значения.
format <string> По умолчанию: 'uncompressed'
Возвращает: <Buffer> | <string>

Генерирует значения закрытого и открытого ключей Диффи — Хеллмана на эллиптической кривой и возвращает открытый ключ в указанных format и encoding. Этот ключ следует передать другой стороне.

Аргумент format задаёт кодирование точки и может иметь значение 'compressed' или 'uncompressed'. Если format не указан, точка будет возвращена в формате 'uncompressed'.

Если задан encoding, возвращается строка; в противном случае возвращается Buffer.

`ecdh.getPrivateKey([encoding])`

Добавлено в: v0.11.14

encoding <string> Кодировка возвращаемого значения.
Возвращает: <Buffer> | <string> Ключ Диффи — Хеллмана на эллиптической кривой в указанном encoding.

Если задан encoding, возвращается строка; в противном случае возвращается Buffer.

`ecdh.getPublicKey([encoding][, format])`

Добавлено в: v0.11.14

encoding <string> Кодировка возвращаемого значения.
format <string> По умолчанию: 'uncompressed'
Возвращает: <Buffer> | <string> Открытый ключ Диффи — Хеллмана на эллиптической кривой в указанных encoding и format.

Если задан encoding, возвращается строка; в противном случае возвращается Buffer.

`ecdh.setPrivateKey(privateKey[, encoding])`

Добавлено в: v0.11.14

privateKey <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
encoding <string> Кодировка строки privateKey.

Устанавливает закрытый ключ Диффи — Хеллмана на эллиптической кривой. Если задан encoding, ожидается, что privateKey будет строкой; в противном случае ожидается, что privateKey будет объектом Buffer, TypedArray или DataView.

Если privateKey недопустим для кривой, указанной при создании объекта ECDH, будет выброшена ошибка. При установке закрытого ключа соответствующая открытая точка (ключ) также генерируется и задаётся в объекте ECDH.

`ecdh.setPublicKey(publicKey[, encoding])`

Добавлено в: v0.11.14Устарело с: v5.2.0

Стабильность: 0 — Устарело

publicKey <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
encoding <string> Кодировка строки publicKey.

Устанавливает открытый ключ Диффи — Хеллмана на эллиптической кривой. Если задан encoding, ожидается, что publicKey будет строкой; в противном случае ожидается объект Buffer, TypedArray или DataView.

Обычно нет причин вызывать этот метод, поскольку для вычисления общего секрета ECDH требуются только закрытый ключ и открытый ключ другой стороны. Как правило, вызывается либо ecdh.generateKeys(), либо ecdh.setPrivateKey(). Метод ecdh.setPrivateKey() пытается сгенерировать открытую точку/ключ, соответствующую устанавливаемому закрытому ключу.

Пример (получение общего секрета):

Модули JavaScript

const {
  createECDH,
  createHash,
} = await import('node:crypto');

const alice = createECDH('secp256k1');
const bob = createECDH('secp256k1');

// This is a shortcut way of specifying one of Alice's previous private
// keys. It would be unwise to use such a predictable private key in a real
// application.
alice.setPrivateKey(
  createHash('sha256').update('alice', 'utf8').digest(),
);

// Bob uses a newly generated cryptographically strong
// pseudorandom key pair
bob.generateKeys();

const aliceSecret = alice.computeSecret(bob.getPublicKey(), null, 'hex');
const bobSecret = bob.computeSecret(alice.getPublicKey(), null, 'hex');

// aliceSecret and bobSecret should be the same shared secret value
console.log(aliceSecret === bobSecret);

CommonJS

const {
  createECDH,
  createHash,
} = require('node:crypto');

const alice = createECDH('secp256k1');
const bob = createECDH('secp256k1');

// This is a shortcut way of specifying one of Alice's previous private
// keys. It would be unwise to use such a predictable private key in a real
// application.
alice.setPrivateKey(
  createHash('sha256').update('alice', 'utf8').digest(),
);

// Bob uses a newly generated cryptographically strong
// pseudorandom key pair
bob.generateKeys();

const aliceSecret = alice.computeSecret(bob.getPublicKey(), null, 'hex');
const bobSecret = bob.computeSecret(alice.getPublicKey(), null, 'hex');

// aliceSecret and bobSecret should be the same shared secret value
console.log(aliceSecret === bobSecret);

Класс: `Hash`

Добавлено в: v0.1.92

Наследует: <stream.Transform>

Класс Hash — это утилита для создания хеш-дайджестов данных. Его можно использовать одним из двух способов:

как поток, доступный для чтения и записи, в который записываются данные, чтобы на стороне чтения получить вычисленный хеш-дайджест; либо
с помощью методов hash.update() и hash.digest() для получения вычисленного хеша.

Для создания экземпляров Hash используется метод crypto.createHash(). Объекты Hash нельзя создавать напрямую с помощью ключевого слова new.

Пример: использование объектов Hash в качестве потоков:

Модули JavaScript

const {
  createHash,
} = await import('node:crypto');

const hash = createHash('sha256');

hash.on('readable', () => {
  // Only one element is going to be produced by the
  // hash stream.
  const data = hash.read();
  if (data) {
    console.log(data.toString('hex'));
    // Prints:
    //   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50
  }
});

hash.write('some data to hash');
hash.end();

CommonJS

const {
  createHash,
} = require('node:crypto');

const hash = createHash('sha256');

hash.on('readable', () => {
  // Only one element is going to be produced by the
  // hash stream.
  const data = hash.read();
  if (data) {
    console.log(data.toString('hex'));
    // Prints:
    //   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50
  }
});

hash.write('some data to hash');
hash.end();

Пример: использование Hash и связанных потоков:

Модули JavaScript

import { createReadStream } from 'node:fs';
import { stdout } from 'node:process';
const { createHash } = await import('node:crypto');

const hash = createHash('sha256');

const input = createReadStream('test.js');
input.pipe(hash).setEncoding('hex').pipe(stdout);

CommonJS

const { createReadStream } = require('node:fs');
const { createHash } = require('node:crypto');
const { stdout } = require('node:process');

const hash = createHash('sha256');

const input = createReadStream('test.js');
input.pipe(hash).setEncoding('hex').pipe(stdout);

Пример: использование методов hash.update() и hash.digest():

Модули JavaScript

const {
  createHash,
} = await import('node:crypto');

const hash = createHash('sha256');

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

CommonJS

const {
  createHash,
} = require('node:crypto');

const hash = createHash('sha256');

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

`hash.copy([options])`

Добавлено в: v13.1.0

options <Object> stream.transform options
Возвращает: <Hash>

Создаёт новый объект Hash, содержащий глубокую копию внутреннего состояния текущего объекта Hash.

Необязательный аргумент options управляет поведением потока. Для хеш-функций XOF, таких как 'shake256', параметр outputLength можно использовать для указания желаемой длины выходных данных в байтах.

При попытке скопировать объект Hash после вызова его метода hash.digest() выбрасывается ошибка.

Модули JavaScript

// Calculate a rolling hash.
const {
  createHash,
} = await import('node:crypto');

const hash = createHash('sha256');

hash.update('one');
console.log(hash.copy().digest('hex'));

hash.update('two');
console.log(hash.copy().digest('hex'));

hash.update('three');
console.log(hash.copy().digest('hex'));

// Etc.

CommonJS

// Calculate a rolling hash.
const {
  createHash,
} = require('node:crypto');

const hash = createHash('sha256');

hash.update('one');
console.log(hash.copy().digest('hex'));

hash.update('two');
console.log(hash.copy().digest('hex'));

hash.update('three');
console.log(hash.copy().digest('hex'));

// Etc.

`hash.digest([encoding])`

Добавлено в: v0.1.92

encoding <string> Кодировка возвращаемого значения.
Возвращает: <Buffer> | <string>

Вычисляет дайджест всех данных, переданных для хеширования (с помощью метода hash.update()). Если задан encoding, возвращается строка; в противном случае возвращается Buffer.

После вызова метода hash.digest() объект Hash больше нельзя использовать. Повторные вызовы приведут к выбрасыванию ошибки.

`hash.update(data[, inputEncoding])`

История

Версия	Изменения
v6.0.0	Значение `inputEncoding` по умолчанию изменено с `binary` на `utf8`.
v0.1.92	Добавлено в: v0.1.92

data <string> | <Buffer> | <TypedArray> | <DataView>
inputEncoding <string> Кодировка строки data.

Обновляет содержимое хеша с использованием переданного значения data, кодировка которого задаётся параметром inputEncoding. Если encoding не задан, а data является строкой, принудительно используется кодировка 'utf8'. Если data является объектом Buffer, TypedArray или DataView, параметр inputEncoding игнорируется.

Этот метод можно многократно вызывать с новыми данными по мере их поступления в поток.

Класс: `Hmac`

Добавлено в: v0.1.94

Наследует: <stream.Transform>

Класс Hmac — это утилита для создания криптографических дайджестов HMAC. Его можно использовать одним из двух способов:

как поток, доступный для чтения и записи, в который записываются данные, чтобы на стороне чтения получить вычисленный дайджест HMAC; либо
с помощью методов hmac.update() и hmac.digest() для получения вычисленного дайджеста HMAC.

Для создания экземпляров Hmac используется метод crypto.createHmac(). Объекты Hmac нельзя создавать напрямую с помощью ключевого слова new.

Пример: использование объектов Hmac в качестве потоков:

Модули JavaScript

const {
  createHmac,
} = await import('node:crypto');

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

hmac.on('readable', () => {
  // Only one element is going to be produced by the
  // hash stream.
  const data = hmac.read();
  if (data) {
    console.log(data.toString('hex'));
    // Prints:
    //   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e
  }
});

hmac.write('some data to hash');
hmac.end();

CommonJS

const {
  createHmac,
} = require('node:crypto');

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

hmac.on('readable', () => {
  // Only one element is going to be produced by the
  // hash stream.
  const data = hmac.read();
  if (data) {
    console.log(data.toString('hex'));
    // Prints:
    //   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e
  }
});

hmac.write('some data to hash');
hmac.end();

Пример: использование Hmac и связанных потоков:

Модули JavaScript

import { createReadStream } from 'node:fs';
import { stdout } from 'node:process';
const {
  createHmac,
} = await import('node:crypto');

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

const input = createReadStream('test.js');
input.pipe(hmac).pipe(stdout);

CommonJS

const {
  createReadStream,
} = require('node:fs');
const {
  createHmac,
} = require('node:crypto');
const { stdout } = require('node:process');

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

const input = createReadStream('test.js');
input.pipe(hmac).pipe(stdout);

Пример: использование методов hmac.update() и hmac.digest():

Модули JavaScript

const {
  createHmac,
} = await import('node:crypto');

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

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

CommonJS

const {
  createHmac,
} = require('node:crypto');

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

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

`hmac.digest([encoding])`

Добавлено в: v0.1.94

encoding <string> Кодировка возвращаемого значения.
Возвращает: <Buffer> | <string>

Вычисляет дайджест HMAC всех данных, переданных с помощью hmac.update(). Если задан encoding, возвращается строка; в противном случае возвращается Buffer.

После вызова hmac.digest() объект Hmac больше нельзя использовать. Повторные вызовы hmac.digest() приведут к выбрасыванию ошибки.

`hmac.update(data[, inputEncoding])`

История

Версия	Изменения
v6.0.0	Значение `inputEncoding` по умолчанию изменено с `binary` на `utf8`.
v0.1.94	Добавлено в: v0.1.94

data <string> | <Buffer> | <TypedArray> | <DataView>
inputEncoding <string> Кодировка строки data.

Обновляет содержимое Hmac с использованием переданного значения data, кодировка которого задаётся параметром inputEncoding. Если encoding не задан, а data является строкой, принудительно используется кодировка 'utf8'. Если data является объектом Buffer, TypedArray или DataView, параметр inputEncoding игнорируется.

Этот метод можно многократно вызывать с новыми данными по мере их поступления в поток.

Класс: `KeyObject`

История

Версия	Изменения
v14.5.0, v12.19.0	Теперь экземпляры этого класса можно передавать рабочим потокам с помощью `postMessage`.
v11.13.0	Теперь этот класс экспортируется.
v11.6.0	Добавлено в: v11.6.0

Node.js использует класс KeyObject для представления симметричного или асимметричного ключа; для каждого типа ключа доступны разные функции. Методы crypto.createSecretKey(), crypto.createPublicKey() и crypto.createPrivateKey() используются для создания экземпляров KeyObject. Объекты KeyObject не следует создавать напрямую с помощью ключевого слова new.

Большинству приложений следует использовать новый API KeyObject вместо передачи ключей в виде строк или Buffer, поскольку он обеспечивает повышенную безопасность.

Экземпляры KeyObject можно передавать в другие потоки через postMessage(). Получатель получает клонированный объект KeyObject, и указывать KeyObject в аргументе transferList не требуется.

Статический метод: `KeyObject.from(key)`

Добавлено в: v15.0.0

key <CryptoKey>
Возвращает: <KeyObject>

Пример: преобразование экземпляра CryptoKey в KeyObject:

Модули JavaScript

const { KeyObject } = await import('node:crypto');
const { subtle } = globalThis.crypto;

const key = await subtle.generateKey({
  name: 'HMAC',
  hash: 'SHA-256',
  length: 256,
}, true, ['sign', 'verify']);

const keyObject = KeyObject.from(key);
console.log(keyObject.symmetricKeySize);
// Prints: 32 (symmetric key size in bytes)

CommonJS

const { KeyObject } = require('node:crypto');
const { subtle } = globalThis.crypto;

(async function() {
  const key = await subtle.generateKey({
    name: 'HMAC',
    hash: 'SHA-256',
    length: 256,
  }, true, ['sign', 'verify']);

  const keyObject = KeyObject.from(key);
  console.log(keyObject.symmetricKeySize);
  // Prints: 32 (symmetric key size in bytes)
})();

`keyObject.asymmetricKeyDetails`

История

Версия	Изменения
v16.9.0	Предоставлены параметры последовательности `RSASSA-PSS-params` для ключей RSA-PSS.
v15.7.0	Добавлено в: v15.7.0

Тип: <Object>
- modulusLength <number> Размер ключа в битах (RSA, DSA).
- publicExponent <bigint> Открытая экспонента (RSA).
- hashAlgorithm <string> Название хеш-функции (RSA-PSS).
- mgf1HashAlgorithm <string> Название хеш-функции, используемой MGF1 (RSA-PSS).
- saltLength <number> Минимальная длина соли в байтах (RSA-PSS).
- divisorLength <number> Размер q в битах (DSA).
- namedCurve <string> Название эллиптической кривой (EC).

Это свойство существует только для асимметричных ключей. В зависимости от типа ключа этот объект содержит сведения о ключе. Сведения, полученные с помощью этого свойства, нельзя использовать для однозначной идентификации ключа или нарушения его безопасности.

Если материал ключа RSA-PSS содержит последовательность RSASSA-PSS-params, будут установлены свойства hashAlgorithm, mgf1HashAlgorithm и saltLength.

С помощью этого API могут предоставляться и другие сведения о ключе в виде дополнительных атрибутов.

`keyObject.asymmetricKeyType`

История

Версия	Изменения
v13.9.0, v12.17.0	Добавлена поддержка `'dh'`.
v12.0.0	Добавлена поддержка `'rsa-pss'`.
v12.0.0	Для экземпляров KeyObject неизвестного типа это свойство теперь возвращает `undefined` вместо аварийного завершения работы.
v12.0.0	Добавлена поддержка `'x25519'` и `'x448'`.
v12.0.0	Добавлена поддержка `'ed25519'` и `'ed448'`.
v11.6.0	Добавлено в: v11.6.0

Тип: <string>

Для асимметричных ключей это свойство обозначает тип ключа. Поддерживаются следующие типы ключей:

'rsa' (OID 1.2.840.113549.1.1.1)
'rsa-pss' (OID 1.2.840.113549.1.1.10)
'dsa' (OID 1.2.840.10040.4.1)
'ec' (OID 1.2.840.10045.2.1)
'x25519' (OID 1.3.101.110)
'x448' (OID 1.3.101.111)
'ed25519' (OID 1.3.101.112)
'ed448' (OID 1.3.101.113)
'dh' (OID 1.2.840.113549.1.3.1)

Для неизвестных типов undefined и симметричных ключей это свойство имеет значение KeyObject.

`keyObject.equals(otherKeyObject)`

Добавлено в: v17.7.0, v16.15.0

otherKeyObject <KeyObject> Объект KeyObject, с которым сравнивается keyObject.
Возвращает: <boolean>

Возвращает true или false в зависимости от того, совпадают ли тип, значение и параметры ключей полностью. Этот метод не выполняется за постоянное время.

`keyObject.export([options])`

История

Версия	Изменения
v15.9.0	Добавлена поддержка формата `'jwk'`.
v11.6.0	Добавлено в: v11.6.0

options <Object>
Возвращает: <string> | <Buffer> | <Object>

Для симметричных ключей можно использовать следующие параметры кодирования:

format <string> Должно иметь значение 'buffer' (по умолчанию) или 'jwk'.

Для открытых ключей можно использовать следующие параметры кодирования:

type <string> Должно иметь одно из значений: 'pkcs1' (только RSA) или 'spki'.
format <string> Должно иметь значение 'pem', 'der' или 'jwk'.

Для закрытых ключей можно использовать следующие параметры кодирования:

type <string> Должно иметь одно из значений: 'pkcs1' (только RSA), 'pkcs8' или 'sec1' (только EC).
format <string> Должно иметь значение 'pem', 'der' или 'jwk'.
cipher <string> Если задано, закрытый ключ будет зашифрован с использованием указанного cipher и passphrase посредством шифрования на основе пароля PKCS#5 v2.0.
passphrase <string> | <Buffer> Парольная фраза для шифрования; см. cipher.

Тип результата зависит от выбранного формата кодирования: при PEM результатом будет строка, при DER — буфер с данными, закодированными в DER, а при JWK — объект.

Если выбран формат кодирования JWK, все остальные параметры кодирования игнорируются.

Ключи типов PKCS#1, SEC1 и PKCS#8 можно зашифровать, используя сочетание параметров cipher и format. Формат type PKCS#8 можно использовать с любым format для шифрования ключа любого алгоритма (RSA, EC или DH), указав cipher. Ключи PKCS#1 и SEC1 можно зашифровать, указав cipher, только если используется формат PEM format. Для максимальной совместимости используйте PKCS#8 для зашифрованных закрытых ключей. Поскольку PKCS#8 определяет собственный механизм шифрования, шифрование на уровне PEM не поддерживается при шифровании ключа PKCS#8. См. RFC 5208 для шифрования PKCS#8 и RFC 1421 для шифрования PKCS#1 и SEC1.

`keyObject.symmetricKeySize`

Добавлено в: v11.6.0

Тип: <number>

Для секретных ключей это свойство обозначает размер ключа в байтах. Для асимметричных ключей это свойство имеет значение undefined.

`keyObject.toCryptoKey(algorithm, extractable, keyUsages)`

Добавлено в: v22.10.0

algorithm <string> | <Algorithm> | <RsaHashedImportParams> | <EcKeyImportParams> | <HmacImportParams>

extractable <boolean>
keyUsages <string[]> См. Использование ключей.
Возвращает: <CryptoKey>

Преобразует экземпляр KeyObject в CryptoKey.

`keyObject.type`

Добавлено в: v11.6.0

Тип: <string>

В зависимости от типа этого объекта KeyObject это свойство имеет значение 'secret' для секретных (симметричных) ключей, 'public' для открытых (асимметричных) ключей или 'private' для закрытых (асимметричных) ключей.

Класс: `Sign`

Добавлено в: v0.1.92

Наследует: <stream.Writable>

Класс Sign — это средство для создания цифровых подписей. Его можно использовать одним из двух способов:

Как записываемый поток, в который записываются подписываемые данные, а для создания и возврата подписи используется метод sign.sign(), или
С помощью методов sign.update() и sign.sign() для создания подписи.

Метод crypto.createSign() используется для создания экземпляров Sign. Аргументом является строковое название используемой хеш-функции. Объекты Sign не следует создавать напрямую с помощью ключевого слова new.

Пример: использование объектов Sign и Verify в качестве потоков:

Модули JavaScript

const {
  generateKeyPairSync,
  createSign,
  createVerify,
} = await import('node:crypto');

const { privateKey, publicKey } = generateKeyPairSync('ec', {
  namedCurve: 'sect239k1',
});

const sign = createSign('SHA256');
sign.write('some data to sign');
sign.end();
const signature = sign.sign(privateKey, 'hex');

const verify = createVerify('SHA256');
verify.write('some data to sign');
verify.end();
console.log(verify.verify(publicKey, signature, 'hex'));
// Prints: true

CommonJS

const {
  generateKeyPairSync,
  createSign,
  createVerify,
} = require('node:crypto');

const { privateKey, publicKey } = generateKeyPairSync('ec', {
  namedCurve: 'sect239k1',
});

const sign = createSign('SHA256');
sign.write('some data to sign');
sign.end();
const signature = sign.sign(privateKey, 'hex');

const verify = createVerify('SHA256');
verify.write('some data to sign');
verify.end();
console.log(verify.verify(publicKey, signature, 'hex'));
// Prints: true

Пример: использование методов sign.update() и verify.update():

Модули JavaScript

const {
  generateKeyPairSync,
  createSign,
  createVerify,
} = await import('node:crypto');

const { privateKey, publicKey } = generateKeyPairSync('rsa', {
  modulusLength: 2048,
});

const sign = createSign('SHA256');
sign.update('some data to sign');
sign.end();
const signature = sign.sign(privateKey);

const verify = createVerify('SHA256');
verify.update('some data to sign');
verify.end();
console.log(verify.verify(publicKey, signature));
// Prints: true

CommonJS

const {
  generateKeyPairSync,
  createSign,
  createVerify,
} = require('node:crypto');

const { privateKey, publicKey } = generateKeyPairSync('rsa', {
  modulusLength: 2048,
});

const sign = createSign('SHA256');
sign.update('some data to sign');
sign.end();
const signature = sign.sign(privateKey);

const verify = createVerify('SHA256');
verify.update('some data to sign');
verify.end();
console.log(verify.verify(publicKey, signature));
// Prints: true

`sign.sign(privateKey[, outputEncoding])`

История

Версия	Изменения
v15.0.0	Закрытый ключ также может быть объектом ArrayBuffer или CryptoKey.
v13.2.0, v12.16.0	Теперь эта функция поддерживает подписи DSA и ECDSA в формате IEEE-P1363.
v12.0.0	Теперь эта функция поддерживает ключи RSA-PSS.
v11.6.0	Теперь эта функция поддерживает объекты ключей.
v8.0.0	Добавлена поддержка RSASSA-PSS и дополнительных параметров.
v0.1.92	Добавлено в: v0.1.92

privateKey <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
- dsaEncoding <string>
- padding <integer>
- saltLength <integer>
outputEncoding <string> Кодировка возвращаемого значения.
Возвращает: <Buffer> | <string>

Вычисляет подпись для всех данных, переданных с помощью метода sign.update() или sign.write().

Если privateKey не является объектом KeyObject, эта функция действует так, как если бы privateKey был передан в crypto.createPrivateKey(). Если это объект, можно передать следующие дополнительные свойства:

dsaEncoding <string> Для DSA и ECDSA этот параметр задает формат создаваемой подписи. Возможные значения:
- 'der' (по умолчанию): структура подписи ASN.1 в кодировке DER, кодирующая (r, s).
- 'ieee-p1363': формат подписи r || s, предложенный в IEEE-P1363.
padding <integer> Необязательное значение дополнения для RSA, одно из следующих:
- crypto.constants.RSA_PKCS1_PADDING (по умолчанию)
- crypto.constants.RSA_PKCS1_PSS_PADDING
RSA_PKCS1_PSS_PADDING будет использовать MGF1 с той же хеш-функцией, что и для подписания сообщения, как указано в разделе 3.1 RFC 4055, если только хеш-функция MGF1 не была указана в составе ключа в соответствии с разделом 3.3 RFC 4055.
saltLength <integer> Длина соли, если для дополнения используется RSA_PKCS1_PSS_PADDING. Специальное значение crypto.constants.RSA_PSS_SALTLEN_DIGEST устанавливает длину соли равной размеру дайджеста, а crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN (по умолчанию) — равной максимально допустимому значению.

Если задан outputEncoding, возвращается строка; в противном случае возвращается Buffer.

После вызова метода sign.sign() объект Sign нельзя использовать повторно. Повторные вызовы sign.sign() приведут к ошибке.

`sign.update(data[, inputEncoding])`

История

Версия	Изменения
v6.0.0	Значение `inputEncoding` по умолчанию изменено с `binary` на `utf8`.
v0.1.92	Добавлено в: v0.1.92

data <string> | <Buffer> | <TypedArray> | <DataView>
inputEncoding <string> Кодировка строки data.

Обновляет содержимое Sign указанными данными data, кодировка которых задается в inputEncoding. Если encoding не задан, а data является строкой, используется кодировка 'utf8'. Если data является Buffer, TypedArray или DataView, параметр inputEncoding игнорируется.

Этот метод можно вызывать многократно по мере поступления новых данных в потоке.

Класс: `Verify`

Добавлено в: v0.1.92

Наследует: <stream.Writable>

Класс Verify — это вспомогательный класс для проверки подписей. Его можно использовать одним из двух способов:

Как записываемый поток, в который записываются данные для проверки предоставленной подписи, или
С помощью методов verify.update() и verify.verify() для проверки подписи.

Метод crypto.createVerify() используется для создания экземпляров Verify. Объекты Verify не следует создавать напрямую с помощью ключевого слова new.

Примеры см. в разделе Sign.

`verify.update(data[, inputEncoding])`

История

Версия	Изменения
v6.0.0	Значение `inputEncoding` по умолчанию изменено с `binary` на `utf8`.
v0.1.92	Добавлено в: v0.1.92

data <string> | <Buffer> | <TypedArray> | <DataView>
inputEncoding <string> Кодировка строки data.

Обновляет содержимое Verify указанными данными data, кодировка которых задается в inputEncoding. Если inputEncoding не указано и data является строкой, принудительно используется кодировка 'utf8'. Если data является Buffer, TypedArray или DataView, то inputEncoding игнорируется.

Этот метод можно вызывать много раз, передавая новые данные по мере их поступления в поток.

`verify.verify(object, signature[, signatureEncoding])`

История

Версия	Изменения
v15.0.0	В качестве объекта также можно использовать ArrayBuffer и CryptoKey.
v13.2.0, v12.16.0	Теперь эта функция поддерживает подписи DSA и ECDSA в формате IEEE-P1363.
v12.0.0	Теперь эта функция поддерживает ключи RSA-PSS.
v11.7.0	Теперь ключом может быть закрытый ключ.
v8.0.0	Добавлена поддержка RSASSA-PSS и дополнительных параметров.
v0.1.92	Добавлено в: v0.1.92

object <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
- dsaEncoding <string>
- padding <integer>
- saltLength <integer>
signature <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
signatureEncoding <string> Кодировка строки signature.
Возвращает: <boolean> true или false в зависимости от того, действительна ли подпись для данных и открытого ключа.

Проверяет предоставленные данные с помощью заданных object и signature.

Если object не является KeyObject, эта функция работает так, как если бы object был передан в crypto.createPublicKey(). Если это объект, можно передать следующие дополнительные свойства:

dsaEncoding <string> Для DSA и ECDSA этот параметр задает формат подписи. Возможны следующие значения:
- 'der' (по умолчанию): структура подписи ASN.1 в кодировке DER, содержащая (r, s).
- 'ieee-p1363': формат подписи r || s, предложенный в IEEE-P1363.
padding <integer> Необязательное значение заполнения для RSA, одно из следующих:
- crypto.constants.RSA_PKCS1_PADDING (по умолчанию)
- crypto.constants.RSA_PKCS1_PSS_PADDING
RSA_PKCS1_PSS_PADDING будет использовать MGF1 с той же хеш-функцией, что и для проверки сообщения, как указано в разделе 3.1 RFC 4055, если только хеш-функция MGF1 не указана в составе ключа в соответствии с разделом 3.3 RFC 4055.
saltLength <integer> Длина соли при использовании заполнения RSA_PKCS1_PSS_PADDING. Специальное значение crypto.constants.RSA_PSS_SALTLEN_DIGEST задает длину соли, равную размеру дайджеста, а crypto.constants.RSA_PSS_SALTLEN_AUTO (по умолчанию) позволяет определить ее автоматически.

Аргумент signature — это ранее вычисленная подпись данных в формате signatureEncoding. Если указано signatureEncoding, ожидается, что signature будет строкой; в противном случае ожидается, что signature будет Buffer, TypedArray или DataView.

Объект verify нельзя повторно использовать после вызова verify.verify(). Повторные вызовы verify.verify() приведут к возникновению ошибки.

Поскольку открытые ключи можно получить из закрытых ключей, вместо открытого ключа можно передать закрытый ключ.

Класс: `X509Certificate`

Добавлено в: v15.6.0

Содержит сертификат X509 и предоставляет доступ только для чтения к его сведениям.

Модули JavaScript

const { X509Certificate } = await import('node:crypto');

const x509 = new X509Certificate('{... pem encoded cert ...}');

console.log(x509.subject);

CommonJS

const { X509Certificate } = require('node:crypto');

const x509 = new X509Certificate('{... pem encoded cert ...}');

console.log(x509.subject);

`new X509Certificate(buffer)`

Добавлено в: v15.6.0

buffer <string> | <TypedArray> | <Buffer> | <DataView> Сертификат X509 в кодировке PEM или DER.

`x509.ca`

Добавлено в: v15.6.0

Тип: <boolean> Будет true, если это сертификат центра сертификации (CA).

`x509.checkEmail(email[, options])`

История

Версия	Изменения
v18.0.0	Теперь для параметра subject по умолчанию используется `'default'`.
v17.5.0, v16.15.0	Теперь для параметра subject можно задать значение `'default'`.
v17.5.0, v16.14.1	Параметры `wildcards`, `partialWildcards`, `multiLabelWildcards` и `singleLabelSubdomains` удалены, поскольку они не влияли на результат.
v15.6.0	Добавлено в: v15.6.0

email <string>
options <Object>
- subject <string> 'default', 'always' или 'never'. По умолчанию: 'default'.
Возвращает: <string> | <undefined> Возвращает email, если сертификат соответствует адресу, и undefined, если нет.

Проверяет, соответствует ли сертификат указанному адресу электронной почты.

Если параметр 'subject' не задан или имеет значение 'default', субъект сертификата учитывается только в том случае, если расширение альтернативного имени субъекта отсутствует или не содержит адресов электронной почты.

Если параметр 'subject' имеет значение 'always', субъект сертификата учитывается, если расширение альтернативного имени субъекта отсутствует или не содержит соответствующего адреса электронной почты.

Если параметр 'subject' имеет значение 'never', субъект сертификата никогда не учитывается, даже если сертификат не содержит альтернативных имен субъекта.

`x509.checkHost(name[, options])`

История

Версия	Изменения
v18.0.0	Теперь для параметра subject по умолчанию используется `'default'`.
v17.5.0, v16.15.0	Теперь для параметра subject можно задать значение `'default'`.
v15.6.0	Добавлено в: v15.6.0

name <string>
options <Object>
- subject <string> 'default', 'always' или 'never'. По умолчанию: 'default'.
- wildcards <boolean> По умолчанию: true.
- partialWildcards <boolean> По умолчанию: true.
- multiLabelWildcards <boolean> По умолчанию: false.
- singleLabelSubdomains <boolean> По умолчанию: false.
Возвращает: <string> | <undefined> Возвращает имя субъекта, соответствующее name, или undefined, если имя субъекта не соответствует name.

Проверяет, соответствует ли сертификат указанному имени хоста.

Если сертификат соответствует указанному имени хоста, возвращается соответствующее имя субъекта. Возвращаемое имя может точно совпадать (например, foo.example.com) или содержать подстановочные знаки (например, *.example.com). Поскольку сравнение имен хостов не учитывает регистр, возвращаемое имя субъекта также может отличаться от указанного name регистром букв.

`x509.checkIP(ip)`

История

Версия	Изменения
v17.5.0, v16.14.1	Аргумент `options` удален, поскольку он не влиял на результат.
v15.6.0	Добавлено в: v15.6.0

ip <string>
Возвращает: <string> | <undefined> Возвращает ip, если сертификат соответствует адресу, и undefined, если нет.

Проверяет, соответствует ли сертификат указанному IP-адресу (IPv4 или IPv6).

Учитываются только альтернативные имена субъекта iPAddress по стандарту RFC 5280, и они должны в точности совпадать с указанным ip адресом. Остальные альтернативные имена субъекта, а также поле субъекта сертификата игнорируются.

`x509.checkIssued(otherCert)`

Добавлено в: v15.6.0

otherCert <X509Certificate>
Возвращает: <boolean>

Проверяет, мог ли указанный otherCert выдать этот сертификат, путем сравнения метаданных сертификата.

Это полезно для отсева списка возможных сертификатов издателей, отобранных с помощью более простого фильтра, то есть только на основе имен субъекта и издателя.

Чтобы окончательно проверить, что подпись этого сертификата создана закрытым ключом, соответствующим открытому ключу otherCert, используйте x509.verify(publicKey) с открытым ключом otherCert, представленным в виде KeyObject, например:

if (!x509.verify(otherCert.publicKey)) {
  throw new Error('otherCert did not issue x509');
} copy

`x509.checkPrivateKey(privateKey)`

Добавлено в: v15.6.0

privateKey <KeyObject> Закрытый ключ.
Возвращает: <boolean>

Проверяет, соответствует ли открытый ключ этого сертификата указанному закрытому ключу.

`x509.fingerprint`

Добавлено в: v15.6.0

Тип: <string>

Отпечаток этого сертификата, вычисленный с помощью SHA-1.

Поскольку SHA-1 криптографически скомпрометирован, а его безопасность значительно ниже, чем у алгоритмов, обычно используемых для подписания сертификатов, рассмотрите возможность использования x509.fingerprint256.

`x509.fingerprint256`

Добавлено в: v15.6.0

Тип: <string>

Отпечаток этого сертификата, вычисленный с помощью SHA-256.

`x509.fingerprint512`

Добавлено в: v17.2.0, v16.14.0

Тип: <string>

Отпечаток этого сертификата, вычисленный с помощью SHA-512.

Поскольку вычисление отпечатка SHA-256 обычно выполняется быстрее, а его размер вдвое меньше размера отпечатка SHA-512, x509.fingerprint256 может быть предпочтительнее. Хотя SHA-512, предположительно, обеспечивает более высокий общий уровень безопасности, SHA-256 не уступает по безопасности большинству алгоритмов, обычно используемых для подписания сертификатов.

`x509.infoAccess`

История

Версия	Изменения
v17.3.1, v16.13.2	В ответ на CVE-2021-44532 некоторые части этой строки могут кодироваться как строковые литералы JSON.
v15.6.0	Добавлено в: v15.6.0

Тип: <string>

Текстовое представление расширения сертификата с информацией о доступе к центру сертификации.

Это список описаний доступа, разделенных символами перевода строки. Каждая строка начинается с метода доступа и типа расположения точки доступа, за которыми следуют двоеточие и связанное с точкой доступа значение.

После префикса, обозначающего метод доступа и тип расположения точки доступа, оставшаяся часть каждой строки может быть заключена в кавычки, указывающие на то, что значение является строковым литералом JSON. Для обратной совместимости Node.js использует строковые литералы JSON в этом свойстве только в случае необходимости, чтобы избежать неоднозначности. Сторонний код должен быть готов обрабатывать оба возможных формата записей.

`x509.issuer`

Добавлено в: v15.6.0

Тип: <string>

Идентификатор издателя, включенный в этот сертификат.

`x509.issuerCertificate`

Добавлено в: v15.9.0

Тип: <X509Certificate>

Сертификат издателя или undefined, если сертификат издателя недоступен.

`x509.keyUsage`

Добавлено в: v15.6.0

Тип: <string[]>

Массив, содержащий сведения о расширенных назначениях ключа для этого сертификата.

`x509.publicKey`

Добавлено в: v15.6.0

Тип: <KeyObject>

Открытый ключ <KeyObject> для этого сертификата.

`x509.raw`

Добавлено в: v15.6.0

Тип: <Buffer>

Объект Buffer, содержащий сертификат в кодировке DER.

`x509.serialNumber`

Добавлено в: v15.6.0

Тип: <string>

Серийный номер этого сертификата.

Серийные номера присваиваются центрами сертификации и не позволяют однозначно идентифицировать сертификаты. Вместо этого рассмотрите возможность использования x509.fingerprint256 в качестве уникального идентификатора.

`x509.subject`

Добавлено в: v15.6.0

Тип: <string>

Полное имя субъекта этого сертификата.

`x509.subjectAltName`

История

Версия	Изменения
v17.3.1, v16.13.2	В ответ на CVE-2021-44532 некоторые части этой строки могут кодироваться как строковые литералы JSON.
v15.6.0	Добавлено в: v15.6.0

Тип: <string>

Альтернативное имя субъекта, указанное для этого сертификата.

Это список альтернативных имен субъекта, разделенных запятыми. Каждая запись начинается со строки, обозначающей тип альтернативного имени субъекта, за которой следуют двоеточие и связанное с этой записью значение.

В более ранних версиях Node.js ошибочно предполагалось, что это свойство безопасно разделять по последовательности из двух символов ', ' (см. CVE-2021-44532). Однако как вредоносные, так и легитимные сертификаты могут содержать альтернативные имена субъекта с этой последовательностью в строковом представлении.

После префикса, обозначающего тип записи, оставшаяся часть каждой записи может быть заключена в кавычки, указывающие на то, что значение является строковым литералом JSON. Для обратной совместимости Node.js использует строковые литералы JSON в этом свойстве только в случае необходимости, чтобы избежать неоднозначности. Сторонний код должен быть готов обрабатывать оба возможных формата записей.

`x509.toJSON()`

Добавлено в: v15.6.0

Тип: <string>

Стандартного формата JSON для сертификатов X509 не существует. Метод toJSON() возвращает строку, содержащую сертификат в кодировке PEM.

`x509.toLegacyObject()`

Добавлено в: v15.6.0

Тип: <Object>

Возвращает сведения об этом сертификате в кодировке устаревшего объекта сертификата.

`x509.toString()`

Добавлено в: v15.6.0

Тип: <string>

Возвращает сертификат в кодировке PEM.

`x509.validFrom`

Добавлено в: v15.6.0

Тип: <string>

Дата и время, начиная с которых этот сертификат действителен.

`x509.validFromDate`

Добавлено в: v22.10.0

Тип: <Date>

Дата и время, начиная с которых этот сертификат действителен, представлены в объекте Date.

`x509.validTo`

Добавлено в: v15.6.0

Тип: <string>

Дата и время, до которых этот сертификат действителен.

`x509.validToDate`

Добавлено в: v22.10.0

Тип: <Date>

Дата и время, до которых этот сертификат действителен, представлены в объекте Date.

`x509.verify(publicKey)`

Добавлено в: v15.6.0

publicKey <KeyObject> Открытый ключ.
Возвращает: <boolean>

Проверяет, был ли этот сертификат подписан указанным открытым ключом. Не выполняет никаких других проверок сертификата.

`node:crypto` методы и свойства модуля

`crypto.checkPrime(candidate[, options], callback)`

История

Версия	Изменения
v18.0.0	Теперь передача недопустимого обратного вызова в аргумент `callback` вызывает `ERR_INVALID_ARG_TYPE` вместо `ERR_INVALID_CALLBACK`.
v15.8.0	Добавлено в: v15.8.0

candidate <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Buffer> | <DataView> | <bigint> Возможное простое число, закодированное в виде последовательности октетов произвольной длины в порядке от старшего к младшему.
options <Object>
- checks <number> Количество вероятностных итераций проверки простоты Миллера — Рабина. Если значение равно 0 (нулю), используется количество проверок, обеспечивающее вероятность ложноположительного результата не более 2^-64 для случайного ввода. Выбирать количество проверок следует с осторожностью. Дополнительные сведения см. в документации OpenSSL по параметрам функции BN_is_prime_ex nchecks. По умолчанию: 0
callback <Function>
- err <Error> При возникновении ошибки во время проверки здесь устанавливается объект <Error>.
- result <boolean> true, если кандидат является простым числом с вероятностью ошибки менее 0.25 ** options.checks.

Проверяет, является ли candidate простым числом.

`crypto.checkPrimeSync(candidate[, options])`

Добавлено в: v15.8.0

candidate <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Buffer> | <DataView> | <bigint> Возможное простое число, закодированное в виде последовательности октетов произвольной длины в порядке от старшего к младшему.
options <Object>
- checks <number> Количество вероятностных итераций проверки простоты Миллера — Рабина. Если значение равно 0 (нулю), используется количество проверок, обеспечивающее вероятность ложноположительного результата не более 2^-64 для случайного ввода. Выбирать количество проверок следует с осторожностью. Дополнительные сведения см. в документации OpenSSL по параметрам функции BN_is_prime_ex nchecks. По умолчанию: 0
Возвращает: <boolean> true, если кандидат является простым числом с вероятностью ошибки менее 0.25 ** options.checks.

Проверяет, является ли candidate простым числом.

`crypto.constants`

Добавлено в: v6.3.0

Тип: <Object>

Объект, содержащий часто используемые константы для криптографических операций и операций, связанных с безопасностью. Описание конкретных констант, определённых на данный момент, приведено в разделе Константы криптографии.

`crypto.createCipheriv(algorithm, key, iv[, options])`

История

Версия	Изменения
v17.9.0, v16.17.0	Параметр `authTagLength` теперь необязателен при использовании шифра `chacha20-poly1305`; значение по умолчанию — 16 байт.
v15.0.0	Аргументы password и iv могут быть объектами ArrayBuffer; максимальный размер каждого из них ограничен 2 ** 31 - 1 байтами.
v11.6.0	Аргумент `key` теперь может быть объектом `KeyObject`.
v11.2.0, v10.17.0	Теперь поддерживается шифр `chacha20-poly1305` (вариант ChaCha20-Poly1305 для IETF).
v10.10.0	Теперь поддерживаются шифры в режиме OCB.
v10.2.0	Теперь параметр `authTagLength` можно использовать для создания более коротких тегов аутентификации в режиме GCM; значение по умолчанию — 16 байт.
v9.9.0	Теперь параметр `iv` может иметь значение `null` для шифров, которым не нужен вектор инициализации.
v0.1.94	Добавлено в: v0.1.94

algorithm <string>
key <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
iv <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <null>
options <Object> stream.transform параметры
Возвращает: <Cipher>

Создаёт и возвращает объект Cipher с заданными значениями algorithm, key и вектора инициализации (iv).

Аргумент options управляет поведением потока и является необязательным, за исключением случаев использования шифра в режиме CCM или OCB (например, 'aes-128-ccm'). В этом случае параметр authTagLength обязателен и задаёт длину тега аутентификации в байтах; см. раздел Режим CCM. В режиме GCM параметр authTagLength необязателен, но его можно использовать для установки длины тега аутентификации, возвращаемого методом getAuthTag(); значение по умолчанию — 16 байт. Для chacha20-poly1305 значение параметра authTagLength по умолчанию составляет 16 байт.

Набор доступных algorithm зависит от OpenSSL; примеры: 'aes192' и т. д. В последних версиях OpenSSL команда openssl list -cipher-algorithms выводит список доступных алгоритмов шифрования.

key — это необработанный ключ, используемый algorithm, а iv — это вектор инициализации. Оба аргумента должны быть строками в кодировке 'utf8', объектами Buffer, TypedArray или DataView. В качестве key также можно передать объект KeyObject типа secret. Если шифру не нужен вектор инициализации, iv может иметь значение null.

Передавая строки в качестве key или iv, учитывайте особенности использования строк в качестве входных данных для криптографических API.

Векторы инициализации должны быть непредсказуемыми и уникальными; в идеале они должны быть криптографически случайными. Они не обязаны быть секретными: обычно IV просто добавляются к зашифрованным сообщениям в незашифрованном виде. Может показаться противоречивым, что значение должно быть непредсказуемым и уникальным, но при этом не обязано быть секретным; следует помнить, что злоумышленник не должен иметь возможности заранее предсказать, каким будет конкретный IV.

`crypto.createDecipheriv(algorithm, key, iv[, options])`

История

Версия	Изменения
v17.9.0, v16.17.0	Параметр `authTagLength` теперь необязателен при использовании шифра `chacha20-poly1305`; значение по умолчанию — 16 байт.
v11.6.0	Аргумент `key` теперь может быть объектом `KeyObject`.
v11.2.0, v10.17.0	Теперь поддерживается шифр `chacha20-poly1305` (вариант ChaCha20-Poly1305 для IETF).
v10.10.0	Теперь поддерживаются шифры в режиме OCB.
v10.2.0	Теперь параметр `authTagLength` можно использовать для ограничения допустимой длины тега аутентификации GCM.
v9.9.0	Теперь параметр `iv` может иметь значение `null` для шифров, которым не нужен вектор инициализации.
v0.1.94	Добавлено в: v0.1.94

algorithm <string>
key <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
iv <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <null>
options <Object> stream.transform параметры
Возвращает: <Decipher>

Создаёт и возвращает объект Decipher, использующий заданные значения algorithm, key и вектора инициализации (iv).

Аргумент options управляет поведением потока и является необязательным, за исключением случаев использования шифра в режиме CCM или OCB (например, 'aes-128-ccm'). В этом случае параметр authTagLength обязателен и задаёт длину тега аутентификации в байтах; см. раздел Режим CCM. В режиме GCM параметр authTagLength необязателен, но его можно использовать, чтобы ограничить принимаемые теги аутентификации тегами указанной длины. Для chacha20-poly1305 значение параметра authTagLength по умолчанию составляет 16 байт.

`crypto.createDiffieHellman(prime[, primeEncoding][, generator][, generatorEncoding])`

История

Версия	Изменения
v8.0.0	Теперь аргумент `prime` может иметь тип `TypedArray` или `DataView`.
v8.0.0	Теперь аргумент `prime` может иметь тип `Uint8Array`.
v6.0.0	Значение кодировки по умолчанию изменено с `binary` на `utf8`.
v0.11.12	Добавлено в: v0.11.12

prime <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
primeEncoding <string> Кодировка строки prime.
generator <number> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> По умолчанию: 2
generatorEncoding <string> Кодировка строки generator.
Возвращает: <DiffieHellman>

Создаёт объект обмена ключами DiffieHellman, используя заданные prime и необязательный конкретный generator.

Аргумент generator может быть числом, строкой или Buffer. Если generator не задан, используется значение 2.

Если задан primeEncoding, ожидается, что prime будет строкой; в противном случае ожидается Buffer, TypedArray или DataView.

Если задан generatorEncoding, ожидается, что generator будет строкой; в противном случае ожидается число, Buffer, TypedArray или DataView.

`crypto.createDiffieHellman(primeLength[, generator])`

Добавлено в: v0.5.0

primeLength <number>
generator <number> По умолчанию: 2
Возвращает: <DiffieHellman>

Создаёт объект обмена ключами DiffieHellman и генерирует простое число длиной primeLength бит, используя необязательный числовой параметр generator. Если generator не задан, используется значение 2.

`crypto.createDiffieHellmanGroup(name)`

Добавлено в: v0.9.3

name <string>
Возвращает: <DiffieHellmanGroup>

Псевдоним для crypto.getDiffieHellman()

`crypto.createECDH(curveName)`

Добавлено в: v0.11.14

curveName <string>
Возвращает: <ECDH>

Создаёт объект обмена ключами на основе эллиптической кривой Диффи — Хеллмана (ECDH), используя предопределённую кривую, указанную строкой curveName. Чтобы получить список доступных имён кривых, используйте crypto.getCurves(). В последних версиях OpenSSL команда openssl ecparam -list_curves также выводит имена и описания всех доступных эллиптических кривых.

`crypto.createHash(algorithm[, options])`

История

Версия	Изменения
v12.8.0	Для хеш-функций XOF добавлен параметр `outputLength`.
v0.1.92	Добавлено в: v0.1.92

algorithm <string>
options <Object> stream.transform параметры
Возвращает: <Hash>

Создаёт и возвращает объект Hash, который можно использовать для генерации хеш-дайджестов с помощью заданного algorithm. Необязательный аргумент options управляет поведением потока. Для хеш-функций XOF, например 'shake256', параметр outputLength позволяет указать желаемую длину результата в байтах.

Набор доступных algorithm зависит от алгоритмов, поддерживаемых версией OpenSSL на платформе. Примеры: 'sha256', 'sha512' и т. д. В последних версиях OpenSSL команда openssl list -digest-algorithms выводит список доступных алгоритмов дайджестов.

Пример: вычисление суммы sha256 файла

Модули JavaScript

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', () => {
  // Only one element is going to be produced by the
  // hash stream.
  const data = input.read();
  if (data)
    hash.update(data);
  else {
    console.log(`${hash.digest('hex')} ${filename}`);
  }
});

CommonJS

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', () => {
  // Only one element is going to be produced by the
  // hash stream.
  const data = input.read();
  if (data)
    hash.update(data);
  else {
    console.log(`${hash.digest('hex')} ${filename}`);
  }
});

`crypto.createHmac(algorithm, key[, options])`

История

Версия	Изменения
v15.0.0	Ключ также может быть объектом ArrayBuffer или CryptoKey. Добавлен параметр кодировки. Размер ключа не может превышать 2 ** 32 - 1 байт.
v11.6.0	Аргумент `key` теперь может быть объектом `KeyObject`.
v0.1.94	Добавлено в: v0.1.94

algorithm <string>
key <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
options <Object> stream.transform параметры
- encoding <string> Кодировка строки, используемая, когда key является строкой.
Возвращает: <Hmac>

Создаёт и возвращает объект Hmac, использующий заданные algorithm и key. Необязательный аргумент options управляет поведением потока.

key — это ключ HMAC, используемый для генерации криптографического хеша HMAC. Если это объект KeyObject, его тип должен быть secret. Если это строка, учитывайте особенности использования строк в качестве входных данных для криптографических API. Если ключ получен из криптографически безопасного источника энтропии, например crypto.randomBytes() или crypto.generateKey(), его длина не должна превышать размер блока algorithm (например, 512 бит для SHA-256).

Пример: вычисление HMAC sha256 файла

Модули JavaScript

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', () => {
  // Only one element is going to be produced by the
  // hash stream.
  const data = input.read();
  if (data)
    hmac.update(data);
  else {
    console.log(`${hmac.digest('hex')} ${filename}`);
  }
});

CommonJS

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', () => {
  // Only one element is going to be produced by the
  // hash stream.
  const data = input.read();
  if (data)
    hmac.update(data);
  else {
    console.log(`${hmac.digest('hex')} ${filename}`);
  }
});

`crypto.createPrivateKey(key)`

История

Версия	Изменения
v15.12.0	Ключ также может быть объектом JWK.
v15.0.0	Ключ также может быть объектом ArrayBuffer. Добавлена возможность указать параметр кодировки. Размер ключа не может превышать 2 ** 32 - 1 байт.
v11.6.0	Добавлено в версии: v11.6.0

key <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
- key <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <Object> Материал ключа в формате PEM, DER или JWK.
- format <string> Должно быть 'pem', 'der' или ''jwk'. По умолчанию: 'pem'.
- type <string> Должно быть 'pkcs1', 'pkcs8' или 'sec1'. Этот параметр обязателен, только если format имеет значение 'der', в противном случае он игнорируется.
- passphrase <string> | <Buffer> Парольная фраза для расшифрования.
- encoding <string> Кодировка строки, используемая, если key является строкой.
Возвращает: <KeyObject>

Создает и возвращает новый объект ключа, содержащий закрытый ключ. Если key является строкой или Buffer, предполагается, что format имеет значение 'pem'; в противном случае key должен быть объектом со свойствами, описанными выше.

Если закрытый ключ зашифрован, необходимо указать passphrase. Длина парольной фразы не должна превышать 1024 байта.

`crypto.createPublicKey(key)`

История

Версия	Изменения
v15.12.0	Ключ также может быть объектом JWK.
v15.0.0	Ключ также может быть объектом ArrayBuffer. Добавлена возможность указать параметр кодировки. Размер ключа не может превышать 2 ** 32 - 1 байт.
v11.13.0	Аргумент `key` теперь может быть `KeyObject` с типом `private`.
v11.7.0	Аргумент `key` теперь может быть закрытым ключом.
v11.6.0	Добавлено в версии: v11.6.0

key <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
- key <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <Object> Материал ключа в формате PEM, DER или JWK.
- format <string> Должно быть 'pem', 'der' или 'jwk'. По умолчанию: 'pem'.
- type <string> Должно быть 'pkcs1' или 'spki'. Этот параметр обязателен, только если format имеет значение 'der', в противном случае он игнорируется.
- encoding <string> Кодировка строки, используемая, если key является строкой.
Возвращает: <KeyObject>

Создает и возвращает новый объект ключа, содержащий открытый ключ. Если key является строкой или Buffer, предполагается, что format имеет значение 'pem'; если key — это KeyObject с типом 'private', открытый ключ извлекается из заданного закрытого ключа; в противном случае key должен быть объектом со свойствами, описанными выше.

Если формат — 'pem', 'key' также может быть сертификатом X.509.

Поскольку открытые ключи можно получить из закрытых, вместо открытого ключа можно передать закрытый. В этом случае функция работает так, как если бы была вызвана crypto.createPrivateKey(), за исключением того, что тип возвращаемого KeyObject будет 'public', а извлечь закрытый ключ из возвращенного KeyObject будет невозможно. Аналогично, если передан KeyObject с типом 'private', будет возвращен новый KeyObject с типом 'public', и извлечь закрытый ключ из возвращенного объекта будет невозможно.

`crypto.createSecretKey(key[, encoding])`

История

Версия	Изменения
v18.8.0, v16.18.0	Теперь ключ может иметь нулевую длину.
v15.0.0	Ключ также может быть объектом ArrayBuffer или строкой. Добавлен аргумент кодировки. Размер ключа не может превышать 2 ** 32 - 1 байт.
v11.6.0	Добавлено в версии: v11.6.0

key <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
encoding <string> Кодировка строки, если key является строкой.
Возвращает: <KeyObject>

Создает и возвращает новый объект ключа, содержащий секретный ключ для симметричного шифрования или Hmac.

`crypto.createSign(algorithm[, options])`

Добавлено в версии: v0.1.92

algorithm <string>
options <Object> stream.Writable параметры
Возвращает: <Sign>

Создает и возвращает объект Sign, использующий заданный алгоритм algorithm. Используйте crypto.getHashes(), чтобы получить названия доступных алгоритмов хеширования. Необязательный аргумент options управляет поведением stream.Writable.

В некоторых случаях экземпляр Sign можно создать, указав название алгоритма подписи, например 'RSA-SHA256', вместо алгоритма хеширования. При этом будет использован соответствующий алгоритм хеширования. Это не работает для всех алгоритмов подписи, например 'ecdsa-with-SHA256', поэтому рекомендуется всегда указывать названия алгоритмов хеширования.

`crypto.createVerify(algorithm[, options])`

Добавлено в версии: v0.1.92

algorithm <string>
options <Object> stream.Writable параметры
Возвращает: <Verify>

Создает и возвращает объект Verify, использующий заданный алгоритм. Используйте crypto.getHashes(), чтобы получить массив названий доступных алгоритмов подписи. Необязательный аргумент options управляет поведением stream.Writable.

В некоторых случаях экземпляр Verify можно создать, указав название алгоритма подписи, например 'RSA-SHA256', вместо алгоритма хеширования. При этом будет использован соответствующий алгоритм хеширования. Это не работает для всех алгоритмов подписи, например 'ecdsa-with-SHA256', поэтому рекомендуется всегда указывать названия алгоритмов хеширования.

`crypto.diffieHellman(options)`

Добавлено в версии: v13.9.0, v12.17.0

options: <Object>
- privateKey: <KeyObject>
- publicKey: <KeyObject>
Возвращает: <Buffer>

Вычисляет общий секрет Диффи — Хеллмана на основе privateKey и publicKey. Оба ключа должны иметь одинаковый asymmetricKeyType, который должен быть одним из 'dh' (для Диффи — Хеллмана), 'ec', 'x448' или 'x25519' (для ECDH).

`crypto.fips`

Добавлено в версии: v6.0.0Не рекомендуется с версии: v10.0.0

Стабильность: 0 — Не рекомендуется

Свойство для проверки и управления тем, используется ли в данный момент криптопровайдер, совместимый с FIPS. Для установки значения true требуется сборка Node.js с поддержкой FIPS.

Это свойство не рекомендуется использовать. Вместо него используйте crypto.setFips() и crypto.getFips().

`crypto.generateKey(type, options, callback)`

История

Версия	Изменения
v18.0.0	Передача недопустимой функции обратного вызова в аргумент `callback` теперь вызывает исключение `ERR_INVALID_ARG_TYPE` вместо `ERR_INVALID_CALLBACK`.
v15.0.0	Добавлено в версии: v15.0.0

type <string> Предполагаемое назначение создаваемого секретного ключа. В настоящее время допустимы значения 'hmac' и 'aes'.
options <Object>
- length <number> Длина создаваемого ключа в битах. Значение должно быть больше 0.
  - Если type равно 'hmac', минимальное значение — 8, а максимальная длина — 2³¹-1. Если значение не кратно 8, создаваемый ключ будет усечен до Math.floor(length / 8).
  - Если type равно 'aes', длина должна быть равна 128, 192 или 256.
callback <Function>
- err <Error>
- key <KeyObject>

Асинхронно создает новый случайный секретный ключ заданного length. type определяет, какие проверки будут выполнены для length.

Модули JavaScript

const {
  generateKey,
} = await import('node:crypto');

generateKey('hmac', { length: 512 }, (err, key) => {
  if (err) throw err;
  console.log(key.export().toString('hex'));  // 46e..........620
});

CommonJS

const {
  generateKey,
} = require('node:crypto');

generateKey('hmac', { length: 512 }, (err, key) => {
  if (err) throw err;
  console.log(key.export().toString('hex'));  // 46e..........620
});

Размер создаваемого ключа HMAC не должен превышать размер блока используемой хеш-функции. Дополнительные сведения см. в разделе crypto.createHmac().

`crypto.generateKeyPair(type, options, callback)`

История

Версия	Изменения
v18.0.0	Передача недопустимой функции обратного вызова в аргумент `callback` теперь вызывает исключение `ERR_INVALID_ARG_TYPE` вместо `ERR_INVALID_CALLBACK`.
v16.10.0	Добавлена возможность задавать параметры последовательности `RSASSA-PSS-params` для пар ключей RSA-PSS.
v13.9.0, v12.17.0	Добавлена поддержка Диффи — Хеллмана.
v12.0.0	Добавлена поддержка пар ключей RSA-PSS.
v12.0.0	Добавлена возможность создавать пары ключей X25519 и X448.
v12.0.0	Добавлена возможность создавать пары ключей Ed25519 и Ed448.
v11.6.0	Функции `generateKeyPair` и `generateKeyPairSync` теперь возвращают объекты ключей, если кодировка не указана.
v10.12.0	Добавлено в версии: v10.12.0

type <string> Должно быть 'rsa', 'rsa-pss', 'dsa', 'ec', 'ed25519', 'ed448', 'x25519', 'x448' или 'dh'.
options <Object>
- modulusLength <number> Размер ключа в битах (RSA, DSA).
- publicExponent <number> Открытая экспонента (RSA). По умолчанию: 0x10001.
- hashAlgorithm <string> Название хеш-функции (RSA-PSS).
- mgf1HashAlgorithm <string> Название хеш-функции, используемой MGF1 (RSA-PSS).
- saltLength <number> Минимальная длина соли в байтах (RSA-PSS).
- divisorLength <number> Размер q в битах (DSA).
- namedCurve <string> Название используемой эллиптической кривой (EC).
- prime <Buffer> Простой параметр (DH).
- primeLength <number> Длина простого числа в битах (DH).
- generator <number> Пользовательский генератор (DH). По умолчанию: 2.
- groupName <string> Название группы Диффи — Хеллмана (DH). См. crypto.getDiffieHellman().
- paramEncoding <string> Должно быть 'named' или 'explicit' (EC). По умолчанию: 'named'.
- publicKeyEncoding <Object> См. keyObject.export().
- privateKeyEncoding <Object> См. keyObject.export().
callback <Function>
- err <Error>
- publicKey <string> | <Buffer> | <KeyObject>
- privateKey <string> | <Buffer> | <KeyObject>

Создает новую пару асимметричных ключей заданного type. В настоящее время поддерживаются RSA, RSA-PSS, DSA, EC, Ed25519, Ed448, X25519, X448 и DH.

Если указано publicKeyEncoding или privateKeyEncoding, функция работает так, как если бы для результата была вызвана keyObject.export(). В противном случае соответствующая часть ключа возвращается как KeyObject.

Для долговременного хранения рекомендуется кодировать открытые ключи как 'spki', а закрытые ключи — как 'pkcs8' с шифрованием:

Модули JavaScript

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) => {
  // Handle errors and use the generated key pair.
});

CommonJS

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) => {
  // Handle errors and use the generated key pair.
});

По завершении callback будет вызвана; err будет иметь значение undefined, а publicKey / privateKey будут представлять созданную пару ключей.

При вызове этой функции в виде версии с поддержкой util.promisify() она возвращает Promise для Object со свойствами publicKey и privateKey.

`crypto.generateKeyPairSync(type, options)`

История

Версия	Изменения
v16.10.0	Добавлена возможность задавать параметры последовательности `RSASSA-PSS-params` для пар ключей RSA-PSS.
v13.9.0, v12.17.0	Добавлена поддержка Диффи — Хеллмана.
v12.0.0	Добавлена поддержка пар ключей RSA-PSS.
v12.0.0	Добавлена возможность создавать пары ключей X25519 и X448.
v12.0.0	Добавлена возможность создавать пары ключей Ed25519 и Ed448.
v11.6.0	Функции `generateKeyPair` и `generateKeyPairSync` теперь возвращают объекты ключей, если кодировка не указана.
v10.12.0	Добавлено в версии: v10.12.0

type <string> Должно быть 'rsa', 'rsa-pss', 'dsa', 'ec', 'ed25519', 'ed448', 'x25519', 'x448' или 'dh'.
options <Object>
- modulusLength <number> Размер ключа в битах (RSA, DSA).
- publicExponent <number> Открытая экспонента (RSA). По умолчанию: 0x10001.
- hashAlgorithm <string> Название хеш-функции (RSA-PSS).
- mgf1HashAlgorithm <string> Название хеш-функции, используемой MGF1 (RSA-PSS).
- saltLength <number> Минимальная длина соли в байтах (RSA-PSS).
- divisorLength <number> Размер q в битах (DSA).
- namedCurve <string> Название используемой эллиптической кривой (EC).
- prime <Buffer> Простой параметр (DH).
- primeLength <number> Длина простого числа в битах (DH).
- generator <number> Пользовательский генератор (DH). По умолчанию: 2.
- groupName <string> Название группы Диффи — Хеллмана (DH). См. crypto.getDiffieHellman().
- paramEncoding <string> Должно быть 'named' или 'explicit' (EC). По умолчанию: 'named'.
- publicKeyEncoding <Object> См. keyObject.export().
- privateKeyEncoding <Object> См. keyObject.export().
Возвращает: <Object>
- publicKey <string> | <Buffer> | <KeyObject>
- privateKey <string> | <Buffer> | <KeyObject>

При кодировании открытых ключей рекомендуется использовать 'spki'. При кодировании закрытых ключей рекомендуется использовать 'pkcs8' с надежной парольной фразой и хранить ее в тайне.

Модули JavaScript

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',
  },
});

CommonJS

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',
  },
});

Возвращаемое значение { publicKey, privateKey } представляет созданную пару ключей. Если выбрана кодировка PEM, соответствующий ключ будет строкой; в противном случае это будет буфер с данными в кодировке DER.

`crypto.generateKeySync(type, options)`

Добавлено в: v15.0.0

type <string> Предполагаемое назначение сгенерированного секретного ключа. В настоящее время допустимы значения 'hmac' и 'aes'.
options <Object>
- length <number> Длина генерируемого ключа в битах.
  - Если type равно 'hmac', минимальное значение составляет 8, а максимальная длина — 2³¹-1. Если значение не кратно 8, сгенерированный ключ будет усечен до Math.floor(length / 8).
  - Если type равно 'aes', длина должна быть равна одному из значений: 128, 192 или 256.
Возвращает: <KeyObject>

Синхронно генерирует новый случайный секретный ключ заданного length. type определяет, какие проверки будут выполнены для length.

Модули JavaScript

const {
  generateKeySync,
} = await import('node:crypto');

const key = generateKeySync('hmac', { length: 512 });
console.log(key.export().toString('hex'));  // e89..........41e

CommonJS

const {
  generateKeySync,
} = require('node:crypto');

const key = generateKeySync('hmac', { length: 512 });
console.log(key.export().toString('hex'));  // e89..........41e

Размер сгенерированного ключа HMAC не должен превышать размер блока используемой хеш-функции. Дополнительную информацию см. в разделе crypto.createHmac().

`crypto.generatePrime(size[, options], callback)`

История

Версия	Изменения
v18.0.0	Передача недопустимой функции обратного вызова в аргумент `callback` теперь приводит к выбросу `ERR_INVALID_ARG_TYPE` вместо `ERR_INVALID_CALLBACK`.
v15.8.0	Добавлено в: v15.8.0

size <number> Размер генерируемого простого числа в битах.
options <Object>
- add <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Buffer> | <DataView> | <bigint>
- rem <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Buffer> | <DataView> | <bigint>
- safe <boolean> По умолчанию: false.
- bigint <boolean> Если true, сгенерированное простое число возвращается как bigint.
callback <Function>
- err <Error>
- prime <ArrayBuffer> | <bigint>

Генерирует псевдослучайное простое число длиной size бит.

Если options.safe равно true, простое число будет безопасным, то есть (prime - 1) / 2 также будет простым числом.

Параметры options.add и options.rem можно использовать для задания дополнительных требований, например, для Диффи — Хеллмана:

Если заданы и options.add, и options.rem, простое число будет удовлетворять условию prime % add = rem.
Если задан только options.add, а options.safe не равно true, простое число будет удовлетворять условию prime % add = 1.
Если задан только options.add и options.safe установлено в true, простое число будет удовлетворять условию prime % add = 3. Это необходимо, поскольку prime % add = 1 для options.add > 2 противоречило бы условию, заданному параметром options.safe.
options.rem игнорируется, если options.add не задан.

Если options.add и options.rem заданы как ArrayBuffer, SharedArrayBuffer, TypedArray, Buffer или DataView, они должны быть закодированы в виде последовательностей в порядке от старшего байта к младшему.

По умолчанию простое число кодируется как последовательность октетов в порядке от старшего байта к младшему в <ArrayBuffer>. Если параметр bigint равен true, возвращается <bigint>.

size простого числа напрямую влияет на время его генерации. Чем больше размер, тем больше времени это займет. Поскольку используется функция BN_generate_prime_ex из OpenSSL, которая предоставляет лишь минимальные возможности для прерывания процесса генерации, не рекомендуется генерировать слишком большие простые числа: это может привести к зависанию процесса.

`crypto.generatePrimeSync(size[, options])`

Добавлено в: v15.8.0

size <number> Размер генерируемого простого числа в битах.
options <Object>
- add <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Buffer> | <DataView> | <bigint>
- rem <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Buffer> | <DataView> | <bigint>
- safe <boolean> По умолчанию: false.
- bigint <boolean> Если true, сгенерированное простое число возвращается как bigint.
Возвращает: <ArrayBuffer> | <bigint>

Генерирует псевдослучайное простое число длиной size бит.

Если options.safe равно true, простое число будет безопасным, то есть (prime - 1) / 2 также будет простым числом.

Если заданы и options.add, и options.rem, простое число будет удовлетворять условию prime % add = rem.
Если задан только options.add, а options.safe не равно true, простое число будет удовлетворять условию prime % add = 1.
Если задан только options.add и options.safe установлено в true, простое число будет удовлетворять условию prime % add = 3. Это необходимо, поскольку prime % add = 1 для options.add > 2 противоречило бы условию, заданному параметром options.safe.
options.rem игнорируется, если options.add не задан.

`crypto.getCipherInfo(nameOrNid[, options])`

Добавлено в: v15.0.0

nameOrNid <string> | <number> Имя или nid шифра, сведения о котором нужно получить.
options <Object>
- keyLength <number> Тестовая длина ключа.
- ivLength <number> Тестовая длина IV.
Возвращает: <Object>
- name <string> Имя шифра
- nid <number> Nid шифра
- blockSize <number> Размер блока шифра в байтах. Это свойство отсутствует, если mode равно 'stream'.
- ivLength <number> Ожидаемая или используемая по умолчанию длина вектора инициализации в байтах. Это свойство отсутствует, если шифр не использует вектор инициализации.
- keyLength <number> Ожидаемая или используемая по умолчанию длина ключа в байтах.
- mode <string> Режим шифрования. Одно из значений: 'cbc', 'ccm', 'cfb', 'ctr', 'ecb', 'gcm', 'ocb', 'ofb', 'stream', 'wrap', 'xts'.

Возвращает сведения о заданном шифре.

Некоторые шифры поддерживают ключи и векторы инициализации переменной длины. По умолчанию метод crypto.getCipherInfo() возвращает значения по умолчанию для таких шифров. Чтобы проверить, допустима ли заданная длина ключа или IV для указанного шифра, используйте параметры keyLength и ivLength. Если указанные значения недопустимы, будет возвращено undefined.

`crypto.getCiphers()`

Добавлено в: v0.9.3

Возвращает: <string[]> Массив с именами поддерживаемых алгоритмов шифрования.

Модули JavaScript

const {
  getCiphers,
} = await import('node:crypto');

console.log(getCiphers()); // ['aes-128-cbc', 'aes-128-ccm', ...]

CommonJS

const {
  getCiphers,
} = require('node:crypto');

console.log(getCiphers()); // ['aes-128-cbc', 'aes-128-ccm', ...]

`crypto.getCurves()`

Добавлено в: v2.3.0

Возвращает: <string[]> Массив с именами поддерживаемых эллиптических кривых.

Модули JavaScript

const {
  getCurves,
} = await import('node:crypto');

console.log(getCurves()); // ['Oakley-EC2N-3', 'Oakley-EC2N-4', ...]

CommonJS

const {
  getCurves,
} = require('node:crypto');

console.log(getCurves()); // ['Oakley-EC2N-3', 'Oakley-EC2N-4', ...]

`crypto.getDiffieHellman(groupName)`

Добавлено в: v0.7.5

groupName <string>
Возвращает: <DiffieHellmanGroup>

Создает предопределенный объект обмена ключами DiffieHellmanGroup. Поддерживаемые группы перечислены в документации для DiffieHellmanGroup.

Возвращаемый объект имитирует интерфейс объектов, созданных с помощью crypto.createDiffieHellman(), но не позволяет изменять ключи (например, с помощью diffieHellman.setPublicKey()). Преимущество этого метода заключается в том, что сторонам не нужно заранее генерировать или обмениваться модулем группы, что позволяет сэкономить время на вычислениях и передаче данных.

Пример (получение общего секрета):

Модули JavaScript

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');

/* aliceSecret and bobSecret should be the same */
console.log(aliceSecret === bobSecret);

CommonJS

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');

/* aliceSecret and bobSecret should be the same */
console.log(aliceSecret === bobSecret);

`crypto.getFips()`

Добавлено в: v10.0.0

Возвращает: <number> 1 тогда и только тогда, когда в данный момент используется криптографический провайдер, соответствующий FIPS; в противном случае — 0. В будущей версии с повышением основной версии semver тип возвращаемого значения этого API может быть изменен на <boolean>.

`crypto.getHashes()`

Добавлено в: v0.9.3

Возвращает: <string[]> Массив имен поддерживаемых алгоритмов хеширования, например 'RSA-SHA256'. Алгоритмы хеширования также называются алгоритмами вычисления дайджеста.

Модули JavaScript

const {
  getHashes,
} = await import('node:crypto');

console.log(getHashes()); // ['DSA', 'DSA-SHA', 'DSA-SHA1', ...]

CommonJS

const {
  getHashes,
} = require('node:crypto');

console.log(getHashes()); // ['DSA', 'DSA-SHA', 'DSA-SHA1', ...]

`crypto.getRandomValues(typedArray)`

Добавлено в: v17.4.0

typedArray <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer>
Возвращает: <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> Возвращает typedArray.

Удобный псевдоним для crypto.webcrypto.getRandomValues(). Эта реализация не соответствует спецификации Web Crypto; для написания совместимого с вебом кода используйте вместо нее crypto.webcrypto.getRandomValues().

`crypto.hash(algorithm, data[, outputEncoding])`

Добавлено в: v21.7.0, v20.12.0

Стабильность: 1.2 — релиз-кандидат

algorithm <string> | <undefined>
data <string> | <Buffer> | <TypedArray> | <DataView> Если data является строкой, перед хешированием она будет закодирована в UTF-8. Если для строковых данных требуется другая кодировка, пользователь может закодировать строку в TypedArray с помощью TextEncoder или Buffer.from() и передать закодированный TypedArray в этот API.
outputEncoding <string> | <undefined> Кодировка, используемая для кодирования возвращаемого дайджеста. По умолчанию: 'hex'.
Возвращает: <string> | <Buffer>

Вспомогательная функция для однократного вычисления дайджестов данных. При хешировании небольшого объема данных (<= 5MB), доступных сразу, она может работать быстрее, чем объектный crypto.createHash(). Если объем данных может быть большим или данные передаются потоком, рекомендуется использовать вместо нее crypto.createHash().

Набор algorithm зависит от алгоритмов, поддерживаемых установленной на платформе версией OpenSSL. Например: 'sha256', 'sha512' и т. д. В последних версиях OpenSSL команда openssl list -digest-algorithms выводит список доступных алгоритмов дайджестов.

Пример:

CommonJS

const crypto = require('node:crypto');
const { Buffer } = require('node:buffer');

// Hashing a string and return the result as a hex-encoded string.
const string = 'Node.js';
// 10b3493287f831e81a438811a1ffba01f8cec4b7
console.log(crypto.hash('sha1', string));

// Encode a base64-encoded string into a Buffer, hash it and return
// the result as a buffer.
const base64 = 'Tm9kZS5qcw==';
// <Buffer 10 b3 49 32 87 f8 31 e8 1a 43 88 11 a1 ff ba 01 f8 ce c4 b7>
console.log(crypto.hash('sha1', Buffer.from(base64, 'base64'), 'buffer'));

Модули JavaScript

import crypto from 'node:crypto';
import { Buffer } from 'node:buffer';

// Hashing a string and return the result as a hex-encoded string.
const string = 'Node.js';
// 10b3493287f831e81a438811a1ffba01f8cec4b7
console.log(crypto.hash('sha1', string));

// Encode a base64-encoded string into a Buffer, hash it and return
// the result as a buffer.
const base64 = 'Tm9kZS5qcw==';
// <Buffer 10 b3 49 32 87 f8 31 e8 1a 43 88 11 a1 ff ba 01 f8 ce c4 b7>
console.log(crypto.hash('sha1', Buffer.from(base64, 'base64'), 'buffer'));

`crypto.hkdf(digest, ikm, salt, info, keylen, callback)`

История

Версия	Изменения
v18.0.0	Передача недопустимой функции обратного вызова в аргумент `callback` теперь приводит к выбросу `ERR_INVALID_ARG_TYPE` вместо `ERR_INVALID_CALLBACK`.
v18.8.0, v16.18.0	Теперь длина исходного материала ключа может быть равна нулю.
v15.0.0	Добавлено в: v15.0.0

digest <string> Используемый алгоритм дайджеста.
ikm <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> Исходный материал ключа. Обязателен, но его длина может быть равна нулю.
salt <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> Значение соли. Обязательно, но его длина может быть равна нулю.
info <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> Дополнительная информация. Обязательна, но ее длина может быть равна нулю и не должна превышать 1024 байта.
keylen <number> Длина генерируемого ключа. Должна быть больше 0. Максимальное допустимое значение равно 255, умноженному на число байтов, генерируемых выбранной дайджест-функцией (например, sha512 генерирует хеши длиной 64 байта, поэтому максимальный размер выходных данных HKDF составляет 16320 байт).
callback <Function>
- err <Error>
- derivedKey <ArrayBuffer>

HKDF — это простая функция выработки ключа, определенная в RFC 5869. Заданные ikm, salt и info используются вместе с digest для получения ключа длиной keylen байт.

Переданная функция callback вызывается с двумя аргументами: err и derivedKey. Если при выработке ключа произошла ошибка, будет задано значение err; в противном случае err будет равно null. Успешно сгенерированный derivedKey будет передан функции обратного вызова как <ArrayBuffer>. Если какой-либо входной аргумент имеет недопустимое значение или тип, будет выброшена ошибка.

Модули JavaScript

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'));  // '24156e2...5391653'
});

CommonJS

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'));  // '24156e2...5391653'
});

`crypto.hkdfSync(digest, ikm, salt, info, keylen)`

История

Версия	Изменения
v18.8.0, v16.18.0	Теперь исходный ключевой материал может иметь нулевую длину.
v15.0.0	Добавлено в версии: v15.0.0

digest <string> Используемый алгоритм дайджеста.
ikm <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> Исходный ключевой материал. Обязателен, но может иметь нулевую длину.
salt <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> Значение соли. Обязательно, но может иметь нулевую длину.
info <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> Значение дополнительных сведений. Обязательно, может иметь нулевую длину и не может превышать 1024 байта.
keylen <number> Длина создаваемого ключа. Должна быть больше 0. Максимально допустимое значение — 255, умноженное на количество байтов, генерируемых выбранной функцией дайджеста (например, sha512 генерирует хеши размером 64 байта, поэтому максимальный размер выходных данных HKDF составляет 16320 байт).
Возвращает: <ArrayBuffer>

Предоставляет синхронную функцию выведения ключа HKDF, определённую в RFC 5869. Указанные ikm, salt и info используются вместе с digest для выведения ключа длиной keylen байт.

Успешно созданный derivedKey будет возвращён как <ArrayBuffer>.

Будет выброшена ошибка, если для какого-либо входного аргумента указано недопустимое значение или тип либо если производный ключ не удаётся создать.

Модули JavaScript

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'));  // '24156e2...5391653'

CommonJS

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'));  // '24156e2...5391653'

`crypto.pbkdf2(password, salt, iterations, keylen, digest, callback)`

История

Версия	Изменения
v18.0.0	Передача недопустимого обратного вызова в аргумент `callback` теперь приводит к выбросу `ERR_INVALID_ARG_TYPE` вместо `ERR_INVALID_CALLBACK`.
v15.0.0	Аргументы password и salt теперь также могут быть экземплярами ArrayBuffer.
v14.0.0	Теперь параметр `iterations` может принимать только положительные значения. В предыдущих выпусках остальные значения трактовались как единица.
v8.0.0	Теперь параметр `digest` всегда обязателен.
v6.0.0	Вызов этой функции без передачи параметра `digest` теперь считается устаревшим и приводит к выдаче предупреждения.
v6.0.0	Кодировка по умолчанию для `password`, если это строка, изменилась с `binary` на `utf8`.
v0.5.5	Добавлено в версии: v0.5.5

password <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
salt <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
iterations <number>
keylen <number>
digest <string>
callback <Function>
- err <Error>
- derivedKey <Buffer>

Предоставляет асинхронную реализацию функции выведения ключа на основе пароля 2 (PBKDF2). Выбранный алгоритм дайджеста HMAC, указанный в digest, применяется для выведения ключа запрошенной длины в байтах (keylen) из password, salt и iterations.

Переданная функция callback вызывается с двумя аргументами: err и derivedKey. Если при выведении ключа возникает ошибка, устанавливается err; в противном случае err будет равно null. По умолчанию успешно созданный derivedKey передаётся обратному вызову в виде Buffer. Будет выброшена ошибка, если для какого-либо входного аргумента указано недопустимое значение или тип.

Аргумент iterations должен быть числом, установленным на как можно более высокое значение. Чем больше число итераций, тем безопаснее будет производный ключ, однако выполнение займёт больше времени.

Значение salt должно быть как можно более уникальным. Рекомендуется использовать случайную соль длиной не менее 16 байт. Подробности см. в документе NIST SP 800-132.

При передаче строк для password или salt учитывайте особенности использования строк в качестве входных данных криптографических API.

Модули JavaScript

const {
  pbkdf2,
} = await import('node:crypto');

pbkdf2('secret', 'salt', 100000, 64, 'sha512', (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // '3745e48...08d59ae'
});

CommonJS

const {
  pbkdf2,
} = require('node:crypto');

pbkdf2('secret', 'salt', 100000, 64, 'sha512', (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // '3745e48...08d59ae'
});

Массив поддерживаемых функций дайджеста можно получить с помощью crypto.getHashes().

Этот API использует пул потоков libuv, что может иметь неожиданные и негативные последствия для производительности некоторых приложений; дополнительную информацию см. в документации UV_THREADPOOL_SIZE.

`crypto.pbkdf2Sync(password, salt, iterations, keylen, digest)`

История

Версия	Изменения
v14.0.0	Теперь параметр `iterations` может принимать только положительные значения. В предыдущих выпусках остальные значения трактовались как единица.
v6.0.0	Вызов этой функции без передачи параметра `digest` теперь считается устаревшим и приводит к выдаче предупреждения.
v6.0.0	Кодировка по умолчанию для `password`, если это строка, изменилась с `binary` на `utf8`.
v0.9.3	Добавлено в версии: v0.9.3

password <string> | <Buffer> | <TypedArray> | <DataView>
salt <string> | <Buffer> | <TypedArray> | <DataView>
iterations <number>
keylen <number>
digest <string>
Возвращает: <Buffer>

Предоставляет синхронную реализацию функции выведения ключа на основе пароля 2 (PBKDF2). Выбранный алгоритм дайджеста HMAC, указанный в digest, применяется для выведения ключа запрошенной длины в байтах (keylen) из password, salt и iterations.

Если возникает ошибка, будет выброшен Error; в противном случае производный ключ будет возвращён в виде Buffer.

Модули JavaScript

const {
  pbkdf2Sync,
} = await import('node:crypto');

const key = pbkdf2Sync('secret', 'salt', 100000, 64, 'sha512');
console.log(key.toString('hex'));  // '3745e48...08d59ae'

CommonJS

const {
  pbkdf2Sync,
} = require('node:crypto');

const key = pbkdf2Sync('secret', 'salt', 100000, 64, 'sha512');
console.log(key.toString('hex'));  // '3745e48...08d59ae'

Массив поддерживаемых функций дайджеста можно получить с помощью crypto.getHashes().

`crypto.privateDecrypt(privateKey, buffer)`

История

Версия	Изменения
v21.6.2, v20.11.1, v18.19.1	Дополнение `RSA_PKCS1_PADDING` было отключено, если сборка OpenSSL не поддерживает неявное отклонение.
v15.0.0	Строки, ArrayBuffer и CryptoKey добавлены в список допустимых типов ключей. oaepLabel может быть ArrayBuffer. Буфер может быть строкой или ArrayBuffer. Максимальный размер всех типов, принимающих буферы, ограничен значением 2 ** 31 - 1 байт.
v12.11.0	Добавлен параметр `oaepLabel`.
v12.9.0	Добавлен параметр `oaepHash`.
v11.6.0	Теперь эта функция поддерживает объекты ключей.
v0.11.14	Добавлено в версии: v0.11.14

privateKey <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
- oaepHash <string> Хеш-функция для дополнения OAEP и MGF1. По умолчанию: 'sha1'
- oaepLabel <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> Метка для дополнения OAEP. Если не указана, метка не используется.
- padding <crypto.constants> Необязательное значение дополнения, определённое в crypto.constants. Возможные значения: crypto.constants.RSA_NO_PADDING, crypto.constants.RSA_PKCS1_PADDING или crypto.constants.RSA_PKCS1_OAEP_PADDING.
buffer <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
Возвращает: <Buffer> Новый Buffer с расшифрованным содержимым.

Расшифровывает buffer с помощью privateKey. buffer ранее был зашифрован соответствующим открытым ключом, например с помощью crypto.publicEncrypt().

Если privateKey не является KeyObject, эта функция ведёт себя так, как если бы privateKey был передан в crypto.createPrivateKey(). Если это объект, можно передать свойство padding. В противном случае функция использует RSA_PKCS1_OAEP_PADDING.

Использование crypto.constants.RSA_PKCS1_PADDING в crypto.privateDecrypt() требует поддержки неявного отклонения в OpenSSL (rsa_pkcs1_implicit_rejection). Если версия OpenSSL, используемая Node.js, не поддерживает эту возможность, попытка использовать RSA_PKCS1_PADDING завершится ошибкой.

`crypto.privateEncrypt(privateKey, buffer)`

История

Версия	Изменения
v15.0.0	Строки, ArrayBuffer и CryptoKey добавлены в список допустимых типов ключей. Парольная фраза может быть ArrayBuffer. Буфер может быть строкой или ArrayBuffer. Максимальный размер всех типов, принимающих буферы, ограничен значением 2 ** 31 - 1 байт.
v11.6.0	Теперь эта функция поддерживает объекты ключей.
v1.1.0	Добавлено в версии: v1.1.0

privateKey <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
- key <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey> Закрытый ключ в кодировке PEM.
- passphrase <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> Необязательная парольная фраза для закрытого ключа.
- padding <crypto.constants> Необязательное значение дополнения, определённое в crypto.constants. Возможные значения: crypto.constants.RSA_NO_PADDING или crypto.constants.RSA_PKCS1_PADDING.
- encoding <string> Кодировка строки, используемая, если buffer, key или passphrase являются строками.
buffer <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
Возвращает: <Buffer> Новый Buffer с зашифрованным содержимым.

Зашифровывает buffer с помощью privateKey. Возвращённые данные можно расшифровать соответствующим открытым ключом, например с помощью crypto.publicDecrypt().

`crypto.publicDecrypt(key, buffer)`

История

Версия	Изменения
v15.0.0	Строки, ArrayBuffer и CryptoKey добавлены в список допустимых типов ключей. Парольная фраза может быть ArrayBuffer. Буфер может быть строкой или ArrayBuffer. Максимальный размер всех типов, принимающих буферы, ограничен значением 2 ** 31 - 1 байт.
v11.6.0	Теперь эта функция поддерживает объекты ключей.
v1.1.0	Добавлено в версии: v1.1.0

key <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
- passphrase <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> Необязательная парольная фраза для закрытого ключа.
- padding <crypto.constants> Необязательное значение дополнения, определённое в crypto.constants. Возможные значения: crypto.constants.RSA_NO_PADDING или crypto.constants.RSA_PKCS1_PADDING.
- encoding <string> Кодировка строки, используемая, если buffer, key или passphrase являются строками.
buffer <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
Возвращает: <Buffer> Новый Buffer с расшифрованным содержимым.

Расшифровывает buffer с помощью key.buffer ранее был зашифрован соответствующим закрытым ключом, например с помощью crypto.privateEncrypt().

Если key не является KeyObject, эта функция ведёт себя так, как если бы key был передан в crypto.createPublicKey(). Если это объект, можно передать свойство padding. В противном случае функция использует RSA_PKCS1_PADDING.

Поскольку открытые ключи RSA можно получить из закрытых ключей, вместо открытого ключа можно передать закрытый ключ.

`crypto.publicEncrypt(key, buffer)`

История

Версия	Изменения
v15.0.0	Добавлены string, ArrayBuffer и CryptoKey в качестве допустимых типов ключей. oaepLabel и passphrase могут быть ArrayBuffer. buffer может быть строкой или ArrayBuffer. Для всех типов, принимающих буферы, установлен максимальный размер 2 ** 31 - 1 байт.
v12.11.0	Добавлена опция `oaepLabel`.
v12.9.0	Добавлена опция `oaepHash`.
v11.6.0	Теперь эта функция поддерживает объекты ключей.
v0.11.14	Добавлено в: v0.11.14

key <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
- key <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey> Открытый или закрытый ключ в кодировке PEM, <KeyObject> или <CryptoKey>.
- oaepHash <string> Хеш-функция, используемая для дополнения OAEP и MGF1. По умолчанию: 'sha1'
- oaepLabel <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> Метка, используемая для дополнения OAEP. Если не указана, метка не используется.
- passphrase <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> Необязательная парольная фраза для закрытого ключа.
- padding <crypto.constants> Необязательное значение дополнения, определённое в crypto.constants; допустимы значения: crypto.constants.RSA_NO_PADDING, crypto.constants.RSA_PKCS1_PADDING или crypto.constants.RSA_PKCS1_OAEP_PADDING.
- encoding <string> Кодировка строки, используемая, если buffer, key, oaepLabel или passphrase являются строками.
buffer <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
Возвращает: <Buffer> Новый Buffer с зашифрованным содержимым.

Шифрует содержимое buffer с помощью key и возвращает новый Buffer с зашифрованным содержимым. Возвращённые данные можно расшифровать соответствующим закрытым ключом, например с помощью crypto.privateDecrypt().

Если key не является KeyObject, эта функция работает так, как если бы key был передан в crypto.createPublicKey(). Если это объект, можно передать свойство padding. В противном случае функция использует RSA_PKCS1_OAEP_PADDING.

Поскольку открытые ключи RSA можно получить из закрытых ключей, вместо открытого ключа можно передать закрытый.

`crypto.randomBytes(size[, callback])`

История

Версия	Изменения
v18.0.0	Передача недопустимой функции обратного вызова в аргумент `callback` теперь вызывает `ERR_INVALID_ARG_TYPE` вместо `ERR_INVALID_CALLBACK`.
v9.0.0	Передача `null` в качестве аргумента `callback` теперь вызывает `ERR_INVALID_CALLBACK`.
v0.5.8	Добавлено в: v0.5.8

size <number> Количество генерируемых байтов. Значение size не должно превышать 2**31 - 1.
callback <Function>
- err <Error>
- buf <Buffer>
Возвращает: <Buffer>, если функция callback не передана.

Генерирует криптографически стойкие псевдослучайные данные. Аргумент size — число, указывающее количество генерируемых байтов.

Если передана функция callback, байты генерируются асинхронно, а функция callback вызывается с двумя аргументами: err и buf. При возникновении ошибки err будет объектом Error; в противном случае это null. Аргумент buf — это Buffer, содержащий сгенерированные байты.

Модули JavaScript

// Asynchronous
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')}`);
});

CommonJS

// Asynchronous
const {
  randomBytes,
} = require('node:crypto');

randomBytes(256, (err, buf) => {
  if (err) throw err;
  console.log(`${buf.length} bytes of random data: ${buf.toString('hex')}`);
});

Если функция callback не передана, случайные байты генерируются синхронно и возвращаются в виде Buffer. Если при генерации байтов возникнет проблема, будет выброшена ошибка.

Модули JavaScript

// Synchronous
const {
  randomBytes,
} = await import('node:crypto');

const buf = randomBytes(256);
console.log(
  `${buf.length} bytes of random data: ${buf.toString('hex')}`);

CommonJS

// Synchronous
const {
  randomBytes,
} = require('node:crypto');

const buf = randomBytes(256);
console.log(
  `${buf.length} bytes of random data: ${buf.toString('hex')}`);

Метод crypto.randomBytes() не завершится, пока не станет доступно достаточное количество энтропии. Обычно это занимает не более нескольких миллисекунд. Единственный случай, когда генерация случайных байтов может блокироваться дольше, — сразу после загрузки, когда во всей системе ещё мало энтропии.

Этот API использует пул потоков libuv, что может иметь неожиданные негативные последствия для производительности некоторых приложений; дополнительную информацию см. в документации UV_THREADPOOL_SIZE.

Асинхронная версия crypto.randomBytes() выполняется в рамках одного запроса к пулу потоков. Чтобы свести к минимуму различия в длительности задач пула потоков, разбивайте большие запросы randomBytes на части при их обработке в рамках выполнения клиентского запроса.

`crypto.randomFill(buffer[, offset][, size], callback)`

История

Версия	Изменения
v18.0.0	Передача недопустимой функции обратного вызова в аргумент `callback` теперь вызывает `ERR_INVALID_ARG_TYPE` вместо `ERR_INVALID_CALLBACK`.
v9.0.0	Аргумент `buffer` теперь может иметь тип `TypedArray` или `DataView`.
v7.10.0, v6.13.0	Добавлено в: v7.10.0, v6.13.0

buffer <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> Обязательный аргумент. Размер переданного buffer не должен превышать 2**31 - 1.
offset <number> По умолчанию: 0
size <number> По умолчанию: buffer.length - offset. Значение size не должно превышать 2**31 - 1.
callback <Function> function(err, buf) {}.

Эта функция похожа на crypto.randomBytes(), но в качестве первого аргумента принимает Buffer, который будет заполнен. Кроме того, необходимо передать функцию обратного вызова.

Если функция callback не передана, будет выброшена ошибка.

Модули JavaScript

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'));
});

// The above is equivalent to the following:
randomFill(buf, 5, 5, (err, buf) => {
  if (err) throw err;
  console.log(buf.toString('hex'));
});

CommonJS

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'));
});

// The above is equivalent to the following:
randomFill(buf, 5, 5, (err, buf) => {
  if (err) throw err;
  console.log(buf.toString('hex'));
});

В качестве buffer можно передать любой экземпляр ArrayBuffer, TypedArray или DataView.

Хотя это включает экземпляры Float32Array и Float64Array, эту функцию не следует использовать для генерации случайных чисел с плавающей запятой. Результат может содержать +Infinity, -Infinity и NaN; и даже если массив содержит только конечные числа, они не получены из равномерного случайного распределения и не имеют осмысленных нижней или верхней границы.

Модули JavaScript

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'));
});

CommonJS

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'));
});

Асинхронная версия crypto.randomFill() выполняется в рамках одного запроса к пулу потоков. Чтобы свести к минимуму различия в длительности задач пула потоков, разбивайте большие запросы randomFill на части при их обработке в рамках выполнения клиентского запроса.

`crypto.randomFillSync(buffer[, offset][, size])`

История

Версия	Изменения
v9.0.0	Аргумент `buffer` теперь может иметь тип `TypedArray` или `DataView`.
v7.10.0, v6.13.0	Добавлено в: v7.10.0, v6.13.0

buffer <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> Обязательный аргумент. Размер переданного buffer не должен превышать 2**31 - 1.
offset <number> По умолчанию: 0
size <number> По умолчанию: buffer.length - offset. Значение size не должно превышать 2**31 - 1.
Возвращает: <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> Объект, переданный в качестве аргумента buffer.

Синхронная версия crypto.randomFill().

Модули JavaScript

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'));

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

CommonJS

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'));

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

В качестве buffer можно передать любой экземпляр ArrayBuffer, TypedArray или DataView.

Модули JavaScript

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'));

CommonJS

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])`

История

Версия	Изменения
v18.0.0	Передача недопустимой функции обратного вызова в аргумент `callback` теперь вызывает `ERR_INVALID_ARG_TYPE` вместо `ERR_INVALID_CALLBACK`.
v14.10.0, v12.19.0	Добавлено в: v14.10.0, v12.19.0

min <integer> Начало случайного диапазона (включительно). По умолчанию: 0.
max <integer> Конец случайного диапазона (не включительно).
callback <Function> function(err, n) {}.

Возвращает случайное целое число n такое, что min <= n < max. Эта реализация исключает смещение по модулю.

Диапазон (max - min) должен быть меньше 2⁴⁸. min и max должны быть безопасными целыми числами.

Если функция callback не передана, случайное целое число генерируется синхронно.

Модули JavaScript

// Asynchronous
const {
  randomInt,
} = await import('node:crypto');

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

CommonJS

// Asynchronous
const {
  randomInt,
} = require('node:crypto');

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

Модули JavaScript

// Synchronous
const {
  randomInt,
} = await import('node:crypto');

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

CommonJS

// Synchronous
const {
  randomInt,
} = require('node:crypto');

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

Модули JavaScript

// With `min` argument
const {
  randomInt,
} = await import('node:crypto');

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

CommonJS

// With `min` argument
const {
  randomInt,
} = require('node:crypto');

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

`crypto.randomUUID([options])`

Добавлено в: v15.6.0, v14.17.0

options <Object>
- disableEntropyCache <boolean> По умолчанию для повышения производительности Node.js генерирует и кэширует достаточно случайных данных для создания до 128 случайных UUID. Чтобы создать UUID без использования кэша, установите disableEntropyCache в true. По умолчанию: false.
Возвращает: <string>

Генерирует случайный UUID версии 4 согласно RFC 4122. UUID генерируется с помощью криптографического генератора псевдослучайных чисел.

`crypto.scrypt(password, salt, keylen[, options], callback)`

История

Версия	Изменения
v18.0.0	Передача недопустимой функции обратного вызова в аргумент `callback` теперь вызывает `ERR_INVALID_ARG_TYPE` вместо `ERR_INVALID_CALLBACK`.
v15.0.0	Аргументы password и salt также могут быть экземплярами ArrayBuffer.
v12.8.0, v10.17.0	Значением `maxmem` теперь может быть любое безопасное целое число.
v10.9.0	Добавлены имена опций `cost`, `blockSize` и `parallelization`.
v10.5.0	Добавлено в: v10.5.0

password <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
salt <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
keylen <number>
options <Object>
- cost <number> Параметр вычислительных затрат и затрат памяти. Должен быть степенью двойки больше единицы. По умолчанию: 16384.
- blockSize <number> Параметр размера блока. По умолчанию: 8.
- parallelization <number> Параметр параллелизации. По умолчанию: 1.
- N <number> Псевдоним для cost. Можно указать только один из этих параметров.
- r <number> Псевдоним для blockSize. Можно указать только один из этих параметров.
- p <number> Псевдоним для parallelization. Можно указать только один из этих параметров.
- maxmem <number> Верхний предел памяти. Ошибка возникает, когда значение приблизительно равно 128 * N * r > maxmem. По умолчанию: 32 * 1024 * 1024.
callback <Function>
- err <Error>
- derivedKey <Buffer>

Предоставляет асинхронную реализацию scrypt. Scrypt — это функция выработки ключа на основе пароля, требующая значительных вычислительных ресурсов и объёма памяти, чтобы сделать атаки методом перебора невыгодными.

При передаче строк для password или salt учитывайте особенности использования строк в качестве входных данных для криптографических API.

Функция callback вызывается с двумя аргументами: err и derivedKey. Если выработка ключа завершается с ошибкой, err является объектом исключения; в противном случае err — это null. Аргумент derivedKey передаётся функции обратного вызова в виде Buffer.

Если во входных аргументах указаны недопустимые значения или типы, выбрасывается исключение.

Модули JavaScript

const {
  scrypt,
} = await import('node:crypto');

// Using the factory defaults.
scrypt('password', 'salt', 64, (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // '3745e48...08d59ae'
});
// Using a custom N parameter. Must be a power of two.
scrypt('password', 'salt', 64, { N: 1024 }, (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // '3745e48...aa39b34'
});

CommonJS

const {
  scrypt,
} = require('node:crypto');

// Using the factory defaults.
scrypt('password', 'salt', 64, (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // '3745e48...08d59ae'
});
// Using a custom N parameter. Must be a power of two.
scrypt('password', 'salt', 64, { N: 1024 }, (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // '3745e48...aa39b34'
});

`crypto.scryptSync(password, salt, keylen[, options])`

История

Версия	Изменения
v12.8.0, v10.17.0	Значением `maxmem` теперь может быть любое безопасное целое число.
v10.9.0	Добавлены имена опций `cost`, `blockSize` и `parallelization`.
v10.5.0	Добавлено в: v10.5.0

password <string> | <Buffer> | <TypedArray> | <DataView>
salt <string> | <Buffer> | <TypedArray> | <DataView>
keylen <number>
options <Object>
- cost <number> Параметр вычислительных затрат и затрат памяти. Должен быть степенью двойки больше единицы. По умолчанию: 16384.
- blockSize <number> Параметр размера блока. По умолчанию: 8.
- parallelization <number> Параметр параллелизации. По умолчанию: 1.
- N <number> Псевдоним для cost. Можно указать только один из этих параметров.
- r <number> Псевдоним для blockSize. Можно указать только один из этих параметров.
- p <number> Псевдоним для parallelization. Можно указать только один из этих параметров.
- maxmem <number> Верхний предел памяти. Ошибка возникает, когда значение приблизительно равно 128 * N * r > maxmem. По умолчанию: 32 * 1024 * 1024.
Возвращает: <Buffer>

Предоставляет синхронную реализацию scrypt. Scrypt — это функция выработки ключа на основе пароля, требующая значительных вычислительных ресурсов и объёма памяти, чтобы сделать атаки методом перебора невыгодными.

Если выработка ключа завершается с ошибкой, выбрасывается исключение; в противном случае производный ключ возвращается в виде Buffer.

Если во входных аргументах указаны недопустимые значения или типы, выбрасывается исключение.

Модули JavaScript

const {
  scryptSync,
} = await import('node:crypto');
// Using the factory defaults.

const key1 = scryptSync('password', 'salt', 64);
console.log(key1.toString('hex'));  // '3745e48...08d59ae'
// Using a custom N parameter. Must be a power of two.
const key2 = scryptSync('password', 'salt', 64, { N: 1024 });
console.log(key2.toString('hex'));  // '3745e48...aa39b34'

CommonJS

const {
  scryptSync,
} = require('node:crypto');
// Using the factory defaults.

const key1 = scryptSync('password', 'salt', 64);
console.log(key1.toString('hex'));  // '3745e48...08d59ae'
// Using a custom N parameter. Must be a power of two.
const key2 = scryptSync('password', 'salt', 64, { N: 1024 });
console.log(key2.toString('hex'));  // '3745e48...aa39b34'

`crypto.secureHeapUsed()`

Добавлено в: v15.6.0

Возвращает: <Object>
- total <number> Общий размер выделенной защищённой кучи, заданный с помощью флага командной строки --secure-heap=n.
- min <number> Минимальный объём выделения из защищённой кучи, заданный с помощью флага командной строки --secure-heap-min.
- used <number> Общее количество байтов, выделенных в данный момент из защищённой кучи.
- utilization <number> Рассчитанное отношение used к total выделенных байтов.

`crypto.setEngine(engine[, flags])`

История

Версия	Изменения
v22.4.0	Поддержка пользовательских движков в OpenSSL 3 устарела.
v0.11.11	Добавлено в: v0.11.11

engine <string>
flags <crypto.constants> По умолчанию: crypto.constants.ENGINE_METHOD_ALL

Загружает и задаёт engine для некоторых или всех функций OpenSSL (выбираемых с помощью флагов). Поддержка пользовательских движков в OpenSSL устарела начиная с OpenSSL 3.

engine может быть идентификатором или путём к общей библиотеке движка.

Необязательный аргумент flags по умолчанию использует ENGINE_METHOD_ALL. flags — это битовое поле, принимающее один или несколько следующих флагов (определённых в 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)`

Добавлено в: v10.0.0

bool <boolean> true для включения режима FIPS.

Включает криптографический провайдер, соответствующий FIPS, в сборке Node.js с поддержкой FIPS. Вызывает ошибку, если режим FIPS недоступен.

`crypto.sign(algorithm, data, key[, callback])`

История

Версия	Изменения
v18.0.0	Передача недопустимой функции обратного вызова в аргумент `callback` теперь вызывает `ERR_INVALID_ARG_TYPE` вместо `ERR_INVALID_CALLBACK`.
v15.12.0	Добавлен необязательный аргумент функции обратного вызова.
v13.2.0, v12.16.0	Теперь эта функция поддерживает подписи DSA и ECDSA в формате IEEE-P1363.
v12.0.0	Добавлено в: v12.0.0

algorithm <string> | <null> | <undefined>
data <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
key <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
callback <Function>
- err <Error>
- signature <Buffer>
Возвращает: <Buffer>, если функция callback не указана.

Вычисляет и возвращает подпись для data с использованием заданного закрытого ключа и алгоритма. Если algorithm имеет значение null или undefined, алгоритм зависит от типа ключа (особенно для Ed25519 и Ed448).

Если key не является KeyObject, эта функция ведёт себя так, как если бы key был передан в crypto.createPrivateKey(). Если это объект, можно передать следующие дополнительные свойства:

dsaEncoding <string> Для DSA и ECDSA этот параметр задаёт формат создаваемой подписи. Возможны следующие значения:
- 'der' (по умолчанию): структура подписи ASN.1 в кодировке DER, содержащая (r, s).
- 'ieee-p1363': формат подписи r || s, предложенный в IEEE-P1363.
padding <integer> Необязательное значение дополнения для RSA, одно из следующих:
- crypto.constants.RSA_PKCS1_PADDING (по умолчанию)
- crypto.constants.RSA_PKCS1_PSS_PADDING
RSA_PKCS1_PSS_PADDING будет использовать MGF1 с той же хеш-функцией, которая использовалась для подписи сообщения, как указано в разделе 3.1 RFC 4055.
saltLength <integer> Длина соли для дополнения RSA_PKCS1_PSS_PADDING. Специальное значение crypto.constants.RSA_PSS_SALTLEN_DIGEST задаёт длину соли, равную размеру дайджеста, а crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN (по умолчанию) задаёт её равной максимально допустимому значению.

Если указана функция callback, эта функция использует пул потоков libuv.

`crypto.subtle`

Добавлено в: v17.4.0

Тип: <SubtleCrypto>

Удобный псевдоним для crypto.webcrypto.subtle.

`crypto.timingSafeEqual(a, b)`

История

Версия	Изменения
v15.0.0	Аргументы a и b также могут быть объектами ArrayBuffer.
v6.6.0	Добавлено в: v6.6.0

a <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
b <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
Возвращает: <boolean>

Эта функция сравнивает базовые байты, представляющие заданные экземпляры ArrayBuffer, TypedArray или DataView, используя алгоритм с постоянным временем выполнения.

Эта функция не раскрывает информацию о времени выполнения, которая позволила бы злоумышленнику угадать одно из значений. Она подходит для сравнения дайджестов HMAC или секретных значений, таких как файлы cookie аутентификации или URL-адреса с возможностями.

a и b должны быть оба значениями типа Buffer, TypedArray или DataView и иметь одинаковую длину в байтах. Если a и b имеют разную длину в байтах, возникает ошибка.

Если хотя бы один из аргументов a и b является TypedArray, содержащим более одного байта на элемент, например Uint16Array, результат будет вычислен с учётом порядка байтов платформы.

Если оба входных значения являются Float32Array или Float64Array, эта функция может возвращать неожиданные результаты из-за представления чисел с плавающей запятой в формате IEEE 754. В частности, ни x === y, ни Object.is(x, y) не подразумевает, что байтовые представления двух чисел с плавающей запятой x и y равны.

Использование crypto.timingSafeEqual не гарантирует, что окружающий код защищён от атак по времени выполнения. Необходимо убедиться, что окружающий код не создаёт уязвимостей, связанных со временем выполнения.

`crypto.verify(algorithm, data, key, signature[, callback])`

История

Версия	Изменения
v18.0.0	Передача недопустимой функции обратного вызова в аргумент `callback` теперь вызывает `ERR_INVALID_ARG_TYPE` вместо `ERR_INVALID_CALLBACK`.
v15.12.0	Добавлен необязательный аргумент функции обратного вызова.
v15.0.0	Аргументы data, key и signature также могут быть объектами ArrayBuffer.
v13.2.0, v12.16.0	Теперь эта функция поддерживает подписи DSA и ECDSA в формате IEEE-P1363.
v12.0.0	Добавлено в: v12.0.0

algorithm <string> | <null> | <undefined>
data <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
key <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
signature <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
callback <Function>
- err <Error>
- result <boolean>
Возвращает: <boolean> true или false в зависимости от того, действительна ли подпись для данных и открытого ключа, если функция callback не указана.

Проверяет заданную подпись для data с использованием заданных ключа и алгоритма. Если algorithm имеет значение null или undefined, алгоритм зависит от типа ключа (особенно для Ed25519 и Ed448).

Если key не является KeyObject, эта функция ведёт себя так, как если бы key был передан в crypto.createPublicKey(). Если это объект, можно передать следующие дополнительные свойства:

dsaEncoding <string> Для DSA и ECDSA этот параметр задаёт формат подписи. Возможны следующие значения:
- 'der' (по умолчанию): структура подписи ASN.1 в кодировке DER, содержащая (r, s).
- 'ieee-p1363': формат подписи r || s, предложенный в IEEE-P1363.
padding <integer> Необязательное значение дополнения для RSA, одно из следующих:
- crypto.constants.RSA_PKCS1_PADDING (по умолчанию)
- crypto.constants.RSA_PKCS1_PSS_PADDING
RSA_PKCS1_PSS_PADDING будет использовать MGF1 с той же хеш-функцией, которая использовалась для подписи сообщения, как указано в разделе 3.1 RFC 4055.
saltLength <integer> Длина соли для дополнения RSA_PKCS1_PSS_PADDING. Специальное значение crypto.constants.RSA_PSS_SALTLEN_DIGEST задаёт длину соли, равную размеру дайджеста, а crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN (по умолчанию) задаёт её равной максимально допустимому значению.

Аргумент signature — это ранее вычисленная подпись для data.

Поскольку открытые ключи можно получить из закрытых ключей, для key можно передать как закрытый, так и открытый ключ.

Если указана функция callback, эта функция использует пул потоков libuv.

`crypto.webcrypto`

Добавлено в: v15.0.0

Тип: <Crypto> Реализация стандарта Web Crypto API.

Подробности см. в документации Web Crypto API.

Примечания

Использование строк в качестве входных данных для криптографических API

По историческим причинам многие криптографические API, предоставляемые Node.js, принимают в качестве входных данных строки, хотя базовый криптографический алгоритм работает с последовательностями байтов. К таким данным относятся открытый текст, шифротекст, симметричные ключи, векторы инициализации, парольные фразы, соли, теги аутентификации и дополнительные аутентифицированные данные.

При передаче строк в криптографические API учитывайте следующие факторы.

Не все последовательности байтов являются допустимыми строками UTF-8. Поэтому, если из строки получается последовательность байтов длиной n, её энтропия, как правило, ниже энтропии случайной или псевдослучайной последовательности байтов n. Например, ни одна строка UTF-8 не даст последовательность байтов c0 af. Секретные ключи почти всегда должны быть случайными или псевдослучайными последовательностями байтов.
Аналогично, при преобразовании случайных или псевдослучайных последовательностей байтов в строки UTF-8 подпоследовательности, не представляющие допустимые кодовые точки, могут быть заменены символом замены Unicode (U+FFFD). Поэтому байтовое представление полученной строки Unicode может не совпадать с последовательностью байтов, из которой она была создана.
```
const original = [0xc0, 0xaf];
const bytesAsString = Buffer.from(original).toString('utf8');
const stringAsBytes = Buffer.from(bytesAsString, 'utf8');
console.log(stringAsBytes);
// Prints '<Buffer ef bf bd ef bf bd>'. copy
```
Результаты работы шифров, хеш-функций, алгоритмов подписи и функций выработки ключа являются псевдослучайными последовательностями байтов и не должны использоваться как строки Unicode.
При получении строк от пользователя некоторые символы Unicode могут быть представлены несколькими эквивалентными способами, в результате чего получаются разные последовательности байтов. Например, при передаче пользовательской парольной фразы в функцию выработки ключа, такую как PBKDF2 или scrypt, результат зависит от того, использует ли строка составные или разложенные символы. Node.js не нормализует представление символов. Разработчикам следует рассмотреть возможность применения String.prototype.normalize() к пользовательским данным перед их передачей в криптографические API.

Устаревший API потоков (до Node.js 0.10)

Модуль Crypto был добавлен в Node.js до появления единого API потоков и до появления объектов Buffer для обработки двоичных данных. Поэтому многие классы crypto имеют методы, обычно не встречающиеся в других классах Node.js, реализующих API потоков (например, update(), final() или digest()). Кроме того, многие методы по умолчанию принимали и возвращали строки в кодировке 'latin1', а не объекты Buffer. После Node.js v0.8 это поведение по умолчанию было изменено: вместо него стали использоваться объекты Buffer.

Поддержка слабых или скомпрометированных алгоритмов

Модуль node:crypto по-прежнему поддерживает некоторые уже скомпрометированные алгоритмы, использование которых не рекомендуется. API также позволяет использовать шифры и хеш-функции с небольшим размером ключа, недостаточным для безопасного использования.

Пользователи несут полную ответственность за выбор криптографического алгоритма и размера ключа в соответствии со своими требованиями безопасности.

Согласно рекомендациям NIST SP 800-131A:

MD5 и SHA-1 больше не подходят для случаев, когда требуется устойчивость к коллизиям, например для цифровых подписей.
Для безопасного использования в течение нескольких лет рекомендуется, чтобы ключи алгоритмов RSA, DSA и DH имели размер не менее 2048 бит, а ключи кривых ECDSA и ECDH — не менее 224 бит.
Группы DH modp1, modp2 и modp5 имеют размер ключа менее 2048 бит и не рекомендуются.

Другие рекомендации и подробности см. в справочном документе.

Некоторые алгоритмы с известными уязвимостями, имеющие малое практическое значение, доступны только через устаревший провайдер, который по умолчанию отключён.

Режим CCM

CCM — один из поддерживаемых алгоритмов AEAD. Приложения, использующие этот режим, должны соблюдать определённые ограничения при работе с API шифров:

Длина тега аутентификации должна быть задана при создании шифра с помощью параметра authTagLength и должна составлять 4, 6, 8, 10, 12, 14 или 16 байт.
Длина вектора инициализации (nonce) N должна составлять от 7 до 13 байт (7 ≤ N ≤ 13).
Длина открытого текста ограничена 2 ** (8 * (15 - N)) байтами.
При расшифровании тег аутентификации необходимо задать с помощью setAuthTag() до вызова update(). В противном случае расшифрование завершится неудачно, а final() вызовет ошибку в соответствии с разделом 2.6 RFC 3610.
Использование потоковых методов, таких как write(data), end(data) или pipe(), в режиме CCM может завершиться ошибкой, поскольку CCM не может обрабатывать более одного фрагмента данных на экземпляр.
При передаче дополнительных аутентифицированных данных (AAD) длину фактического сообщения в байтах необходимо передать в setAAD() с помощью параметра plaintextLength. Многие криптографические библиотеки включают тег аутентификации в шифротекст, поэтому длина создаваемого ими шифротекста составляет plaintextLength + authTagLength. Node.js не включает тег аутентификации, поэтому длина шифротекста всегда составляет plaintextLength. Это не требуется, если AAD не используется.
Поскольку CCM обрабатывает всё сообщение целиком, update() необходимо вызвать ровно один раз.
Хотя для шифрования или расшифрования сообщения достаточно вызвать update(), приложения должны вызвать final() для вычисления или проверки тега аутентификации.

Модули JavaScript

import { Buffer } from 'node:buffer';
const {
  createCipheriv,
  createDecipheriv,
  randomBytes,
} = await import('node:crypto');

const key = 'keykeykeykeykeykeykeykey';
const nonce = randomBytes(12);

const aad = Buffer.from('0123456789', 'hex');

const cipher = createCipheriv('aes-192-ccm', key, nonce, {
  authTagLength: 16,
});
const plaintext = 'Hello world';
cipher.setAAD(aad, {
  plaintextLength: Buffer.byteLength(plaintext),
});
const ciphertext = cipher.update(plaintext, 'utf8');
cipher.final();
const tag = cipher.getAuthTag();

// Now transmit { ciphertext, nonce, tag }.

const decipher = createDecipheriv('aes-192-ccm', key, nonce, {
  authTagLength: 16,
});
decipher.setAuthTag(tag);
decipher.setAAD(aad, {
  plaintextLength: ciphertext.length,
});
const receivedPlaintext = decipher.update(ciphertext, null, 'utf8');

try {
  decipher.final();
} catch (err) {
  throw new Error('Authentication failed!', { cause: err });
}

console.log(receivedPlaintext);

CommonJS

const { Buffer } = require('node:buffer');
const {
  createCipheriv,
  createDecipheriv,
  randomBytes,
} = require('node:crypto');

const key = 'keykeykeykeykeykeykeykey';
const nonce = randomBytes(12);

const aad = Buffer.from('0123456789', 'hex');

const cipher = createCipheriv('aes-192-ccm', key, nonce, {
  authTagLength: 16,
});
const plaintext = 'Hello world';
cipher.setAAD(aad, {
  plaintextLength: Buffer.byteLength(plaintext),
});
const ciphertext = cipher.update(plaintext, 'utf8');
cipher.final();
const tag = cipher.getAuthTag();

// Now transmit { ciphertext, nonce, tag }.

const decipher = createDecipheriv('aes-192-ccm', key, nonce, {
  authTagLength: 16,
});
decipher.setAuthTag(tag);
decipher.setAAD(aad, {
  plaintextLength: ciphertext.length,
});
const receivedPlaintext = decipher.update(ciphertext, null, 'utf8');

try {
  decipher.final();
} catch (err) {
  throw new Error('Authentication failed!', { cause: err });
}

console.log(receivedPlaintext);

Режим FIPS

При использовании OpenSSL 3 Node.js поддерживает FIPS 140-2 при наличии соответствующего провайдера OpenSSL 3, например провайдера FIPS для OpenSSL 3, который можно установить, следуя инструкциям в файле README по FIPS проекта OpenSSL.

Для поддержки FIPS в Node.js необходимы:

Корректно установленный провайдер FIPS для OpenSSL 3.
Файл конфигурации модуля FIPS для OpenSSL 3.
Файл конфигурации OpenSSL 3, ссылающийся на файл конфигурации модуля FIPS.

Для Node.js необходимо настроить файл конфигурации OpenSSL, указывающий на провайдер FIPS. Пример такого файла конфигурации:

nodejs_conf = nodejs_init

.include /<absolute path>/fipsmodule.cnf

[nodejs_init]
providers = provider_sect

[provider_sect]
default = default_sect
# The fips section name should match the section name inside the
# included fipsmodule.cnf.
fips = fips_sect

[default_sect]
activate = 1 copy

где fipsmodule.cnf — это файл конфигурации модуля FIPS, созданный на этапе установки провайдера FIPS:

openssl fipsinstall copy

Задайте переменной среды OPENSSL_CONF путь к файлу конфигурации, а переменной OPENSSL_MODULES — путь к динамической библиотеке провайдера FIPS. Например:

export OPENSSL_CONF=/<path to configuration file>/nodejs.cnf
export OPENSSL_MODULES=/<path to openssl lib>/ossl-modules copy

После этого режим FIPS можно включить в Node.js одним из следующих способов:

Запустить Node.js с флагами командной строки --enable-fips или --force-fips.
Программно вызвать crypto.setFips(true).

При желании режим FIPS можно включить в Node.js с помощью файла конфигурации OpenSSL. Например:

nodejs_conf = nodejs_init

.include /<absolute path>/fipsmodule.cnf

[nodejs_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
default = default_sect
# The fips section name should match the section name inside the
# included fipsmodule.cnf.
fips = fips_sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes copy

Криптографические константы

Следующие константы, экспортируемые crypto.constants, используются в различных целях в модулях node:crypto, node:tls и node:https и, как правило, специфичны для OpenSSL.

Параметры OpenSSL

Подробную информацию см. в списке флагов SSL OP.

Константа	Описание
`SSL_OP_ALL`	Применяет несколько обходных решений для ошибок в OpenSSL. Подробности см. на странице https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set_options.html.
`SSL_OP_ALLOW_NO_DHE_KEX`	Указывает OpenSSL разрешить режим обмена ключами, не основанный на [EC]DHE, для TLS v1.3
`SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION`	Разрешает устаревшую небезопасную повторную установку соединения между OpenSSL и клиентами или серверами без исправлений. См. https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set_options.html.
`SSL_OP_CIPHER_SERVER_PREFERENCE`	При выборе шифра пытается использовать предпочтения сервера вместо предпочтений клиента. Поведение зависит от версии протокола. См. https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set_options.html.
`SSL_OP_CISCO_ANYCONNECT`	Указывает OpenSSL использовать идентификатор версии DTLS_BAD_VER от Cisco.
`SSL_OP_COOKIE_EXCHANGE`	Указывает OpenSSL включить обмен cookie.
`SSL_OP_CRYPTOPRO_TLSEXT_BUG`	Указывает OpenSSL добавить расширение server-hello из ранней версии черновика cryptopro.
`SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS`	Указывает OpenSSL отключить обходное решение для уязвимости SSL 3.0/TLS 1.0, добавленное в OpenSSL 0.9.6d.
`SSL_OP_LEGACY_SERVER_CONNECT`	Разрешает первоначальное подключение к серверам, не поддерживающим RI.
`SSL_OP_NO_COMPRESSION`	Указывает OpenSSL отключить поддержку сжатия SSL/TLS.
`SSL_OP_NO_ENCRYPT_THEN_MAC`	Указывает OpenSSL отключить encrypt-then-MAC.
`SSL_OP_NO_QUERY_MTU`
`SSL_OP_NO_RENEGOTIATION`	Указывает OpenSSL отключить повторную установку соединения.
`SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION`	Указывает OpenSSL всегда начинать новый сеанс при повторной установке соединения.
`SSL_OP_NO_SSLv2`	Указывает OpenSSL отключить SSL v2
`SSL_OP_NO_SSLv3`	Указывает OpenSSL отключить SSL v3
`SSL_OP_NO_TICKET`	Указывает OpenSSL отключить использование билетов RFC4507bis.
`SSL_OP_NO_TLSv1`	Указывает OpenSSL отключить TLS v1
`SSL_OP_NO_TLSv1_1`	Указывает OpenSSL отключить TLS v1.1
`SSL_OP_NO_TLSv1_2`	Указывает OpenSSL отключить TLS v1.2
`SSL_OP_NO_TLSv1_3`	Указывает OpenSSL отключить TLS v1.3
`SSL_OP_PRIORITIZE_CHACHA`	Указывает серверу OpenSSL отдавать приоритет ChaCha20-Poly1305, если это делает клиент. Этот параметр не действует, если `SSL_OP_CIPHER_SERVER_PREFERENCE` не включен.
`SSL_OP_TLS_ROLLBACK_BUG`	Указывает OpenSSL отключить обнаружение атак с откатом версии.

Константы движка OpenSSL

Константа	Описание
`ENGINE_METHOD_RSA`	Ограничивает использование движка алгоритмом RSA
`ENGINE_METHOD_DSA`	Ограничивает использование движка алгоритмом DSA
`ENGINE_METHOD_DH`	Ограничивает использование движка алгоритмом DH
`ENGINE_METHOD_RAND`	Ограничивает использование движка генератором случайных чисел RAND
`ENGINE_METHOD_EC`	Ограничивает использование движка алгоритмом EC
`ENGINE_METHOD_CIPHERS`	Ограничивает использование движка шифрами CIPHERS
`ENGINE_METHOD_DIGESTS`	Ограничивает использование движка дайджестами DIGESTS
`ENGINE_METHOD_PKEY_METHS`	Ограничивает использование движка методами PKEY_METHS
`ENGINE_METHOD_PKEY_ASN1_METHS`	Ограничивает использование движка методами PKEY_ASN1_METHS
`ENGINE_METHOD_ALL`
`ENGINE_METHOD_NONE`

Другие константы OpenSSL

Константа	Описание
`DH_CHECK_P_NOT_SAFE_PRIME`
`DH_CHECK_P_NOT_PRIME`
`DH_UNABLE_TO_CHECK_GENERATOR`
`DH_NOT_SUITABLE_GENERATOR`
`RSA_PKCS1_PADDING`
`RSA_SSLV23_PADDING`
`RSA_NO_PADDING`
`RSA_PKCS1_OAEP_PADDING`
`RSA_X931_PADDING`
`RSA_PKCS1_PSS_PADDING`
`RSA_PSS_SALTLEN_DIGEST`	При подписании или проверке подписи задает длину соли для `RSA_PKCS1_PSS_PADDING` равной размеру дайджеста.
`RSA_PSS_SALTLEN_MAX_SIGN`	При подписании данных задает для соли `RSA_PKCS1_PSS_PADDING` максимально допустимую длину.
`RSA_PSS_SALTLEN_AUTO`	При проверке подписи автоматически определяет длину соли для `RSA_PKCS1_PSS_PADDING`.
`POINT_CONVERSION_COMPRESSED`
`POINT_CONVERSION_UNCOMPRESSED`
`POINT_CONVERSION_HYBRID`

Криптографические константы Node.js

Константа	Описание
`defaultCoreCipherList`	Задает встроенный список шифров по умолчанию, используемый Node.js.
`defaultCipherList`	Задает активный список шифров по умолчанию, используемый текущим процессом Node.js.

© Joyent, Inc. and other Node contributors
Licensed under the MIT License.
Node.js is a trademark of Joyent, Inc. and is used with its permission.
We are not endorsed by or affiliated with Joyent.
https://nodejs.org/dist/latest-v22.x/docs/api/crypto.html

Криптография

Определение отсутствия поддержки криптографии

Класс: Certificate

Статический метод: Certificate.exportChallenge(spkac[, encoding])

Статический метод: Certificate.exportPublicKey(spkac[, encoding])

Статический метод: Certificate.verifySpkac(spkac[, encoding])

Устаревший API

new crypto.Certificate()

certificate.exportChallenge(spkac[, encoding])

certificate.exportPublicKey(spkac[, encoding])

certificate.verifySpkac(spkac[, encoding])

Класс: Cipher

cipher.final([outputEncoding])

cipher.getAuthTag()

cipher.setAAD(buffer[, options])

cipher.setAutoPadding([autoPadding])

cipher.update(data[, inputEncoding][, outputEncoding])

Класс: Decipher

decipher.final([outputEncoding])

decipher.setAAD(buffer[, options])

decipher.setAuthTag(buffer[, encoding])

decipher.setAutoPadding([autoPadding])

decipher.update(data[, inputEncoding][, outputEncoding])

Класс: DiffieHellman

diffieHellman.computeSecret(otherPublicKey[, inputEncoding][, outputEncoding])

diffieHellman.generateKeys([encoding])

diffieHellman.getGenerator([encoding])

diffieHellman.getPrime([encoding])

diffieHellman.getPrivateKey([encoding])

diffieHellman.getPublicKey([encoding])

diffieHellman.setPrivateKey(privateKey[, encoding])

diffieHellman.setPublicKey(publicKey[, encoding])

diffieHellman.verifyError

Класс: DiffieHellmanGroup

Класс: ECDH

Статический метод: ECDH.convertKey(key, curve[, inputEncoding[, outputEncoding[, format]]])

ecdh.computeSecret(otherPublicKey[, inputEncoding][, outputEncoding])

ecdh.generateKeys([encoding[, format]])

ecdh.getPrivateKey([encoding])

ecdh.getPublicKey([encoding][, format])

ecdh.setPrivateKey(privateKey[, encoding])

ecdh.setPublicKey(publicKey[, encoding])

Класс: Hash

hash.copy([options])

hash.digest([encoding])

hash.update(data[, inputEncoding])

Класс: Hmac

hmac.digest([encoding])

hmac.update(data[, inputEncoding])

Класс: KeyObject

Статический метод: KeyObject.from(key)

keyObject.asymmetricKeyDetails

keyObject.asymmetricKeyType

keyObject.equals(otherKeyObject)

keyObject.export([options])

keyObject.symmetricKeySize

keyObject.toCryptoKey(algorithm, extractable, keyUsages)

keyObject.type

Класс: Sign

sign.sign(privateKey[, outputEncoding])

sign.update(data[, inputEncoding])

Класс: Verify

verify.update(data[, inputEncoding])

verify.verify(object, signature[, signatureEncoding])

Класс: X509Certificate

new X509Certificate(buffer)

x509.ca

x509.checkEmail(email[, options])

x509.checkHost(name[, options])

x509.checkIP(ip)

x509.checkIssued(otherCert)

x509.checkPrivateKey(privateKey)

x509.fingerprint

x509.fingerprint256

x509.fingerprint512

x509.infoAccess

x509.issuer

x509.issuerCertificate

x509.keyUsage

x509.publicKey

Класс: `Certificate`

Статический метод: `Certificate.exportChallenge(spkac[, encoding])`

Статический метод: `Certificate.exportPublicKey(spkac[, encoding])`

Статический метод: `Certificate.verifySpkac(spkac[, encoding])`

`new crypto.Certificate()`

`certificate.exportChallenge(spkac[, encoding])`

`certificate.exportPublicKey(spkac[, encoding])`

`certificate.verifySpkac(spkac[, encoding])`

Класс: `Cipher`

`cipher.final([outputEncoding])`

`cipher.getAuthTag()`

`cipher.setAAD(buffer[, options])`

`cipher.setAutoPadding([autoPadding])`

`cipher.update(data[, inputEncoding][, outputEncoding])`

Класс: `Decipher`

`decipher.final([outputEncoding])`

`decipher.setAAD(buffer[, options])`

`decipher.setAuthTag(buffer[, encoding])`

`decipher.setAutoPadding([autoPadding])`

`decipher.update(data[, inputEncoding][, outputEncoding])`

Класс: `DiffieHellman`

`diffieHellman.computeSecret(otherPublicKey[, inputEncoding][, outputEncoding])`

`diffieHellman.generateKeys([encoding])`

`diffieHellman.getGenerator([encoding])`

`diffieHellman.getPrime([encoding])`

`diffieHellman.getPrivateKey([encoding])`

`diffieHellman.getPublicKey([encoding])`

`diffieHellman.setPrivateKey(privateKey[, encoding])`

`diffieHellman.setPublicKey(publicKey[, encoding])`

`diffieHellman.verifyError`

Класс: `DiffieHellmanGroup`

Класс: `ECDH`

Статический метод: `ECDH.convertKey(key, curve[, inputEncoding[, outputEncoding[, format]]])`

`ecdh.computeSecret(otherPublicKey[, inputEncoding][, outputEncoding])`

`ecdh.generateKeys([encoding[, format]])`

`ecdh.getPrivateKey([encoding])`

`ecdh.getPublicKey([encoding][, format])`

`ecdh.setPrivateKey(privateKey[, encoding])`

`ecdh.setPublicKey(publicKey[, encoding])`

Класс: `Hash`

`hash.copy([options])`

`hash.digest([encoding])`

`hash.update(data[, inputEncoding])`

Класс: `Hmac`

`hmac.digest([encoding])`

`hmac.update(data[, inputEncoding])`

Класс: `KeyObject`

Статический метод: `KeyObject.from(key)`

`keyObject.asymmetricKeyDetails`

`keyObject.asymmetricKeyType`

`keyObject.equals(otherKeyObject)`

`keyObject.export([options])`

`keyObject.symmetricKeySize`

`keyObject.toCryptoKey(algorithm, extractable, keyUsages)`

`keyObject.type`

Класс: `Sign`

`sign.sign(privateKey[, outputEncoding])`

`sign.update(data[, inputEncoding])`

Класс: `Verify`

`verify.update(data[, inputEncoding])`

`verify.verify(object, signature[, signatureEncoding])`

Класс: `X509Certificate`

`new X509Certificate(buffer)`

`x509.ca`

`x509.checkEmail(email[, options])`

`x509.checkHost(name[, options])`

`x509.checkIP(ip)`

`x509.checkIssued(otherCert)`

`x509.checkPrivateKey(privateKey)`

`x509.fingerprint`

`x509.fingerprint256`

`x509.fingerprint512`

`x509.infoAccess`

`x509.issuer`

`x509.issuerCertificate`

`x509.keyUsage`

`x509.publicKey`

`x509.raw`

`x509.serialNumber`

`x509.subject`