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

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

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

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

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

Модули 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> | <Буфер> | <Массив типизированных значений> | <DataView>
• encoding <строка> Кодировка строки spkac.
• Возвращает: <логическое значение> 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() для получения зашифрованных данных.

Метод crypto.createCipheriv() используется для создания экземпляров Cipher. Объекты 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 и потоков piped:

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

При использовании режима аутентифицированного шифрования (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 автоматически добавит заполнение к входным данным до соответствующего размера блока. Для отключения стандартного заполнения вызовите cipher.setAutoPadding(false).

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

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

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

• data <строка> | <Буфер> | <TypedArray> | <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.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 и конвейерных потоков:

Модули 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> Тот же объект 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> Тот же объект 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 для цепочки методов.

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

Преобразует открытый ключ ECDH, указанный 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> | <Буфер> | <TypedArray> | <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'
• Возвращает: <Буфер> | <строка>

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

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

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

ecdh.getPrivateKey([encoding])

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

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

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

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

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

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

ecdh.setPrivateKey(privateKey[, encoding])

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

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

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

ecdh.setPublicKey(publicKey[, encoding])

• publicKey <строка> | <ArrayBuffer> | <Буфер> | <Массив с типом> | <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 <строка> | <Буфер> | <Массив с типом> | <DataView>
• inputEncoding <строка> Кодировка data строки.

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

Можно вызывать многократно с новыми данными по мере их потоковой передачи.

Класс: Hmac

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

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

• В качестве потока (stream), который одновременно читается и записывается, где данные записываются для вычисления дайджеста 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 <строка> | <Буфер> | <Массив типов> | <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 { KeyObject } = await import('node:crypto');
const { subtle } = globalThis.crypto;

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

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

CJS-модули

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

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

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

keyObject.asymmetricKeyDetails

• <Объект>
  • 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. Аргументом является строковое имя функции хэширования, которую следует использовать. Экземпляры new не должны создаваться напрямую с помощью ключевого слова 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' (по умолчанию): 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_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 — это утилита для проверки подписей. Его можно использовать двумя способами:

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

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

См. Sign для примеров.

verify.update(data[, inputEncoding])

• data <строка> | <Буфер> | <Массив типов> | <DataView>
• inputEncoding <строка> Кодировка строки data.

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

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

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

• object <Объект> | <строка> | <ArrayBuffer> | <Буфер> | <Массив типов> | <DataView> | <Объект ключа> | <Криптоключ>
  • dsaEncoding <строка>
  • padding <целое>
  • saltLength <целое>
• signature <строка> | <ArrayBuffer> | <Буфер> | <Массив типов> | <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> | <Буфер> | <DataView> Кодированный в PEM или DER сертификат X509.

x509.ca

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

x509.checkEmail(email[, options])

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

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

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

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

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

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', тема сертификата рассматривается только в том случае, если расширение альтернативного имени темы не существует или не содержит имён DNS. Это поведение соответствует RFC 2818 ("HTTP Over TLS").

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

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

x509.checkIP(ip)

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

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

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

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

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

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

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

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

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

x509.toString()

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

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

x509.validFrom

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

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

x509.validTo

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

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

x509.verify(publicKey)

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

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

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

crypto.constants

• <Объект>

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

crypto.fips

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

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

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

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

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

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

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

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

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

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

crypto.createSecretKey(key[, encoding])

• key <строка> | <ArrayBuffer> | <Буфер> | <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.hash(algorithm, data[, outputEncoding])

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

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

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

Пример:

Модули CJS

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

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

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

Модули MJS

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

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

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

crypto.generateKey(type, options, callback)

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

Асинхронно генерирует новый случайный секретный ключ заданной length. 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: <строка> Должно быть 'rsa', 'rsa-pss', 'dsa', 'ec', 'ed25519', 'ed448', 'x25519', 'x448', или 'dh'.
• options: <Объект>
  • modulusLength: <число> Размер ключа в битах (RSA, DSA).
  • publicExponent: <число> Открытый показатель (RSA). По умолчанию: 0x10001.
  • hashAlgorithm: <строка> Название дайджеста сообщения (RSA-PSS).
  • mgf1HashAlgorithm: <строка> Название дайджеста сообщения, используемого MGF1 (RSA-PSS).
  • saltLength: <число> Минимальная длина соли в байтах (RSA-PSS).
  • divisorLength: <число> Размер q в битах (DSA).
  • namedCurve: <строка> Название кривой для использования (EC).
  • prime: <Буфер> Простой параметр (DH).
  • primeLength: <число> Длина простого числа в битах (DH).
  • generator: <число> Пользовательский генератор (DH). По умолчанию: 2.
  • groupName: <строка> Название группы Diffie-Hellman (DH). См. crypto.getDiffieHellman().
  • paramEncoding: <строка> Должно быть 'named' или 'explicit' (EC). По умолчанию: 'named'.
  • publicKeyEncoding: <Объект> См. keyObject.export().
  • privateKeyEncoding: <Объект> См. keyObject.export().
• callback: <Функция>
  • err: <Ошибка>
  • publicKey: <строка> | <Буфер> | <Объект ключа>
  • privateKey: <строка> | <Буфер> | <Объект ключа>

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

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

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

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

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

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

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

Оба options.add и options.rem должны быть закодированы как последовательности big-endian, если они заданы в виде ArrayBuffer, SharedArrayBuffer, TypedArray, Buffer или DataView.

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

crypto.generatePrimeSync(size[, options])

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

Создаёт объект для обмена ключами Diffie-Hellman с предварительно заданным значением. Поддерживаемые группы перечислены в документации для 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 в противном случае. В будущей версии с изменением основного номера версии тип возвращаемого значения этого API может быть изменен на <логическое значение>.

crypto.getHashes()

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

Модули 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 <строка> Алгоритм хеширования для использования.
• ikm <строка> | <ArrayBuffer> | <Буфер> | <Тип данных> | <DataView> | <Объект ключа> Входные данные ключа. Должны быть предоставлены, но могут быть нулевой длины.
• salt <строка> | <ArrayBuffer> | <Буфер> | <Тип данных> | <DataView> Значение соли. Должно быть предоставлено, но может быть нулевой длины.
• info <строка> | <ArrayBuffer> | <Буфер> | <Тип данных> | <DataView> Дополнительное значение информации. Должно быть предоставлено, но может быть нулевой длины и не может быть больше 1024 байт.
• keylen <число> Длина генерируемого ключа. Должно быть больше 0. Максимально допустимое значение равно 255 умноженному на количество байт, производимых выбранной функцией хеширования (например, sha512 генерирует хеши длиной 64 байта, что делает максимальный вывод HKDF равным 16320 байтам).
• callback <Функция>
  • err <Ошибка>
  • 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 <строка> Алгоритм хеширования для использования.
• ikm <строка> | <ArrayBuffer> | <Буфер> | <Тип данных> | <DataView> | <Объект ключа> Входные данные ключа. Должны быть предоставлены, но могут быть нулевой длины.
• salt <строка> | <ArrayBuffer> | <Буфер> | <Тип данных> | <DataView> Значение соли. Должно быть предоставлено, но может быть нулевой длины.
• info <строка> | <ArrayBuffer> | <Буфер> | <Тип данных> | <DataView> Дополнительное значение информации. Должно быть предоставлено, но может быть нулевой длины и не может быть больше 1024 байт.
• keylen <число> Длина генерируемого ключа. Должно быть больше 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 <Буфер>

Предоставляет асинхронную реализацию функции вывода пароля PBKDF2 (Password-Based Key Derivation Function 2). Выбранный алгоритм 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 <строка>
• Возвращает: <Буфер>

Предоставляет синхронную реализацию функции вывода пароля PBKDF2 (Password-Based Key Derivation Function 2). Выбранный алгоритм 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> | <Объект ключа> | <CryptoKey>
  • 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.constants.RSA_PKCS1_PADDING в crypto.privateDecrypt() требует, чтобы OpenSSL поддерживал неявное отклонение (rsa_pkcs1_implicit_rejection). Если версия OpenSSL, используемая Node.js, не поддерживает эту функцию, попытка использовать RSA_PKCS1_PADDING завершится ошибкой.

crypto.privateEncrypt(privateKey, buffer)

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

В качестве аргумента buffer можно передать любой экземпляр 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> | <Буфер> | <Массив типов данных> | <Представление данных> Должен быть предоставлен. Размер предоставленного 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'));
});

В качестве аргумента buffer можно передать любой экземпляр 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 <boolean> По умолчанию, для повышения производительности, 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 <число> Параметр затрат CPU/памяти. Должно быть степенью двойки, большей единицы. По умолчанию: 16384.
  • blockSize <число> Параметр размера блока. По умолчанию: 8.
  • parallelization <число> Параметр распараллеливания. По умолчанию: 1.
  • N <число> Псевдоним для cost. Может быть указан только один из двух.
  • r <число> Псевдоним для blockSize. Может быть указан только один из двух.
  • p <число> Верхняя граница памяти. Возникает ошибка, когда (приблизительно) 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 <число> Параметр затрат CPU/памяти. Должно быть степенью двойки, большей единицы. По умолчанию: 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' (по умолчанию): кодировка 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 <целое> Длина соли для случая, когда заполнение — 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 или Float64Arrays, эта функция может возвращать неожиданные результаты из-за кодирования чисел с плавающей точкой в соответствии со стандартом IEEE 754. В частности, ни x === y ни Object.is(x, y) не подразумевает, что байтовые представления двух чисел с плавающей точкой x и y равны.

Использование crypto.timingSafeEqual не гарантирует, что окружающий код является безопасным по времени. Следует быть внимательным, чтобы убедиться, что окружающий код не вводит уязвимости, связанные с временем.

crypto.verify(algorithm, data, key, signature[, callback])

• algorithm <строка> | <null> | <undefined>
• data <ArrayBuffer> | <Буфер> | <TypedArray> | <DataView>
• key <Объект> | <строка> | <ArrayBuffer> | <Буфер> | <TypedArray> | <DataView> | <Объект ключа> | <CryptoKey>
• signature <ArrayBuffer> | <Буфер> | <TypedArray> | <DataView>
• callback <Функция>
  • err <Ошибка>
  • result <boolean>
• Возвращает: <boolean> 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 <целое число> Длина соли для заполнения 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 потоков streams (например, 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 вам потребуется:

• Правильно установленный провайдер FIPS OpenSSL 3.
• Файл конфигурации модуля FIPS OpenSSL 3 FIPS module configuration file.
• Файл конфигурации 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