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

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

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

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

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

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

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

Класс: Certificate

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

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

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

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

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

MJS модули

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

CJS модули

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

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

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

MJS модули

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

CJS модули

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

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

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

MJS модули

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

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

CJS модули

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

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

Устаревший API

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

new crypto.Certificate()

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

MJS модули

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

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

CJS модули

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

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

certificate.exportChallenge(spkac[, encoding])

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

MJS модули

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

CJS модули

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

certificate.exportPublicKey(spkac[, encoding])

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

MJS модули

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

CJS модули

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

certificate.verifySpkac(spkac[, encoding])

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

MJS модули

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

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

CJS модули

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

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

Класс: Cipher

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

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

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

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

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

Модули MJS

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

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

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

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

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

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

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

Модули CJS

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

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

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

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

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

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

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

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

Модули MJS

import {
  createReadStream,
  createWriteStream,
} from 'node:fs';

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

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

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

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

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

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

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

Модули CJS

const {
  createReadStream,
  createWriteStream,
} = require('node:fs');

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

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

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

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

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

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

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

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

Модули MJS

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

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

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

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

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

Модули CJS

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

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

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

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

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

cipher.final([outputEncoding])

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

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

cipher.getAuthTag()

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

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

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

cipher.setAAD(buffer[, options])

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

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

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

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

cipher.setAutoPadding([autoPadding])

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

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

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

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

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

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

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

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

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

Класс: Decipher

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

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

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

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

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

Модули MJS

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

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

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

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

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

Модули CJS

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

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

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

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

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

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

Модули MJS

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

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

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

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

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

Модули CJS

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

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

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

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

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

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

Модули MJS

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

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

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

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

Модули CJS

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

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

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

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

decipher.final([outputEncoding])

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

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

decipher.setAAD(buffer[, options])

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

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

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

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

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

decipher.setAuthTag(buffer[, encoding])

• buffer <строка> | <Буфер> | <ArrayBuffer> | <TypedArray> | <DataView>
• encoding <строка> Кодировка строки, используемая, когда buffer является строкой.
• Возвращает: <Расшифровка> Тот же Decipher для цепочки методов.

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

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

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

decipher.setAutoPadding([autoPadding])

• autoPadding <логическое значение> По умолчанию: true
• Возвращает: <Расшифровка> Тот же Decipher для цепочки методов.

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

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

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

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

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

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

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

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

Класс: DiffieHellman

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

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

Модули MJS

import assert from 'node:assert';

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

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

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

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

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

Модули CJS

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

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

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

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

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

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

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

• otherPublicKey <строка> | <ArrayBuffer> | <Буфер> | <Массив с плавающей точкой> | <DataView>
• inputEncoding <строка> Кодировка строки otherPublicKey.
• outputEncoding <строка> Кодировка возвращаемого значения.
• Возвращает: <Буфер> | <строка>

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

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

diffieHellman.generateKeys([encoding])

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

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

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

diffieHellman.getGenerator([encoding])

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

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

diffieHellman.getPrime([encoding])

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

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

diffieHellman.getPrivateKey([encoding])

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

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

diffieHellman.getPublicKey([encoding])

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

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

diffieHellman.setPrivateKey(privateKey[, encoding])

• privateKey <строка> | <ArrayBuffer> | <Буфер> | <Массив с плавающей точкой> | <DataView>
• encoding <строка> Кодировка строки privateKey.

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

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

diffieHellman.setPublicKey(publicKey[, encoding])

• publicKey <строка> | <ArrayBuffer> | <Буфер> | <Массив с плавающей точкой> | <DataView>
• encoding <строка> Кодировка строки publicKey.

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

diffieHellman.verifyError

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

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

• DH_CHECK_P_NOT_SAFE_PRIME
• DH_CHECK_P_NOT_PRIME
• DH_UNABLE_TO_CHECK_GENERATOR
• DH_NOT_SUITABLE_GENERATOR

Класс: DiffieHellmanGroup

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

Модули MJS

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

Модули CJS

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

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

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

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

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

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

Класс: ECDH

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

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

Модули MJS

import assert from 'node:assert';

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

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

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

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

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

Модули CJS

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

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

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

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

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

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

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

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

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

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

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

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

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

Модули MJS

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

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

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

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

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

Модули CJS

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ecdh.getPrivateKey([encoding])

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

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

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

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

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

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

ecdh.setPrivateKey(privateKey[, encoding])

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

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

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

ecdh.setPublicKey(publicKey[, encoding])

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

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

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

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

МОДУЛИ MJS

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

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

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

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

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

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

Модули CJS

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

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

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

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

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

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

Класс: Hash

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

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

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

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

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

МОДУЛИ MJS

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

const hash = createHash('sha256');

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

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

Модули CJS

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

const hash = createHash('sha256');

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

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

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

МОДУЛИ MJS

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

const hash = createHash('sha256');

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

Модули CJS

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

const hash = createHash('sha256');

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

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

МОДУЛИ MJS

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

const hash = createHash('sha256');

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

Модули CJS

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

const hash = createHash('sha256');

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

hash.copy([options])

• options <Объект> stream.transform опции
• Возвращает: <Хэш>

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

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

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

МОДУЛИ MJS

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

const hash = createHash('sha256');

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

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

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

// Etc.

Модули CJS

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

const hash = createHash('sha256');

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

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

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

// Etc.

hash.digest([encoding])

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

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

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

hash.update(data[, inputEncoding])

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

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

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

Класс: Hmac

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

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

• В качестве потока, который является одновременно читаемым и записываемым, где данные записываются для вычисления хэш-суммы HMAC на стороне чтения, или
• Используя методы hmac.update() и hmac.digest() для вычисления хэш-суммы HMAC.

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

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

Модули MJS

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

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

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

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

Модули CJS

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

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

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

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

Пример: использование Hmac и потоков со связью через pipe:

Модули MJS

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

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

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

Модули CJS

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

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

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

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

Модули MJS

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

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

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

Модули CJS

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

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

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

hmac.digest([encoding])

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

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

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

hmac.update(data[, inputEncoding])

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

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

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

Класс: KeyObject

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

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

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

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

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

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

Модули MJS

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

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

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

Модули CJS

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

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

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

keyObject.asymmetricKeyDetails

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

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

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

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

keyObject.asymmetricKeyType

• <строка>

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

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

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

keyObject.export([options])

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

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

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

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

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

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

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

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

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

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

keyObject.equals(otherKeyObject)

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

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

keyObject.symmetricKeySize

• <число>

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

keyObject.type

• <строка>

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

Класс: Sign

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

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

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

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

Пример: используя объекты Sign и Verify как потоки:

MJS модули

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

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

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

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

CJS модули

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

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

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

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

Пример: используя методы sign.update() и verify.update():

MJS модули

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

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

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

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

CJS модули

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

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

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

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

sign.sign(privateKey[, outputEncoding])

• privateKey <Объект> | <строка> | <ArrayBuffer> | <Буфер> | <Массив типов данных> | <DataView> | <Объект ключа> | <Ключ Crypto>
  • dsaEncoding <строка>
  • padding <целое число>
  • saltLength <целое число>
• outputEncoding <строка> Кодировка возвращаемого значения.
• Возвращает: <Буфер> | <строка>

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

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

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

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

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

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

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

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

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

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

sign.update(data[, inputEncoding])

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

Обновляет содержимое Sign с помощью предоставленных данных data, кодировка которых указана в inputEncoding.

Если encoding не предоставлен, а data — строка, используется кодировка 'utf8'.

Если data — Buffer, TypedArray, или DataView, то inputEncoding игнорируется.

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

Класс: Verify

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

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

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

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

Примеры см. в Sign.

verify.update(data[, inputEncoding])

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

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

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

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

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

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

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

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

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

• padding <целое число> Дополнительное значение заполнения для RSA. Возможные значения:

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

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

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

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

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

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

Класс: X509Certificate

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

Модули MJS

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

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

console.log(x509.subject);

Модули CJS

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

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

console.log(x509.subject);

new X509Certificate(buffer)

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

x509.ca

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

x509.checkEmail(email[, options])

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

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

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

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

Если параметр 'subject' установлен в 'never', поле subject сертификата никогда не рассматривается, даже если сертификат не содержит расширений Subject Alternative Names.

x509.checkHost(name[, options])

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

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

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

Если параметр 'subject' не определен или установлен в 'default', поле subject сертификата рассматривается только в том случае, если расширение Subject Alternative Name не существует или не содержит имён DNS. Это поведение соответствует RFC 2818 ("HTTP Over TLS").

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

Если параметр 'subject' установлен в 'never', поле subject сертификата никогда не рассматривается, даже если сертификат не содержит расширений Subject Alternative Names.

x509.checkIP(ip)

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

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

Рассматриваются только расширения Subject Alternative Name по RFC 5280, и они должны точно соответствовать заданному IP-адресу. Другие расширения Subject Alternative Name, а также поле subject сертификата игнорируются.

x509.checkIssued(otherCert)

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

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

x509.checkPrivateKey(privateKey)

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

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

x509.fingerprint

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

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

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

x509.fingerprint256

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

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

x509.fingerprint512

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

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

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

x509.infoAccess

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

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

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

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

x509.issuer

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

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

x509.issuerCertificate

• Тип: <X509Certificate>

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

x509.extKeyUsage

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

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

x509.publicKey

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

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

x509.raw

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

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

x509.serialNumber

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

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

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

x509.subject

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

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

x509.subjectAltName

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

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

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

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

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

x509.toJSON()

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

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

x509.toLegacyObject()

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

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

x509.toString()

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

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

x509.validFrom

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

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

x509.validTo

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

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

x509.verify(publicKey)

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

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

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

crypto.constants

• <Объект>

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

crypto.fips

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

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

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

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

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

crypto.checkPrimeSync(candidate[, options])

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• algorithm <строка>
• key <строка> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
• iv <Объект> stream.transform параметры
• Возвращает: <Decipher>

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

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

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

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

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

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

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

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

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

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

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

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

crypto.createDiffieHellman(primeLength[, generator])

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

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

crypto.createDiffieHellmanGroup(name)

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

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

crypto.createECDH(curveName)

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

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

crypto.createHash(algorithm[, options])

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

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

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

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

Модули MJS

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

const filename = argv[2];

const hash = createHash('sha256');

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

Модули CJS

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

const filename = argv[2];

const hash = createHash('sha256');

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

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

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

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

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

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

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

Модули MJS

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

const filename = argv[2];

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

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

Модули CJS

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

const filename = argv[2];

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

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

crypto.createPrivateKey(key)

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

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

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

crypto.createPublicKey(key)

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

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

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

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

crypto.createSecretKey(key[, encoding])

• key <строка> | <ArrayBuffer> | <Буфер> | <TypedArray> | <DataView>
• encoding <строка> Кодировка строки, когда key является строкой.
• Возвращает: <Объект ключа>

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

crypto.createSign(algorithm[, options])

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

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

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

crypto.createVerify(algorithm[, options])

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

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

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

crypto.diffieHellman(options)

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

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

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

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

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

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

Пример:

Модули CJS

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

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

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

Модули MJS

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

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

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

crypto.generateKey(type, options, callback)

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

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

Модули MJS

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

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

Модули CJS

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

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

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

crypto.generateKeyPair(type, options, callback)

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

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

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

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

Модули MJS

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

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

Модули CJS

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

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

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

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

crypto.generateKeyPairSync(type, options)

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

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

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

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

Модули MJS

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

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

Модули CJS

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

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

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

crypto.generateKeySync(type, options)

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

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

Модули MJS

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

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

Модули CJS

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

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

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

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

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

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

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

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

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

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

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

crypto.generatePrimeSync(size[, options])

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

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

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

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

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

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

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

crypto.getCipherInfo(nameOrNid[, options])

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

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

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

crypto.getCiphers()

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

Модули MJS

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

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

Модули CJS

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

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

crypto.getCurves()

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

Модули MJS

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

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

Модули CJS

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

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

crypto.getDiffieHellman(groupName)

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

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

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

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

Модули MJS

const {
  getDiffieHellman,
} = await import('node:crypto');
const alice = getDiffieHellman('modp14');
const bob = getDiffieHellman('modp14');

alice.generateKeys();
bob.generateKeys();

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

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

Модули CJS

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

const alice = getDiffieHellman('modp14');
const bob = getDiffieHellman('modp14');

alice.generateKeys();
bob.generateKeys();

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

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

crypto.getFips()

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

crypto.getHashes()

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

Модули MJS

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

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

Модули CJS

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

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

crypto.getRandomValues(typedArray)

• typedArray <Буфер> | <Тип массива> | <DataView> | <Объект ArrayBuffer>
• Возвращает: <Буфер> | <Тип массива> | <DataView> | <Объект ArrayBuffer> Возвращает typedArray.

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

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

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

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

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

Модули MJS

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

hkdf('sha512', 'key', 'salt', 'info', 64, (err, derivedKey) => {
  if (err) throw err;
  console.log(Buffer.from(derivedKey).toString('hex'));  // '24156e2...5391653'
});

Модули CJS

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

hkdf('sha512', 'key', 'salt', 'info', 64, (err, derivedKey) => {
  if (err) throw err;
  console.log(Buffer.from(derivedKey).toString('hex'));  // '24156e2...5391653'
});

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

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

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

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

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

Модули MJS

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

const derivedKey = hkdfSync('sha512', 'key', 'salt', 'info', 64);
console.log(Buffer.from(derivedKey).toString('hex'));  // '24156e2...5391653'

Модули CJS

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

const derivedKey = hkdfSync('sha512', 'key', 'salt', 'info', 64);
console.log(Buffer.from(derivedKey).toString('hex'));  // '24156e2...5391653'

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

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

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

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

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

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

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

Модули MJS

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

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

Модули CJS

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

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

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

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

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

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

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

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

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

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

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

Модули MJS

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

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

Модули CJS

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

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

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

crypto.privateDecrypt(privateKey, buffer)

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

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

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

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

crypto.privateEncrypt(privateKey, buffer)

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

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

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

crypto.publicDecrypt(key, buffer)

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

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

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

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

crypto.publicEncrypt(key, buffer)

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

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

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

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

crypto.randomBytes(size[, callback])

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

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

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

Модули MJS

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

randomBytes(256, (err, buf) => {
  if (err) throw err;
  console.log(`${buf.length} bytes of random data: ${buf.toString('hex')}`);
});

Модули CJS

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

randomBytes(256, (err, buf) => {
  if (err) throw err;
  console.log(`${buf.length} bytes of random data: ${buf.toString('hex')}`);
});

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

Модули MJS

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

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

Модули CJS

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

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

Метод crypto.randomBytes() завершит свою работу только после того, как будет доступна достаточная энтропия. Это обычно занимает несколько миллисекунд. Единственный случай, когда генерация случайных байтов может занять больше времени, — сразу после загрузки системы, когда система ещё недостаточно обеспечена энтропией.

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

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

crypto.randomFillSync(buffer[, offset][, size])

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

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

Модули MJS

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

const buf = Buffer.alloc(10);
console.log(randomFillSync(buf).toString('hex'));

randomFillSync(buf, 5);
console.log(buf.toString('hex'));

// The above is equivalent to the following:
randomFillSync(buf, 5, 5);
console.log(buf.toString('hex'));

Модули CJS

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

const buf = Buffer.alloc(10);
console.log(randomFillSync(buf).toString('hex'));

randomFillSync(buf, 5);
console.log(buf.toString('hex'));

// The above is equivalent to the following:
randomFillSync(buf, 5, 5);
console.log(buf.toString('hex'));

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

Модули MJS

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

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

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

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

Модули CJS

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

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

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

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

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

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

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

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

Модули MJS

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

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

randomFill(buf, 5, (err, buf) => {
  if (err) throw err;
  console.log(buf.toString('hex'));
});

// The above is equivalent to the following:
randomFill(buf, 5, 5, (err, buf) => {
  if (err) throw err;
  console.log(buf.toString('hex'));
});

Модули CJS

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

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

randomFill(buf, 5, (err, buf) => {
  if (err) throw err;
  console.log(buf.toString('hex'));
});

// The above is equivalent to the following:
randomFill(buf, 5, 5, (err, buf) => {
  if (err) throw err;
  console.log(buf.toString('hex'));
});

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

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

Модули MJS

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

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

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

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

Модули CJS

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

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

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

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

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

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

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

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

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

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

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

Модули MJS

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

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

Модули CJS

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

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

Модули MJS

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

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

Модули CJS

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

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

Модули MJS

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

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

Модули CJS

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

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

crypto.randomUUID([options])

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

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

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

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

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

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

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

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

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

MJS модули

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

// Using the factory defaults.
scrypt('password', 'salt', 64, (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // '3745e48...08d59ae'
});
// Using a custom N parameter. Must be a power of two.
scrypt('password', 'salt', 64, { N: 1024 }, (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // '3745e48...aa39b34'
});

CJS модули

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

// Using the factory defaults.
scrypt('password', 'salt', 64, (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // '3745e48...08d59ae'
});
// Using a custom N parameter. Must be a power of two.
scrypt('password', 'salt', 64, { N: 1024 }, (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // '3745e48...aa39b34'
});

crypto.scryptSync(password, salt, keylen[, options])

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

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

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

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

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

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

MJS-модули

const {
  scryptSync,
} = await import('node:crypto');
// Using the factory defaults.

const key1 = scryptSync('password', 'salt', 64);
console.log(key1.toString('hex'));  // '3745e48...08d59ae'
// Using a custom N parameter. Must be a power of two.
const key2 = scryptSync('password', 'salt', 64, { N: 1024 });
console.log(key2.toString('hex'));  // '3745e48...aa39b34'

CJS-модули

const {
  scryptSync,
} = require('node:crypto');
// Using the factory defaults.

const key1 = scryptSync('password', 'salt', 64);
console.log(key1.toString('hex'));  // '3745e48...08d59ae'
// Using a custom N parameter. Must be a power of two.
const key2 = scryptSync('password', 'salt', 64, { N: 1024 });
console.log(key2.toString('hex'));  // '3745e48...aa39b34'

crypto.secureHeapUsed()

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

crypto.setEngine(engine[, flags])

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

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

engine может быть либо идентификатором, либо путём к общей библиотеке модуля.

Необязательный аргумент flags по умолчанию использует ENGINE_METHOD_ALL. Аргумент flags представляет собой битовую маску, принимающую одно или несколько следующих значений (определены в crypto.constants) или их комбинации:

• crypto.constants.ENGINE_METHOD_RSA
• crypto.constants.ENGINE_METHOD_DSA
• crypto.constants.ENGINE_METHOD_DH
• crypto.constants.ENGINE_METHOD_RAND
• crypto.constants.ENGINE_METHOD_EC
• crypto.constants.ENGINE_METHOD_CIPHERS
• crypto.constants.ENGINE_METHOD_DIGESTS
• crypto.constants.ENGINE_METHOD_PKEY_METHS
• crypto.constants.ENGINE_METHOD_PKEY_ASN1_METHS
• crypto.constants.ENGINE_METHOD_ALL
• crypto.constants.ENGINE_METHOD_NONE

crypto.setFips(bool)

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

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

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

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

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

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

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

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

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

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

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

• saltLength <целое> Длина соли, когда используется заполнение RSA_PKCS1_PSS_PADDING. Специальное значение crypto.constants.RSA_PSS_SALTLEN_DIGEST устанавливает длину соли до размера хеша, crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN (по умолчанию) устанавливает её до максимально допустимого значения.

Если функция callback предоставлена, эта функция использует пул потоков libuv.

crypto.subtle

• Тип: <SubtleCrypto>

Удобный псевдоним для crypto.webcrypto.subtle.

crypto.timingSafeEqual(a, b)

• a <ArrayBuffer> | <Буфер> | <Массив_типизированных_данных> | <DataView>
• b <ArrayBuffer> | <Буфер> | <Массив_типизированных_данных> | <DataView>
• Возвращает: <логическое>

Эта функция сравнивает лежащие в основе байты, представляющие заданные ArrayBuffer, TypedArray, или DataView объекты, используя алгоритм постоянного времени.

Эта функция не раскрывает временную информацию, которая позволила бы злоумышленнику угадать одно из значений. Это подходит для сравнения хэш-кодов HMAC или секретных значений, таких как аутентификационные куки или URL-адреса возможностей.

a и b должны быть Buffer, TypedArray или DataView с одинаковой длиной в байтах. Возникает ошибка, если a и b имеют различную длину в байтах.

Если хотя бы один из a и b является TypedArray с более чем одним байтом на запись, например Uint16Array, результат будет вычислен с использованием порядка байтов платформы.

При использовании в качестве обоих входных данных Float32Array или Float64Array данная функция может возвращать непредсказуемые результаты из-за кодирования чисел с плавающей точкой в соответствии со стандартом IEEE 754. В частности, ни x === y, ни Object.is(x, y) не подразумевают, что байтовые представления двух чисел с плавающей точкой x и y равны.

Использование crypto.timingSafeEqual не гарантирует, что окружающий код является безопасным с точки зрения тайминга. Необходимо позаботиться о том, чтобы окружающий код не вносил уязвимости, связанные с таймингом.

crypto.verify(algorithm, data, key, signature[, callback])

• algorithm <строка> | <null> | <undefined>
• data <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• key <Объект> | <строка> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <Ключ> | <CryptoKey>
• signature <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• callback <Функция>
  • err <Ошибка>
  • result <логический тип>
• Возвращает: <логический тип> true или false в зависимости от валидности подписи для данных и открытого ключа, если функция callback не указана.

Проверяет указанную подпись для data с использованием заданного ключа и алгоритма. Если algorithm является null или undefined, то алгоритм зависит от типа ключа (особенно Ed25519 и Ed448).

Если key не является KeyObject, эта функция ведет себя так, как если бы key было передано в crypto.createPublicKey(). Если это объект, могут быть переданы следующие дополнительные свойства:

• dsaEncoding <строка> Для DSA и ECDSA этот параметр задаёт формат подписи. Он может быть одним из следующих:

  • 'der' (по умолчанию): DER-кодированная структура ASN.1, кодирующая (r, s).
  • 'ieee-p1363': Формат подписи r || s, предложенный в IEEE-P1363.

• padding <целое число> Необязательное значение заполнения для RSA, одно из следующих:

  • crypto.constants.RSA_PKCS1_PADDING (по умолчанию)
  • crypto.constants.RSA_PKCS1_PSS_PADDING

  RSA_PKCS1_PSS_PADDING будет использовать MGF1 с той же функцией хеширования, которая использовалась для подписи сообщения, как указано в разделе 3.1 RFC 4055.

• saltLength <целое число> Длина соли для заполнения RSA_PKCS1_PSS_PADDING. Специальное значение crypto.constants.RSA_PSS_SALTLEN_DIGEST устанавливает длину соли в размер дайджеста, crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN (по умолчанию) устанавливает её в максимально допустимое значение.

Аргумент signature — предварительно вычисленная подпись для data.

Так как открытые ключи могут быть получены из закрытых, для key может быть передан закрытый или открытый ключ.

Если функция callback указана, функция использует пул потоков libuv.

crypto.webcrypto

Тип: <Crypto> Реализация стандарта Web Crypto API.

Подробности см. в документации Web Crypto API.

Примечания

Использование строк в качестве входных данных для криптографических API

По историческим причинам многие криптографические API, предоставляемые Node.js, принимают строки в качестве входных данных, тогда как лежащий в основе криптографический алгоритм работает с последовательностями байтов. К таким случаям относятся открытые тексты, шифрованные тексты, симметричные ключи, векторы инициализации, пароли, соли, теги аутентификации и дополнительные данные аутентификации.

При передаче строк в криптографические API следует учитывать следующие факторы.

• Не все последовательности байтов являются допустимыми строками UTF-8. Поэтому, когда последовательность байтов длиной n получена из строки, её энтропия, как правило, ниже, чем энтропия случайной или псевдослучайной n последовательности байтов. Например, ни одна строка UTF-8 не приведет к последовательности байтов c0 af. Секретные ключи практически всегда должны быть случайными или псевдослучайными последовательностями байтов.

• Аналогично, при преобразовании случайных или псевдослучайных последовательностей байтов в строки UTF-8, подпоследовательности, которые не представляют собой допустимые кодовые точки, могут быть заменены универсальным символом замены (U+FFFD). Таким образом, байтовое представление результирующей строки Unicode может не совпадать с последовательностью байтов, из которой была создана строка.

  const original = [0xc0, 0xaf];
  const bytesAsString = Buffer.from(original).toString('utf8');
  const stringAsBytes = Buffer.from(bytesAsString, 'utf8');
  console.log(stringAsBytes);
  // Prints '<Buffer ef bf bd ef bf bd>'. copy

  Результаты работы шифров, хэш-функций, алгоритмов подписи и функций вывода ключей — это псевдослучайные последовательности байтов, и их не следует использовать в качестве строк Unicode.

• Когда строки получены из пользовательского ввода, некоторые символы Unicode могут быть представлены несколькими эквивалентными способами, что приводит к различным последовательностям байтов. Например, при передаче пользовательского пароля функции вывода ключей, такой как PBKDF2 или scrypt, результат функции вывода ключей зависит от того, используются ли составные или разложенные символы. Node.js не нормализует представления символов. Разработчики должны рассмотреть возможность использования String.prototype.normalize() для пользовательского ввода перед передачей его в криптографические API.

API потоков устаревшего типа (до Node.js 0.10)

Модуль Crypto был добавлен в Node.js до появления понятия унифицированного API потоков и до появления объектов Buffer для обработки двоичных данных. Таким образом, многие crypto классы имеют методы, нетипичные для других классов Node.js, которые реализуют API потоков streams (например, update(), final(), или digest()). Кроме того, многие методы по умолчанию принимали и возвращали закодированные строки 'latin1', а не объекты Buffer. Этот параметр по умолчанию был изменён после Node.js v0.8 на использование объектов Buffer по умолчанию.

Поддержка слабых или скомпрометированных алгоритмов

Модуль node:crypto по-прежнему поддерживает некоторые алгоритмы, которые уже скомпрометированы и не рекомендуются к использованию. API также позволяет использовать шифры и хэши с небольшим размером ключа, которые слишком слабые для безопасного использования.

Пользователи должны нести полную ответственность за выбор криптографического алгоритма и размера ключа в соответствии с требованиями безопасности.

В соответствии с рекомендациями NIST SP 800-131A:

• MD5 и SHA-1 больше не приемлемы, где требуется устойчивость к коллизиям, например, при цифровых подписях.
• Рекомендуется, чтобы ключ, используемый с алгоритмами RSA, DSA и DH, имел как минимум 2048 бит, а ключ кривой ECDSA и ECDH — как минимум 224 бита, для безопасного использования на протяжении нескольких лет.
• Группы DH modp1, modp2 и modp5 имеют размер ключа меньше 2048 бит и не рекомендуются.

См. справку для получения других рекомендаций и подробностей.

Некоторые алгоритмы, имеющие известные уязвимости и имеющие мало практического значения, доступны только через устаревший провайдер, который по умолчанию отключён.

Режим CCM

CCM — один из поддерживаемых алгоритмов AEAD. Приложения, использующие этот режим, должны соблюдать определённые ограничения при использовании API шифрования:

• Длина тега аутентификации должна быть указана при создании шифра, установив параметр authTagLength, и должна быть равна 4, 6, 8, 10, 12, 14 или 16 байтам.
• Длина вектора инициализации (nonce) N должна быть от 7 до 13 байтов (7 ≤ N ≤ 13).
• Длина открытого текста ограничена 2 ** (8 * (15 - N)) байтами.
• При дешифровании тег аутентификации должен быть установлен с помощью setAuthTag() перед вызовом update(). В противном случае дешифрование завершится неудачно, и final() выбросит ошибку в соответствии со разделом 2.6 RFC 3610.
• Использование методов потока, таких как write(data), end(data) или pipe() в режиме CCM может завершиться ошибкой, так как CCM не может обработать более одного фрагмента данных за раз.
• При передаче дополнительных данных аутентификации (AAD) длина фактического сообщения в байтах должна быть передана setAAD() с помощью параметра plaintextLength. Многие библиотеки криптографии включают тег аутентификации в шифрованный текст, что означает, что они создают шифрованный текст длиной plaintextLength + authTagLength. Node.js не включает тег аутентификации, поэтому длина шифрованного текста всегда равна plaintextLength. Это не требуется, если не используется AAD.
• Поскольку CCM обрабатывает всё сообщение сразу, update() должен вызываться ровно один раз.
• Хотя вызов update() достаточно для шифрования/дешифрования сообщения, приложения обязаны вызвать final() для вычисления или проверки тега аутентификации.

Модули MJS

import { Buffer } from 'node:buffer';
const {
  createCipheriv,
  createDecipheriv,
  randomBytes,
} = await import('node:crypto');

const key = 'keykeykeykeykeykeykeykey';
const nonce = randomBytes(12);

const aad = Buffer.from('0123456789', 'hex');

const cipher = createCipheriv('aes-192-ccm', key, nonce, {
  authTagLength: 16,
});
const plaintext = 'Hello world';
cipher.setAAD(aad, {
  plaintextLength: Buffer.byteLength(plaintext),
});
const ciphertext = cipher.update(plaintext, 'utf8');
cipher.final();
const tag = cipher.getAuthTag();

// Now transmit { ciphertext, nonce, tag }.

const decipher = createDecipheriv('aes-192-ccm', key, nonce, {
  authTagLength: 16,
});
decipher.setAuthTag(tag);
decipher.setAAD(aad, {
  plaintextLength: ciphertext.length,
});
const receivedPlaintext = decipher.update(ciphertext, null, 'utf8');

try {
  decipher.final();
} catch (err) {
  throw new Error('Authentication failed!', { cause: err });
}

console.log(receivedPlaintext);

Модули CJS

const { Buffer } = require('node:buffer');
const {
  createCipheriv,
  createDecipheriv,
  randomBytes,
} = require('node:crypto');

const key = 'keykeykeykeykeykeykeykey';
const nonce = randomBytes(12);

const aad = Buffer.from('0123456789', 'hex');

const cipher = createCipheriv('aes-192-ccm', key, nonce, {
  authTagLength: 16,
});
const plaintext = 'Hello world';
cipher.setAAD(aad, {
  plaintextLength: Buffer.byteLength(plaintext),
});
const ciphertext = cipher.update(plaintext, 'utf8');
cipher.final();
const tag = cipher.getAuthTag();

// Now transmit { ciphertext, nonce, tag }.

const decipher = createDecipheriv('aes-192-ccm', key, nonce, {
  authTagLength: 16,
});
decipher.setAuthTag(tag);
decipher.setAAD(aad, {
  plaintextLength: ciphertext.length,
});
const receivedPlaintext = decipher.update(ciphertext, null, 'utf8');

try {
  decipher.final();
} catch (err) {
  throw new Error('Authentication failed!', { cause: err });
}

console.log(receivedPlaintext);

Режим FIPS

При использовании OpenSSL 3, Node.js поддерживает FIPS 140-2 при использовании соответствующего провайдера OpenSSL 3, например, провайдер FIPS из OpenSSL 3, который можно установить, следуя инструкциям в файле README FIPS OpenSSL.

Для поддержки FIPS в Node.js потребуется:

• Правильно установленный провайдер FIPS OpenSSL 3.
• Файл конфигурации модуля FIPS OpenSSL 3 FIPS module configuration file.
• Файл конфигурации OpenSSL 3, который ссылается на файл конфигурации модуля FIPS.

Node.js потребуется настроить с файлом конфигурации OpenSSL, который указывает на провайдер FIPS. Пример файла конфигурации выглядит следующим образом:

nodejs_conf = nodejs_init

.include /<absolute path>/fipsmodule.cnf

[nodejs_init]
providers = provider_sect

[provider_sect]
default = default_sect
# The fips section name should match the section name inside the
# included fipsmodule.cnf.
fips = fips_sect

[default_sect]
activate = 1 copy

где fipsmodule.cnf — это файл конфигурации модуля FIPS, сгенерированный на этапе установки провайдера FIPS:

openssl fipsinstall copy

Установите переменную среды OPENSSL_CONF для указания на ваш файл конфигурации и OPENSSL_MODULES для указания расположения динамической библиотеки провайдера FIPS. Например:

export OPENSSL_CONF=/<path to configuration file>/nodejs.cnf
export OPENSSL_MODULES=/<path to openssl lib>/ossl-modules copy

Затем режим FIPS можно включить в Node.js, выполнив следующие действия:

• Запустить Node.js с флагами командной строки --enable-fips или --force-fips.
• Вызвать crypto.setFips(true) программно.

По желанию, режим FIPS можно включить в Node.js через файл конфигурации OpenSSL. Например:

nodejs_conf = nodejs_init

.include /<absolute path>/fipsmodule.cnf

[nodejs_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
default = default_sect
# The fips section name should match the section name inside the
# included fipsmodule.cnf.
fips = fips_sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes copy

Криптографические константы

Следующие константы, экспортируемые crypto.constants, применяются к различным использованиям модулей node:crypto, node:tls, и node:https и, как правило, специфичны для OpenSSL.

Опции OpenSSL

Для получения подробной информации см. список флагов SSL OP.

Константы движка OpenSSL

Другие константы OpenSSL

Константы Node.js crypto