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

Возможна ситуация, когда 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') зарегистрирован до любой попытки загрузки модуля (например, с помощью модуля preload).

При использовании 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 и формально определённый как часть элемента HTML5 keygen.

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

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

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

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

Модули MJS

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

Модули CJS

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

Модули MJS

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

Модули CJS

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

Модули MJS

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

Модули CJS

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() как функцию:

Модули MJS

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

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

Модули CJS

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

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

certificate.exportChallenge(spkac[, encoding])

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

Модули MJS

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

Модули CJS

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

Модули MJS

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

Модули CJS

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

Модули MJS

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

Модули CJS

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 используются для шифрования данных. Класс можно использовать двумя способами:

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

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

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

Модули MJS

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

Модули CJS

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

Модули MJS

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

Модули CJS

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

Модули MJS

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

Модули CJS

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

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

cipher.getAuthTag()

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

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

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

cipher.setAAD(buffer[, options])

• buffer <строка> | <ArrayBuffer> | <Буфер> | <Массив типов> | <DataView>
• options <Объект> stream.transform опции
  • plaintextLength <число>
  • encoding <строка> Кодировка строки, используемой при buffer является строкой.
• Возвращает: <Шифр> для цепочки вызовов.

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

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

Метод cipher.setAAD() должен быть вызван до cipher.update().

cipher.setAutoPadding([autoPadding])

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

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

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

Метод cipher.setAutoPadding() должен быть вызван перед cipher.final().

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

• data <строка> | <Буфер> | <Массив типов> | <DataView>
• inputEncoding <строка> Кодировка данных.
• outputEncoding <строка> Кодировка значения, возвращаемого методом.
• Возвращает: <Буфер> | <строка>

Обновляет шифр с помощью 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 используются для расшифровки данных. Класс может быть использован двумя способами:

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

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

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

Модули MJS

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

Модули CJS

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 и потоков (piped streams):

Модули MJS

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

Модули CJS

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

Модули MJS

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

Модули CJS

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

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

decipher.setAAD(buffer[, options])

• buffer <строка> | <ArrayBuffer> | <Буфер> | <TypedArray> | <DataView>
• options <Объект> stream.transform параметры
  • plaintextLength <число>
  • encoding <строка> Кодировка строки, которая должна быть использована, когда buffer является строкой.
• Возвращает: <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 <строка> | <Буфер> | <ArrayBuffer> | <TypedArray> | <DataView>
• encoding <строка> Кодировка строки, которая должна быть использована, когда buffer является строкой.
• Возвращает: <Decipher> для цепочки методов.

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

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

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

decipher.setAutoPadding([autoPadding])

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

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

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

Метод decipher.setAutoPadding() должен быть вызван до decipher.final().

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

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

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

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

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

Класс: DiffieHellman

Класс DiffieHellman — это утилита для создания обмена ключами Диффи-Хеллмана.

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

Модули MJS

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

Модули CJS

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 <строка> | <ArrayBuffer> | <Буфер> | <TypedArray> | <DataView>
• inputEncoding <строка> Кодировка строки otherPublicKey.
• outputEncoding <строка> Кодировка возвращаемого значения.
• Возвращает: <Буфер> | <строка>

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

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

diffieHellman.generateKeys([encoding])

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

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

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

diffieHellman.getGenerator([encoding])

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

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

diffieHellman.getPrime([encoding])

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

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

diffieHellman.getPrivateKey([encoding])

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

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

diffieHellman.getPublicKey([encoding])

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

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

diffieHellman.setPrivateKey(privateKey[, encoding])

• privateKey <строка> | <ArrayBuffer> | <Буфер> | <TypedArray> | <DataView>
• encoding <строка> Кодировка строки privateKey.

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

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

diffieHellman.setPublicKey(publicKey[, encoding])

• publicKey <строка> | <ArrayBuffer> | <Буфер> | <TypedArray> | <DataView>
• encoding <строка> Кодировка строки 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().

Модули MJS

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

Модули CJS

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

Модули MJS

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

Модули CJS

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 <строка> | <ArrayBuffer> | <Буфер> | <Тип массива> | <DataView>
• curve <строка>
• inputEncoding <строка> Кодировка кодировки строки key.
• outputEncoding <строка> Кодировка кодировки возвращаемого значения.
• format <строка> По умолчанию: 'uncompressed'
• Возвращает: <Буфер> | <строка>

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

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

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

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

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

Модули MJS

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

Модули CJS

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 <строка> | <ArrayBuffer> | <Буфер> | <Тип массива> | <DataView>
• inputEncoding <строка> Кодировка кодировки строки otherPublicKey.
• outputEncoding <строка> Кодировка кодировки возвращаемого значения.
• Возвращает: <Буфер> | <строка>

Вычисляет общий секрет, используя 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 <строка> Кодировка кодировки возвращаемого значения.
• format <строка> По умолчанию: 'uncompressed'
• Возвращает: <Буфер> | <строка>

Генерирует частные и открытые ключи ECDiffie-Hellмана и возвращает открытый ключ в указанном format и encoding формате. Этот ключ должен быть передан другой стороне.

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

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

ecdh.getPrivateKey([encoding])

• encoding <строка> Кодировка кодировки возвращаемого значения.
• Возвращает: <Буфер> | <строка> ECDiffie-Hellman в указанном encoding формате.

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

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

• encoding <строка> Кодировка кодировки возвращаемого значения.
• format <строка> По умолчанию: 'uncompressed'
• Возвращает: <Буфер> | <строка> Открытый ключ ECDiffie-Hellman в указанном encoding и format формате.

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

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

ecdh.setPrivateKey(privateKey[, encoding])

• privateKey <строка> | <ArrayBuffer> | <Буфер> | <Тип массива> | <DataView>
• encoding <строка> Кодировка кодировки строки privateKey.

Устанавливает закрытый ключ ECDiffie-Hellмана. Если encoding задан, privateKey ожидается как строка; в противном случае privateKey ожидается как Buffer, TypedArray или DataView.

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

ecdh.setPublicKey(publicKey[, encoding])

• publicKey <строка> | <ArrayBuffer> | <Буфер> | <TypedArray> | <DataView>
• encoding <строка> Кодировка publicKey строки.

Устанавливает открытый ключ EC Diffie-Hellman. Если encoding предоставлен, publicKey ожидается, что он будет строкой; в противном случае ожидается Buffer, TypedArray, или DataView.

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

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

Модули MJS

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

Модули CJS

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 в качестве потоков:

Модули MJS

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

Модули CJS

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 и потоков с использованием конвейера:

Модули MJS

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

Модули CJS

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

Модули MJS

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

const hash = createHash('sha256');

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

Модули CJS

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 <Объект> stream.transform опции
• Возвращает: <Хэш>

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

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

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

Модули MJS

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

Модули CJS

// 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 <строка> Кодировка возвращаемого значения.
• Возвращает: <Буфер> | <строка>

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

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

hash.update(data[, inputEncoding])

• data <строка> | <Буфер> | <TypedArray> | <DataView>
• inputEncoding <строка> Кодировка 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 в качестве потоков:

MJS модули

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

CJS модули

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

MJS модули

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

CJS модули

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

MJS модули

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

CJS модули

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 <строка> Кодировка возвращаемого значения.
• Возвращает: <Буфер> | <строка>

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

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

hmac.update(data[, inputEncoding])

• data <строка> | <Буфер> | <TypedArray> | <DataView>
• inputEncoding <строка> Кодировка строки 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:

MJS модули

const { webcrypto, KeyObject } = await import('node:crypto');
const { subtle } = webcrypto;

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)

CJS модули

const {
  webcrypto: {
    subtle,
  },
  KeyObject,
} = require('node: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

• <Объект>
  • modulusLength: <число> Размер ключа в битах (RSA, DSA).
  • publicExponent: <bigint> Открытый показатель (RSA).
  • hashAlgorithm: <строка> Название дайджеста сообщения (RSA-PSS).
  • mgf1HashAlgorithm: <строка> Название дайджеста сообщения, используемого MGF1 (RSA-PSS).
  • saltLength: <число> Минимальная длина соли в байтах (RSA-PSS).
  • divisorLength: <число> Размер q в битах (DSA).
  • namedCurve: <строка> Название кривой (EC).

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

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

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

keyObject.asymmetricKeyType

• <строка>

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

• '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: <Объект>
• Возвращает: <строка> | <Буфер> | <Объект>

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

• format: <строка> Должно быть 'buffer' (по умолчанию) или 'jwk'.

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

• type: <строка> Должно быть одним из 'pkcs1' (только RSA) или 'spki'.
• format: <строка> Должно быть 'pem', 'der', или 'jwk'.

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

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

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

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

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

keyObject.equals(otherKeyObject)

• otherKeyObject: <KeyObject> Экземпляр KeyObject для сравнения с keyObject.
• Возвращает: <логическое значение>

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

keyObject.symmetricKeySize

• <число>

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

keyObject.type

• <строка>

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

Класс: Sign

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

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

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

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

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

MJS-модули

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

CJS-модули

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

MJS-модули

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

CJS-модули

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 <Объект> | <строка> | <ArrayBuffer> | <Буфер> | <TypedArray> | <DataView> | <Объект ключа> | <CryptoKey>
  • dsaEncoding <строка>
  • padding <целое число>
  • saltLength <целое число>
• outputEncoding <строка> Кодировка возвращаемого значения.
• Возвращает: <Буфер> | <строка>

Вычисляет подпись для всех прошедших данных, используя либо sign.update(), либо sign.write().

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

• dsaEncoding <строка> Для DSA и ECDSA этот параметр указывает формат сгенерированной подписи. Он может быть одним из следующих:

  • 'der' (по умолчанию): кодировка ASN.1 подписи в формате DER, кодирующая (r, s).
  • 'ieee-p1363': формат подписи r || s, предложенный в IEEE-P1363.

• padding <целое число> Необязательное значение дополнения для 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 <целое число> Длина соли для случаев, когда padding — 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 <строка> | <Буфер> | <TypedArray> | <DataView>
• inputEncoding <строка> Кодировка строки 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 <строка> | <Буфер> | <TypedArray> | <DataView>
• inputEncoding <строка> Кодировка data строки.

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

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

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

• object <Объект> | <строка> | <ArrayBuffer> | <Буфер> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
  • dsaEncoding <строка>
  • padding <целое число>
  • saltLength <целое число>
• signature <строка> | <ArrayBuffer> | <Буфер> | <TypedArray> | <DataView>
• signatureEncoding <строка> Кодировка signature строки.
• Возвращает: <логическое значение> true или false в зависимости от валидности подписи для данных и открытого ключа.

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

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

• dsaEncoding <строка> Для DSA и ECDSA этот параметр определяет формат подписи. Он может быть одним из следующих:

  • 'der' (по умолчанию): DER-кодированная структура ASN.1 подписи, кодирующая (r, s).
  • 'ieee-p1363': Формат подписи r || s как предложено в IEEE-P1363.

• padding <целое число> Дополнительное значение заполнения для 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 <целое число> Длина соли при использовании заполнения 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 и предоставляет чтение только информации о нём.

Модули MJS

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

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

console.log(x509.subject);

Модули CJS

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

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

console.log(x509.subject);

new X509Certificate(buffer)

• buffer <строка> | <TypedArray> | <Buffer> | <DataView> Кодированный в PEM или DER сертификат X509.

x509.ca

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

x509.checkEmail(email[, options])

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

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

Если параметр 'subject' не определён или установлен в 'default', поле subject сертификата учитывается только в том случае, если расширение subject alternative name не существует или не содержит адресов электронной почты.

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

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

x509.checkHost(name[, options])

• name <строка>
• options <Объект>
  • subject <строка> 'default', 'always', или 'never'. По умолчанию: 'default'.
  • wildcards <логическое> По умолчанию: true.
  • partialWildcards <логическое> По умолчанию: true.
  • multiLabelWildcards <логическое> По умолчанию: false.
  • singleLabelSubdomains <логическое> По умолчанию: false.
• Возвращает: <строка> | <неопределённо> Возвращает имя субъекта, которое соответствует name, или undefined, если нет совпадений с name.

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

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

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

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

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

x509.checkIP(ip)

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

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

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

x509.checkIssued(otherCert)

• otherCert <X509Certificate>
• Возвращает: <логическое>

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

x509.checkPrivateKey(privateKey)

• privateKey <Ключ> Приватный ключ.
• Возвращает: <логическое>

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

x509.fingerprint

• Тип: <строка>

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

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

x509.fingerprint256

• Тип: <строка>

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

x509.fingerprint512

• Тип: <строка>

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

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

x509.infoAccess

• Тип: <строка>

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

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

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

x509.issuer

• Тип: <строка>

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

x509.issuerCertificate

• Тип: <X509Certificate>

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

x509.keyUsage

• Тип: <массив строк>

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

x509.publicKey

• Тип: <КлючОбъект>

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

x509.raw

• Тип: <Буфер>

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

x509.serialNumber

• Тип: <строка>

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

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

x509.subject

• Тип: <строка>

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

x509.subjectAltName

• Тип: <строка>

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

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

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

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

x509.toJSON()

• Тип: <строка>

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

x509.toLegacyObject()

• Тип: <Объект>

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

x509.toString()

• Тип: <строка>

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

x509.validFrom

• Тип: <строка>

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

x509.validTo

• Тип: <строка>

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

x509.verify(publicKey)

• publicKey <КлючОбъект> Открытый ключ.
• Возвращает: <булево>

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

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

crypto.constants

• <Объект>

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

crypto.DEFAULT_ENCODING

Кодировка по умолчанию для функций, которые могут принимать либо строки, либо буферы. Значение по умолчанию — 'buffer', что делает методы по умолчанию объектами Buffer.

Механизм crypto.DEFAULT_ENCODING предоставляется для обратной совместимости со старыми программами, которые ожидают, что 'latin1' будет кодировкой по умолчанию.

Новые приложения должны ожидать, что кодировкой по умолчанию будет 'buffer'.

Это свойство устарело.

crypto.fips

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

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

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

• candidate <Массив байтов> | <SharedArrayBuffer> | <Тип массива> | <Буфер> | <DataView> | <BigInt> Возможная простая запись, закодированная как последовательность байтов в формате big-endian произвольной длины.
• options <Объект>
  • checks <число> Количество итераций вероятностной проверки простоты Миллера–Рабина. Когда значение равно 0 (ноль), используется количество проверок, которое обеспечивает вероятность ложноположительного результата не более 2^-64 для случайного входного значения. При выборе количества проверок необходимо проявлять осторожность. Обратитесь к документации OpenSSL для функции BN_is_prime_ex и опций nchecks для получения дополнительных сведений. По умолчанию: 0
• callback <Функция>
  • err <Ошибка> Устанавливается в объект <Ошибка>, если во время проверки произошла ошибка.
  • result <логическое значение> true , если проверяемое значение является простым числом с вероятностью ошибки меньше 0.25 ** options.checks.

Проверяет простоту candidate.

crypto.checkPrimeSync(candidate[, options])

• candidate <Массив байтов> | <SharedArrayBuffer> | <Тип массива> | <Буфер> | <DataView> | <BigInt> Возможная простая запись, закодированная как последовательность байтов в формате big-endian произвольной длины.
• options <Объект>
  • checks <число> Количество итераций вероятностной проверки простоты Миллера–Рабина. Когда значение равно 0 (ноль), используется количество проверок, которое обеспечивает вероятность ложноположительного результата не более 2^-64 для случайного входного значения. При выборе количества проверок необходимо проявлять осторожность. Обратитесь к документации OpenSSL для функции BN_is_prime_ex и опций nchecks для получения дополнительных сведений. По умолчанию: 0
• Возвращает: <логическое значение> true , если проверяемое значение является простым числом с вероятностью ошибки меньше 0.25 ** options.checks.

Проверяет простоту candidate.

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

• algorithm <строка>
• password <строка> | <Массив байтов> | <Буфер> | <Тип массива> | <DataView>
• options <Объект> stream.transform опции
• Возвращает: <Шифр>

Создаёт и возвращает объект 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() и использовать crypto.createCipheriv() для создания объекта Cipher. Пользователи не должны использовать шифры с режимом счётчика (например, CTR, GCM или CCM) в crypto.createCipher(). При их использовании выводится предупреждение, чтобы избежать риска повторного использования IV, который приводит к уязвимостям. В случае повторного использования IV в режиме GCM см. Nonce-Disrespecting Adversaries для получения подробной информации.

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

• algorithm <строка>
• key <строка> | <ArrayBuffer> | <Буфер> | <Массив типизированных данных> | <DataView> | <Объект ключа> | <Криптоключ>
• iv <строка> | <ArrayBuffer> | <Буфер> | <Массив типизированных данных> | <DataView> | <null>
• options <Объект> stream.transform параметры
• Возвращает: <Шифр>

Создаёт и возвращает объект 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', буферами, TypedArray, или DataView. key необязательно может быть KeyObject типа secret. Если шифру не нужен вектор инициализации, то iv может быть null.

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

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

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

• algorithm <строка>
• password <строка> | <ArrayBuffer> | <Буфер> | <Массив типизированных данных> | <DataView>
• options <Объект> stream.transform параметры
• Возвращает: <Расшифровщик>

Создаёт и возвращает объект 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() и использовать crypto.createDecipheriv() для создания объекта Decipher.

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

• algorithm <строка>
• key <строка> | <ArrayBuffer> | <Буфер> | <TypedArray> | <DataView> | <Ключевой объект> | <CryptoKey>
• iv <строка> | <ArrayBuffer> | <Буфер> | <TypedArray> | <DataView> | <null>
• options <Объект> stream.transform параметры
• Возвращает: <Расшифровщик>

Создаёт и возвращает объект 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', буферами, TypedArray, или DataView. key может быть необязательно KeyObject типа secret. Если шифру не нужен вектор инициализации, iv может быть null.

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

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

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

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

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

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

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

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

crypto.createDiffieHellman(primeLength[, generator])

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

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

crypto.createDiffieHellmanGroup(name)

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

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

crypto.createECDH(curveName)

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

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

crypto.createHash(algorithm[, options])

• algorithm <строка>
• options <Объект> stream.transform параметры
• Возвращает: <Хеш>

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

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

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

Модули MJS

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

Модули CJS

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 <строка>
• key <строка> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
• options <объект> stream.transform опции
  • encoding <строка> Кодировка строки, используемая при 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).

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

Модули MJS

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

Модули CJS

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 <объект> | <строка> | <ArrayBuffer> | <Буфер> | <Тип массива> | <DataView>
  • key: <строка> | <ArrayBuffer> | <Буфер> | <Тип массива> | <DataView> | <объект> Материализованный ключ в формате PEM, DER или JWK.
  • format: <строка> Должно быть 'pem', 'der', или ''jwk'. По умолчанию: 'pem'.
  • type: <строка> Должно быть 'pkcs1', 'pkcs8', или 'sec1'. Эта опция требуется только, если format — 'der', в противном случае она игнорируется.
  • passphrase: <строка> | <Буфер> Пароль для дешифрования.
  • encoding: <строка> Кодировка строки, используемая при key, если это строка.
• Возвращает: <Объект ключа>

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

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

crypto.createPublicKey(key)

• key <объект> | <строка> | <ArrayBuffer> | <Буфер> | <Тип массива> | <DataView>
  • key: <строка> | <ArrayBuffer> | <Буфер> | <Тип массива> | <DataView> | <объект> Материализованный ключ в формате PEM, DER или JWK.
  • format: <строка> Должно быть 'pem', 'der', или 'jwk'. По умолчанию: 'pem'.
  • type: <строка> Должно быть 'pkcs1' или 'spki'. Эта опция требуется только, если format — 'der', в противном случае она игнорируется.
  • encoding <строка> Кодировка строки, используемая при key, если это строка.
• Возвращает: <Объект ключа>

Создаёт и возвращает новый объект ключа, содержащий открытый ключ. Если 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 <строка> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• encoding <строка> Кодировка строки, когда key — строка.
• Возвращает: <KeyObject>

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

crypto.createSign(algorithm[, options])

• algorithm <строка>
• options <Объект> stream.Writable параметры
• Возвращает: <Sign>

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

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

crypto.createVerify(algorithm[, options])

• algorithm <строка>
• options <Объект> stream.Writable параметры
• Возвращает: <Verify>

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

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

crypto.diffieHellman(options)

• options: <Объект>
  • privateKey: <KeyObject>
  • publicKey: <KeyObject>
• Возвращает: <Буфер>

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

crypto.generateKey(type, options, callback)

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

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

MJS модули

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

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

CJS модули

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> Имя группы Diffie-Hellman (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' с шифрованием для долгосрочного хранения:

МОДУЛИ MJS

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

МОДУЛИ CJS

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> Имя группы Diffie-Hellman (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' со сильным паролем и сохранять его в секрете.

Модули MJS

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

Модули CJS

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

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

Модули MJS

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

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

Модули CJS

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 <число> Размер (в битах) генерируемого простого числа.
• options <Объект>
  • add <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Буфер> | <DataView> | <bigint>
  • rem <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Буфер> | <DataView> | <bigint>
  • safe <булево> По умолчанию: false.
  • bigint <булево> Если true, сгенерированное простое число возвращается как bigint.
• callback <Функция>
  • err <Ошибка>
  • prime <ArrayBuffer> | <bigint>

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

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

Параметры options.add и options.rem могут использоваться для обеспечения дополнительных требований, например, для Diffie-Hellman:

• Если 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 должны быть закодированы как последовательности в формате big-endian, если заданы как ArrayBuffer, SharedArrayBuffer, TypedArray, Buffer, или DataView.

По умолчанию, простое число кодируется как последовательность байтов в формате big-endian в <ArrayBuffer>. Если опция bigint имеет значение true, то предоставляется <bigint>.

crypto.generatePrimeSync(size[, options])

• size <число> Размер (в битах) генерируемого простого числа.
• options <Объект>
  • add <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Буфер> | <DataView> | <bigint>
  • rem <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Буфер> | <DataView> | <bigint>
  • safe <булево> По умолчанию: false.
  • bigint <булево> Если true, сгенерированное простое число возвращается как bigint.
• Возвращает: <ArrayBuffer> | <bigint>

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

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

Параметры options.add и options.rem могут использоваться для обеспечения дополнительных требований, например, для Diffie-Hellman:

• Если 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 должны быть закодированы как последовательности big-endian, если они заданы как ArrayBuffer, SharedArrayBuffer, TypedArray, Buffer или DataView.

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

crypto.getCipherInfo(nameOrNid[, options])

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

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

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

crypto.getCiphers()

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

MJS модули

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

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

CJS модули

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

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

crypto.getCurves()

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

MJS модули

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

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

CJS модули

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

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

crypto.getDiffieHellman(groupName)

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

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

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

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

MJS модули

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

CJS модули

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

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

crypto.getHashes()

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

MJS модули

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

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

CJS модули

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

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

crypto.getRandomValues(typedArray)

• typedArray <Буфер> | <Тип массива> | <DataView> | <ArrayBuffer>
• Возвращает: <Буфер> | <Тип массива> | <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>. Будет выброшено исключение, если любой из входных аргументов указывает неверные значения или типы.

Модули MJS

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

Модули CJS

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

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

Модули MJS

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'

Модули CJS

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 <строка> | <ArrayBuffer> | <Буфер> | <TypedArray> | <DataView>
• salt <строка> | <ArrayBuffer> | <Буфер> | <TypedArray> | <DataView>
• iterations <число>
• keylen <число>
• digest <строка>
• callback <Функция>
  • err <Ошибка>
  • derivedKey <Буфер>

Предоставляет асинхронную реализацию функции вывода ключа на основе пароля 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.

Модули MJS

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

Модули CJS

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 <строка> | <Буфер> | <TypedArray> | <DataView>
• salt <строка> | <Буфер> | <TypedArray> | <DataView>
• iterations <число>
• keylen <число>
• digest <строка>
• Возвращает: <Буфер>

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

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

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

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

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

Модули MJS

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

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

Модули CJS

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 <Объект> | <строка> | <ArrayBuffer> | <Буфер> | <TypedArray> | <DataView> | <Ключевой объект> | <Криптоключ>
  • oaepHash <строка> Функция хэширования, используемая для заполнения OAEP и MGF1. По умолчанию: 'sha1'
  • oaepLabel <строка> | <ArrayBuffer> | <Буфер> | <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 <строка> | <ArrayBuffer> | <Буфер> | <TypedArray> | <DataView>
• Возвращает: <Буфер> Новый Buffer с дешифрованным содержимым.

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

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

crypto.privateEncrypt(privateKey, buffer)

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

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

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

crypto.publicDecrypt(key, buffer)

• key <Объект> | <строка> | <ArrayBuffer> | <Буфер> | <TypedArray> | <DataView> | <Объект_ключа> | <Криптоключ>
  • passphrase <строка> | <ArrayBuffer> | <Буфер> | <TypedArray> | <DataView> Необязательный пароль для закрытого ключа.
  • padding <crypto.constants> Необязательное значение заполнения, определенное в crypto.constants, которое может быть: crypto.constants.RSA_NO_PADDING или crypto.constants.RSA_PKCS1_PADDING.
  • encoding <строка> Кодировка строк, используемая при buffer, key, или passphrase являются строками.
• buffer <строка> | <ArrayBuffer> | <Буфер> | <TypedArray> | <DataView>
• Возвращает: <Буфер> Новый Buffer с расшифрованным содержимым.

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

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

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

crypto.publicEncrypt(key, buffer)

• key <Объект> | <строка> | <ArrayBuffer> | <Буфер> | <TypedArray> | <DataView> | <Объект_ключа> | <Криптоключ>
  • key <строка> | <ArrayBuffer> | <Буфер> | <TypedArray> | <DataView> | <Объект_ключа> | <Криптоключ> PEM-кодированный открытый или закрытый ключ, <Объект_ключа> или <Криптоключ>.
  • oaepHash <строка> Функция хэширования, используемая для заполнения OAEP и MGF1. По умолчанию: 'sha1'
  • oaepLabel <строка> | <ArrayBuffer> | <Буфер> | <TypedArray> | <DataView> Метка для использования в заполнении OAEP. Если не указана, метка не используется.
  • passphrase <строка> | <ArrayBuffer> | <Буфер> | <TypedArray> | <DataView> Необязательный пароль для закрытого ключа.
  • padding <crypto.constants> Необязательное значение заполнения, определенное в crypto.constants, которое может быть: crypto.constants.RSA_NO_PADDING, crypto.constants.RSA_PKCS1_PADDING, или crypto.constants.RSA_PKCS1_OAEP_PADDING.
  • encoding <строка> Кодировка строк, используемая при buffer, key, oaepLabel, или passphrase являются строками.
• buffer <строка> | <ArrayBuffer> | <Буфер> | <TypedArray> | <DataView>
• Возвращает: <Буфер> Новый 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 <Функция>
  • err <Ошибка>
  • buf <Буфер>
• Возвращает: <Буфер>, если функция callback не предоставлена.

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

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

Модули MJS

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

Модули CJS

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

Модули MJS

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

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

Модули CJS

// 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> | <Буфер> | <Тип данных> | <DataView> Должен быть предоставлен. Размер переданного buffer не должен превышать 2**31 - 1.
• offset <Число> По умолчанию: 0
• size <Число> По умолчанию: buffer.length - offset. Значение size не должно превышать 2**31 - 1.
• Возвращает: <ArrayBuffer> | <Буфер> | <Тип данных> | <DataView> Объект, переданный в качестве аргумента buffer.

Синхронная версия crypto.randomFill().

Модули MJS

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

Модули CJS

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

В качестве ArrayBuffer могут быть переданы экземпляры TypedArray или DataView.

Модули MJS

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

Модули CJS

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> | <Буфер> | <Тип данных> | <DataView> Должен быть предоставлен. Размер переданного buffer не должен превышать 2**31 - 1.
• offset <Число> По умолчанию: 0
• size <Число> По умолчанию: buffer.length - offset. Значение size не должно превышать 2**31 - 1.
• callback <Функция> function(err, buf) {}.

Эта функция похожа на crypto.randomBytes(), но требует в качестве первого аргумента Buffer, который будет заполнен. Также требуется передать обратный вызов.

Если функция callback не предоставлена, будет выброшено исключение.

Модули MJS

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

Модули CJS

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

В качестве ArrayBuffer могут быть переданы экземпляры TypedArray или DataView.

Хотя это включает экземпляры Float32Array и Float64Array, эту функцию не следует использовать для генерации случайных чисел с плавающей запятой. Результат может содержать +Infinity, -Infinity, и NaN, и даже если массив содержит только конечные числа, они не взяты из равномерного распределения и не имеют осмысленных нижних или верхних границ.

Модули MJS

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

Модули CJS

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 <целое> Начало диапазона случайных чисел (включительно). По умолчанию: 0.
• max <целое> Конец диапазона случайных чисел (исключительно).
• callback <Функция> function(err, n) {}.

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

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

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

Модули MJS

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

Модули CJS

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

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

Модули MJS

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

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

Модули CJS

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

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

Модули MJS

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

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

Модули CJS

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

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

crypto.randomUUID([options])

• options <Объект>
  • disableEntropyCache <логическое> По умолчанию, для повышения производительности, Node.js генерирует и кэширует достаточно случайных данных для генерации до 128 случайных UUID. Чтобы сгенерировать UUID без использования кэша, установите disableEntropyCache в true. По умолчанию: false.
• Возвращает: <строка>

Генерирует случайный UUID версии 4 по RFC 4122. UUID генерируется с использованием криптографического псевдослучайного генератора.

crypto.scrypt(password, salt, keylen[, options], callback)

• password <строка> | <ArrayBuffer> | <Буфер> | <TypedArray> | <DataView>
• salt <строка> | <ArrayBuffer> | <Буфер> | <TypedArray> | <DataView>
• keylen <число>
• options <Объект>
  • cost <число> Параметр стоимости ЦП/памяти. Должен быть степенью двойки, большей единицы. По умолчанию: 16384.
  • blockSize <число> Параметр размера блока. По умолчанию: 8.
  • parallelization <число> Параметр распараллеливания. По умолчанию: 1.
  • N <число> Псевдоним для cost. Может быть указан только один из них.
  • r <число> Псевдоним для blockSize. Может быть указан только один из них.
  • p <число> Псевдоним для parallelization. Может быть указан только один из них.
  • maxmem <число> Верхняя граница памяти. Ошибка, если (приблизительно) 128 * N * r > maxmem. По умолчанию: 32 * 1024 * 1024.
• callback <Функция>
  • err <Ошибка>
  • derivedKey <Буфер>

Обеспечивает асинхронную реализацию scrypt. Scrypt — это функция вывода ключа на основе пароля, разработанная для вычислительно и по памяти дорогостоящих операций, чтобы сделать атаки методом перебора нецелесообразными.

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

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

Функция callback вызывается с двумя аргументами: err и derivedKey.

err — объект исключения при сбое вывода ключа, в противном случае err — null.

derivedKey передаётся в обратный вызов в качестве Buffer.

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

Модули MJS

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

Модули CJS

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 <строка> | <Буфер> | <TypedArray> | <DataView>
• salt <строка> | <Буфер> | <TypedArray> | <DataView>
• keylen <число>
• options <Объект>
  • cost <число> Параметр стоимости ЦП/памяти. Должен быть степенью двойки, большей единицы. По умолчанию: 16384.
  • blockSize <число> Параметр размера блока. По умолчанию: 8.
  • parallelization <число> Параметр распараллеливания. По умолчанию: 1.
  • N <число> Псевдоним для cost. Может быть указан только один из них.
  • r <число> Псевдоним для blockSize. Может быть указан только один из них.
  • p <число> Псевдоним для parallelization. Может быть указан только один из них.
  • maxmem <число> Верхняя граница памяти. Ошибка, если (приблизительно) 128 * N * r > maxmem. По умолчанию: 32 * 1024 * 1024.
• Возвращает: <Буфер>

Обеспечивает синхронную реализацию scrypt. Scrypt — это функция вывода ключа на основе пароля, разработанная для вычислительно и по памяти дорогостоящих операций, чтобы сделать атаки методом перебора нецелесообразными.

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

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

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

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

Модули MJS

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'

Модули CJS

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

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

crypto.setEngine(engine[, flags])

• engine <строка>
• flags <crypto.constants> По умолчанию: crypto.constants.ENGINE_METHOD_ALL

Загрузка и установка engine для некоторых или всех функций OpenSSL (выбираемых по флагам).

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 <логическое> true для включения режима FIPS.

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

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

• algorithm <строка> | <null> | <undefined>
• data <ArrayBuffer> | <Буфер> | <Тип_массива> | <DataView>
• key <Объект> | <строка> | <ArrayBuffer> | <Буфер> | <Тип_массива> | <DataView> | <Объект_ключа> | <CryptoKey>
• callback <Функция>
  • err <Ошибка>
  • signature <Буфер>
• Возвращает: <Буфер>, если функция callback не предоставлена.

Вычисляет и возвращает подпись для data с использованием заданного закрытого ключа и алгоритма. Если algorithm равно null или undefined, то алгоритм зависит от типа ключа (особенно Ed25519 и Ed448).

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

• dsaEncoding <строка> Для DSA и ECDSA этот параметр определяет формат сгенерированной подписи. Он может быть одним из следующих:

  • 'der' (по умолчанию): кодировка подписи ASN.1 в формате DER, кодирующая (r, s).
  • 'ieee-p1363': Формат подписи r || s как предложено в IEEE-P1363.

• padding <целое> Необязательное значение заполнения для RSA, одно из следующих:

  • crypto.constants.RSA_PKCS1_PADDING (по умолчанию)
  • crypto.constants.RSA_PKCS1_PSS_PADDING

  RSA_PKCS1_PSS_PADDING будет использовать MGF1 с той же функцией хэширования, которая используется для подписи сообщения, как указано в разделе 3.1 RFC 4055.

• saltLength <целое> Длина соли для случая, когда заполнение 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> | <Буфер> | <Тип_массива> | <DataView>
• b <ArrayBuffer> | <Буфер> | <Тип_массива> | <DataView>
• Возвращает: <логическое>

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

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

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 <строка> | <null> | <undefined>
• data <ArrayBuffer> | <Буфер> | <Массив значений> | <DataView>
• key <Объект> | <строка> | <ArrayBuffer> | <Буфер> | <Массив значений> | <DataView> | <Объект ключа> | <CryptoKey>
• signature <ArrayBuffer> | <Буфер> | <Массив значений> | <DataView>
• callback <Функция>
  • err <Ошибка>
  • result <булево>
• Возвращает: <булево> true или false в зависимости от валидности подписи для данных и открытого ключа, если функция callback не предоставлена.

Проверяет заданную подпись для data с использованием заданного ключа и алгоритма. Если algorithm — null или undefined, алгоритм зависит от типа ключа (особенно Ed25519 и Ed448).

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

• dsaEncoding <строка> Для DSA и ECDSA этот параметр определяет формат подписи. Он может быть одним из следующих:

  • 'der' (по умолчанию): DER-кодированная структура ASN.1, кодирующая (r, s).
  • 'ieee-p1363': Формат подписи r || s , предложенный в IEEE-P1363.

• padding <целое> Необязательное значение заполнения для RSA, одно из следующих:

  • crypto.constants.RSA_PKCS1_PADDING (по умолчанию)
  • crypto.constants.RSA_PKCS1_PSS_PADDING

  RSA_PKCS1_PSS_PADDING будет использовать MGF1 с той же функцией хэширования, которая использовалась для подписи сообщения, как указано в разделе 3.1 RFC 4055.

• saltLength <целое> Длина соли для случая, когда padding — 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, подпоследовательности, которые не представляют собой допустимые кодовые точки, могут быть заменены символом замены Юникода (U+FFFD). Поэтому байтовое представление результирующей строки Юникода может не совпадать с последовательностью байтов, из которой она была создана.

  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

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

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

Модули MJS

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

Модули CJS

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 вам потребуется:

• Правильно установленный поставщик OpenSSL 3 FIPS.
• Файл конфигурации модуля OpenSSL 3 FIPS .
• Файл конфигурации OpenSSL 3, который ссылается на файл конфигурации модуля FIPS.

Node.js потребуется настроить с файлом конфигурации OpenSSL, который указывает на поставщика FIPS. Пример файла конфигурации выглядит следующим образом:

nodejs_conf = nodejs_init

.include /<absolute path>/fipsmodule.cnf

[nodejs_init]
providers = provider_sect

[provider_sect]
default = default_sect
# The fips section name should match the section name inside the
# included fipsmodule.cnf.
fips = fips_sect

[default_sect]
activate = 1 copy

где fipsmodule.cnf является файлом конфигурации модуля FIPS, сгенерированным на этапе установки поставщика FIPS:

openssl fipsinstall copy

Установите переменную среды OPENSSL_CONF для указания вашего файла конфигурации и OPENSSL_MODULES для указания расположения динамической библиотеки поставщика FIPS. Например:

export OPENSSL_CONF=/<path to configuration file>/nodejs.cnf
export OPENSSL_MODULES=/<path to openssl lib>/ossl-modules copy

Режим FIPS затем можно включить в Node.js следующим образом:

• Запуск Node.js с флагами командной строки --enable-fips или --force-fips.
• Программный вызов crypto.setFips(true).

По желанию режим FIPS можно включить в Node.js через файл конфигурации OpenSSL. Например:

nodejs_conf = nodejs_init

.include /<absolute path>/fipsmodule.cnf

[nodejs_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
default = default_sect
# The fips section name should match the section name inside the
# included fipsmodule.cnf.
fips = fips_sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes copy

Постоянные значения криптографии

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

Параметры OpenSSL

Для получения подробной информации см. список флагов SSL OP.

Постоянные значения движка OpenSSL

Другие постоянные значения OpenSSL

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