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

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

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

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

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

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

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

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

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])

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

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

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])

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

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

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

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

new crypto.Certificate()

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

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

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

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

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

certificate.exportChallenge(spkac[, encoding])

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

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

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])

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

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 ...>

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])

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

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

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

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

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

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

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

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

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();
  });
});

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 и объединённых в конвейер потоков:

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

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():

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

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])

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

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

cipher.getAuthTag()

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

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

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

cipher.setAAD(buffer[, options])

• 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])

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

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

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

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

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

• 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

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

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

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

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

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

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

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 и потоков с передачей данных:

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

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():

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

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])

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

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

decipher.setAAD(buffer[, options])

• 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])

• 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() выбросит ошибку.

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

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

decipher.setAutoPadding([autoPadding])

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

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

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

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

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

• 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

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

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

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

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])

• 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])

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

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

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

diffieHellman.getGenerator([encoding])

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

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

diffieHellman.getPrime([encoding])

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

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

diffieHellman.getPrivateKey([encoding])

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

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

diffieHellman.getPublicKey([encoding])

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

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

diffieHellman.setPrivateKey(privateKey[, encoding])

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

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

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

diffieHellman.setPublicKey(publicKey[, encoding])

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

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

diffieHellman.verifyError

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

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

• DH_CHECK_P_NOT_SAFE_PRIME
• DH_CHECK_P_NOT_PRIME
• DH_UNABLE_TO_CHECK_GENERATOR
• DH_NOT_SUITABLE_GENERATOR

Класс: DiffieHellmanGroup

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

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

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

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

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

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

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]]])

• 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.

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

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

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])

• 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]])

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

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

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

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

ecdh.getPrivateKey([encoding])

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

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

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

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

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

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

ecdh.setPrivateKey(privateKey[, encoding])

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

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

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

ecdh.setPublicKey(publicKey[, encoding])

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

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

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

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

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

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

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

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

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

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

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

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

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 и потоков с конвейерной передачей:

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

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():

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

const hash = createHash('sha256');

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

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])

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

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

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

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

// 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.

// 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])

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

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

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

hash.update(data[, inputEncoding])

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

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

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

Класс: Hmac

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

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

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

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

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

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

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 и потоков с конвейерной передачей:

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

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():

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

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])

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

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

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

hmac.update(data[, inputEncoding])

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

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

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

Класс: KeyObject

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

В большинстве приложений следует рассмотреть возможность использования нового API KeyObject вместо передачи ключей в виде строк или Buffer из-за улучшенных функций безопасности.

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

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

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

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

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)

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

• <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

• <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.export([options])

• 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, только если используется format формата PEM. Для максимальной совместимости используйте PKCS#8 для зашифрованных закрытых ключей. Поскольку PKCS#8 определяет собственный механизм шифрования, шифрование на уровне PEM не поддерживается при шифровании ключа PKCS#8. См. RFC 5208 для шифрования PKCS#8 и RFC 1421 для шифрования PKCS#1 и SEC1.

keyObject.equals(otherKeyObject)

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

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

keyObject.symmetricKeySize

• <number>

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

keyObject.type

• <string>

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

Класс: Sign

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

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

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

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

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

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

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():

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

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])

• 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])

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

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

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

Класс: Verify

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

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

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

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

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

verify.update(data[, inputEncoding])

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

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

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

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

• 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

Инкапсулирует сертификат X509 и предоставляет доступ только для чтения к содержащейся в нем информации.

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

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

console.log(x509.subject);

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

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

console.log(x509.subject);

new X509Certificate(buffer)

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

x509.ca

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

x509.checkEmail(email[, options])

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

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

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

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

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

x509.checkHost(name[, options])

• 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 регистром букв.

Если параметр 'subject' не задан или имеет значение 'default', субъект сертификата учитывается только в том случае, если расширение альтернативного имени субъекта отсутствует или не содержит DNS-имен. Это поведение соответствует RFC 2818 («HTTP поверх TLS»).

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

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

x509.checkIP(ip)

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

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

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

x509.checkIssued(otherCert)

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

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

x509.checkPrivateKey(privateKey)

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

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

x509.fingerprint

• Тип: <string>

Отпечаток этого сертификата SHA-1.

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

x509.fingerprint256

• Тип: <string>

Отпечаток этого сертификата SHA-256.

x509.fingerprint512

• Тип: <string>

Отпечаток этого сертификата SHA-512.

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

x509.infoAccess

• Тип: <string>

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

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

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

x509.issuer

• Тип: <string>

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

x509.issuerCertificate

• Тип: <X509Certificate>

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

x509.extKeyUsage

• Тип: <string[]>

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

x509.publicKey

• Тип: <KeyObject>

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

x509.raw

• Тип: <Buffer>

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

x509.serialNumber

• Тип: <string>

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

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

x509.subject

• Тип: <string>

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

x509.subjectAltName

• Тип: <string>

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

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

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

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

x509.toJSON()

• Тип: <string>

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

x509.toLegacyObject()

• Тип: <Object>

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

x509.toString()

• Тип: <string>

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

x509.validFrom

• Тип: <string>

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

x509.validTo

• Тип: <string>

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

x509.verify(publicKey)

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

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

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

crypto.constants

• <Object>

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

crypto.fips

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

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

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

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

Проверяет простоту числа candidate.

crypto.checkPrimeSync(candidate[, options])

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

Проверяет простоту числа candidate.

crypto.createCipher(algorithm, password[, options])

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

Создаёт и возвращает объект Cipher, использующий указанные algorithm и password.

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

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

Параметр password используется для получения ключа шифра и вектора инициализации (IV). Значение должно быть строкой в кодировке 'latin1', объектом Buffer, объектом TypedArray или объектом DataView.

Эта функция семантически небезопасна для всех поддерживаемых шифров и критически уязвима для шифров в режиме счётчика (например, CTR, GCM или CCM).

Реализация crypto.createCipher() получает ключи с помощью функции OpenSSL EVP_BytesToKey, используя алгоритм хеширования MD5, одну итерацию и не используя соль. Отсутствие соли делает возможными словарные атаки, поскольку один и тот же пароль всегда создаёт один и тот же ключ. Малое количество итераций и некриптографически стойкий алгоритм хеширования позволяют очень быстро проверять пароли.

В соответствии с рекомендацией OpenSSL использовать более современный алгоритм вместо EVP_BytesToKey разработчикам рекомендуется самостоятельно получать ключ и IV с помощью crypto.scrypt(), а для создания объекта Cipher использовать crypto.createCipheriv(). Не следует использовать шифры в режиме счётчика (например, CTR, GCM или CCM) в crypto.createCipher(). При их использовании выводится предупреждение, чтобы избежать риска повторного использования IV, приводящего к уязвимостям. Подробнее о повторном использовании IV в GCM см. в статье «Противники, игнорирующие nonce».

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

• 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.createDecipher(algorithm, password[, options])

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

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

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

Эта функция семантически небезопасна для всех поддерживаемых шифров и критически уязвима для шифров в режиме счётчика (например, CTR, GCM или CCM).

Реализация crypto.createDecipher() получает ключи с помощью функции OpenSSL EVP_BytesToKey, используя алгоритм хеширования MD5, одну итерацию и не используя соль. Отсутствие соли делает возможными словарные атаки, поскольку один и тот же пароль всегда создаёт один и тот же ключ. Малое количество итераций и некриптографически стойкий алгоритм хеширования позволяют очень быстро проверять пароли.

В соответствии с рекомендацией OpenSSL использовать более современный алгоритм вместо EVP_BytesToKey разработчикам рекомендуется самостоятельно получать ключ и IV с помощью crypto.scrypt(), а для создания объекта Decipher использовать crypto.createDecipheriv().

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

• 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 байт.

Значение 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.createDiffieHellman(prime[, primeEncoding][, generator][, generatorEncoding])

• 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])

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

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

crypto.createDiffieHellmanGroup(name)

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

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

crypto.createECDH(curveName)

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

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

crypto.createHash(algorithm[, options])

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

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

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

Пример: вычисление контрольной суммы sha256 для файла

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}`);
  }
});

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])

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

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

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

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

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

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}`);
  }
});

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)

• 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)

• 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])

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

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

crypto.createSign(algorithm[, options])

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

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

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

crypto.createVerify(algorithm[, options])

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

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

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

crypto.diffieHellman(options)

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

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

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

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

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

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

Пример:

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

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.generateKey(type, options, callback)

• 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.

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

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

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)

• 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' с шифрованием:

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.
});

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)

• 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>

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

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

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

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

const {
  publicKey,
  privateKey,
} = generateKeyPairSync('rsa', {
  modulusLength: 4096,
  publicKeyEncoding: {
    type: 'spki',
    format: 'pem',
  },
  privateKeyEncoding: {
    type: 'pkcs8',
    format: 'pem',
    cipher: 'aes-256-cbc',
    passphrase: 'top secret',
  },
});

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

const {
  publicKey,
  privateKey,
} = generateKeyPairSync('rsa', {
  modulusLength: 4096,
  publicKeyEncoding: {
    type: 'spki',
    format: 'pem',
  },
  privateKeyEncoding: {
    type: 'pkcs8',
    format: 'pem',
    cipher: 'aes-256-cbc',
    passphrase: 'top secret',
  },
});

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

crypto.generateKeySync(type, options)

• 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.

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

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

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]])

• size <number> Размер создаваемого простого числа (в битах).
• options <Object>
  • add <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Buffer> | <DataView> | <bigint>
  • rem <ArrayBuffer> | <SharedArrayBuffer> | <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>.

crypto.generatePrimeSync(size[, options])

• 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 можно использовать для задания дополнительных требований, например для Диффи — Хеллмана:

• Если заданы оба параметра, 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>.

crypto.getCipherInfo(nameOrNid[, options])

• 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()

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

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

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

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

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

crypto.getCurves()

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

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

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

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

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

crypto.getDiffieHellman(groupName)

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

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

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

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

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

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()

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

crypto.getHashes()

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

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

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

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

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

crypto.getRandomValues(typedArray)

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

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

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

• 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>. Если во входных аргументах указаны недопустимые значения или типы, будет выброшена ошибка.

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

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)

• 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>.

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

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'

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)

• 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.

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

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)

• 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.

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

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

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

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

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

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)

• 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). Если используемая Node.js версия OpenSSL не поддерживает эту возможность, попытка использовать RSA_PKCS1_PADDING завершится ошибкой.

crypto.privateEncrypt(privateKey, buffer)

• 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().

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

crypto.publicDecrypt(key, buffer)

• 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)

• 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])

• size <number> Количество байтов для генерации. Значение size не должно превышать 2**31 - 1.
• callback <Function>
  • err <Error>
  • buf <Buffer>
• Возвращает: <Buffer>, если функция callback не указана.

Генерирует криптографически стойкие псевдослучайные данные. Аргумент size — это число, указывающее количество генерируемых байтов.

Если указана функция callback, байты генерируются асинхронно, а функция callback вызывается с двумя аргументами: err и buf. В случае ошибки err будет объектом Error; в противном случае это null. Аргумент buf — это Buffer, содержащий сгенерированные байты.

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

// 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. Если при генерации байтов возникнет проблема, будет выброшена ошибка.

// Synchronous
const {
  randomBytes,
} = await import('node:crypto');

const buf = randomBytes(256);
console.log(
  `${buf.length} bytes of random data: ${buf.toString('hex')}`);

// 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.randomFillSync(buffer[, offset][, size])

• 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().

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

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.

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

const a = new Uint32Array(10);
console.log(Buffer.from(randomFillSync(a).buffer,
                        a.byteOffset, a.byteLength).toString('hex'));

const b = new DataView(new ArrayBuffer(10));
console.log(Buffer.from(randomFillSync(b).buffer,
                        b.byteOffset, b.byteLength).toString('hex'));

const c = new ArrayBuffer(10);
console.log(Buffer.from(randomFillSync(c)).toString('hex'));

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

const a = new Uint32Array(10);
console.log(Buffer.from(randomFillSync(a).buffer,
                        a.byteOffset, a.byteLength).toString('hex'));

const b = new DataView(new ArrayBuffer(10));
console.log(Buffer.from(randomFillSync(b).buffer,
                        b.byteOffset, b.byteLength).toString('hex'));

const c = new ArrayBuffer(10);
console.log(Buffer.from(randomFillSync(c)).toString('hex'));

crypto.randomFill(buffer[, offset][, size], callback)

• 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 не указана, будет выброшена ошибка.

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

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; даже если массив содержит только конечные числа, они не формируются в соответствии с равномерным случайным распределением и не имеют осмысленных нижней и верхней границ.

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

const a = new Uint32Array(10);
randomFill(a, (err, buf) => {
  if (err) throw err;
  console.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength)
    .toString('hex'));
});

const b = new DataView(new ArrayBuffer(10));
randomFill(b, (err, buf) => {
  if (err) throw err;
  console.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength)
    .toString('hex'));
});

const c = new ArrayBuffer(10);
randomFill(c, (err, buf) => {
  if (err) throw err;
  console.log(Buffer.from(buf).toString('hex'));
});

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

const a = new Uint32Array(10);
randomFill(a, (err, buf) => {
  if (err) throw err;
  console.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength)
    .toString('hex'));
});

const b = new DataView(new ArrayBuffer(10));
randomFill(b, (err, buf) => {
  if (err) throw err;
  console.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength)
    .toString('hex'));
});

const c = new ArrayBuffer(10);
randomFill(c, (err, buf) => {
  if (err) throw err;
  console.log(Buffer.from(buf).toString('hex'));
});

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

Асинхронная версия crypto.randomFill() выполняется в рамках одного запроса к пулу потоков. Чтобы свести к минимуму разброс длительности задач в пуле потоков, разбивайте большие запросы randomFill на части, если они выполняются в рамках обработки запроса клиента.

crypto.randomInt([min, ]max[, callback])

• min <integer> Начало случайного диапазона (включительно). По умолчанию: 0.
• max <integer> Конец случайного диапазона (не включительно).
• callback <Function> function(err, n) {}.

Возвращает случайное целое число n такое, что min <= n < max. Эта реализация устраняет смещение по модулю.

Диапазон (max - min) должен быть меньше 2⁴⁸. min и max должны быть безопасными целыми числами.

Если функция callback не указана, случайное целое число генерируется синхронно.

// 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}`);
});

// Asynchronous
const {
  randomInt,
} = require('node:crypto');

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

// Synchronous
const {
  randomInt,
} = await import('node:crypto');

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

// Synchronous
const {
  randomInt,
} = require('node:crypto');

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

// With `min` argument
const {
  randomInt,
} = await import('node:crypto');

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

// With `min` argument
const {
  randomInt,
} = require('node:crypto');

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

crypto.randomUUID([options])

• 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)

• 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 — это функция получения ключа на основе пароля, вычислительно и ресурсоёмкая, чтобы сделать атаки перебором нецелесообразными.

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

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

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

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

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

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])

• 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 — это функция выработки ключа на основе пароля, которая требует значительных вычислительных ресурсов и объема памяти, чтобы сделать перебор паролей невыгодным.

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

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

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

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

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'

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()

• Возвращает: <Object>
  • total <number> Общий размер выделенной защищенной кучи, заданный с помощью флага командной строки --secure-heap=n.
  • min <number> Минимальный объем выделения из защищенной кучи, заданный с помощью флага командной строки --secure-heap-min.
  • used <number> Общее количество байтов, выделенных в данный момент из защищенной кучи.
  • utilization <number> Рассчитанное отношение used к total выделенным байтам.

crypto.setEngine(engine[, flags])

• 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)

• bool <boolean> true для включения режима FIPS.

Включает криптографический провайдер, соответствующий требованиям FIPS, в сборке Node.js с поддержкой FIPS. Если режим FIPS недоступен, выбрасывается ошибка.

crypto.sign(algorithm, data, key[, callback])

• 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' (по умолчанию): структура подписи в кодировке DER ASN.1, кодирующая (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

• Тип: <SubtleCrypto>

Удобный псевдоним для crypto.webcrypto.subtle.

crypto.timingSafeEqual(a, b)

• 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])

• 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' (по умолчанию): структура подписи в кодировке DER ASN.1, кодирующая (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

Тип: <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() для вычисления или проверки тега аутентификации.

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

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

Следующие константы, экспортируемые crypto.constants, применяются в различных случаях использования модулей node:crypto, node:tls и node:https и, как правило, относятся непосредственно к OpenSSL.

Параметры OpenSSL

Подробнее см. в списке флагов SSL OP.

Константы движка OpenSSL

Другие константы OpenSSL

Криптографические константы Node.js