iDoc.dev

Русский

English
简体中文
Español
Français
Português
Deutsch
Italiano
日本語
한국어
العربية

Русский

English
简体中文
Español
Français
Português
Deutsch
Italiano
日本語
한국어
العربية

Тема

Crypto ​

[Stable: 2 - Stable]

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

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

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

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

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

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

Определение недоступности поддержки crypto ​

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

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

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

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

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

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

Класс: Certificate ​

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

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

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

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

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

[История]

ВерсияИзменения
v15.0.0Аргумент spkac может быть ArrayBuffer. Ограничен размер аргумента spkac до максимума в 2**31 - 1 байт.
v9.0.0Добавлено в версии: v9.0.0
js
const { Certificate } = await import('node:crypto');
const spkac = getSpkacSomehow();
const challenge = Certificate.exportChallenge(spkac);
console.log(challenge.toString('utf8'));
// Выводит: challenge в виде строки UTF8
js
const { Certificate } = require('node:crypto');
const spkac = getSpkacSomehow();
const challenge = Certificate.exportChallenge(spkac);
console.log(challenge.toString('utf8'));
// Выводит: challenge в виде строки UTF8

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

[История]

ВерсияИзменения
v15.0.0Аргумент spkac может быть ArrayBuffer. Ограничен размер аргумента spkac до максимума в 2**31 - 1 байт.
v9.0.0Добавлено в: v9.0.0
js
const { Certificate } = await import('node:crypto');
const spkac = getSpkacSomehow();
const publicKey = Certificate.exportPublicKey(spkac);
console.log(publicKey);
// Выводит: открытый ключ как <Buffer ...>
js
const { Certificate } = require('node:crypto');
const spkac = getSpkacSomehow();
const publicKey = Certificate.exportPublicKey(spkac);
console.log(publicKey);
// Выводит: открытый ключ как <Buffer ...>

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

[История]

ВерсияИзменения
v15.0.0Аргумент spkac может быть ArrayBuffer. Добавлена кодировка. Ограничен размер аргумента spkac до максимума в 2**31 - 1 байт.
v9.0.0Добавлено в: v9.0.0
js
import { Buffer } from 'node:buffer';
const { Certificate } = await import('node:crypto');

const spkac = getSpkacSomehow();
console.log(Certificate.verifySpkac(Buffer.from(spkac)));
// Выводит: true или false
js
const { Buffer } = require('node:buffer');
const { Certificate } = require('node:crypto');

const spkac = getSpkacSomehow();
console.log(Certificate.verifySpkac(Buffer.from(spkac)));
// Выводит: true или false

Устаревший API ​

[Stable: 0 - Deprecated]

Stable: 0 Stability: 0 - Устаревший

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

new crypto.Certificate() ​

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

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

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

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

certificate.exportChallenge(spkac[, encoding]) ​

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

js
const { Certificate } = await import('node:crypto');
const cert = Certificate();
const spkac = getSpkacSomehow();
const challenge = cert.exportChallenge(spkac);
console.log(challenge.toString('utf8'));
// Выводит: challenge как строку UTF8
js
const { Certificate } = require('node:crypto');
const cert = Certificate();
const spkac = getSpkacSomehow();
const challenge = cert.exportChallenge(spkac);
console.log(challenge.toString('utf8'));
// Выводит: challenge как строку UTF8

certificate.exportPublicKey(spkac[, encoding]) ​

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

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

certificate.verifySpkac(spkac[, encoding]) ​

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

js
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
js
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 ​

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

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

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

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

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

js
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();
  });
});
js
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 и конвейерных потоков:

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

js
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);
  });
});
js
const {
  scrypt,
  randomFill,
  createCipheriv,
} = require('node:crypto');

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

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

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

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

cipher.final([outputEncoding]) ​

Добавлено в версии: v0.1.94

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

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

cipher.getAuthTag() ​

Добавлено в версии: v1.0.0

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

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

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

cipher.setAAD(buffer[, options]) ​

Добавлено в версии: v1.0.0

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

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

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

cipher.setAutoPadding([autoPadding]) ​

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

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

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

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

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

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

[История]

ВерсияИзменения
v6.0.0Значение inputEncoding по умолчанию изменено с binary на utf8.
v0.1.94Добавлено в: v0.1.94

Обновляет шифр с помощью data. Если указан аргумент 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 ​

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

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

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

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

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

js
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();
js
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 и конвейерных потоков:

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

js
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
js
const {
  scryptSync,
  createDecipheriv,
} = require('node:crypto');
const { Buffer } = require('node:buffer');

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

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

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

decipher.final([outputEncoding]) ​

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

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

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

decipher.setAAD(buffer[, options]) ​

[История]

ВерсияИзменения
v15.0.0Аргумент buffer может быть строкой или ArrayBuffer и ограничен не более чем 2 ** 31 - 1 байтами.
v7.2.0Теперь этот метод возвращает ссылку на decipher.
v1.0.0Добавлено в: v1.0.0

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

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

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

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

decipher.setAuthTag(buffer[, encoding]) ​

[История]

ВерсияИзменения
v22.0.0, v20.13.0Использование длин тегов GCM, отличных от 128 бит, без указания опции authTagLength при создании decipher считается устаревшим.
v15.0.0Аргумент buffer может быть строкой или ArrayBuffer и ограничен не более чем 2 ** 31 - 1 байтами.
v11.0.0Этот метод теперь выдает ошибку, если длина тега GCM недействительна.
v7.2.0Этот метод теперь возвращает ссылку на decipher.
v1.0.0Добавлено в версии: v1.0.0

При использовании режима аутентифицированного шифрования (в настоящее время поддерживаются 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]) ​

Добавлено в версии: v0.7.1

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

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

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

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

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

[История]

ВерсияИзменения
v6.0.0Значение inputEncoding по умолчанию изменено с binary на utf8.
v0.1.94Добавлено в версии: v0.1.94

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

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

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

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

Класс: DiffieHellman ​

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

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

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

js
import assert from 'node:assert';

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

// Сгенерировать ключи Алисы...
const alice = createDiffieHellman(2048);
const aliceKey = alice.generateKeys();

// Сгенерировать ключи Боба...
const bob = createDiffieHellman(alice.getPrime(), alice.getGenerator());
const bobKey = bob.generateKeys();

// Обменяться и сгенерировать секрет...
const aliceSecret = alice.computeSecret(bobKey);
const bobSecret = bob.computeSecret(aliceKey);

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

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

// Сгенерировать ключи Алисы...
const alice = createDiffieHellman(2048);
const aliceKey = alice.generateKeys();

// Сгенерировать ключи Боба...
const bob = createDiffieHellman(alice.getPrime(), alice.getGenerator());
const bobKey = bob.generateKeys();

// Обменяться и сгенерировать секрет...
const aliceSecret = alice.computeSecret(bobKey);
const bobSecret = bob.computeSecret(aliceKey);

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

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

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

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

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

diffieHellman.generateKeys([encoding]) ​

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

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

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

diffieHellman.getGenerator([encoding]) ​

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

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

diffieHellman.getPrime([encoding]) ​

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

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

diffieHellman.getPrivateKey([encoding]) ​

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

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

diffieHellman.getPublicKey([encoding]) ​

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

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

diffieHellman.setPrivateKey(privateKey[, encoding]) ​

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

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

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

diffieHellman.setPublicKey(publicKey[, encoding]) ​

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

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

diffieHellman.verifyError ​

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

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

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

  • DH_CHECK_P_NOT_SAFE_PRIME
  • DH_CHECK_P_NOT_PRIME
  • DH_UNABLE_TO_CHECK_GENERATOR
  • DH_NOT_SUITABLE_GENERATOR

Класс: DiffieHellmanGroup ​

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

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

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

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

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

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

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

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

Класс: ECDH ​

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

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

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

js
import assert from 'node:assert';

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

// Создаем ключи Алисы...
const alice = createECDH('secp521r1');
const aliceKey = alice.generateKeys();

// Создаем ключи Боба...
const bob = createECDH('secp521r1');
const bobKey = bob.generateKeys();

// Обмениваемся и генерируем секрет...
const aliceSecret = alice.computeSecret(bobKey);
const bobSecret = bob.computeSecret(aliceKey);

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

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

// Создаем ключи Алисы...
const alice = createECDH('secp521r1');
const aliceKey = alice.generateKeys();

// Создаем ключи Боба...
const bob = createECDH('secp521r1');
const bobKey = bob.generateKeys();

// Обмениваемся и генерируем секрет...
const aliceSecret = alice.computeSecret(bobKey);
const bobSecret = bob.computeSecret(aliceKey);

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

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

Добавлено в: v10.0.0

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

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

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

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

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

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

// Преобразованный ключ и распакованный открытый ключ должны быть одинаковыми
console.log(uncompressedKey === ecdh.getPublicKey('hex'));
js
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');

// Преобразованный ключ и распакованный открытый ключ должны быть одинаковыми
console.log(uncompressedKey === ecdh.getPublicKey('hex'));

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

[История]

ВерсияИзменения
v10.0.0Изменен формат ошибки для лучшей поддержки ошибки недопустимого открытого ключа.
v6.0.0Значение inputEncoding по умолчанию изменено с binary на utf8.
v0.11.14Добавлено в: v0.11.14

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

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

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

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

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

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

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

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

ecdh.getPrivateKey([encoding]) ​

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

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

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

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

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

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

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

ecdh.setPrivateKey(privateKey[, encoding]) ​

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

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

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

ecdh.setPublicKey(publicKey[, encoding]) ​

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

Устарело с версии: v5.2.0

[Stable: 0 - Deprecated]

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

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

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

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

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

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

// Это сокращенный способ указания одного из предыдущих закрытых
// ключей Алисы. Было бы неразумно использовать такой предсказуемый закрытый ключ в реальном
// приложении.
alice.setPrivateKey(
  createHash('sha256').update('alice', 'utf8').digest(),
);

// Боб использует новую сгенерированную криптографически стойкую
// псевдослучайную пару ключей
bob.generateKeys();

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

// aliceSecret и bobSecret должны быть одним и тем же общим секретным значением
console.log(aliceSecret === bobSecret);
js
const {
  createECDH,
  createHash,
} = require('node:crypto');

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

// Это сокращенный способ указания одного из предыдущих закрытых
// ключей Алисы. Было бы неразумно использовать такой предсказуемый закрытый ключ в реальном
// приложении.
alice.setPrivateKey(
  createHash('sha256').update('alice', 'utf8').digest(),
);

// Боб использует новую сгенерированную криптографически стойкую
// псевдослучайную пару ключей
bob.generateKeys();

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

// aliceSecret и bobSecret должны быть одним и тем же общим секретным значением
console.log(aliceSecret === bobSecret);

Класс: Hash ​

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

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

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

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

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

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

const hash = createHash('sha256');

hash.on('readable', () => {
  // Только один элемент будет создан
  // хеш-потоком.
  const data = hash.read();
  if (data) {
    console.log(data.toString('hex'));
    // Выводит:
    //   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50
  }
});

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

const hash = createHash('sha256');

hash.on('readable', () => {
  // Только один элемент будет создан
  // хеш-потоком.
  const data = hash.read();
  if (data) {
    console.log(data.toString('hex'));
    // Выводит:
    //   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50
  }
});

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

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

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

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

const hash = createHash('sha256');

hash.update('some data to hash');
console.log(hash.digest('hex'));
// Выводит:
//   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50
js
const {
  createHash,
} = require('node:crypto');

const hash = createHash('sha256');

hash.update('some data to hash');
console.log(hash.digest('hex'));
// Выводит:
//   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50

hash.copy([options]) ​

Добавлено в версии: v13.1.0

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

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

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

js
// 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.
js
// Calculate a rolling hash.
const {
  createHash,
} = require('node:crypto');

const hash = createHash('sha256');

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

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

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

// Etc.

hash.digest([encoding]) ​

Добавлено в версии: v0.1.92

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

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

hash.update(data[, inputEncoding]) ​

[История]

ВерсияИзменения
v6.0.0inputEncoding по умолчанию изменён с binary на utf8.
v0.1.92Добавлено в версии: v0.1.92

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

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

Класс: Hmac ​

Добавлено в версии: v0.1.94

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

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

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

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

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

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

hmac.on('readable', () => {
  // Только один элемент будет произведён
  // потоком хэширования.
  const data = hmac.read();
  if (data) {
    console.log(data.toString('hex'));
    // Выводит:
    //   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f33ad9c87c518115a45971f7f77e
  }
});

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

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

hmac.on('readable', () => {
  // Только один элемент будет произведён
  // потоком хэширования.
  const data = hmac.read();
  if (data) {
    console.log(data.toString('hex'));
    // Выводит:
    //   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e
  }
});

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

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

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

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

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

hmac.update('some data to hash');
console.log(hmac.digest('hex'));
// Выводит:
//   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e
js
const {
  createHmac,
} = require('node:crypto');

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

hmac.update('some data to hash');
console.log(hmac.digest('hex'));
// Выводит:
//   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e

hmac.digest([encoding]) ​

Added in: v0.1.94

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

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

hmac.update(data[, inputEncoding]) ​

[История]

ВерсияИзменения
v6.0.0Значение inputEncoding по умолчанию изменено с binary на utf8.
v0.1.94Added in: v0.1.94

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

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

Class: KeyObject ​

[История]

ВерсияИзменения
v14.5.0, v12.19.0Экземпляры этого класса теперь могут быть переданы в рабочие потоки с помощью postMessage.
v11.13.0Этот класс теперь экспортируется.
v11.6.0Added in: v11.6.0

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

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

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

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

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

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

js
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)
js
const { KeyObject } = require('node:crypto');
const { subtle } = globalThis.crypto;

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

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

keyObject.asymmetricKeyDetails ​

[История]

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

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

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

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

keyObject.asymmetricKeyType ​

[История]

ВерсияИзменения
v13.9.0, v12.17.0Добавлена поддержка 'dh'.
v12.0.0Добавлена поддержка 'rsa-pss'.
v12.0.0Теперь это свойство возвращает undefined для экземпляров KeyObject неопознанного типа вместо прерывания.
v12.0.0Добавлена поддержка 'x25519' и 'x448'.
v12.0.0Добавлена поддержка 'ed25519' и 'ed448'.
v11.6.0Добавлено в: v11.6.0

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

  • '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.equals(otherKeyObject) ​

Добавлено в: v17.7.0, v16.15.0

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

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

keyObject.export([options]) ​

[История]

ВерсияИзменения
v15.9.0Добавлена поддержка формата 'jwk'.
v11.6.0Добавлено в: v11.6.0

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

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

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

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

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

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

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

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

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

keyObject.symmetricKeySize ​

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

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

keyObject.toCryptoKey(algorithm, extractable, keyUsages) ​

Добавлено в: v23.0.0

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

keyObject.type ​

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

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

Класс: Sign ​

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

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

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

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

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

js
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'));
// Выводит: true
js
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'));
// Выводит: true

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

js
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));
// Выводит: true
js
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));
// Выводит: true

sign.sign(privateKey[, outputEncoding]) ​

[История изменений]

ВерсияИзменения
v15.0.0privateKey теперь может быть ArrayBuffer и CryptoKey.
v13.2.0, v12.16.0Эта функция теперь поддерживает подписи IEEE-P1363 DSA и ECDSA.
v12.0.0Эта функция теперь поддерживает ключи RSA-PSS.
v11.6.0Эта функция теперь поддерживает объекты ключей.
v8.0.0Добавлена поддержка RSASSA-PSS и дополнительных параметров.
v0.1.92Добавлено в версии: v0.1.92

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

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

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

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

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

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

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

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

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

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

sign.update(data[, inputEncoding]) ​

[История]

ВерсияИзменения
v6.0.0Кодировка inputEncoding по умолчанию изменена с binary на utf8.
v0.1.92Добавлено в: v0.1.92

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

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

Класс: Verify ​

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

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

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

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

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

verify.update(data[, inputEncoding]) ​

[История]

ВерсияИзменения
v6.0.0Кодировка inputEncoding по умолчанию изменена с binary на utf8.
v0.1.92Добавлено в: v0.1.92

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

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

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

[История]

ВерсияИзменения
v15.0.0Объект также может быть ArrayBuffer и CryptoKey.
v13.2.0, v12.16.0Эта функция теперь поддерживает подписи IEEE-P1363 DSA и ECDSA.
v12.0.0Эта функция теперь поддерживает ключи RSA-PSS.
v11.7.0Ключ теперь может быть закрытым ключом.
v8.0.0Добавлена поддержка RSASSA-PSS и дополнительных параметров.
v0.1.92Добавлено в: v0.1.92

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

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

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

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

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

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

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

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

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

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

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

Класс: X509Certificate ​

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

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

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

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

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

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

console.log(x509.subject);

new X509Certificate(buffer) ​

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

x509.ca ​

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

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

x509.checkEmail(email[, options]) ​

[История]

ВерсияИзменения
v18.0.0Параметр subject теперь по умолчанию имеет значение 'default'.
v17.5.0, v16.15.0Параметр subject теперь может быть установлен в значение 'default'.
v17.5.0, v16.14.1Параметры wildcards, partialWildcards, multiLabelWildcards и singleLabelSubdomains были удалены, поскольку они не оказывали никакого эффекта.
v15.6.0Добавлено в: v15.6.0

  • email <string>

  • options <Object>

    • subject <string> 'default', 'always' или 'never'. По умолчанию: 'default'.

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

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

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

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

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

x509.checkHost(name[, options]) ​

[История]

ВерсияИзменения
v18.0.0Параметр subject теперь по умолчанию имеет значение 'default'.
v17.5.0, v16.15.0Параметру subject теперь можно присвоить значение 'default'.
v15.6.0Добавлено в версии: v15.6.0

  • name <string>

  • options <Object>

    • subject <string> 'default', 'always' или 'never'. По умолчанию: 'default'.
    • wildcards <boolean> По умолчанию: true.
    • partialWildcards <boolean> По умолчанию: true.
    • multiLabelWildcards <boolean> По умолчанию: false.
    • singleLabelSubdomains <boolean> По умолчанию: false.

  • Возвращает: <string> | <undefined> Возвращает имя субъекта, соответствующее name, или undefined, если имя субъекта не соответствует name.

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

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

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

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

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

x509.checkIP(ip) ​

[История]

ВерсияИзменения
v17.5.0, v16.14.1Аргумент options был удален, так как он не имел никакого эффекта.
v15.6.0Добавлено в: v15.6.0
  • ip <string>
  • Возвращает: <string> | <undefined> Возвращает ip, если сертификат соответствует, undefined, если нет.

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

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

x509.checkIssued(otherCert) ​

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

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

x509.checkPrivateKey(privateKey) ​

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

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

x509.extKeyUsage ​

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

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

x509.fingerprint ​

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

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

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

x509.fingerprint256 ​

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

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

x509.fingerprint512 ​

Добавлено в: v17.2.0, v16.14.0

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

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

x509.infoAccess ​

[История]

ВерсияИзменения
v17.3.1, v16.13.2Части этой строки могут быть закодированы как строковые литералы JSON в ответ на CVE-2021-44532.
v15.6.0Добавлено в: v15.6.0

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

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

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

x509.issuer ​

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

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

x509.issuerCertificate ​

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

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

x509.publicKey ​

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

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

x509.raw ​

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

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

x509.serialNumber ​

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

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

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

x509.subject ​

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

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

x509.subjectAltName ​

[История]

ВерсияИзменения
v17.3.1, v16.13.2Части этой строки могут быть закодированы как строковые литералы JSON в ответ на CVE-2021-44532.
v15.6.0Добавлено в: v15.6.0

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

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

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

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

x509.toJSON() ​

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

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

x509.toLegacyObject() ​

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

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

x509.toString() ​

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

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

x509.validFrom ​

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

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

x509.validFromDate ​

Добавлено в: v23.0.0

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

x509.validTo ​

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

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

x509.validToDate ​

Добавлено в: v23.0.0

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

x509.verify(publicKey) ​

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

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

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

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

[История]

ВерсияИзменения
v18.0.0Передача недействительного обратного вызова в аргумент callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v15.8.0Добавлено в: v15.8.0

  • candidate <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Buffer> | <DataView> | <bigint> Возможное простое число, закодированное как последовательность байтов с прямым порядком байтов произвольной длины.

  • options <Object>

    • checks <number> Количество итераций вероятностного теста простоты Миллера-Рабина. Если значение равно 0 (нулю), используется количество проверок, которое дает частоту ложных срабатываний не более 2 для случайных входных данных. Следует проявлять осторожность при выборе количества проверок. Обратитесь к документации OpenSSL для функции BN_is_prime_ex для получения более подробной информации об опциях nchecks. По умолчанию: 0

  • callback <Function>

    • err <Error> Устанавливается в объект <Error>, если во время проверки произошла ошибка.
    • result <boolean> true, если кандидат является простым числом с вероятностью ошибки менее 0.25 ** options.checks.

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

crypto.checkPrimeSync(candidate[, options]) ​

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

  • candidate <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Buffer> | <DataView> | <bigint> Возможное простое число, закодированное как последовательность октетов в формате big endian произвольной длины.

  • options <Object>

    • checks <number> Количество итераций вероятностной проверки простоты числа по тесту Миллера-Рабина. Если значение равно 0 (нулю), используется количество проверок, которое дает вероятность ложноположительного результата не более 2 для случайных входных данных. При выборе количества проверок необходимо проявлять осторожность. Подробности смотрите в документации OpenSSL для функции BN_is_prime_ex параметр nchecks. По умолчанию: 0

  • Возвращает: <boolean> true, если кандидат является простым числом с вероятностью ошибки менее 0.25 ** options.checks.

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

crypto.constants ​

Добавлено в: v6.3.0

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

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

[История]

ВерсияИзменения
v17.9.0, v16.17.0Параметр authTagLength теперь не является обязательным при использовании шифра chacha20-poly1305 и по умолчанию равен 16 байтам.
v15.0.0Аргументы password и iv могут быть ArrayBuffer и ограничены максимум 2 ** 31 - 1 байтами каждый.
v11.6.0Аргумент key теперь может быть KeyObject.
v11.2.0, v10.17.0Теперь поддерживается шифр chacha20-poly1305 (вариант IETF ChaCha20-Poly1305).
v10.10.0Теперь поддерживаются шифры в режиме OCB.
v10.2.0Теперь можно использовать параметр authTagLength для создания более коротких тегов аутентификации в режиме GCM, по умолчанию 16 байт.
v9.9.0Параметр iv теперь может быть null для шифров, которым не нужен вектор инициализации.
v0.1.94Добавлено в версии: v0.1.94

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

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

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

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

[История изменений]

ВерсияИзменения
v17.9.0, v16.17.0Параметр authTagLength теперь не обязателен при использовании шифра chacha20-poly1305 и по умолчанию равен 16 байтам.
v11.6.0Аргумент key теперь может быть KeyObject.
v11.2.0, v10.17.0Теперь поддерживается шифр chacha20-poly1305 (вариант IETF ChaCha20-Poly1305).
v10.10.0Теперь поддерживаются шифры в режиме OCB.
v10.2.0Теперь параметр authTagLength можно использовать для ограничения принимаемых длин тегов аутентификации GCM.
v9.9.0Параметр iv теперь может быть null для шифров, которым не нужен вектор инициализации.
v0.1.94Добавлено в версии: v0.1.94

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

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

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

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

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

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

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

[История]

ВерсияИзменения
v8.0.0Аргумент prime теперь может быть любым TypedArray или DataView.
v8.0.0Аргумент prime теперь может быть Uint8Array.
v6.0.0Значение по умолчанию для параметров кодировки изменено с binary на utf8.
v0.11.12Добавлено в версии: v0.11.12

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

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

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

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

crypto.createDiffieHellman(primeLength[, generator]) ​

Added in: v0.5.0

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

crypto.createDiffieHellmanGroup(name) ​

Added in: v0.9.3

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

crypto.createECDH(curveName) ​

Added in: v0.11.14

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

crypto.createHash(algorithm[, options]) ​

[История]

ВерсияИзменения
v12.8.0Добавлена опция outputLength для XOF-функций хеширования.
v0.1.92Добавлено в: v0.1.92

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

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

Пример: генерация sha256 суммы файла

js
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', () => {
  // Только один элемент будет сгенерирован
  // хеш-потоком.
  const data = input.read();
  if (data)
    hash.update(data);
  else {
    console.log(`${hash.digest('hex')} ${filename}`);
  }
});
js
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', () => {
  // Только один элемент будет сгенерирован
  // хеш-потоком.
  const data = input.read();
  if (data)
    hash.update(data);
  else {
    console.log(`${hash.digest('hex')} ${filename}`);
  }
});

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

[История]

ВерсияИзменения
v15.0.0Ключ также может быть ArrayBuffer или CryptoKey. Добавлен параметр кодировки. Ключ не может содержать более 2 ** 32 - 1 байт.
v11.6.0Аргумент key теперь может быть KeyObject.
v0.1.94Добавлено в версии: v0.1.94

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

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

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

Пример: генерация sha256 HMAC файла

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

[История]

ВерсияИзменения
v15.12.0Ключ также может быть объектом JWK.
v15.0.0Ключ также может быть ArrayBuffer. Добавлен параметр кодировки. Ключ не может содержать более 2 ** 32 - 1 байт.
v11.6.0Добавлено в: v11.6.0

  • key <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>

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

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

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

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

crypto.createPublicKey(key) ​

[История]

ВерсияИзменения
v15.12.0Ключ также может быть объектом JWK.
v15.0.0Ключ также может быть ArrayBuffer. Добавлен параметр encoding. Ключ не может содержать более 2 ** 32 - 1 байт.
v11.13.0Аргумент key теперь может быть KeyObject с типом private.
v11.7.0Аргумент key теперь может быть закрытым ключом.
v11.6.0Добавлено в версии: v11.6.0

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

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

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

crypto.createSecretKey(key[, encoding]) ​

[История изменений]

ВерсияИзменения
v18.8.0, v16.18.0Ключ теперь может быть нулевой длины.
v15.0.0Ключ также может быть ArrayBuffer или строкой. Добавлен аргумент encoding. Ключ не может содержать более 2 ** 32 - 1 байт.
v11.6.0Добавлено в версии: v11.6.0

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

crypto.createSign(algorithm[, options]) ​

Добавлено в версии: v0.1.92

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

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

crypto.createVerify(algorithm[, options]) ​

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

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

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

crypto.diffieHellman(options) ​

Добавлено в: v13.9.0, v12.17.0

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

crypto.fips ​

Добавлено в: v6.0.0

Устарело с: v10.0.0

[Stable: 0 - Deprecated]

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

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

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

crypto.generateKey(type, options, callback) ​

[История изменений]

ВерсияИзменения
v18.0.0Передача недействительного обратного вызова в аргумент callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v15.0.0Добавлено в: v15.0.0

  • type: <string> Предполагаемое использование сгенерированного секретного ключа. В настоящее время принимаются значения 'hmac' и 'aes'.

  • options: <Object>

    • length: <number> Битовая длина генерируемого ключа. Это должно быть значение больше 0.
    • Если type равно 'hmac', минимальная длина равна 8, а максимальная длина равна 2-1. Если значение не кратно 8, сгенерированный ключ будет усечен до Math.floor(length / 8).
    • Если type равно 'aes', длина должна быть одной из 128, 192 или 256.

  • callback: <Function>

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

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

generateKey('hmac', { length: 512 }, (err, key) => {
  if (err) throw err;
  console.log(key.export().toString('hex'));  // 46e..........620
});
js
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) ​

[История]

ВерсияИзменения
v18.0.0Передача недействительного обратного вызова аргументу callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v16.10.0Добавлена возможность определять параметры последовательности RSASSA-PSS-params для пар ключей RSA-PSS.
v13.9.0, v12.17.0Добавлена поддержка Diffie-Hellman.
v12.0.0Добавлена поддержка пар ключей RSA-PSS.
v12.0.0Добавлена возможность генерации пар ключей X25519 и X448.
v12.0.0Добавлена возможность генерации пар ключей Ed25519 и Ed448.
v11.6.0Функции generateKeyPair и generateKeyPairSync теперь создают объекты ключей, если кодировка не указана.
v10.12.0Добавлено в версии: v10.12.0

  • type: <string> Должно быть 'rsa', 'rsa-pss', 'dsa', 'ec', 'ed25519', 'ed448', 'x25519', 'x448' или 'dh'.

  • options: <Object>

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

  • callback: <Function>

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

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

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

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

[История]

ВерсияИзменения
v16.10.0Добавлена возможность определять параметры последовательности RSASSA-PSS-params для пар ключей RSA-PSS.
v13.9.0, v12.17.0Добавлена поддержка Diffie-Hellman.
v12.0.0Добавлена поддержка пар ключей RSA-PSS.
v12.0.0Добавлена возможность генерации пар ключей X25519 и X448.
v12.0.0Добавлена возможность генерации пар ключей Ed25519 и Ed448.
v11.6.0Функции generateKeyPair и generateKeyPairSync теперь создают объекты ключей, если кодировка не указана.
v10.12.0Добавлено в: v10.12.0

  • type: <string> Должно быть '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>

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

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

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

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

Added in: v15.0.0

  • type: <string> Предполагаемое использование сгенерированного секретного ключа. В настоящее время принимаются значения 'hmac' и 'aes'.

  • options: <Object>

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

  • Returns: <KeyObject>

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

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

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

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

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

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

[История]

ВерсияИзменения
v18.0.0Передача недействительного обратного вызова в аргумент callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v15.8.0Добавлено в: v15.8.0

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

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

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

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

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

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

crypto.generatePrimeSync(size[, options]) ​

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

Генерирует псевдослучайное простое число размером 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 должны быть закодированы как последовательности с прямым порядком байтов, если они указаны как ArrayBuffer, SharedArrayBuffer, TypedArray, Buffer или DataView.

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

crypto.getCipherInfo(nameOrNid[, options]) ​

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

  • nameOrNid: <string> | <number> Имя или NID шифра для запроса.

  • options: <Object>

    • keyLength: <number> Тестовая длина ключа.
    • ivLength: <number> Тестовая длина вектора инициализации.

  • Возвращает: <Object>

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

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

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

crypto.getCiphers() ​

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

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

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

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

crypto.getCurves() ​

Добавлено в: v2.3.0

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

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

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

crypto.getDiffieHellman(groupName) ​

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

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

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

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

js
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);
js
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 и bobSecret должны быть одинаковыми */
console.log(aliceSecret === bobSecret);

crypto.getFips() ​

Added in: v10.0.0

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

crypto.getHashes() ​

Added in: v0.9.3

  • Возвращает: <string[]> Массив названий поддерживаемых алгоритмов хеширования, таких как 'RSA-SHA256'. Алгоритмы хеширования также называются "алгоритмами дайджеста".
js
const {
  getHashes,
} = await import('node:crypto');

console.log(getHashes()); // ['DSA', 'DSA-SHA', 'DSA-SHA1', ...]
js
const {
  getHashes,
} = require('node:crypto');

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

crypto.getRandomValues(typedArray) ​

Added in: v17.4.0

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

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

Добавлено в: v21.7.0, v20.12.0

[Stable: 1 - Experimental]

Stable: 1 Стабильность: 1.2 - Кандидат на выпуск

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

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

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

Пример:

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

// Хеширование строки и возврат результата в виде строки, закодированной в hex.
const string = 'Node.js';
// 10b3493287f831e81a438811a1ffba01f8cec4b7
console.log(crypto.hash('sha1', string));

// Кодирование строки в кодировке base64 в 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'));
js
import crypto from 'node:crypto';
import { Buffer } from 'node:buffer';

// Хеширование строки и возврат результата в виде строки, закодированной в hex.
const string = 'Node.js';
// 10b3493287f831e81a438811a1ffba01f8cec4b7
console.log(crypto.hash('sha1', string));

// Кодирование строки в кодировке base64 в Buffer, ее хеширование и возврат
// результата в виде буфера.
const base64 = 'Tm9kZS5qcw==';
// <Buffer 10 b3 49 32 87 f8 31 e8 1a 43 88 11 a1 ff ba 01 f8 ce c4 b7>
console.log(crypto.hash('sha1', Buffer.from(base64, 'base64'), 'buffer'));

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

[История]

ВерсияИзменения
v18.0.0Передача недействительного обратного вызова аргументу callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v18.8.0, v16.18.0Входной ключевой материал теперь может иметь нулевую длину.
v15.0.0Добавлено в: v15.0.0
  • digest <string> Алгоритм хеширования для использования.
  • ikm <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> Входной ключевой материал. Должен быть предоставлен, но может иметь нулевую длину.
  • salt <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> Значение соли. Должно быть предоставлено, но может иметь нулевую длину.
  • info <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> Дополнительное значение информации. Должно быть предоставлено, но может иметь нулевую длину и не может превышать 1024 байта.
  • keylen <number> Длина ключа для генерации. Должна быть больше 0. Максимально допустимое значение - 255, умноженное на количество байтов, производимых выбранной функцией дайджеста (например, sha512 генерирует 64-байтовые хеши, что делает максимальный выход HKDF равным 16320 байтам).
  • callback <Function>

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

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

js
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'
});
js
const {
  hkdf,
} = require('node:crypto');
const { Buffer } = require('node:buffer');

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

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

[История]

ВерсияИзменения
v18.8.0, v16.18.0Входной ключевой материал теперь может иметь нулевую длину.
v15.0.0Добавлено в версии: v15.0.0
  • digest <string> Используемый алгоритм дайджеста.
  • ikm <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> Входной ключевой материал. Должен быть предоставлен, но может иметь нулевую длину.
  • salt <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> Значение соли. Должно быть предоставлено, но может иметь нулевую длину.
  • info <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> Дополнительное информационное значение. Должно быть предоставлено, но может иметь нулевую длину и не может превышать 1024 байта.
  • keylen <number> Длина ключа для генерации. Должна быть больше 0. Максимально допустимое значение - 255 умноженное на количество байтов, производимых выбранной функцией дайджеста (например, sha512 генерирует 64-байтовые хэши, что делает максимальный вывод HKDF 16320 байт).
  • Возвращает: <ArrayBuffer>

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

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

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

js
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'
js
const {
  hkdfSync,
} = require('node:crypto');
const { Buffer } = require('node:buffer');

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

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

[История]

ВерсияИзменения
v18.0.0Передача недействительного обратного вызова в аргумент callback теперь вызывает ошибку ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v15.0.0Аргументы password и salt также могут быть экземплярами ArrayBuffer.
v14.0.0Параметр iterations теперь ограничен положительными значениями. Более ранние выпуски обрабатывали другие значения как единицу.
v8.0.0Параметр digest теперь всегда обязателен.
v6.0.0Вызов этой функции без передачи параметра digest теперь устарел и будет выдавать предупреждение.
v6.0.0Кодировка по умолчанию для password, если это строка, изменилась с binary на utf8.
v0.5.5Добавлено в версии: v0.5.5

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

js
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'
});
js
const {
  pbkdf2,
} = require('node:crypto');

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

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

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

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

[История]

ВерсияИзменения
v14.0.0Параметр iterations теперь ограничен положительными значениями. Более ранние версии обрабатывали другие значения как единицу.
v6.0.0Вызов этой функции без передачи параметра digest теперь считается устаревшим и вызовет предупреждение.
v6.0.0Кодировка по умолчанию для password, если это строка, изменилась с binary на utf8.
v0.9.3Добавлено в: v0.9.3

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

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

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

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

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

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

const key = pbkdf2Sync('secret', 'salt', 100000, 64, 'sha512');
console.log(key.toString('hex'));  // '3745e48...08d59ae'
js
const {
  pbkdf2Sync,
} = require('node:crypto');

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

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

crypto.privateDecrypt(privateKey, buffer) ​

[История]

ВерсияИзменения
v21.6.2, v20.11.1, v18.19.1Отступ RSA_PKCS1_PADDING был отключен, если сборка OpenSSL не поддерживает неявный отказ.
v15.0.0Добавлены string, ArrayBuffer и CryptoKey в качестве допустимых типов ключей. oaepLabel может быть ArrayBuffer. Буфер может быть строкой или ArrayBuffer. Все типы, принимающие буферы, ограничены максимальным размером 2 ** 31 - 1 байт.
v12.11.0Добавлена опция oaepLabel.
v12.9.0Добавлена опция oaepHash.
v11.6.0Эта функция теперь поддерживает объекты ключей.
v0.11.14Добавлено в версии: v0.11.14

Расшифровывает 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) ​

[История]

ВерсияИзменения
v15.0.0Добавлены string, ArrayBuffer и CryptoKey в качестве допустимых типов ключей. Парольная фраза может быть ArrayBuffer. Буфер может быть string или ArrayBuffer. Все типы, принимающие буферы, ограничены максимум 2 ** 31 - 1 байтами.
v11.6.0Эта функция теперь поддерживает объекты ключей.
v1.1.0Добавлено в: v1.1.0

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

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

crypto.publicDecrypt(key, buffer) ​

[История]

ВерсияИзменения
v15.0.0Добавлены string, ArrayBuffer и CryptoKey в качестве допустимых типов ключей. Парольная фраза может быть ArrayBuffer. Буфер может быть строкой или ArrayBuffer. Все типы, принимающие буферы, ограничены максимумом в 2 ** 31 - 1 байт.
v11.6.0Эта функция теперь поддерживает объекты ключей.
v1.1.0Добавлено в версии: v1.1.0

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

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

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

crypto.publicEncrypt(key, buffer) ​

[История]

ВерсияИзменения
v15.0.0Добавлены string, ArrayBuffer и CryptoKey в качестве допустимых типов ключей. oaepLabel и passphrase могут быть ArrayBuffer. buffer может быть string или ArrayBuffer. Все типы, принимающие буферы, ограничены максимум 2 ** 31 - 1 байтами.
v12.11.0Добавлена опция oaepLabel.
v12.9.0Добавлена опция oaepHash.
v11.6.0Теперь эта функция поддерживает объекты ключей.
v0.11.14Добавлено в: v0.11.14

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

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

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

crypto.randomBytes(size[, callback]) ​

[История]

ВерсияИзменения
v18.0.0Передача недействительного обратного вызова аргументу callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v9.0.0Передача null в качестве аргумента callback теперь вызывает ERR_INVALID_CALLBACK.
v0.5.8Добавлено в версии: v0.5.8

  • size <number> Количество генерируемых байтов. size не должен превышать 2**31 - 1.

  • callback <Function>

  • Возвращает: <Buffer>, если функция callback не предоставлена.

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

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

js
// Асинхронно
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')}`);
});
js
// Асинхронно
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. В случае возникновения проблемы при генерации байтов будет выдана ошибка.

js
// Синхронно
const {
  randomBytes,
} = await import('node:crypto');

const buf = randomBytes(256);
console.log(
  `${buf.length} bytes of random data: ${buf.toString('hex')}`);
js
// Синхронно
const {
  randomBytes,
} = require('node:crypto');

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

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

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

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

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

[История]

ВерсияИзменения
v18.0.0Передача неверного обратного вызова в аргумент callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v9.0.0Аргумент buffer может быть любым TypedArray или DataView.
v7.10.0, v6.13.0Добавлено в: v7.10.0, v6.13.0
  • buffer <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> Обязательно к указанию. Размер предоставленного buffer не должен превышать 2**31 - 1.
  • offset <number> По умолчанию: 0
  • size <number> По умолчанию: buffer.length - offset. Значение size не должно превышать 2**31 - 1.
  • callback <Function> function(err, buf) {}.

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

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

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

// Вышеуказанное эквивалентно следующему:
randomFill(buf, 5, 5, (err, buf) => {
  if (err) throw err;
  console.log(buf.toString('hex'));
});
js
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'));
});

// Вышеуказанное эквивалентно следующему:
randomFill(buf, 5, 5, (err, buf) => {
  if (err) throw err;
  console.log(buf.toString('hex'));
});

Любой экземпляр ArrayBuffer, TypedArray или DataView может быть передан в качестве buffer.

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

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

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

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

[История]

ВерсияИзменения
v9.0.0Аргумент buffer может быть любым TypedArray или DataView.
v7.10.0, v6.13.0Добавлено в: v7.10.0, v6.13.0
  • buffer <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> Обязательный параметр. Размер предоставленного buffer не должен превышать 2**31 - 1.
  • offset <number> По умолчанию: 0
  • size <number> По умолчанию: buffer.length - offset. Значение size не должно превышать 2**31 - 1.
  • Возвращает: <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> Объект, переданный в качестве аргумента buffer.

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

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

// Вышеуказанное эквивалентно следующему:
randomFillSync(buf, 5, 5);
console.log(buf.toString('hex'));
js
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'));

// Вышеуказанное эквивалентно следующему:
randomFillSync(buf, 5, 5);
console.log(buf.toString('hex'));

Любой экземпляр ArrayBuffer, TypedArray или DataView может быть передан в качестве buffer.

js
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'));
js
const { randomFillSync } = require('node:crypto');
const { Buffer } = require('node:buffer');

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

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

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

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

[История]

ВерсияИзменения
v18.0.0Передача недействительного обратного вызова в аргумент callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v14.10.0, v12.19.0Добавлено в: v14.10.0, v12.19.0
  • min <integer> Начало случайного диапазона (включительно). По умолчанию: 0.
  • max <integer> Конец случайного диапазона (исключительно).
  • callback <Function> function(err, n) {}.

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

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

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

js
// Асинхронно
const {
  randomInt,
} = await import('node:crypto');

randomInt(3, (err, n) => {
  if (err) throw err;
  console.log(`Случайное число, выбранное из (0, 1, 2): ${n}`);
});
js
// Асинхронно
const {
  randomInt,
} = require('node:crypto');

randomInt(3, (err, n) => {
  if (err) throw err;
  console.log(`Случайное число, выбранное из (0, 1, 2): ${n}`);
});
js
// Синхронно
const {
  randomInt,
} = await import('node:crypto');

const n = randomInt(3);
console.log(`Случайное число, выбранное из (0, 1, 2): ${n}`);
js
// Синхронно
const {
  randomInt,
} = require('node:crypto');

const n = randomInt(3);
console.log(`Случайное число, выбранное из (0, 1, 2): ${n}`);
js
// С аргументом `min`
const {
  randomInt,
} = await import('node:crypto');

const n = randomInt(1, 7);
console.log(`На кубике выпало: ${n}`);
js
// С аргументом `min`
const {
  randomInt,
} = require('node:crypto');

const n = randomInt(1, 7);
console.log(`На кубике выпало: ${n}`);

crypto.randomUUID([options]) ​

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

  • options <Object>

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

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

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

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

[История]

ВерсияИзменения
v18.0.0Передача недействительного обратного вызова аргументу callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v15.0.0Аргументы пароля и соли также могут быть экземплярами ArrayBuffer.
v12.8.0, v10.17.0Значение maxmem теперь может быть любым безопасным целым числом.
v10.9.0Добавлены имена опций cost, blockSize и parallelization.
v10.5.0Добавлено в: v10.5.0

  • password <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>

  • salt <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>

  • keylen <number>

  • options <Object>

    • cost <number> Параметр стоимости ЦП/памяти. Должен быть степенью двойки больше единицы. По умолчанию: 16384.
    • blockSize <number> Параметр размера блока. По умолчанию: 8.
    • parallelization <number> Параметр параллелизации. По умолчанию: 1.
    • N <number> Псевдоним для cost. Можно указать только один из них.
    • r <number> Псевдоним для blockSize. Можно указать только один из них.
    • p <number> Псевдоним для parallelization. Можно указать только один из них.
    • maxmem <number> Верхняя граница памяти. Ошибка возникает, когда (приблизительно) 128 * N * r \> maxmem. По умолчанию: 32 * 1024 * 1024.

  • callback <Function>

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

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

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

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

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

js
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'
});
js
const {
  scrypt,
} = require('node:crypto');

// Using the factory defaults.
scrypt('password', 'salt', 64, (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // '3745e48...08d59ae'
});
// Using a custom N parameter. Must be a power of two.
scrypt('password', 'salt', 64, { N: 1024 }, (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // '3745e48...aa39b34'
});

crypto.scryptSync(password, salt, keylen[, options]) ​

[История]

ВерсияИзменения
v12.8.0, v10.17.0Теперь значение maxmem может быть любым безопасным целым числом.
v10.9.0Добавлены названия параметров cost, blockSize и parallelization.
v10.5.0Добавлено в версии: v10.5.0

  • password <string> | <Buffer> | <TypedArray> | <DataView>

  • salt <string> | <Buffer> | <TypedArray> | <DataView>

  • keylen <number>

  • options <Object>

    • cost <number> Параметр стоимости CPU/памяти. Должен быть степенью двойки больше единицы. По умолчанию: 16384.
    • blockSize <number> Параметр размера блока. По умолчанию: 8.
    • parallelization <number> Параметр параллелизации. По умолчанию: 1.
    • N <number> Псевдоним для cost. Может быть указан только один из них.
    • r <number> Псевдоним для blockSize. Может быть указан только один из них.
    • p <number> Псевдоним для parallelization. Может быть указан только один из них.
    • maxmem <number> Верхняя граница памяти. Возникает ошибка, когда (приблизительно) 128 * N * r \> maxmem. По умолчанию: 32 * 1024 * 1024.

  • Возвращает: <Buffer>

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

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

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

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

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

js
const {
  scryptSync,
} = await import('node:crypto');
// Использование заводских настроек по умолчанию.

const key1 = scryptSync('password', 'salt', 64);
console.log(key1.toString('hex'));  // '3745e48...08d59ae'
// Использование пользовательского параметра N. Должен быть степенью двойки.
const key2 = scryptSync('password', 'salt', 64, { N: 1024 });
console.log(key2.toString('hex'));  // '3745e48...aa39b34'
js
const {
  scryptSync,
} = require('node:crypto');
// Использование заводских настроек по умолчанию.

const key1 = scryptSync('password', 'salt', 64);
console.log(key1.toString('hex'));  // '3745e48...08d59ae'
// Использование пользовательского параметра N. Должен быть степенью двойки.
const key2 = scryptSync('password', 'salt', 64, { N: 1024 });
console.log(key2.toString('hex'));  // '3745e48...aa39b34'

crypto.secureHeapUsed() ​

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

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

crypto.setEngine(engine[, flags]) ​

[История]

ВерсияИзменения
v22.4.0, v20.16.0Поддержка пользовательских движков в OpenSSL 3 устарела.
v0.11.11Добавлено в версии: v0.11.11

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

engine может быть либо идентификатором, либо путем к разделяемой библиотеке движка.

Необязательный аргумент flags по умолчанию использует ENGINE_METHOD_ALL. flags - это битовое поле, принимающее один или комбинацию следующих флагов (определенных в crypto.constants):

  • crypto.constants.ENGINE_METHOD_RSA
  • crypto.constants.ENGINE_METHOD_DSA
  • crypto.constants.ENGINE_METHOD_DH
  • crypto.constants.ENGINE_METHOD_RAND
  • crypto.constants.ENGINE_METHOD_EC
  • crypto.constants.ENGINE_METHOD_CIPHERS
  • crypto.constants.ENGINE_METHOD_DIGESTS
  • crypto.constants.ENGINE_METHOD_PKEY_METHS
  • crypto.constants.ENGINE_METHOD_PKEY_ASN1_METHS
  • crypto.constants.ENGINE_METHOD_ALL
  • crypto.constants.ENGINE_METHOD_NONE

crypto.setFips(bool) ​

Добавлено в версии: v10.0.0

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

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

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

[История]

| Версия | Изменения

crypto.subtle ​

Added in: v17.4.0

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

crypto.timingSafeEqual(a, b) ​

[История]

ВерсияИзменения
v15.0.0Аргументы a и b также могут быть ArrayBuffer.
v6.6.0Added in: v6.6.0

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

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

a и b должны быть либо Buffers, либо TypedArrays, либо DataViews, и они должны иметь одинаковую длину в байтах. Если a и b имеют разную длину в байтах, возникает ошибка.

Если хотя бы один из a и b является TypedArray с более чем одним байтом на запись, например Uint16Array, результат будет вычислен с использованием порядка байтов платформы.

Когда оба входа являются Float32Arrays или Float64Arrays, эта функция может возвращать неожиданные результаты из-за IEEE 754 кодирования чисел с плавающей запятой. В частности, ни x === y, ни Object.is(x, y) не подразумевает, что байтовые представления двух чисел с плавающей запятой x и y равны.

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

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

[История]

ВерсияИзменения
v18.0.0Передача невалидной функции обратного вызова аргументу callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v15.12.0Добавлен необязательный аргумент обратного вызова.
v15.0.0Аргументы data, key и signature также могут быть ArrayBuffer.
v13.2.0, v12.16.0Эта функция теперь поддерживает подписи IEEE-P1363 DSA и ECDSA.
v12.0.0Добавлено в: v12.0.0

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

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

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

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

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

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

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

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

Аргумент signature - это ранее вычисленная подпись для data.

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

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

crypto.webcrypto ​

Добавлено в версии: v15.0.0

Тип: <Crypto> Реализация стандарта Web Crypto API.

Подробности см. в документации Web Crypto API.

Примечания ​

Использование строк в качестве входных данных для криптографических API ​

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

При передаче строк в криптографические API следует учитывать следующие факторы.

  • Не все последовательности байтов являются допустимыми строками UTF-8. Поэтому, когда последовательность байтов длиной n получается из строки, ее энтропия обычно ниже, чем энтропия случайной или псевдослучайной последовательности из n байтов. Например, ни одна строка UTF-8 не приведет к последовательности байтов c0 af. Секретные ключи должны почти исключительно быть случайными или псевдослучайными последовательностями байтов.
  • Аналогично, при преобразовании случайных или псевдослучайных последовательностей байтов в строки UTF-8 подпоследовательности, не представляющие допустимые кодовые точки, могут быть заменены символом замены Unicode (U+FFFD). Байтовое представление результирующей строки Unicode может, следовательно, не совпадать с последовательностью байтов, из которой была создана строка. Выходы шифров, хеш-функций, алгоритмов подписи и функций деривации ключей являются псевдослучайными последовательностями байтов и не должны использоваться в качестве строк Unicode.
  • Когда строки получаются от пользователя, некоторые символы Unicode могут быть представлены несколькими эквивалентными способами, приводящими к разным последовательностям байтов. Например, при передаче пользовательской парольной фразы в функцию деривации ключей, такую как PBKDF2 или scrypt, результат функции деривации ключей зависит от того, использует ли строка составные или разложенные символы. Node.js не нормализует представления символов. Разработчикам следует рассмотреть возможность использования String.prototype.normalize() на пользовательских вводах перед их передачей в криптографические API.

Устаревший API потоков (до Node.js 0.10) ​

Модуль Crypto был добавлен в Node.js до появления концепции унифицированного API потоков и до появления объектов Buffer для обработки двоичных данных. Таким образом, многие классы crypto имеют методы, которые обычно не встречаются в других классах Node.js, реализующих API потоков (например, update(), final() или digest()). Кроме того, многие методы принимали и возвращали строки в кодировке 'latin1' по умолчанию, а не Bufferы. После Node.js v0.8 это значение по умолчанию было изменено на использование объектов Buffer по умолчанию.

Поддержка слабых или скомпрометированных алгоритмов ​

Модуль node:crypto по-прежнему поддерживает некоторые алгоритмы, которые уже скомпрометированы и не рекомендуются к использованию. API также позволяет использовать шифры и хеши с небольшим размером ключа, которые слишком слабы для безопасного использования.

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

Основываясь на рекомендациях NIST SP 800-131A:

  • MD5 и SHA-1 больше не приемлемы там, где требуется устойчивость к коллизиям, например, в цифровых подписях.
  • Рекомендуется, чтобы ключ, используемый с алгоритмами RSA, DSA и DH, имел длину не менее 2048 бит, а кривая ECDSA и ECDH — не менее 224 бит, чтобы их можно было безопасно использовать в течение нескольких лет.
  • Группы DH modp1, modp2 и modp5 имеют размер ключа менее 2048 бит и не рекомендуются.

См. справку для получения других рекомендаций и подробностей.

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

Режим CCM ​

CCM — один из поддерживаемых алгоритмов AEAD. Приложения, использующие этот режим, должны соблюдать определенные ограничения при использовании API шифрования:

  • Длина тега аутентификации должна быть указана во время создания шифра с помощью параметра authTagLength и должна быть одним из следующих значений: 4, 6, 8, 10, 12, 14 или 16 байт.
  • Длина вектора инициализации (nonce) N должна быть от 7 до 13 байт (7 ≤ N ≤ 13).
  • Длина открытого текста ограничена 2 ** (8 * (15 - N)) байтами.
  • При расшифровке тег аутентификации должен быть установлен с помощью setAuthTag() перед вызовом update(). В противном случае расшифровка завершится неудачей, и final() вызовет ошибку в соответствии с разделом 2.6 RFC 3610.
  • Использование потоковых методов, таких как write(data), end(data) или pipe() в режиме CCM, может привести к сбою, поскольку CCM не может обрабатывать более одного фрагмента данных на экземпляр.
  • При передаче дополнительных аутентифицированных данных (AAD) длина фактического сообщения в байтах должна быть передана в setAAD() с помощью параметра plaintextLength. Многие криптографические библиотеки включают тег аутентификации в зашифрованный текст, что означает, что они создают зашифрованные тексты длиной plaintextLength + authTagLength. Node.js не включает тег аутентификации, поэтому длина зашифрованного текста всегда равна plaintextLength. Это не обязательно, если AAD не используется.
  • Поскольку CCM обрабатывает все сообщение сразу, update() должен быть вызван ровно один раз.
  • Даже если вызова update() достаточно для шифрования/дешифрования сообщения, приложения должны вызвать final(), чтобы вычислить или проверить тег аутентификации.
js
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);
js
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, который можно установить, следуя инструкциям в FIPS README-файле OpenSSL.

Для поддержки FIPS в Node.js вам потребуется:

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

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

text
nodejs_conf = nodejs_init

.include /<абсолютный путь>/fipsmodule.cnf

[nodejs_init]
providers = provider_sect

[provider_sect]
default = default_sect
# Имя раздела fips должно совпадать с именем раздела внутри {#the-fips-section-name-should-match-the-section-name-inside-the}
# включенного fipsmodule.cnf.
fips = fips_sect

[default_sect]
activate = 1

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

bash
openssl fipsinstall

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

bash
export OPENSSL_CONF=/<путь к файлу конфигурации>/nodejs.cnf
export OPENSSL_MODULES=/<путь к openssl lib>/ossl-modules

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

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

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

text
nodejs_conf = nodejs_init

.include /<абсолютный путь>/fipsmodule.cnf

[nodejs_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
default = default_sect
# Имя раздела fips должно совпадать с именем раздела внутри {#included-fipsmodulecnf}
# включенного fipsmodule.cnf.
fips = fips_sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

Крипто константы ​

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

Опции OpenSSL ​

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

КонстантаОписание
SSL_OP_ALLПрименяет несколько обходных путей для исправления ошибок в OpenSSL. Смотрите https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set_options.html для подробностей.
SSL_OP_ALLOW_NO_DHE_KEXУказывает OpenSSL разрешить режим обмена ключами, не основанный на [EC]DHE, для TLS v1.3
SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATIONРазрешает устаревшее небезопасное пересогласование между OpenSSL и неисправленными клиентами или серверами. Смотрите https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set_options.html.
SSL_OP_CIPHER_SERVER_PREFERENCEПытается использовать предпочтения сервера, а не клиента, при выборе шифра. Поведение зависит от версии протокола. Смотрите https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set_options.html.
SSL_OP_CISCO_ANYCONNECTУказывает OpenSSL использовать идентификатор версии Cisco DTLS_BAD_VER.
SSL_OP_COOKIE_EXCHANGEУказывает OpenSSL включить обмен cookie.
SSL_OP_CRYPTOPRO_TLSEXT_BUGУказывает OpenSSL добавить расширение server-hello из ранней версии черновика cryptopro.
SSL_OP_DONT_INSERT_EMPTY_FRAGMENTSУказывает OpenSSL отключить обходной путь для уязвимости SSL 3.0/TLS 1.0, добавленный в OpenSSL 0.9.6d.
SSL_OP_LEGACY_SERVER_CONNECTРазрешает начальное подключение к серверам, которые не поддерживают RI.
SSL_OP_NO_COMPRESSIONУказывает OpenSSL отключить поддержку сжатия SSL/TLS.
SSL_OP_NO_ENCRYPT_THEN_MACУказывает OpenSSL отключить encrypt-then-MAC.
SSL_OP_NO_QUERY_MTU
SSL_OP_NO_RENEGOTIATIONУказывает OpenSSL отключить пересогласование.
SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATIONУказывает OpenSSL всегда начинать новую сессию при выполнении пересогласования.
SSL_OP_NO_SSLv2Указывает OpenSSL отключить SSL v2
SSL_OP_NO_SSLv3Указывает OpenSSL отключить SSL v3
SSL_OP_NO_TICKETУказывает OpenSSL отключить использование тикетов RFC4507bis.
SSL_OP_NO_TLSv1Указывает OpenSSL отключить TLS v1
SSL_OP_NO_TLSv1_1Указывает OpenSSL отключить TLS v1.1
SSL_OP_NO_TLSv1_2Указывает OpenSSL отключить TLS v1.2
SSL_OP_NO_TLSv1_3Указывает OpenSSL отключить TLS v1.3
SSL_OP_PRIORITIZE_CHACHAУказывает серверу OpenSSL приоритизировать ChaCha20-Poly1305, когда это делает клиент. Эта опция не действует, если SSL_OP_CIPHER_SERVER_PREFERENCE не включена.
SSL_OP_TLS_ROLLBACK_BUGУказывает OpenSSL отключить обнаружение атаки отката версии.

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

КонстантаОписание
ENGINE_METHOD_RSAОграничение использования движка RSA
ENGINE_METHOD_DSAОграничение использования движка DSA
ENGINE_METHOD_DHОграничение использования движка DH
ENGINE_METHOD_RANDОграничение использования движка RAND
ENGINE_METHOD_ECОграничение использования движка EC
ENGINE_METHOD_CIPHERSОграничение использования движка CIPHERS
ENGINE_METHOD_DIGESTSОграничение использования движка DIGESTS
ENGINE_METHOD_PKEY_METHSОграничение использования движка PKEY_METHS
ENGINE_METHOD_PKEY_ASN1_METHSОграничение использования движка PKEY_ASN1_METHS
ENGINE_METHOD_ALL
ENGINE_METHOD_NONE

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

КонстантаОписание
DH_CHECK_P_NOT_SAFE_PRIME
DH_CHECK_P_NOT_PRIME
DH_UNABLE_TO_CHECK_GENERATOR
DH_NOT_SUITABLE_GENERATOR
RSA_PKCS1_PADDING
RSA_SSLV23_PADDING
RSA_NO_PADDING
RSA_PKCS1_OAEP_PADDING
RSA_X931_PADDING
RSA_PKCS1_PSS_PADDING
RSA_PSS_SALTLEN_DIGESTУстанавливает длину соли для RSA_PKCS1_PSS_PADDING равной размеру дайджеста при подписи или проверке.
RSA_PSS_SALTLEN_MAX_SIGNУстанавливает длину соли для RSA_PKCS1_PSS_PADDING равной максимально допустимому значению при подписании данных.
RSA_PSS_SALTLEN_AUTOПриводит к тому, что длина соли для RSA_PKCS1_PSS_PADDING определяется автоматически при проверке подписи.
POINT_CONVERSION_COMPRESSED
POINT_CONVERSION_UNCOMPRESSED
POINT_CONVERSION_HYBRID

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

КонстантаОписание
defaultCoreCipherListУказывает встроенный список шифров по умолчанию, используемый Node.js.
defaultCipherListУказывает активный список шифров по умолчанию, используемый текущим процессом Node.js.