Spec-Zone.ru › Node.js 24 LTS

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

Стабильность: 2 - Стабильный

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

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

Модули JavaScript
const { createHmac } = await import('node:crypto');

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

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

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

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

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

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

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

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

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

Типы асимметричных ключей

В следующей таблице перечислены типы асимметричных ключей, распознаваемые API KeyObject:

Тип ключа Описание OID
'dh' Диффи — Хеллман 1.2.840.113549.1.3.1
'dsa' DSA 1.2.840.10040.4.1
'ec' Эллиптическая кривая 1.2.840.10045.2.1
'ed25519' Ed25519 1.3.101.112
'ed448' Ed448 1.3.101.113
'ml-dsa-44'1 ML-DSA-44 2.16.840.1.101.3.4.3.17
'ml-dsa-65'1 ML-DSA-65 2.16.840.1.101.3.4.3.18
'ml-dsa-87'1 ML-DSA-87 2.16.840.1.101.3.4.3.19
'ml-kem-512'1 ML-KEM-512 2.16.840.1.101.3.4.4.1
'ml-kem-768'1 ML-KEM-768 2.16.840.1.101.3.4.4.2
'ml-kem-1024'1 ML-KEM-1024 2.16.840.1.101.3.4.4.3
'rsa-pss' RSA PSS 1.2.840.113549.1.1.10
'rsa' RSA 1.2.840.113549.1.1.1
'slh-dsa-sha2-128f'1 SLH-DSA-SHA2-128f 2.16.840.1.101.3.4.3.21
'slh-dsa-sha2-128s'1 SLH-DSA-SHA2-128s 2.16.840.1.101.3.4.3.20
'slh-dsa-sha2-192f'1 SLH-DSA-SHA2-192f 2.16.840.1.101.3.4.3.23
'slh-dsa-sha2-192s'1 SLH-DSA-SHA2-192s 2.16.840.1.101.3.4.3.22
'slh-dsa-sha2-256f'1 SLH-DSA-SHA2-256f 2.16.840.1.101.3.4.3.25
'slh-dsa-sha2-256s'1 SLH-DSA-SHA2-256s 2.16.840.1.101.3.4.3.24
'slh-dsa-shake-128f'1 SLH-DSA-SHAKE-128f 2.16.840.1.101.3.4.3.27
'slh-dsa-shake-128s'1 SLH-DSA-SHAKE-128s 2.16.840.1.101.3.4.3.26
'slh-dsa-shake-192f'1 SLH-DSA-SHAKE-192f 2.16.840.1.101.3.4.3.29
'slh-dsa-shake-192s'1 SLH-DSA-SHAKE-192s 2.16.840.1.101.3.4.3.28
'slh-dsa-shake-256f'1 SLH-DSA-SHAKE-256f 2.16.840.1.101.3.4.3.31
'slh-dsa-shake-256s'1 SLH-DSA-SHAKE-256s 2.16.840.1.101.3.4.3.30
'x25519' X25519 1.3.101.110
'x448' X448 1.3.101.111

Класс: Certificate

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

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

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

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

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

История
Версия Изменения
v15.0.0

Аргумент spkac может иметь тип ArrayBuffer. Размер аргумента spkac ограничен максимумом в 2**31 - 1 байт.
v9.0.0

Добавлено в: v9.0.0
  • spkac <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
  • encoding <string> Кодировка строки spkac.
  • Возвращает: <Buffer> Компонент challenge структуры данных spkac, которая включает открытый ключ и challenge.
Модули JavaScript
const { Certificate } = await import('node:crypto');
const spkac = getSpkacSomehow();
const challenge = Certificate.exportChallenge(spkac);
console.log(challenge.toString('utf8'));
// Prints: the challenge as a UTF8 string
CommonJS
const { Certificate } = require('node:crypto');
const spkac = getSpkacSomehow();
const challenge = Certificate.exportChallenge(spkac);
console.log(challenge.toString('utf8'));
// Prints: the challenge as a UTF8 string

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

История
Версия Изменения
v15.0.0

Аргумент spkac может иметь тип ArrayBuffer. Размер аргумента spkac ограничен максимумом в 2**31 - 1 байт.
v9.0.0

Добавлено в: v9.0.0
  • spkac <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
  • encoding <string> Кодировка строки spkac.
  • Возвращает: <Buffer> Компонент открытого ключа структуры данных spkac, которая включает открытый ключ и challenge.
Модули JavaScript
const { Certificate } = await import('node:crypto');
const spkac = getSpkacSomehow();
const publicKey = Certificate.exportPublicKey(spkac);
console.log(publicKey);
// Prints: the public key as <Buffer ...>
CommonJS
const { Certificate } = require('node:crypto');
const spkac = getSpkacSomehow();
const publicKey = Certificate.exportPublicKey(spkac);
console.log(publicKey);
// Prints: the public key as <Buffer ...>

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

История
Версия Изменения
v15.0.0

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

Добавлено в: v9.0.0
  • spkac <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
  • encoding <string> Кодировка строки spkac.
  • Возвращает: <boolean> true, если указанная структура данных spkac действительна, и false в противном случае.
Модули JavaScript
import { Buffer } from 'node:buffer';
const { Certificate } = await import('node:crypto');

const spkac = getSpkacSomehow();
console.log(Certificate.verifySpkac(Buffer.from(spkac)));
// Prints: true or false
CommonJS
const { Buffer } = require('node:buffer');
const { Certificate } = require('node:crypto');

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

Устаревший API

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

Для обеспечения совместимости со старым интерфейсом можно создавать экземпляры класса crypto.Certificate, как показано в примерах ниже.

new crypto.Certificate()

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

Модули JavaScript
const { Certificate } = await import('node:crypto');

const cert1 = new Certificate();
const cert2 = Certificate();
CommonJS
const { Certificate } = require('node:crypto');

const cert1 = new Certificate();
const cert2 = Certificate();
certificate.exportChallenge(spkac[, encoding])
Добавлено в: v0.11.8
  • spkac <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
  • encoding <string> Кодировка строки spkac.
  • Возвращает: <Buffer> Компонент challenge структуры данных spkac, которая включает открытый ключ и challenge.
Модули JavaScript
const { Certificate } = await import('node:crypto');
const cert = Certificate();
const spkac = getSpkacSomehow();
const challenge = cert.exportChallenge(spkac);
console.log(challenge.toString('utf8'));
// Prints: the challenge as a UTF8 string
CommonJS
const { Certificate } = require('node:crypto');
const cert = Certificate();
const spkac = getSpkacSomehow();
const challenge = cert.exportChallenge(spkac);
console.log(challenge.toString('utf8'));
// Prints: the challenge as a UTF8 string
certificate.exportPublicKey(spkac[, encoding])
Добавлено в: v0.11.8
  • spkac <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
  • encoding <string> Кодировка строки spkac.
  • Возвращает: <Buffer> Компонент открытого ключа структуры данных spkac, которая включает открытый ключ и challenge.
Модули JavaScript
const { Certificate } = await import('node:crypto');
const cert = Certificate();
const spkac = getSpkacSomehow();
const publicKey = cert.exportPublicKey(spkac);
console.log(publicKey);
// Prints: the public key as <Buffer ...>
CommonJS
const { Certificate } = require('node:crypto');
const cert = Certificate();
const spkac = getSpkacSomehow();
const publicKey = cert.exportPublicKey(spkac);
console.log(publicKey);
// Prints: the public key as <Buffer ...>
certificate.verifySpkac(spkac[, encoding])
Добавлено в: v0.11.8
  • spkac <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
  • encoding <string> Кодировка строки spkac.
  • Возвращает: <boolean> true, если указанная структура данных spkac действительна, и false в противном случае.
Модули JavaScript
import { Buffer } from 'node:buffer';
const { Certificate } = await import('node:crypto');

const cert = Certificate();
const spkac = getSpkacSomehow();
console.log(cert.verifySpkac(Buffer.from(spkac)));
// Prints: true or false
CommonJS
const { Buffer } = require('node:buffer');
const { Certificate } = require('node:crypto');

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

Класс: Cipheriv

Добавлено в: v0.1.94
  • Расширяет: <stream.Transform>

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

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

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

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

Модули JavaScript
const {
  scrypt,
  randomFill,
  createCipheriv,
} = await import('node:crypto');

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

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

    // Once we have the key and iv, we can create and use the cipher...
    const cipher = createCipheriv(algorithm, key, iv);

    let encrypted = '';
    cipher.setEncoding('hex');

    cipher.on('data', (chunk) => encrypted += chunk);
    cipher.on('end', () => console.log(encrypted));

    cipher.write('some clear text data');
    cipher.end();
  });
});
CommonJS
const {
  scrypt,
  randomFill,
  createCipheriv,
} = require('node:crypto');

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

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

    // Once we have the key and iv, we can create and use the cipher...
    const cipher = createCipheriv(algorithm, key, iv);

    let encrypted = '';
    cipher.setEncoding('hex');

    cipher.on('data', (chunk) => encrypted += chunk);
    cipher.on('end', () => console.log(encrypted));

    cipher.write('some clear text data');
    cipher.end();
  });
});

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

Модули JavaScript
import {
  createReadStream,
  createWriteStream,
} from 'node:fs';

import {
  pipeline,
} from 'node:stream';

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

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

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

    const cipher = createCipheriv(algorithm, key, iv);

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

    pipeline(input, cipher, output, (err) => {
      if (err) throw err;
    });
  });
});
CommonJS
const {
  createReadStream,
  createWriteStream,
} = require('node:fs');

const {
  pipeline,
} = require('node:stream');

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

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

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

    const cipher = createCipheriv(algorithm, key, iv);

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

    pipeline(input, cipher, output, (err) => {
      if (err) throw err;
    });
  });
});

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

Модули JavaScript
const {
  scrypt,
  randomFill,
  createCipheriv,
} = await import('node:crypto');

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

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

    const cipher = createCipheriv(algorithm, key, iv);

    let encrypted = cipher.update('some clear text data', 'utf8', 'hex');
    encrypted += cipher.final('hex');
    console.log(encrypted);
  });
});
CommonJS
const {
  scrypt,
  randomFill,
  createCipheriv,
} = require('node:crypto');

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

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

    const cipher = createCipheriv(algorithm, key, iv);

    let encrypted = cipher.update('some clear text data', 'utf8', 'hex');
    encrypted += cipher.final('hex');
    console.log(encrypted);
  });
});

cipher.final([outputEncoding])

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

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

cipher.getAuthTag()

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

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

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

cipher.setAAD(buffer[, options])

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

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

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

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

cipher.setAutoPadding([autoPadding])

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

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

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

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

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

История
Версия Изменения
v6.0.0

Значение inputEncoding по умолчанию изменено с binary на utf8.
v0.1.94

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

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

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

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

Класс: Decipheriv

Добавлено в: v0.1.94
  • Расширяет: <stream.Transform>

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

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

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

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

Модули JavaScript
import { Buffer } from 'node:buffer';
const {
  scryptSync,
  createDecipheriv,
} = await import('node:crypto');

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

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

let decrypted = '';
decipher.on('readable', () => {
  let chunk;
  while (null !== (chunk = decipher.read())) {
    decrypted += chunk.toString('utf8');
  }
});
decipher.on('end', () => {
  console.log(decrypted);
  // Prints: some clear text data
});

// Encrypted with same algorithm, key and iv.
const encrypted =
  'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa';
decipher.write(encrypted, 'hex');
decipher.end();
CommonJS
const {
  scryptSync,
  createDecipheriv,
} = require('node:crypto');
const { Buffer } = require('node:buffer');

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

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

let decrypted = '';
decipher.on('readable', () => {
  let chunk;
  while (null !== (chunk = decipher.read())) {
    decrypted += chunk.toString('utf8');
  }
});
decipher.on('end', () => {
  console.log(decrypted);
  // Prints: some clear text data
});

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

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

Модули JavaScript
import {
  createReadStream,
  createWriteStream,
} from 'node:fs';
import { Buffer } from 'node:buffer';
const {
  scryptSync,
  createDecipheriv,
} = await import('node:crypto');

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

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

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

input.pipe(decipher).pipe(output);
CommonJS
const {
  createReadStream,
  createWriteStream,
} = require('node:fs');
const {
  scryptSync,
  createDecipheriv,
} = require('node:crypto');
const { Buffer } = require('node:buffer');

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

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

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

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

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

Модули JavaScript
import { Buffer } from 'node:buffer';
const {
  scryptSync,
  createDecipheriv,
} = await import('node:crypto');

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

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

// Encrypted using same algorithm, key and iv.
const encrypted =
  'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa';
let decrypted = decipher.update(encrypted, 'hex', 'utf8');
decrypted += decipher.final('utf8');
console.log(decrypted);
// Prints: some clear text data
CommonJS
const {
  scryptSync,
  createDecipheriv,
} = require('node:crypto');
const { Buffer } = require('node:buffer');

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

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

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

decipher.final([outputEncoding])

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

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

decipher.setAAD(buffer[, options])

История
Версия Изменения
v15.0.0

Аргумент buffer может быть строкой или ArrayBuffer и ограничен размером не более 2 ** 31 - 1 байт.
v7.2.0

Теперь этот метод возвращает ссылку на decipher.
v1.0.0

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

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

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

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

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

decipher.setAuthTag(buffer[, encoding])

История
Версия Изменения
v22.0.0, v20.13.0

Использование тегов GCM длиной, отличной от 128 бит, без указания параметра authTagLength при создании decipher объявлено устаревшим.
v15.0.0

Аргумент buffer может быть строкой или ArrayBuffer и ограничен размером не более 2 ** 31 - 1 байт.
v11.0.0

Теперь этот метод вызывает исключение, если длина тега GCM недопустима.
v7.2.0

Теперь этот метод возвращает ссылку на decipher.
v1.0.0

Добавлено в: v1.0.0
  • buffer <string> | <Buffer> | <ArrayBuffer> | <TypedArray> | <DataView>
  • encoding <string> Кодировка строки, используемая, если buffer является строкой.
  • Возвращает: <Decipheriv> Тот же объект 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() можно вызвать только один раз.

Поскольку модуль node:crypto изначально разрабатывался для точного соответствия поведению OpenSSL, эта функция допускает короткие теги аутентификации GCM, если при создании объекта decipher для crypto.createDecipheriv() не была явно задана длина тега аутентификации. Такое поведение объявлено устаревшим и может измениться (см. DEP0182). До тех пор приложениям следует либо задавать параметр authTagLength при вызове createDecipheriv(), либо проверять фактическую длину тега аутентификации перед передачей его в setAuthTag().

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

decipher.setAutoPadding([autoPadding])

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

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

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

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

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

История
Версия Изменения
v6.0.0

Значение inputEncoding по умолчанию изменено с binary на utf8.
v0.1.94

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

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

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

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

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

Класс: DiffieHellman

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

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

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

Модули JavaScript
import assert from 'node:assert';

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

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

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

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

// OK
assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex'));
CommonJS
const assert = require('node:assert');

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

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

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

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

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

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

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

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

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

diffieHellman.generateKeys([encoding])

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

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

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

diffieHellman.getGenerator([encoding])

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

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

diffieHellman.getPrime([encoding])

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

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

diffieHellman.getPrivateKey([encoding])

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

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

diffieHellman.getPublicKey([encoding])

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

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

diffieHellman.setPrivateKey(privateKey[, encoding])

Добавлено в: v0.5.0
  • privateKey <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
  • encoding <string> Кодировка строки privateKey.

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

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

diffieHellman.setPublicKey(publicKey[, encoding])

Добавлено в: v0.5.0
  • publicKey <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
  • encoding <string> Кодировка строки publicKey.

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

diffieHellman.verifyError

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

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

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

  • DH_CHECK_P_NOT_SAFE_PRIME
  • DH_CHECK_P_NOT_PRIME
  • DH_UNABLE_TO_CHECK_GENERATOR
  • DH_NOT_SUITABLE_GENERATOR

Класс: DiffieHellmanGroup

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

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

Модули JavaScript
const { createDiffieHellmanGroup } = await import('node:crypto');
const dh = createDiffieHellmanGroup('modp16');
CommonJS
const { createDiffieHellmanGroup } = require('node:crypto');
const dh = createDiffieHellmanGroup('modp16');

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

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

Также поддерживаются следующие группы, использование которых объявлено устаревшим (см. Предупреждения):

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

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

Класс: ECDH

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

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

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

Модули JavaScript
import assert from 'node:assert';

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

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

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

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

assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex'));
// OK
CommonJS
const assert = require('node:assert');

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

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

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

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

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

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

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

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

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

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

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

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

Модули JavaScript
const {
  createECDH,
  ECDH,
} = await import('node:crypto');

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

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

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

// The converted key and the uncompressed public key should be the same
console.log(uncompressedKey === ecdh.getPublicKey('hex'));
CommonJS
const {
  createECDH,
  ECDH,
} = require('node:crypto');

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

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

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

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

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

История
Версия Изменения
v10.0.0

Формат ошибки изменен для улучшения обработки ошибки недопустимого открытого ключа.
v6.0.0

Значение inputEncoding по умолчанию изменено с binary на utf8.
v0.11.14

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

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

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

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

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

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

Генерирует закрытый и открытый ключи EC Diffie-Hellman и возвращает открытый ключ в указанных format и encoding. Этот ключ следует передать другой стороне.

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

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

ecdh.getPrivateKey([encoding])

Добавлено в: v0.11.14
  • encoding <string> Кодировка возвращаемого значения.
  • Возвращает: <Buffer> | <string> Ключ EC Diffie-Hellman в указанном encoding.

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

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

Добавлено в: v0.11.14
  • encoding <string> Кодировка возвращаемого значения.
  • format <string> По умолчанию: 'uncompressed'
  • Возвращает: <Buffer> | <string> Открытый ключ EC Diffie-Hellman в указанных encoding и format.

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

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

ecdh.setPrivateKey(privateKey[, encoding])

Добавлено в: v0.11.14
  • privateKey <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
  • encoding <string> Кодировка строки privateKey.

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

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

ecdh.setPublicKey(publicKey[, encoding])

Добавлено в: v0.11.14Устарело с: v5.2.0
Стабильность: 0 — Устарело
  • publicKey <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
  • encoding <string> Кодировка строки publicKey.

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

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

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

Модули JavaScript
const {
  createECDH,
  createHash,
} = await import('node:crypto');

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

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

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

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

// aliceSecret and bobSecret should be the same shared secret value
console.log(aliceSecret === bobSecret);
CommonJS
const {
  createECDH,
  createHash,
} = require('node:crypto');

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

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

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

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

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

Класс: Hash

Добавлено в: v0.1.92
  • Наследует: <stream.Transform>

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

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

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

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

Модули JavaScript
const {
  createHash,
} = await import('node:crypto');

const hash = createHash('sha256');

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

hash.write('some data to hash');
hash.end();
CommonJS
const {
  createHash,
} = require('node:crypto');

const hash = createHash('sha256');

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

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

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

Модули JavaScript
import { createReadStream } from 'node:fs';
import { stdout } from 'node:process';
const { createHash } = await import('node:crypto');

const hash = createHash('sha256');

const input = createReadStream('test.js');
input.pipe(hash).setEncoding('hex').pipe(stdout);
CommonJS
const { createReadStream } = require('node:fs');
const { createHash } = require('node:crypto');
const { stdout } = require('node:process');

const hash = createHash('sha256');

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

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

Модули JavaScript
const {
  createHash,
} = await import('node:crypto');

const hash = createHash('sha256');

hash.update('some data to hash');
console.log(hash.digest('hex'));
// Prints:
//   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50
CommonJS
const {
  createHash,
} = require('node:crypto');

const hash = createHash('sha256');

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

hash.copy([options])

Добавлено в: v13.1.0
  • options <Object> stream.transform параметры
  • Возвращает: <Hash>

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

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

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

Модули JavaScript
// Calculate a rolling hash.
const {
  createHash,
} = await import('node:crypto');

const hash = createHash('sha256');

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

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

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

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

const hash = createHash('sha256');

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

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

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

// Etc.

hash.digest([encoding])

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

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

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

hash.update(data[, inputEncoding])

История
Версия Изменения
v6.0.0

Значение inputEncoding по умолчанию изменено с binary на utf8.
v0.1.92

Добавлено в: v0.1.92
  • data <string> | <Buffer> | <TypedArray> | <DataView>
  • inputEncoding <string> Кодировка строки data.

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

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

Класс: Hmac

Добавлено в: v0.1.94
  • Наследует: <stream.Transform>

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

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

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

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

Модули JavaScript
const {
  createHmac,
} = await import('node:crypto');

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

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

hmac.write('some data to hash');
hmac.end();
CommonJS
const {
  createHmac,
} = require('node:crypto');

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

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

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

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

Модули JavaScript
import { createReadStream } from 'node:fs';
import { stdout } from 'node:process';
const {
  createHmac,
} = await import('node:crypto');

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

const input = createReadStream('test.js');
input.pipe(hmac).pipe(stdout);
CommonJS
const {
  createReadStream,
} = require('node:fs');
const {
  createHmac,
} = require('node:crypto');
const { stdout } = require('node:process');

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

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

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

Модули JavaScript
const {
  createHmac,
} = await import('node:crypto');

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

hmac.update('some data to hash');
console.log(hmac.digest('hex'));
// Prints:
//   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e
CommonJS
const {
  createHmac,
} = require('node:crypto');

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

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

hmac.digest([encoding])

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

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

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

hmac.update(data[, inputEncoding])

История
Версия Изменения
v6.0.0

Значение inputEncoding по умолчанию изменено с binary на utf8.
v0.1.94

Добавлено в: v0.1.94
  • data <string> | <Buffer> | <TypedArray> | <DataView>
  • inputEncoding <string> Кодировка строки data.

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

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

Класс: KeyObject

История
Версия Изменения
v24.6.0

Добавлена поддержка ключей ML-DSA.
v14.5.0, v12.19.0

Теперь экземпляры этого класса можно передавать рабочим потокам с помощью postMessage.
v11.13.0

Теперь этот класс экспортируется.
v11.6.0

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

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

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

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

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

Добавлено в: v15.0.0
  • key <CryptoKey>
  • Возвращает: <KeyObject>

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

Модули JavaScript
const { KeyObject } = await import('node:crypto');
const { subtle } = globalThis.crypto;

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

const keyObject = KeyObject.from(key);
console.log(keyObject.symmetricKeySize);
// Prints: 32 (symmetric key size in bytes)
CommonJS
const { KeyObject } = require('node:crypto');
const { subtle } = globalThis.crypto;

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

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

keyObject.asymmetricKeyDetails

История
Версия Изменения
v16.9.0

Предоставлены параметры последовательности RSASSA-PSS-params для ключей RSA-PSS.
v15.7.0

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

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

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

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

keyObject.asymmetricKeyType

История
Версия Изменения
v24.8.0

Добавлена поддержка ключей SLH-DSA.
v24.7.0

Добавлена поддержка ключей ML-KEM.
v24.6.0

Добавлена поддержка ключей ML-DSA.
v13.9.0, v12.17.0

Добавлена поддержка 'dh'.
v12.0.0

Добавлена поддержка 'rsa-pss'.
v12.0.0

Теперь это свойство возвращает undefined для экземпляров KeyObject неизвестного типа вместо аварийного завершения.
v12.0.0

Добавлена поддержка 'x25519' и 'x448'.
v12.0.0

Добавлена поддержка 'ed25519' и 'ed448'.
v11.6.0

Добавлено в: v11.6.0
  • Тип: <string>

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

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

keyObject.equals(otherKeyObject)

Добавлено в: v17.7.0, v16.15.0
  • otherKeyObject <KeyObject> Объект KeyObject для сравнения с keyObject.
  • Возвращает: <boolean>

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

keyObject.export([options])

История
Версия Изменения
v15.9.0

Добавлена поддержка формата 'jwk'.
v11.6.0

Добавлено в: v11.6.0
  • options <Object>
  • Возвращает: <string> | <Buffer> | <Object>

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

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

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

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

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

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

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

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

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

keyObject.symmetricKeySize

Добавлено в: v11.6.0
  • Тип: <number>

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

keyObject.toCryptoKey(algorithm, extractable, keyUsages)

Добавлено в: v23.0.0, v22.10.0
  • algorithm <string> | <Algorithm> | <RsaHashedImportParams> | <EcKeyImportParams> | <HmacImportParams>
  • extractable <boolean>
  • keyUsages <string[]> См. варианты использования ключей.
  • Возвращает: <CryptoKey>

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

keyObject.type

Добавлено в: v11.6.0
  • Тип: <string>

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

Класс: Sign

Добавлено в: v0.1.92
  • Расширяет: <stream.Writable>

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

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

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

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

Модули JavaScript
const {
  generateKeyPairSync,
  createSign,
  createVerify,
} = await import('node:crypto');

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

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

const verify = createVerify('SHA256');
verify.write('some data to sign');
verify.end();
console.log(verify.verify(publicKey, signature, 'hex'));
// Prints: true
CommonJS
const {
  generateKeyPairSync,
  createSign,
  createVerify,
} = require('node:crypto');

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

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

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

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

Модули JavaScript
const {
  generateKeyPairSync,
  createSign,
  createVerify,
} = await import('node:crypto');

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

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

const verify = createVerify('SHA256');
verify.update('some data to sign');
verify.end();
console.log(verify.verify(publicKey, signature));
// Prints: true
CommonJS
const {
  generateKeyPairSync,
  createSign,
  createVerify,
} = require('node:crypto');

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

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

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

sign.sign(privateKey[, outputEncoding])

История
Версия Изменения
v15.0.0

В качестве privateKey также можно передавать ArrayBuffer и CryptoKey.
v13.2.0, v12.16.0

Теперь эта функция поддерживает подписи DSA и ECDSA в формате IEEE-P1363.
v12.0.0

Теперь эта функция поддерживает ключи RSA-PSS.
v11.6.0

Теперь эта функция поддерживает объекты ключей.
v8.0.0

Добавлена поддержка RSASSA-PSS и дополнительных параметров.
v0.1.92

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

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

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

  • dsaEncoding <string> Для DSA и ECDSA этот параметр задаёт формат создаваемой подписи. Возможны следующие значения:

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

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

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

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

  • saltLength <integer> Длина соли, если заполнение имеет значение RSA_PKCS1_PSS_PADDING. Специальное значение crypto.constants.RSA_PSS_SALTLEN_DIGEST устанавливает длину соли равной размеру дайджеста, а crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN (по умолчанию) устанавливает её равной максимально допустимому значению.

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

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

sign.update(data[, inputEncoding])

История
Версия Изменения
v6.0.0

Значение inputEncoding по умолчанию изменено с binary на utf8.
v0.1.92

Добавлено в: v0.1.92
  • data <string> | <Buffer> | <TypedArray> | <DataView>
  • inputEncoding <string> Кодировка строки data.

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

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

Класс: Verify

Добавлено в: v0.1.92
  • Расширяет: <stream.Writable>

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

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

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

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

verify.update(data[, inputEncoding])

История
Версия Изменения
v6.0.0

Значение inputEncoding по умолчанию изменено с binary на utf8.
v0.1.92

Добавлено в: v0.1.92
  • data <string> | <Buffer> | <TypedArray> | <DataView>
  • inputEncoding <string> Кодировка строки data.

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

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

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

История
Версия Изменения
v15.0.0

В качестве объекта также можно передавать ArrayBuffer и CryptoKey.
v13.2.0, v12.16.0

Теперь эта функция поддерживает подписи DSA и ECDSA в формате IEEE-P1363.
v12.0.0

Теперь эта функция поддерживает ключи RSA-PSS.
v11.7.0

Теперь в качестве ключа можно передавать закрытый ключ.
v8.0.0

Добавлена поддержка RSASSA-PSS и дополнительных параметров.
v0.1.92

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

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

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

  • dsaEncoding <string> Для DSA и ECDSA этот параметр задаёт формат подписи. Возможны следующие значения:

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

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

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

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

  • saltLength <integer> Длина соли, если заполнение имеет значение RSA_PKCS1_PSS_PADDING. Специальное значение crypto.constants.RSA_PSS_SALTLEN_DIGEST устанавливает длину соли равной размеру дайджеста, а crypto.constants.RSA_PSS_SALTLEN_AUTO (по умолчанию) позволяет определить её автоматически.

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

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

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

Class: X509Certificate

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

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

Модули JavaScript
const { X509Certificate } = await import('node:crypto');

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

console.log(x509.subject);
CommonJS
const { X509Certificate } = require('node:crypto');

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

console.log(x509.subject);

new X509Certificate(buffer)

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

x509.ca

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

x509.checkEmail(email[, options])

История
Версия Изменения
v18.0.0

Теперь для параметра subject по умолчанию используется 'default'.
v17.5.0, v16.15.0

Теперь параметру subject можно присвоить значение 'default'.
v17.5.0, v16.14.1

Параметры wildcards, partialWildcards, multiLabelWildcards и singleLabelSubdomains удалены, поскольку они не оказывали влияния.
v15.6.0

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

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

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

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

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

x509.checkHost(name[, options])

История
Версия Изменения
v18.0.0

Теперь для параметра subject по умолчанию используется 'default'.
v17.5.0, v16.15.0

Теперь параметру subject можно присвоить значение 'default'.
v15.6.0

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

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

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

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

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

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

x509.checkIP(ip)

История
Версия Изменения
v17.5.0, v16.14.1

Аргумент options удалён, поскольку он не оказывал влияния.
v15.6.0

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

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

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

x509.checkIssued(otherCert)

Добавлено в: v15.6.0
  • otherCert <X509Certificate>
  • Возвращает: <boolean>

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

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

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

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

x509.checkPrivateKey(privateKey)

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

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

x509.fingerprint

Добавлено в: v15.6.0
  • Тип: <string>

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

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

x509.fingerprint256

Добавлено в: v15.6.0
  • Тип: <string>

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

x509.fingerprint512

Добавлено в: v17.2.0, v16.14.0
  • Тип: <string>

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

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

x509.infoAccess

История
Версия Изменения
v17.3.1, v16.13.2

В ответ на CVE-2021-44532 части этой строки могут кодироваться как строковые литералы JSON.
v15.6.0

Добавлено в: v15.6.0
  • Тип: <string>

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

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

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

x509.issuer

Добавлено в: v15.6.0
  • Тип: <string>

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

x509.issuerCertificate

Добавлено в: v15.9.0
  • Тип: <X509Certificate>

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

x509.keyUsage

Добавлено в: v15.6.0
  • Тип: <string[]>

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

x509.publicKey

Добавлено в: v15.6.0
  • Тип: <KeyObject>

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

x509.raw

Добавлено в: v15.6.0
  • Тип: <Buffer>

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

x509.serialNumber

Добавлено в: v15.6.0
  • Тип: <string>

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

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

x509.subject

Добавлено в: v15.6.0
  • Тип: <string>

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

x509.subjectAltName

История
Версия Изменения
v17.3.1, v16.13.2

В ответ на CVE-2021-44532 части этой строки могут кодироваться как строковые литералы JSON.
v15.6.0

Добавлено в: v15.6.0
  • Тип: <string>

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

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

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

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

x509.toJSON()

Добавлено в: v15.6.0
  • Тип: <string>

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

x509.toLegacyObject()

Добавлено в: v15.6.0
  • Тип: <Object>

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

x509.toString()

Добавлено в: v15.6.0
  • Тип: <string>

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

x509.validFrom

Добавлено в: v15.6.0
  • Тип: <string>

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

x509.validFromDate

Добавлено в: v23.0.0, v22.10.0
  • Тип: <Date>

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

x509.validTo

Добавлено в: v15.6.0
  • Тип: <string>

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

x509.validToDate

Добавлено в: v23.0.0, v22.10.0
  • Тип: <Date>

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

x509.signatureAlgorithm

Добавлено в: v24.9.0
  • Тип: <string> | <undefined>

Алгоритм, использованный для подписания сертификата, или undefined, если OpenSSL не распознаёт алгоритм подписи.

x509.signatureAlgorithmOid

Добавлено в: v24.9.0
  • Тип: <string>

OID алгоритма, использованного для подписания сертификата.

x509.verify(publicKey)

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

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

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

crypto.argon2(algorithm, parameters, callback)

Добавлено в: v24.7.0
Стабильность: 1.2 — кандидат на выпуск
  • algorithm <string> Вариант Argon2: один из "argon2d", "argon2i" или "argon2id".
  • parameters <Object>
    • message <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> ОБЯЗАТЕЛЬНО, пароль для приложений хеширования паролей с использованием Argon2.
    • nonce <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> ОБЯЗАТЕЛЬНО, длина должна составлять не менее 8 байт. Это соль для приложений хеширования паролей с использованием Argon2.
    • parallelism <number> ОБЯЗАТЕЛЬНО, степень параллелизма определяет количество вычислительных цепочек (дорожек), которые можно запустить. Значение должно быть больше 1 и меньше 2**24-1.
    • tagLength <number> ОБЯЗАТЕЛЬНО, длина создаваемого ключа. Значение должно быть больше 4 и меньше 2**32-1.
    • memory <number> ОБЯЗАТЕЛЬНО, затраты памяти в блоках по 1 КиБ. Значение должно быть больше 8 * parallelism и меньше 2**32-1. Фактическое количество блоков округляется вниз до ближайшего числа, кратного 4 * parallelism.
    • passes <number> ОБЯЗАТЕЛЬНО, количество проходов (итераций). Значение должно быть больше 1 и меньше 2**32-1.
    • secret <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <undefined> НЕОБЯЗАТЕЛЬНО, случайные дополнительные входные данные, похожие на соль, которые НЕ следует сохранять вместе с производным ключом. В приложениях хеширования паролей они называются «перцем». Если значение задано, его длина не должна превышать 2**32-1 байт.
    • associatedData <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <undefined> НЕОБЯЗАТЕЛЬНО, дополнительные данные для добавления в хеш; функционально эквивалентны соли или секрету, но предназначены для непроизвольных данных. Если значение задано, его длина не должна превышать 2**32-1 байт.
  • callback <Function>
    • err <Error>
    • derivedKey <Buffer>

Предоставляет асинхронную реализацию Argon2. Argon2 — это функция выработки ключа на основе пароля, требующая значительных вычислительных ресурсов и объема памяти, чтобы сделать атаки методом перебора неэффективными.

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

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

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

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

Модули JavaScript
const { argon2, randomBytes } = await import('node:crypto');

const parameters = {
  message: 'password',
  nonce: randomBytes(16),
  parallelism: 4,
  tagLength: 64,
  memory: 65536,
  passes: 3,
};

argon2('argon2id', parameters, (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // 'af91dad...9520f15'
});
CommonJS
const { argon2, randomBytes } = require('node:crypto');

const parameters = {
  message: 'password',
  nonce: randomBytes(16),
  parallelism: 4,
  tagLength: 64,
  memory: 65536,
  passes: 3,
};

argon2('argon2id', parameters, (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // 'af91dad...9520f15'
});

crypto.argon2Sync(algorithm, parameters)

Добавлено в: v24.7.0
Стабильность: 1.2 — кандидат на выпуск
  • algorithm <string> Вариант Argon2: один из "argon2d", "argon2i" или "argon2id".
  • parameters <Object>
    • message <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> ОБЯЗАТЕЛЬНО, пароль для приложений хеширования паролей с использованием Argon2.
    • nonce <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> ОБЯЗАТЕЛЬНО, длина должна составлять не менее 8 байт. Это соль для приложений хеширования паролей с использованием Argon2.
    • parallelism <number> ОБЯЗАТЕЛЬНО, степень параллелизма определяет количество вычислительных цепочек (дорожек), которые можно запустить. Значение должно быть больше 1 и меньше 2**24-1.
    • tagLength <number> ОБЯЗАТЕЛЬНО, длина создаваемого ключа. Значение должно быть больше 4 и меньше 2**32-1.
    • memory <number> ОБЯЗАТЕЛЬНО, затраты памяти в блоках по 1 КиБ. Значение должно быть больше 8 * parallelism и меньше 2**32-1. Фактическое количество блоков округляется вниз до ближайшего числа, кратного 4 * parallelism.
    • passes <number> ОБЯЗАТЕЛЬНО, количество проходов (итераций). Значение должно быть больше 1 и меньше 2**32-1.
    • secret <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <undefined> НЕОБЯЗАТЕЛЬНО, случайные дополнительные входные данные, похожие на соль, которые НЕ следует сохранять вместе с производным ключом. В приложениях хеширования паролей они называются «перцем». Если значение задано, его длина не должна превышать 2**32-1 байт.
    • associatedData <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <undefined> НЕОБЯЗАТЕЛЬНО, дополнительные данные для добавления в хеш; функционально эквивалентны соли или секрету, но предназначены для непроизвольных данных. Если значение задано, его длина не должна превышать 2**32-1 байт.
  • Возвращает: <Buffer>

Предоставляет синхронную реализацию Argon2. Argon2 — это функция выработки ключа на основе пароля, требующая значительных вычислительных ресурсов и объема памяти, чтобы сделать атаки методом перебора неэффективными.

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

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

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

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

Модули JavaScript
const { argon2Sync, randomBytes } = await import('node:crypto');

const parameters = {
  message: 'password',
  nonce: randomBytes(16),
  parallelism: 4,
  tagLength: 64,
  memory: 65536,
  passes: 3,
};

const derivedKey = argon2Sync('argon2id', parameters);
console.log(derivedKey.toString('hex'));  // 'af91dad...9520f15'
CommonJS
const { argon2Sync, randomBytes } = require('node:crypto');

const parameters = {
  message: 'password',
  nonce: randomBytes(16),
  parallelism: 4,
  tagLength: 64,
  memory: 65536,
  passes: 3,
};

const derivedKey = argon2Sync('argon2id', parameters);
console.log(derivedKey.toString('hex'));  // 'af91dad...9520f15'

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

История
Версия Изменения
v18.0.0

Передача недопустимой функции обратного вызова в аргумент callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v15.8.0

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

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

crypto.checkPrimeSync(candidate[, options])

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

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

crypto.constants

Добавлено в: v6.3.0
  • Тип: <Object>

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

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

История
Версия Изменения
v17.9.0, v16.17.0

Параметр authTagLength стал необязательным при использовании шифра chacha20-poly1305; значение по умолчанию — 16 байт.
v15.0.0

Аргументы password и iv могут иметь тип ArrayBuffer; максимальный размер каждого ограничен 2 ** 31 - 1 байтами.
v11.6.0

Аргумент key теперь может иметь тип KeyObject.
v11.2.0, v10.17.0

Теперь поддерживается шифр chacha20-poly1305 (вариант ChaCha20-Poly1305 для IETF).
v10.10.0

Добавлена поддержка шифров в режиме OCB.
v10.2.0

Параметр authTagLength теперь можно использовать для создания более коротких тегов аутентификации в режиме GCM; значение по умолчанию — 16 байт.
v9.9.0

Параметр iv теперь может иметь значение null для шифров, которым не требуется вектор инициализации.
v0.1.94

Добавлено в: v0.1.94
  • algorithm <string>
  • key <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
  • iv <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <null>
  • options <Object> параметры stream.transform
  • Возвращает: <Cipheriv>

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

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

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

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

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

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

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

История
Версия Изменения
v17.9.0, v16.17.0

Параметр authTagLength теперь необязателен при использовании шифра chacha20-poly1305 и по умолчанию равен 16 байтам.
v11.6.0

Аргумент key теперь может иметь тип KeyObject.
v11.2.0, v10.17.0

Теперь поддерживается шифр chacha20-poly1305 (вариант ChaCha20-Poly1305 для IETF).
v10.10.0

Теперь поддерживаются шифры в режиме OCB.
v10.2.0

Теперь параметр authTagLength можно использовать для ограничения допустимой длины тега аутентификации GCM.
v9.9.0

Параметр iv теперь может иметь значение null для шифров, которым не нужен вектор инициализации.
v0.1.94

Добавлено в: v0.1.94
  • algorithm <string>
  • key <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
  • iv <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <null>
  • options <Object> stream.transform параметры
  • Возвращает: <Decipheriv>

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

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

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

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

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

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

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

История
Версия Изменения
v8.0.0

Теперь аргумент prime может иметь тип TypedArray или DataView.
v8.0.0

Теперь аргумент prime может иметь тип Uint8Array.
v6.0.0

Кодировка по умолчанию для параметров кодирования изменилась с binary на utf8.
v0.11.12

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

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

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

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

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

crypto.createDiffieHellman(primeLength[, generator])

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

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

crypto.createDiffieHellmanGroup(name)

Добавлено в: v0.9.3
  • name <string>
  • Возвращает: <DiffieHellmanGroup>

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

crypto.createECDH(curveName)

Добавлено в: v0.11.14
  • curveName <string>
  • Возвращает: <ECDH>

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

crypto.createHash(algorithm[, options])

История
Версия Изменения
v12.8.0

Для хеш-функций XOF добавлен параметр outputLength.
v0.1.92

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

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

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

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

Модули JavaScript
import {
  createReadStream,
} from 'node:fs';
import { argv } from 'node:process';
const {
  createHash,
} = await import('node:crypto');

const filename = argv[2];

const hash = createHash('sha256');

const input = createReadStream(filename);
input.on('readable', () => {
  // Only one element is going to be produced by the
  // hash stream.
  const data = input.read();
  if (data)
    hash.update(data);
  else {
    console.log(`${hash.digest('hex')} ${filename}`);
  }
});
CommonJS
const {
  createReadStream,
} = require('node:fs');
const {
  createHash,
} = require('node:crypto');
const { argv } = require('node:process');

const filename = argv[2];

const hash = createHash('sha256');

const input = createReadStream(filename);
input.on('readable', () => {
  // Only one element is going to be produced by the
  // hash stream.
  const data = input.read();
  if (data)
    hash.update(data);
  else {
    console.log(`${hash.digest('hex')} ${filename}`);
  }
});

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

История
Версия Изменения
v15.0.0

Ключ теперь также может быть объектом ArrayBuffer или CryptoKey. Добавлен параметр кодировки. Размер ключа не может превышать 2 ** 32 - 1 байт.
v11.6.0

Аргумент key теперь может иметь тип KeyObject.
v0.1.94

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

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

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

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

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

Модули JavaScript
import {
  createReadStream,
} from 'node:fs';
import { argv } from 'node:process';
const {
  createHmac,
} = await import('node:crypto');

const filename = argv[2];

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

const input = createReadStream(filename);
input.on('readable', () => {
  // Only one element is going to be produced by the
  // hash stream.
  const data = input.read();
  if (data)
    hmac.update(data);
  else {
    console.log(`${hmac.digest('hex')} ${filename}`);
  }
});
CommonJS
const {
  createReadStream,
} = require('node:fs');
const {
  createHmac,
} = require('node:crypto');
const { argv } = require('node:process');

const filename = argv[2];

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

const input = createReadStream(filename);
input.on('readable', () => {
  // Only one element is going to be produced by the
  // hash stream.
  const data = input.read();
  if (data)
    hmac.update(data);
  else {
    console.log(`${hmac.digest('hex')} ${filename}`);
  }
});

crypto.createPrivateKey(key)

История
Версия Изменения
v24.6.0

Добавлена поддержка ключей ML-DSA.
v15.12.0

Теперь ключ также может быть объектом JWK.
v15.0.0

Теперь ключ также может быть объектом ArrayBuffer. Добавлен параметр кодировки. Размер ключа не может превышать 2 ** 32 - 1 байт.
v11.6.0

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

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

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

crypto.createPublicKey(key)

История
Версия Изменения
v24.6.0

Добавлена поддержка ключей ML-DSA.
v15.12.0

Теперь ключ также может быть объектом JWK.
v15.0.0

Теперь ключ также может быть объектом ArrayBuffer. Добавлен параметр кодировки. Размер ключа не может превышать 2 ** 32 - 1 байт.
v11.13.0

Аргумент key теперь может быть объектом KeyObject типа private.
v11.7.0

Аргумент key теперь может быть закрытым ключом.
v11.6.0

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

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

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

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

crypto.createSecretKey(key[, encoding])

История
Версия Изменения
v18.8.0, v16.18.0

Теперь ключ может иметь нулевую длину.
v15.0.0

Теперь ключ также может быть объектом ArrayBuffer или строкой. Добавлен аргумент кодировки. Размер ключа не может превышать 2 ** 32 - 1 байт.
v11.6.0

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

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

crypto.createSign(algorithm[, options])

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

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

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

crypto.createVerify(algorithm[, options])

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

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

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

crypto.decapsulate(key, ciphertext[, callback])

Добавлено в: v24.7.0
Стабильность: 1.2 — кандидат на выпуск
  • key <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> закрытый ключ
  • ciphertext <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
  • callback <Function>
    • err <Error>
    • sharedKey <Buffer>
  • Возвращает: <Buffer>, если функция callback не указана.

Декапсуляция ключа с использованием алгоритма KEM и закрытого ключа.

Поддерживаемые типы ключей и соответствующие им алгоритмы KEM:

  • 'rsa'2 инкапсуляция секретного значения RSA
  • 'ec'3 DHKEM(P-256, HKDF-SHA256), DHKEM(P-384, HKDF-SHA256), DHKEM(P-521, HKDF-SHA256)
  • 'x25519'3 DHKEM(X25519, HKDF-SHA256)
  • 'x448'3 DHKEM(X448, HKDF-SHA512)
  • 'ml-kem-512'1 ML-KEM
  • 'ml-kem-768'1 ML-KEM
  • 'ml-kem-1024'1 ML-KEM

Если key не является KeyObject, эта функция работает так, как если бы key был передан в crypto.createPrivateKey().

Если указана функция callback, эта функция использует пул потоков libuv.

crypto.diffieHellman(options[, callback])

История
Версия Изменения
v23.11.0

Добавлен необязательный аргумент обратного вызова.
v13.9.0, v12.17.0

Добавлено в: v13.9.0, v12.17.0
  • options <Object>
    • privateKey <KeyObject>
    • publicKey <KeyObject>
  • callback <Function>
    • err <Error>
    • secret <Buffer>
  • Возвращает: <Buffer>, если функция callback не указана.

Вычисляет общий секрет Диффи — Хеллмана на основе privateKey и publicKey. Оба ключа должны иметь одинаковый asymmetricKeyType и поддерживать операцию DH или ECDH.

Если указана функция callback, эта функция использует пул потоков libuv.

crypto.encapsulate(key[, callback])

Добавлено в: v24.7.0
Стабильность: 1.2 — кандидат на выпуск
  • key <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> открытый ключ
  • callback <Function>
    • err <Error>
    • result <Object>
      • sharedKey <Buffer>
      • ciphertext <Buffer>
  • Возвращает: <Object>, если функция callback не указана.
    • sharedKey <Buffer>
    • ciphertext <Buffer>

Инкапсуляция ключа с использованием алгоритма KEM и открытого ключа.

Поддерживаемые типы ключей и соответствующие им алгоритмы KEM:

  • 'rsa'2 инкапсуляция секретного значения RSA
  • 'ec'3 DHKEM(P-256, HKDF-SHA256), DHKEM(P-384, HKDF-SHA256), DHKEM(P-521, HKDF-SHA256)
  • 'x25519'3 DHKEM(X25519, HKDF-SHA256)
  • 'x448'3 DHKEM(X448, HKDF-SHA512)
  • 'ml-kem-512'1 ML-KEM
  • 'ml-kem-768'1 ML-KEM
  • 'ml-kem-1024'1 ML-KEM

Если key не является KeyObject, эта функция работает так, как если бы key был передан в crypto.createPublicKey().

Если указана функция callback, эта функция использует пул потоков libuv.

crypto.fips

Добавлено в: v6.0.0Устарело с: v10.0.0
Стабильность: 0 — устарело

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

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

crypto.generateKey(type, options, callback)

История
Версия Изменения
v18.0.0

Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v15.0.0

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

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

Модули JavaScript
const {
  generateKey,
} = await import('node:crypto');

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

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

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

crypto.generateKeyPair(type, options, callback)

История
Версия Изменения
v24.8.0

Добавлена поддержка пар ключей SLH-DSA.
v24.7.0

Добавлена поддержка пар ключей ML-KEM.
v24.6.0

Добавлена поддержка пар ключей ML-DSA.
v18.0.0

Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v16.10.0

Добавлена возможность задавать параметры последовательности RSASSA-PSS-params для пар ключей RSA-PSS.
v13.9.0, v12.17.0

Добавлена поддержка Diffie-Hellman.
v12.0.0

Добавлена поддержка пар ключей RSA-PSS.
v12.0.0

Добавлена возможность создавать пары ключей X25519 и X448.
v12.0.0

Добавлена возможность создавать пары ключей Ed25519 и Ed448.
v11.6.0

Функции generateKeyPair и generateKeyPairSync теперь возвращают объекты ключей, если кодировка не указана.
v10.12.0

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

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

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

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

Модули JavaScript
const {
  generateKeyPair,
} = await import('node:crypto');

generateKeyPair('rsa', {
  modulusLength: 4096,
  publicKeyEncoding: {
    type: 'spki',
    format: 'pem',
  },
  privateKeyEncoding: {
    type: 'pkcs8',
    format: 'pem',
    cipher: 'aes-256-cbc',
    passphrase: 'top secret',
  },
}, (err, publicKey, privateKey) => {
  // Handle errors and use the generated key pair.
});
CommonJS
const {
  generateKeyPair,
} = require('node:crypto');

generateKeyPair('rsa', {
  modulusLength: 4096,
  publicKeyEncoding: {
    type: 'spki',
    format: 'pem',
  },
  privateKeyEncoding: {
    type: 'pkcs8',
    format: 'pem',
    cipher: 'aes-256-cbc',
    passphrase: 'top secret',
  },
}, (err, publicKey, privateKey) => {
  // Handle errors and use the generated key pair.
});

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

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

crypto.generateKeyPairSync(type, options)

История
Версия Изменения
v24.8.0

Добавлена поддержка пар ключей SLH-DSA.
v24.7.0

Добавлена поддержка пар ключей ML-KEM.
v24.6.0

Добавлена поддержка пар ключей ML-DSA.
v16.10.0

Добавлена возможность задавать параметры последовательности RSASSA-PSS-params для пар ключей RSA-PSS.
v13.9.0, v12.17.0

Добавлена поддержка Diffie-Hellman.
v12.0.0

Добавлена поддержка пар ключей RSA-PSS.
v12.0.0

Добавлена возможность создавать пары ключей X25519 и X448.
v12.0.0

Добавлена возможность создавать пары ключей Ed25519 и Ed448.
v11.6.0

Функции generateKeyPair и generateKeyPairSync теперь возвращают объекты ключей, если кодировка не указана.
v10.12.0

Добавлено в: v10.12.0
  • type <string> Тип создаваемого асимметричного ключа. См. список поддерживаемых типов асимметричных ключей.
  • 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. См. список поддерживаемых типов асимметричных ключей.

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

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

Модули JavaScript
const {
  generateKeyPairSync,
} = await import('node:crypto');

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

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

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

crypto.generateKeySync(type, options)

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

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

Модули JavaScript
const {
  generateKeySync,
} = await import('node:crypto');

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

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

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

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

История
Версия Изменения
v18.0.0

Передача недопустимого обратного вызова в аргумент callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v15.8.0

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

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

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

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

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

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

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

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

crypto.generatePrimeSync(size[, options])

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

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

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

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

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

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

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

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

crypto.getCipherInfo(nameOrNid[, options])

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

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

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

crypto.getCiphers()

Добавлено в: v0.9.3
  • Возвращает: <string[]> Массив с именами поддерживаемых алгоритмов шифрования.
Модули JavaScript
const {
  getCiphers,
} = await import('node:crypto');

console.log(getCiphers()); // ['aes-128-cbc', 'aes-128-ccm', ...]
CommonJS
const {
  getCiphers,
} = require('node:crypto');

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

crypto.getCurves()

Добавлено в: v2.3.0
  • Возвращает: <string[]> Массив с именами поддерживаемых эллиптических кривых.
Модули JavaScript
const {
  getCurves,
} = await import('node:crypto');

console.log(getCurves()); // ['Oakley-EC2N-3', 'Oakley-EC2N-4', ...]
CommonJS
const {
  getCurves,
} = require('node:crypto');

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

crypto.getDiffieHellman(groupName)

Добавлено в: v0.7.5
  • groupName <string>
  • Возвращает: <DiffieHellmanGroup>

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

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

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

Модули JavaScript
const {
  getDiffieHellman,
} = await import('node:crypto');
const alice = getDiffieHellman('modp14');
const bob = getDiffieHellman('modp14');

alice.generateKeys();
bob.generateKeys();

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

/* aliceSecret and bobSecret should be the same */
console.log(aliceSecret === bobSecret);
CommonJS
const {
  getDiffieHellman,
} = require('node:crypto');

const alice = getDiffieHellman('modp14');
const bob = getDiffieHellman('modp14');

alice.generateKeys();
bob.generateKeys();

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

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

crypto.getFips()

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

crypto.getHashes()

Добавлено в: v0.9.3
  • Возвращает: <string[]> Массив имен поддерживаемых алгоритмов хеширования, например 'RSA-SHA256'. Алгоритмы хеширования также называются алгоритмами вычисления дайджеста.
Модули JavaScript
const {
  getHashes,
} = await import('node:crypto');

console.log(getHashes()); // ['DSA', 'DSA-SHA', 'DSA-SHA1', ...]
CommonJS
const {
  getHashes,
} = require('node:crypto');

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

crypto.getRandomValues(typedArray)

Добавлено в: v17.4.0
  • typedArray <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer>
  • Возвращает: <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> Возвращает typedArray.

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

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

История
Версия Изменения
v24.13.1

Этот API больше не является экспериментальным.
v24.4.0

Для хеш-функций XOF добавлен параметр outputLength.
v21.7.0, v20.12.0

Добавлено в: v21.7.0, v20.12.0
  • algorithm <string> | <undefined>
  • data <string> | <Buffer> | <TypedArray> | <DataView> Если data — строка, перед хешированием она будет закодирована в UTF-8. Если для строкового входного значения требуется другая кодировка, пользователь может закодировать строку в TypedArray с помощью TextEncoder или Buffer.from() и вместо этого передать в этот API закодированное значение TypedArray.
  • options <Object> | <string>
    • outputEncoding <string> Кодировка, используемая для кодирования возвращаемого дайджеста. По умолчанию: 'hex'.
    • outputLength <number> Для хеш-функций XOF, таких как 'shake256', параметр outputLength позволяет указать желаемую длину результата в байтах.
  • Возвращает: <string> | <Buffer>

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

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

Если options — строка, она задает outputEncoding.

Пример:

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

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

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

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

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

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

История
Версия Изменения
v18.0.0

Передача недопустимого обратного вызова в аргумент callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v18.8.0, v16.18.0

Теперь длина входного ключевого материала может быть равна нулю.
v15.0.0

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

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

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

Модули JavaScript
import { Buffer } from 'node:buffer';
const {
  hkdf,
} = await import('node:crypto');

hkdf('sha512', 'key', 'salt', 'info', 64, (err, derivedKey) => {
  if (err) throw err;
  console.log(Buffer.from(derivedKey).toString('hex'));  // '24156e2...5391653'
});
CommonJS
const {
  hkdf,
} = require('node:crypto');
const { Buffer } = require('node:buffer');

hkdf('sha512', 'key', 'salt', 'info', 64, (err, derivedKey) => {
  if (err) throw err;
  console.log(Buffer.from(derivedKey).toString('hex'));  // '24156e2...5391653'
});

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

История
Версия Изменения
v18.8.0, v16.18.0

Теперь исходный материал ключа может иметь нулевую длину.
v15.0.0

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

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

Успешно сгенерированный derivedKey возвращается в виде <ArrayBuffer>.

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

Модули JavaScript
import { Buffer } from 'node:buffer';
const {
  hkdfSync,
} = await import('node:crypto');

const derivedKey = hkdfSync('sha512', 'key', 'salt', 'info', 64);
console.log(Buffer.from(derivedKey).toString('hex'));  // '24156e2...5391653'
CommonJS
const {
  hkdfSync,
} = require('node:crypto');
const { Buffer } = require('node:buffer');

const derivedKey = hkdfSync('sha512', 'key', 'salt', 'info', 64);
console.log(Buffer.from(derivedKey).toString('hex'));  // '24156e2...5391653'

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

История
Версия Изменения
v18.0.0

Передача недопустимого обратного вызова в аргумент callback теперь приводит к выбрасыванию ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v15.0.0

Аргументы password и salt теперь также могут быть экземплярами ArrayBuffer.
v14.0.0

Параметр iterations теперь принимает только положительные значения. В предыдущих выпусках другие значения интерпретировались как единица.
v8.0.0

Теперь параметр digest всегда обязателен.
v6.0.0

Вызов этой функции без передачи параметра digest теперь считается устаревшим и приводит к появлению предупреждения.
v6.0.0

Кодировка по умолчанию для password, если это строка, изменилась с binary на utf8.
v0.5.5

Добавлено в: v0.5.5
  • password <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
  • salt <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
  • iterations <number>
  • keylen <number>
  • digest <string>
  • callback <Function>
    • err <Error>
    • derivedKey <Buffer>

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

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

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

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

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

Модули JavaScript
const {
  pbkdf2,
} = await import('node:crypto');

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

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

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

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

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

История
Версия Изменения
v14.0.0

Параметр iterations теперь принимает только положительные значения. В предыдущих выпусках другие значения интерпретировались как единица.
v6.0.0

Вызов этой функции без передачи параметра digest теперь считается устаревшим и приводит к появлению предупреждения.
v6.0.0

Кодировка по умолчанию для password, если это строка, изменилась с binary на utf8.
v0.9.3

Добавлено в: v0.9.3
  • password <string> | <Buffer> | <TypedArray> | <DataView>
  • salt <string> | <Buffer> | <TypedArray> | <DataView>
  • iterations <number>
  • keylen <number>
  • digest <string>
  • Возвращает: <Buffer>

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

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

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

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

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

Модули JavaScript
const {
  pbkdf2Sync,
} = await import('node:crypto');

const key = pbkdf2Sync('secret', 'salt', 100000, 64, 'sha512');
console.log(key.toString('hex'));  // '3745e48...08d59ae'
CommonJS
const {
  pbkdf2Sync,
} = require('node:crypto');

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

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

crypto.privateDecrypt(privateKey, buffer)

История
Версия Изменения
v21.6.2, v20.11.1, v18.19.1

Дополнение RSA_PKCS1_PADDING отключено, если сборка OpenSSL не поддерживает неявное отклонение.
v15.0.0

В список допустимых типов ключей добавлены string, ArrayBuffer и CryptoKey. oaepLabel может быть ArrayBuffer. Буфер может быть строкой или ArrayBuffer. Для всех типов, принимающих буферы, установлен максимальный размер 2 ** 31 - 1 байт.
v12.11.0

Добавлена опция oaepLabel.
v12.9.0

Добавлена опция oaepHash.
v11.6.0

Эта функция теперь поддерживает объекты ключей.
v0.11.14

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

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

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

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

crypto.privateEncrypt(privateKey, buffer)

История
Версия Изменения
v15.0.0

В список допустимых типов ключей добавлены string, ArrayBuffer и CryptoKey. passphrase может быть ArrayBuffer. Буфер может быть строкой или ArrayBuffer. Для всех типов, принимающих буферы, установлен максимальный размер 2 ** 31 - 1 байт.
v11.6.0

Эта функция теперь поддерживает объекты ключей.
v1.1.0

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

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

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

crypto.publicDecrypt(key, buffer)

История
Версия Изменения
v15.0.0

В список допустимых типов ключей добавлены string, ArrayBuffer и CryptoKey. passphrase может быть ArrayBuffer. Буфер может быть строкой или ArrayBuffer. Для всех типов, принимающих буферы, установлен максимальный размер 2 ** 31 - 1 байт.
v11.6.0

Эта функция теперь поддерживает объекты ключей.
v1.1.0

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

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

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

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

crypto.publicEncrypt(key, buffer)

История
Версия Изменения
v15.0.0

Строки, ArrayBuffer и CryptoKey добавлены в список допустимых типов ключей. oaepLabel и passphrase могут быть объектами ArrayBuffer. buffer может быть строкой или ArrayBuffer. Для всех типов, принимающих буферы, установлен максимальный размер — 2 ** 31 - 1 байт.
v12.11.0

Добавлен параметр oaepLabel.
v12.9.0

Добавлен параметр oaepHash.
v11.6.0

Теперь эта функция поддерживает объекты ключей.
v0.11.14

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

Шифрует содержимое buffer с помощью key и возвращает новый Buffer с зашифрованным содержимым. Возвращенные данные можно расшифровать соответствующим закрытым ключом, например, с помощью crypto.privateDecrypt().

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

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

crypto.randomBytes(size[, callback])

История
Версия Изменения
v18.0.0

Передача недопустимой функции обратного вызова в аргумент callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v9.0.0

Передача null в качестве аргумента callback теперь вызывает ERR_INVALID_CALLBACK.
v0.5.8

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

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

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

Модули JavaScript
// Asynchronous
const {
  randomBytes,
} = await import('node:crypto');

randomBytes(256, (err, buf) => {
  if (err) throw err;
  console.log(`${buf.length} bytes of random data: ${buf.toString('hex')}`);
});
CommonJS
// Asynchronous
const {
  randomBytes,
} = require('node:crypto');

randomBytes(256, (err, buf) => {
  if (err) throw err;
  console.log(`${buf.length} bytes of random data: ${buf.toString('hex')}`);
});

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

Модули JavaScript
// Synchronous
const {
  randomBytes,
} = await import('node:crypto');

const buf = randomBytes(256);
console.log(
  `${buf.length} bytes of random data: ${buf.toString('hex')}`);
CommonJS
// Synchronous
const {
  randomBytes,
} = require('node:crypto');

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

Метод crypto.randomBytes() не завершится, пока не будет доступно достаточное количество энтропии. Обычно это занимает не более нескольких миллисекунд. Генерация случайных байтов может блокироваться на более длительное время только сразу после загрузки, когда в системе еще недостаточно энтропии.

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

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

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

История
Версия Изменения
v18.0.0

Передача недопустимой функции обратного вызова в аргумент callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v9.0.0

Аргумент buffer теперь может быть любым TypedArray или DataView.
v7.10.0, v6.13.0

Добавлено в: v7.10.0, v6.13.0
  • buffer <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> Обязательный аргумент. Размер предоставленного buffer не должен превышать 2**31 - 1.
  • offset <number> По умолчанию: 0
  • size <number> По умолчанию: buffer.length - offset. Значение size не должно превышать 2**31 - 1.
  • callback <Function> function(err, buf) {}.

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

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

Модули JavaScript
import { Buffer } from 'node:buffer';
const { randomFill } = await import('node:crypto');

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

randomFill(buf, 5, (err, buf) => {
  if (err) throw err;
  console.log(buf.toString('hex'));
});

// The above is equivalent to the following:
randomFill(buf, 5, 5, (err, buf) => {
  if (err) throw err;
  console.log(buf.toString('hex'));
});
CommonJS
const { randomFill } = require('node:crypto');
const { Buffer } = require('node:buffer');

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

randomFill(buf, 5, (err, buf) => {
  if (err) throw err;
  console.log(buf.toString('hex'));
});

// The above is equivalent to the following:
randomFill(buf, 5, 5, (err, buf) => {
  if (err) throw err;
  console.log(buf.toString('hex'));
});

В качестве buffer можно передать любой экземпляр ArrayBuffer, TypedArray или DataView.

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

Модули JavaScript
import { Buffer } from 'node:buffer';
const { randomFill } = await import('node:crypto');

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

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

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

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

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

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

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

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

crypto.randomFillSync(buffer[, offset][, size])

История
Версия Изменения
v9.0.0

Аргумент buffer теперь может быть любым TypedArray или DataView.
v7.10.0, v6.13.0

Добавлено в: v7.10.0, v6.13.0
  • buffer <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> Обязательный аргумент. Размер предоставленного buffer не должен превышать 2**31 - 1.
  • offset <number> По умолчанию: 0
  • size <number> По умолчанию: buffer.length - offset. Значение size не должно превышать 2**31 - 1.
  • Возвращает: <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> Объект, переданный в качестве аргумента buffer.

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

Модули JavaScript
import { Buffer } from 'node:buffer';
const { randomFillSync } = await import('node:crypto');

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

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

// The above is equivalent to the following:
randomFillSync(buf, 5, 5);
console.log(buf.toString('hex'));
CommonJS
const { randomFillSync } = require('node:crypto');
const { Buffer } = require('node:buffer');

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

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

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

В качестве buffer можно передать любой экземпляр ArrayBuffer, TypedArray или DataView.

Модули JavaScript
import { Buffer } from 'node:buffer';
const { randomFillSync } = await import('node:crypto');

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

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

const c = new ArrayBuffer(10);
console.log(Buffer.from(randomFillSync(c)).toString('hex'));
CommonJS
const { randomFillSync } = require('node:crypto');
const { Buffer } = require('node:buffer');

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

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

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

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

История
Версия Изменения
v18.0.0

Передача недопустимой функции обратного вызова в аргумент callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v14.10.0, v12.19.0

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

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

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

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

Модули JavaScript
// Asynchronous
const {
  randomInt,
} = await import('node:crypto');

randomInt(3, (err, n) => {
  if (err) throw err;
  console.log(`Random number chosen from (0, 1, 2): ${n}`);
});
CommonJS
// Asynchronous
const {
  randomInt,
} = require('node:crypto');

randomInt(3, (err, n) => {
  if (err) throw err;
  console.log(`Random number chosen from (0, 1, 2): ${n}`);
});
Модули JavaScript
// Synchronous
const {
  randomInt,
} = await import('node:crypto');

const n = randomInt(3);
console.log(`Random number chosen from (0, 1, 2): ${n}`);
CommonJS
// Synchronous
const {
  randomInt,
} = require('node:crypto');

const n = randomInt(3);
console.log(`Random number chosen from (0, 1, 2): ${n}`);
Модули JavaScript
// With `min` argument
const {
  randomInt,
} = await import('node:crypto');

const n = randomInt(1, 7);
console.log(`The dice rolled: ${n}`);
CommonJS
// With `min` argument
const {
  randomInt,
} = require('node:crypto');

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

crypto.randomUUID([options])

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

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

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

История
Версия Изменения
v18.0.0

Передача недопустимой функции обратного вызова в аргумент callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v15.0.0

Аргументы password и salt теперь также могут быть экземплярами ArrayBuffer.
v12.8.0, v10.17.0

Значением maxmem теперь может быть любое безопасное целое число.
v10.9.0

Добавлены имена параметров cost, blockSize и parallelization.
v10.5.0

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

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

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

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

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

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

Модули JavaScript
const {
  scrypt,
} = await import('node:crypto');

// Using the factory defaults.
scrypt('password', 'salt', 64, (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // '3745e48...08d59ae'
});
// Using a custom N parameter. Must be a power of two.
scrypt('password', 'salt', 64, { N: 1024 }, (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // '3745e48...aa39b34'
});
CommonJS
const {
  scrypt,
} = require('node:crypto');

// Using the factory defaults.
scrypt('password', 'salt', 64, (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // '3745e48...08d59ae'
});
// Using a custom N parameter. Must be a power of two.
scrypt('password', 'salt', 64, { N: 1024 }, (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // '3745e48...aa39b34'
});

crypto.scryptSync(password, salt, keylen[, options])

История
Версия Изменения
v12.8.0, v10.17.0

Значением maxmem теперь может быть любое безопасное целое число.
v10.9.0

Добавлены имена параметров cost, blockSize и parallelization.
v10.5.0

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

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

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

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

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

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

Модули JavaScript
const {
  scryptSync,
} = await import('node:crypto');
// Using the factory defaults.

const key1 = scryptSync('password', 'salt', 64);
console.log(key1.toString('hex'));  // '3745e48...08d59ae'
// Using a custom N parameter. Must be a power of two.
const key2 = scryptSync('password', 'salt', 64, { N: 1024 });
console.log(key2.toString('hex'));  // '3745e48...aa39b34'
CommonJS
const {
  scryptSync,
} = require('node:crypto');
// Using the factory defaults.

const key1 = scryptSync('password', 'salt', 64);
console.log(key1.toString('hex'));  // '3745e48...08d59ae'
// Using a custom N parameter. Must be a power of two.
const key2 = scryptSync('password', 'salt', 64, { N: 1024 });
console.log(key2.toString('hex'));  // '3745e48...aa39b34'

crypto.secureHeapUsed()

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

crypto.setEngine(engine[, flags])

История
Версия Изменения
v22.4.0, v20.16.0

Поддержка пользовательских движков в OpenSSL 3 объявлена устаревшей.
v0.11.11

Добавлено в: v0.11.11
  • engine <string>
  • flags <crypto.constants> По умолчанию: crypto.constants.ENGINE_METHOD_ALL

Загружает и задаёт engine для некоторых или всех функций OpenSSL (выбираемых флагами). Поддержка пользовательских движков в OpenSSL объявлена устаревшей начиная с OpenSSL 3.

engine может быть идентификатором или путём к разделяемой библиотеке движка.

Необязательный аргумент flags по умолчанию использует ENGINE_METHOD_ALL. flags — это битовое поле, в котором можно указать один или несколько следующих флагов (определённых в crypto.constants):

  • crypto.constants.ENGINE_METHOD_RSA
  • crypto.constants.ENGINE_METHOD_DSA
  • crypto.constants.ENGINE_METHOD_DH
  • crypto.constants.ENGINE_METHOD_RAND
  • crypto.constants.ENGINE_METHOD_EC
  • crypto.constants.ENGINE_METHOD_CIPHERS
  • crypto.constants.ENGINE_METHOD_DIGESTS
  • crypto.constants.ENGINE_METHOD_PKEY_METHS
  • crypto.constants.ENGINE_METHOD_PKEY_ASN1_METHS
  • crypto.constants.ENGINE_METHOD_ALL
  • crypto.constants.ENGINE_METHOD_NONE

crypto.setFips(bool)

Добавлено в: v10.0.0
  • bool <boolean> true для включения режима FIPS.

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

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

История
Версия Изменения
v24.8.0

Добавлена поддержка контекстного параметра ML-DSA, Ed448 и SLH-DSA.
v24.8.0

Добавлена поддержка подписания с помощью SLH-DSA.
v24.6.0

Добавлена поддержка подписания с помощью ML-DSA.
v18.0.0

Передача недопустимой функции обратного вызова в аргумент callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v15.12.0

Добавлен необязательный аргумент функции обратного вызова.
v13.2.0, v12.16.0

Эта функция теперь поддерживает подписи DSA и ECDSA в формате IEEE-P1363.
v12.0.0

Добавлено в: v12.0.0
  • algorithm <string> | <null> | <undefined>
  • data <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
  • key <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
  • callback <Function>
    • err <Error>
    • signature <Buffer>
  • Возвращает: <Buffer>, если функция callback не указана.

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

Для Ed25519, Ed448 и ML-DSA значение algorithm должно быть null или undefined.

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

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

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

  • padding <integer> Необязательное значение дополнения для RSA; может принимать одно из следующих значений:

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

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

  • saltLength <integer> Длина соли, если используется дополнение RSA_PKCS1_PSS_PADDING. Специальное значение crypto.constants.RSA_PSS_SALTLEN_DIGEST задаёт длину соли, равную размеру дайджеста, а crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN (по умолчанию) — максимально допустимое значение.

  • context <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> Для Ed448, ML-DSA и SLH-DSA этот параметр задаёт необязательный контекст, позволяющий различать подписи, созданные для разных целей с использованием одного ключа.

Если указана функция callback, эта функция использует пул потоков libuv.

crypto.subtle

Добавлено в: v17.4.0
  • Тип: <SubtleCrypto>

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

crypto.timingSafeEqual(a, b)

История
Версия Изменения
v15.0.0

Аргументы a и b также могут быть объектами ArrayBuffer.
v6.6.0

Добавлено в: v6.6.0
  • a <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
  • b <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
  • Возвращает: <boolean>

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

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

И a, и b должны быть объектами Buffer, TypedArray или DataView одинаковой длины в байтах. Если длина a и b в байтах различается, возникает ошибка.

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

Если оба входных значения являются объектами Float32Array или Float64Array, эта функция может вернуть неожиданные результаты из-за кодирования чисел с плавающей запятой по стандарту IEEE 754. В частности, ни x === y, ни Object.is(x, y) не означают, что байтовые представления двух чисел с плавающей запятой x и y равны.

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

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

История
Версия Изменения
v24.8.0

Добавлена поддержка контекстного параметра ML-DSA, Ed448 и SLH-DSA.
v24.8.0

Добавлена поддержка проверки подписей SLH-DSA.
v24.6.0

Добавлена поддержка проверки подписей ML-DSA.
v18.0.0

Передача недопустимой функции обратного вызова в аргумент callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v15.12.0

Добавлен необязательный аргумент функции обратного вызова.
v15.0.0

Аргументы data, key и signature также могут быть объектами ArrayBuffer.
v13.2.0, v12.16.0

Эта функция теперь поддерживает подписи DSA и ECDSA в формате IEEE-P1363.
v12.0.0

Добавлено в: v12.0.0
  • algorithm <string> | <null> | <undefined>
  • data <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
  • key <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
  • signature <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
  • callback <Function>
    • err <Error>
    • result <boolean>
  • Возвращает: <boolean> true или false в зависимости от корректности подписи для данных и открытого ключа, если функция callback не указана.

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

Для Ed25519, Ed448 и ML-DSA значение algorithm должно быть null или undefined.

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

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

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

  • padding <integer> Необязательное значение дополнения для RSA; может принимать одно из следующих значений:

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

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

  • saltLength <integer> Длина соли, если используется дополнение RSA_PKCS1_PSS_PADDING. Специальное значение crypto.constants.RSA_PSS_SALTLEN_DIGEST задаёт длину соли, равную размеру дайджеста, а crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN (по умолчанию) — максимально допустимое значение.

  • context <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> Для Ed448, ML-DSA и SLH-DSA этот параметр задаёт необязательный контекст, позволяющий различать подписи, созданные для разных целей с использованием одного ключа.

Аргумент signature — это предварительно вычисленная подпись для data.

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

Если указана функция callback, эта функция использует пул потоков libuv.

crypto.webcrypto

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

Тип: <Crypto> Реализация стандарта Web Crypto API.

Подробности см. в документации Web Crypto API.

Примечания

Использование строк в качестве входных данных для криптографических API

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

При передаче строк в криптографические API учитывайте следующие факторы.

  • Не все последовательности байтов являются допустимыми строками UTF-8. Поэтому, если из строки получается последовательность байтов длиной n, её энтропия обычно ниже энтропии случайной или псевдослучайной последовательности байтов n. Например, ни одна строка UTF-8 не даст последовательность байтов c0 af. Секретные ключи почти всегда должны представлять собой случайные или псевдослучайные последовательности байтов.

  • Аналогично, при преобразовании случайных или псевдослучайных последовательностей байтов в строки UTF-8 подстроки, не представляющие допустимые кодовые точки, могут заменяться символом замены Юникода (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 не нормализует представления символов. Перед передачей пользовательских данных в криптографические API разработчикам следует рассмотреть возможность применения метода String.prototype.normalize().

Устаревший API потоков (до Node.js 0.10)

Модуль Crypto был добавлен в Node.js до появления концепции унифицированного API потоков и до появления объектов Buffer для обработки двоичных данных. Поэтому многие классы crypto имеют методы, обычно не встречающиеся в других классах Node.js, реализующих API потоков (например, update(), final() или digest()). Кроме того, многие методы по умолчанию принимали и возвращали строки в кодировке 'latin1' вместо объектов Buffer. В Node.js 0.9.3 это значение по умолчанию было изменено: теперь по умолчанию используются объекты Buffer.

Поддержка слабых или скомпрометированных алгоритмов

Модуль node:crypto по-прежнему поддерживает некоторые уже скомпрометированные алгоритмы, использование которых не рекомендуется. API также позволяет использовать шифры и хеш-функции с малым размером ключа, недостаточным для безопасного применения.

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

Согласно рекомендациям NIST SP 800-131A:

  • MD5 и SHA-1 больше не считаются приемлемыми там, где требуется устойчивость к коллизиям, например для цифровых подписей.
  • Для безопасного использования в течение нескольких лет рекомендуется, чтобы размер ключа для алгоритмов RSA, DSA и DH составлял не менее 2048 бит, а размер кривой для ECDSA и ECDH — не менее 224 бит.
  • Группы DH modp1, modp2 и modp5 имеют размер ключа менее 2048 бит и не рекомендуются к использованию.

Дополнительные рекомендации и подробности см. в справочном документе.

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

Режим CCM

CCM — один из поддерживаемых алгоритмов AEAD. Приложения, использующие этот режим, должны соблюдать определённые ограничения при работе с API шифров:

  • Длина тега аутентификации должна быть задана при создании шифра с помощью параметра authTagLength и составлять 4, 6, 8, 10, 12, 14 или 16 байт.
  • Длина вектора инициализации (nonce) N должна составлять от 7 до 13 байт (7 ≤ N ≤ 13).
  • Длина открытого текста ограничена значением 2 ** (8 * (15 - N)) байт.
  • При расшифровании тег аутентификации необходимо задать с помощью setAuthTag() до вызова update(). В противном случае расшифрование завершится с ошибкой, а final() вызовет исключение в соответствии с разделом 2.6 документа RFC 3610.
  • Использование потоковых методов, таких как write(data), end(data) или pipe(), в режиме CCM может завершиться ошибкой, поскольку CCM не может обрабатывать более одного блока данных на экземпляр.
  • При передаче дополнительных аутентифицированных данных (AAD) длину фактического сообщения в байтах необходимо передать в setAAD() с помощью параметра plaintextLength. Многие криптографические библиотеки включают тег аутентификации в зашифрованный текст, поэтому создаваемые ими зашифрованные тексты имеют длину plaintextLength + authTagLength. Node.js не включает тег аутентификации, поэтому длина зашифрованного текста всегда равна plaintextLength. Это не требуется, если AAD не используется.
  • Поскольку CCM обрабатывает сообщение целиком за один раз, update() необходимо вызвать ровно один раз.
  • Хотя для шифрования или расшифрования сообщения достаточно вызвать update(), приложения должны вызвать final(), чтобы вычислить тег аутентификации или проверить его.
Модули JavaScript
import { Buffer } from 'node:buffer';
const {
  createCipheriv,
  createDecipheriv,
  randomBytes,
} = await import('node:crypto');

const key = 'keykeykeykeykeykeykeykey';
const nonce = randomBytes(12);

const aad = Buffer.from('0123456789', 'hex');

const cipher = createCipheriv('aes-192-ccm', key, nonce, {
  authTagLength: 16,
});
const plaintext = 'Hello world';
cipher.setAAD(aad, {
  plaintextLength: Buffer.byteLength(plaintext),
});
const ciphertext = cipher.update(plaintext, 'utf8');
cipher.final();
const tag = cipher.getAuthTag();

// Now transmit { ciphertext, nonce, tag }.

const decipher = createDecipheriv('aes-192-ccm', key, nonce, {
  authTagLength: 16,
});
decipher.setAuthTag(tag);
decipher.setAAD(aad, {
  plaintextLength: ciphertext.length,
});
const receivedPlaintext = decipher.update(ciphertext, null, 'utf8');

try {
  decipher.final();
} catch (err) {
  throw new Error('Authentication failed!', { cause: err });
}

console.log(receivedPlaintext);
CommonJS
const { Buffer } = require('node:buffer');
const {
  createCipheriv,
  createDecipheriv,
  randomBytes,
} = require('node:crypto');

const key = 'keykeykeykeykeykeykeykey';
const nonce = randomBytes(12);

const aad = Buffer.from('0123456789', 'hex');

const cipher = createCipheriv('aes-192-ccm', key, nonce, {
  authTagLength: 16,
});
const plaintext = 'Hello world';
cipher.setAAD(aad, {
  plaintextLength: Buffer.byteLength(plaintext),
});
const ciphertext = cipher.update(plaintext, 'utf8');
cipher.final();
const tag = cipher.getAuthTag();

// Now transmit { ciphertext, nonce, tag }.

const decipher = createDecipheriv('aes-192-ccm', key, nonce, {
  authTagLength: 16,
});
decipher.setAuthTag(tag);
decipher.setAAD(aad, {
  plaintextLength: ciphertext.length,
});
const receivedPlaintext = decipher.update(ciphertext, null, 'utf8');

try {
  decipher.final();
} catch (err) {
  throw new Error('Authentication failed!', { cause: err });
}

console.log(receivedPlaintext);

Режим FIPS

При использовании OpenSSL 3 Node.js поддерживает FIPS 140-2 при наличии соответствующего поставщика OpenSSL 3, например поставщика FIPS для OpenSSL 3, который можно установить, следуя инструкциям в файле README по FIPS для OpenSSL.

Для поддержки FIPS в Node.js необходимы:

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

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

nodejs_conf = nodejs_init

.include /<absolute path>/fipsmodule.cnf

[nodejs_init]
providers = provider_sect

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

[default_sect]
activate = 1 copy

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

openssl fipsinstall copy

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

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

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

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

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

nodejs_conf = nodejs_init

.include /<absolute path>/fipsmodule.cnf

[nodejs_init]
providers = provider_sect
alg_section = algorithm_sect

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

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes copy

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

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

Параметры OpenSSL

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

Константа Описание
SSL_OP_ALL Применяет несколько обходных решений для ошибок в OpenSSL. Подробнее см. на странице https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set_options.html.
SSL_OP_ALLOW_NO_DHE_KEX Указывает OpenSSL разрешить режим обмена ключами, не основанный на [EC]DHE, для TLS v1.3
SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION Разрешает устаревшее небезопасное повторное согласование между OpenSSL и клиентами или серверами без исправлений. См. https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set_options.html.
SSL_OP_CIPHER_SERVER_PREFERENCE При выборе шифра пытается использовать предпочтения сервера вместо предпочтений клиента. Поведение зависит от версии протокола. См. https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set_options.html.
SSL_OP_CISCO_ANYCONNECT Указывает OpenSSL использовать идентификатор версии DTLS_BAD_VER от Cisco.
SSL_OP_COOKIE_EXCHANGE Указывает OpenSSL включить обмен cookie.
SSL_OP_CRYPTOPRO_TLSEXT_BUG Указывает OpenSSL добавить расширение server-hello из ранней версии черновика cryptopro.
SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS Указывает OpenSSL отключить обходное решение уязвимости SSL 3.0/TLS 1.0, добавленное в OpenSSL 0.9.6d.
SSL_OP_LEGACY_SERVER_CONNECT Разрешает первоначальное подключение к серверам, не поддерживающим RI.
SSL_OP_NO_COMPRESSION Указывает OpenSSL отключить поддержку сжатия SSL/TLS.
SSL_OP_NO_ENCRYPT_THEN_MAC Указывает OpenSSL отключить encrypt-then-MAC.
SSL_OP_NO_QUERY_MTU
SSL_OP_NO_RENEGOTIATION Указывает OpenSSL отключить повторное согласование.
SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION Указывает OpenSSL всегда начинать новый сеанс при повторном согласовании.
SSL_OP_NO_SSLv2 Указывает OpenSSL отключить SSL v2
SSL_OP_NO_SSLv3 Указывает OpenSSL отключить SSL v3
SSL_OP_NO_TICKET Указывает OpenSSL отключить использование билетов RFC4507bis.
SSL_OP_NO_TLSv1 Указывает OpenSSL отключить TLS v1
SSL_OP_NO_TLSv1_1 Указывает OpenSSL отключить TLS v1.1
SSL_OP_NO_TLSv1_2 Указывает OpenSSL отключить TLS v1.2
SSL_OP_NO_TLSv1_3 Указывает OpenSSL отключить TLS v1.3
SSL_OP_PRIORITIZE_CHACHA Указывает серверу OpenSSL отдавать приоритет ChaCha20-Poly1305, если его выбирает клиент. Этот параметр не действует, если SSL_OP_CIPHER_SERVER_PREFERENCE не включён.
SSL_OP_TLS_ROLLBACK_BUG Указывает OpenSSL отключить обнаружение атак с откатом версии.

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

Константа Описание
ENGINE_METHOD_RSA Ограничивает использование движка алгоритмом RSA
ENGINE_METHOD_DSA Ограничивает использование движка алгоритмом DSA
ENGINE_METHOD_DH Ограничивает использование движка алгоритмом DH
ENGINE_METHOD_RAND Ограничивает использование движка генератором RAND
ENGINE_METHOD_EC Ограничивает использование движка алгоритмом EC
ENGINE_METHOD_CIPHERS Ограничивает использование движка шифрами CIPHERS
ENGINE_METHOD_DIGESTS Ограничивает использование движка функциями дайджеста DIGESTS
ENGINE_METHOD_PKEY_METHS Ограничивает использование движка методами PKEY_METHS
ENGINE_METHOD_PKEY_ASN1_METHS Ограничивает использование движка методами PKEY_ASN1_METHS
ENGINE_METHOD_ALL
ENGINE_METHOD_NONE

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

Константа Описание
DH_CHECK_P_NOT_SAFE_PRIME
DH_CHECK_P_NOT_PRIME
DH_UNABLE_TO_CHECK_GENERATOR
DH_NOT_SUITABLE_GENERATOR
RSA_PKCS1_PADDING
RSA_SSLV23_PADDING
RSA_NO_PADDING
RSA_PKCS1_OAEP_PADDING
RSA_X931_PADDING
RSA_PKCS1_PSS_PADDING
RSA_PSS_SALTLEN_DIGEST При подписании или проверке подписи задаёт длину соли для RSA_PKCS1_PSS_PADDING равной размеру дайджеста.
RSA_PSS_SALTLEN_MAX_SIGN При подписании данных задаёт для RSA_PKCS1_PSS_PADDING максимально допустимую длину соли.
RSA_PSS_SALTLEN_AUTO При проверке подписи длина соли для RSA_PKCS1_PSS_PADDING определяется автоматически.
POINT_CONVERSION_COMPRESSED
POINT_CONVERSION_UNCOMPRESSED
POINT_CONVERSION_HYBRID

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

Константа Описание
defaultCoreCipherList Задаёт встроенный список шифров Node.js, используемый по умолчанию.
defaultCipherList Задаёт активный список шифров по умолчанию, используемый текущим процессом Node.js.

Сноски

  1. Требуется OpenSSL >= 3.5 ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8 ↩9 ↩10 ↩11 ↩12 ↩13 ↩14 ↩15 ↩16 ↩17 ↩18 ↩19 ↩20 ↩21 ↩22 ↩23 ↩24

  2. Требуется OpenSSL >= 3.0 ↩ ↩2

  3. Требуется OpenSSL >= 3.2 ↩ ↩2 ↩3 ↩4 ↩5 ↩6

© Joyent, Inc. and other Node contributors
Licensed under the MIT License.
Node.js is a trademark of Joyent, Inc. and is used with its permission.
We are not endorsed by or affiliated with Joyent.
https://nodejs.org/dist/latest-v24.x/docs/api/crypto.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API