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

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

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

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

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

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

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

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

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

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

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

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

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

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

Форматы ключей

Асимметричные ключи могут быть представлены в нескольких форматах. Рекомендуется один раз импортировать ключевой материал в KeyObject и повторно использовать его для всех последующих операций: это позволяет избежать повторного анализа и обеспечивает наилучшую производительность.

Если использование KeyObject нецелесообразно — например, если ключевой материал поступает в сообщении протокола и используется только один раз, — большинство криптографических функций также принимают строку PEM или объект, напрямую задающий формат и ключевой материал. Полный список параметров для каждого формата см. в разделах crypto.createPublicKey(), crypto.createPrivateKey() и keyObject.export().

KeyObject

KeyObject — это хранящееся в памяти представление разобранного ключа. Оно создаётся с помощью crypto.createPublicKey(), crypto.createPrivateKey(), crypto.createSecretKey() или функций генерации ключей, таких как crypto.generateKeyPair(). Первая криптографическая операция с данным KeyObject может выполняться медленнее последующих, поскольку OpenSSL при первом использовании лениво инициализирует внутренние кэши.

PEM и DER

PEM и DER — традиционные форматы кодирования асимметричных ключей на основе структур ASN.1.

• PEM — текстовый формат, в котором данные DER, закодированные в Base64, заключены между строками заголовка и окончания (например, -----BEGIN PUBLIC KEY-----). Строки PEM можно напрямую передавать в большинство криптографических операций.
• DER — бинарное представление тех же структур ASN.1. При передаче входных данных DER необходимо явно указывать type (обычно 'spki' или 'pkcs8').

JSON Web Key (JWK)

JSON Web Key (JWK) — формат представления ключей на основе JSON, определённый в RFC 7517. В JWK каждый компонент ключа кодируется как отдельное значение Base64url внутри объекта JSON. Для ключей RSA JWK позволяет избежать накладных расходов на разбор ASN.1 и является самым быстрым форматом импорта сериализованных данных.

Форматы необработанных ключей

Форматы ключей 'raw-public', 'raw-private' и 'raw-seed' позволяют импортировать и экспортировать необработанный ключевой материал без какой-либо обёртки кодирования. Сведения об использовании см. в разделах keyObject.export(), crypto.createPublicKey() и crypto.createPrivateKey().

'raw-public' — обычно самый быстрый способ импорта открытого ключа. 'raw-private' и 'raw-seed' не всегда быстрее других форматов, поскольку содержат только закрытый скаляр или начальное значение: при импорте необходимо вывести компонент открытого ключа (например, выполнить умножение точки эллиптической кривой или расширение начального значения), что может быть затратным. Другие форматы содержат и закрытые, и открытые компоненты, позволяя избежать этих вычислений.

Выбор формата ключа

Всегда отдавайте предпочтение KeyObject — создайте его из доступного формата и используйте повторно. Приведённые ниже рекомендации относятся только к выбору между форматами сериализации: для импорта в KeyObject или передачи ключевого материала непосредственно в операцию, когда использование KeyObject нецелесообразно.

Импорт ключей

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

Затраты на импорт складываются из двух частей: накладных расходов на разбор (декодирование обёртки сериализации) и вычислений ключа (математических операций, необходимых для восстановления полного ключа, например получения открытого ключа из закрытого скаляра или расширения начального значения). Какая часть будет преобладать, зависит от типа ключа. Например:

• Открытые ключи — 'raw-public' является самым быстрым форматом сериализации, поскольку необработанный формат позволяет пропустить декодирование ASN.1 и Base64.
• Закрытые ключи EC — 'raw-private' быстрее PEM или DER, поскольку не требует разбора ASN.1. Однако для более крупных кривых (например, P-384, P-521) необходимое получение открытой точки из закрытого скаляра становится затратным и уменьшает преимущество.
• Ключи RSA — 'jwk' является самым быстрым форматом сериализации. JWK представляет компоненты ключа RSA в виде отдельных целых чисел, закодированных в Base64url, полностью исключая накладные расходы на разбор ASN.1.

Передача ключевого материала непосредственно в операциях

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

В операциях, где преобладают криптографические вычисления, например при подписании с помощью RSA или согласовании ключей ECDH с P-384 или P-521, формат сериализации практически не влияет на общую пропускную способность, поэтому выбирайте наиболее удобный формат. Для лёгких операций, таких как подписание или проверка Ed25519, затраты на импорт составляют большую долю общего времени, поэтому более быстрый формат, например 'raw-public' или 'raw-private', может заметно повысить пропускную способность.

Даже если один и тот же ключевой материал используется всего несколько раз, его стоит импортировать в KeyObject, а не передавать повторно в необработанном виде или в формате PEM.

Примеры

Пример: повторное использование KeyObject для операций подписания и проверки:

import { promisify } from 'node:util';
const { generateKeyPair, sign, verify } = await import('node:crypto');

const { publicKey, privateKey } = await promisify(generateKeyPair)('ed25519');

// A KeyObject holds the parsed key in memory and can be reused
// across multiple operations without re-parsing.
const data = new TextEncoder().encode('message to sign');
const signature = sign(null, data, privateKey);
verify(null, data, publicKey, signature);
mjscopy

Пример: импорт ключей в различных форматах в KeyObject:

import { promisify } from 'node:util';
const {
  createPrivateKey, createPublicKey, generateKeyPair,
} = await import('node:crypto');

const generated = await promisify(generateKeyPair)('ed25519');

// PEM
const privatePem = generated.privateKey.export({ format: 'pem', type: 'pkcs8' });
const publicPem = generated.publicKey.export({ format: 'pem', type: 'spki' });
createPrivateKey(privatePem);
createPublicKey(publicPem);

// DER - requires explicit type
const privateDer = generated.privateKey.export({ format: 'der', type: 'pkcs8' });
const publicDer = generated.publicKey.export({ format: 'der', type: 'spki' });
createPrivateKey({ key: privateDer, format: 'der', type: 'pkcs8' });
createPublicKey({ key: publicDer, format: 'der', type: 'spki' });

// JWK
const privateJwk = generated.privateKey.export({ format: 'jwk' });
const publicJwk = generated.publicKey.export({ format: 'jwk' });
createPrivateKey({ key: privateJwk, format: 'jwk' });
createPublicKey({ key: publicJwk, format: 'jwk' });

// Raw
const rawPriv = generated.privateKey.export({ format: 'raw-private' });
const rawPub = generated.publicKey.export({ format: 'raw-public' });
createPrivateKey({ key: rawPriv, format: 'raw-private', asymmetricKeyType: 'ed25519' });
createPublicKey({ key: rawPub, format: 'raw-public', asymmetricKeyType: 'ed25519' });
mjscopy

Пример: передача ключевого материала непосредственно в crypto.sign() и crypto.verify() без предварительного создания KeyObject:

import { promisify } from 'node:util';
const { generateKeyPair, sign, verify } = await import('node:crypto');

const generated = await promisify(generateKeyPair)('ed25519');

const data = new TextEncoder().encode('message to sign');

// PEM strings
const privatePem = generated.privateKey.export({ format: 'pem', type: 'pkcs8' });
const publicPem = generated.publicKey.export({ format: 'pem', type: 'spki' });
const sig1 = sign(null, data, privatePem);
verify(null, data, publicPem, sig1);

// JWK objects
const privateJwk = generated.privateKey.export({ format: 'jwk' });
const publicJwk = generated.publicKey.export({ format: 'jwk' });
const sig2 = sign(null, data, { key: privateJwk, format: 'jwk' });
verify(null, data, { key: publicJwk, format: 'jwk' }, sig2);

// Raw key bytes
const rawPriv = generated.privateKey.export({ format: 'raw-private' });
const rawPub = generated.publicKey.export({ format: 'raw-public' });
const sig3 = sign(null, data, {
  key: rawPriv, format: 'raw-private', asymmetricKeyType: 'ed25519',
});
verify(null, data, {
  key: rawPub, format: 'raw-public', asymmetricKeyType: 'ed25519',
}, sig3);
mjscopy

Пример: для ключей EC при импорте необработанных ключей требуется параметр namedCurve:

import { promisify } from 'node:util';
const {
  createPrivateKey, createPublicKey, generateKeyPair, sign, verify,
} = await import('node:crypto');

const generated = await promisify(generateKeyPair)('ec', {
  namedCurve: 'P-256',
});

// Export the raw EC public key (uncompressed by default).
const rawPublicKey = generated.publicKey.export({ format: 'raw-public' });

// The following is equivalent.
const rawPublicKeyUncompressed = generated.publicKey.export({
  format: 'raw-public',
  type: 'uncompressed',
});

// Export compressed point format.
const rawPublicKeyCompressed = generated.publicKey.export({
  format: 'raw-public',
  type: 'compressed',
});

// Export the raw EC private key.
const rawPrivateKey = generated.privateKey.export({ format: 'raw-private' });

// Import the raw EC keys.
// Both compressed and uncompressed point formats are accepted.
const publicKey = createPublicKey({
  key: rawPublicKey,
  format: 'raw-public',
  asymmetricKeyType: 'ec',
  namedCurve: 'P-256',
});
const privateKey = createPrivateKey({
  key: rawPrivateKey,
  format: 'raw-private',
  asymmetricKeyType: 'ec',
  namedCurve: 'P-256',
});

const data = new TextEncoder().encode('message to sign');
const signature = sign('sha256', data, privateKey);
verify('sha256', data, publicKey, signature);
mjscopy

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

import { promisify } from 'node:util';
const {
  createPrivateKey, decapsulate, encapsulate, generateKeyPair,
} = await import('node:crypto');

const generated = await promisify(generateKeyPair)('ml-kem-768');

// Export the raw seed (64 bytes for ML-KEM).
const seed = generated.privateKey.export({ format: 'raw-seed' });

// Import the raw seed.
const privateKey = createPrivateKey({
  key: seed,
  format: 'raw-seed',
  asymmetricKeyType: 'ml-kem-768',
});

const { ciphertext } = encapsulate(generated.publicKey);
decapsulate(privateKey, ciphertext);
mjscopy

Класс: Certificate

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Устаревший API

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

new crypto.Certificate()

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

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

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

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

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

certificate.exportChallenge(spkac[, encoding])

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

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

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

certificate.exportPublicKey(spkac[, encoding])

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

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

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

certificate.verifySpkac(spkac[, encoding])

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

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

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

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

Класс: Cipheriv

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

cipher.final([outputEncoding])

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

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

cipher.getAuthTag()

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

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

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

cipher.setAAD(buffer[, options])

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

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

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

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

cipher.setAutoPadding([autoPadding])

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

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

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

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

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

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

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

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

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

Класс: Decipheriv

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

decipher.final([outputEncoding])

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

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

decipher.setAAD(buffer[, options])

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

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

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

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

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

decipher.setAuthTag(buffer[, encoding])

• buffer <string> | <Buffer> | <ArrayBuffer> | <TypedArray> | <DataView>
• encoding <string> Кодировка строки, используемая, если buffer является строкой.
• Возвращает: <Decipheriv> Тот же экземпляр Decipheriv для цепочки вызовов методов.

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

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

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

decipher.setAutoPadding([autoPadding])

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

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

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

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

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

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

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

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

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

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

Класс: DiffieHellman

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

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

import assert from 'node:assert';

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

diffieHellman.generateKeys([encoding])

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

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

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

diffieHellman.getGenerator([encoding])

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

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

diffieHellman.getPrime([encoding])

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

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

diffieHellman.getPrivateKey([encoding])

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

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

diffieHellman.getPublicKey([encoding])

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

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

diffieHellman.setPrivateKey(privateKey[, encoding])

• privateKey <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• encoding <string> Кодировка строки privateKey.

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

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

diffieHellman.setPublicKey(publicKey[, encoding])

• publicKey <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• encoding <string> Кодировка строки publicKey.

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

diffieHellman.verifyError

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

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

• DH_CHECK_P_NOT_SAFE_PRIME
• DH_CHECK_P_NOT_PRIME
• DH_UNABLE_TO_CHECK_GENERATOR
• DH_NOT_SUITABLE_GENERATOR

Класс: DiffieHellmanGroup

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

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

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

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

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

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

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

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

Класс: ECDH

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

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

import assert from 'node:assert';

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Пример (снятие сжатия ключа):

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ecdh.getPrivateKey([encoding])

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

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

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

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

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

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

ecdh.setPrivateKey(privateKey[, encoding])

• privateKey <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• encoding <string> Кодировка строки privateKey.

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

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

ecdh.setPublicKey(publicKey[, encoding])

• publicKey <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• encoding <string> Кодировка строки publicKey.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Класс: Hash

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

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

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

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

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

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

const hash = createHash('sha256');

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

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

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

const hash = createHash('sha256');

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

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

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

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

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

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

const hash = createHash('sha256');

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

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

const hash = createHash('sha256');

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

hash.copy([options])

• options <Object> stream.transform параметры
• Возвращает: <Hash>

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

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

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

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

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

const hash = createHash('sha256');

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

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

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

// Etc.

hash.digest([encoding])

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

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

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

hash.update(data[, inputEncoding])

• data <string> | <Buffer> | <TypedArray> | <DataView>
• inputEncoding <string> Кодировка строки data.

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

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

Класс: Hmac

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

hmac.digest([encoding])

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

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

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

hmac.update(data[, inputEncoding])

• data <string> | <Buffer> | <TypedArray> | <DataView>
• inputEncoding <string> Кодировка строки data.

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

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

Класс: KeyObject

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

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

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

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

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

Возвращает базовый объект <KeyObject> для объекта <CryptoKey>. Возвращённый объект <KeyObject> не сохраняет никаких ограничений, наложенных Web Crypto API на исходный объект <CryptoKey>, таких как разрешённые способы использования ключа, привязки алгоритма или хеш-алгоритма и флаг возможности экспорта. В частности, базовый материал ключа возвращённого объекта <KeyObject> всегда можно экспортировать.

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)

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

• Тип: <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

• Тип: <string>

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

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

keyObject.equals(otherKeyObject)

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

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

keyObject.export([options])

• options <Object>
• Возвращает: <string> | <Buffer> | <Object>

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

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

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

• format <string> Должно быть 'pem', 'der', 'jwk' или 'raw-public'. Сведения о поддержке форматов см. в разделе типы асимметричных ключей.
• type <string> Если format имеет значение 'pem' или 'der', должно быть 'pkcs1' (только RSA) или 'spki'. Для ключей EC с форматом 'raw-public' может иметь значение 'uncompressed' (по умолчанию) или 'compressed'. Игнорируется, если format имеет значение 'jwk'.

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

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

Тип результата зависит от выбранного формата кодирования: для PEM результатом будет строка, для DER — буфер с данными, закодированными в DER, а для JWK — объект. Для необработанных форматов возвращается <Buffer>, содержащий исходный материал ключа.

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

keyObject.symmetricKeySize

• Тип: <number>

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

keyObject.toCryptoKey(algorithm, extractable, keyUsages)

• algorithm <string> | <Algorithm> | <RsaHashedImportParams> | <EcKeyImportParams> | <HmacImportParams>

• extractable <boolean>
• keyUsages <string[]> См. раздел Использование ключей.
• Возвращает: <CryptoKey>

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

keyObject.type

• Тип: <string>

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

Класс: Sign

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

sign.sign(privateKey[, outputEncoding])

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

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

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

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

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

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

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

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

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

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

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

sign.update(data[, inputEncoding])

• data <string> | <Buffer> | <TypedArray> | <DataView>
• inputEncoding <string> Кодировка строки data.

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

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

Класс: Verify

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

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

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

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

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

verify.update(data[, inputEncoding])

• data <string> | <Buffer> | <TypedArray> | <DataView>
• inputEncoding <string> Кодировка строки data.

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

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

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

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

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

Если 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, если только хеш-функция 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

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

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

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

console.log(x509.subject);

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

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

console.log(x509.subject);

new X509Certificate(buffer)

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

x509.ca

• Тип: <boolean> Имеет значение true, если это сертификат центра сертификации (CA).

x509.checkEmail(email[, options])

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

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

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

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

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

x509.checkHost(name[, options])

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

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

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

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

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

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

x509.checkIP(ip)

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

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

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

x509.checkIssued(otherCert)

• otherCert <X509Certificate>
• Возвращает: <boolean>

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

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

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

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

x509.checkPrivateKey(privateKey)

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

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

x509.fingerprint

• Тип: <string>

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

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

x509.fingerprint256

• Тип: <string>

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

x509.fingerprint512

• Тип: <string>

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

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

x509.infoAccess

• Тип: <string>

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

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

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

x509.issuer

• Тип: <string>

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

x509.issuerCertificate

• Тип: <X509Certificate>

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

x509.keyUsage

• Тип: <string[]>

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

x509.publicKey

• Тип: <KeyObject>

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

x509.raw

• Тип: <Buffer>

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

x509.serialNumber

• Тип: <string>

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

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

x509.subject

• Тип: <string>

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

x509.subjectAltName

• Тип: <string>

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

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

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

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

x509.toJSON()

• Тип: <string>

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

x509.toLegacyObject()

• Тип: <Object>

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

x509.toString()

• Тип: <string>

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

x509.validFrom

• Тип: <string>

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

x509.validFromDate

• Тип: <Date>

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

x509.validTo

• Тип: <string>

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

x509.validToDate

• Тип: <Date>

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

x509.signatureAlgorithm

• Тип: <string> | <undefined>

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

x509.signatureAlgorithmOid

• Тип: <string>

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

x509.verify(publicKey)

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

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

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

crypto.argon2(algorithm, parameters, callback)

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

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

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

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

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

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

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

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

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

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

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

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

crypto.argon2Sync(algorithm, parameters)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

crypto.checkPrimeSync(candidate[, options])

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

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

crypto.constants

• Тип: <Object>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

crypto.createDiffieHellman(primeLength[, generator])

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

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

crypto.createDiffieHellmanGroup(name)

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

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

crypto.createECDH(curveName)

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

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

crypto.createHash(algorithm[, options])

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

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

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

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

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

const filename = argv[2];

const hash = createHash('sha256');

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

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

const filename = argv[2];

const hash = createHash('sha256');

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

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

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

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

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

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

Пример: создание HMAC SHA-256 для файла

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

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

const filename = argv[2];

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

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

crypto.createPrivateKey(key)

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

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

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

crypto.createPublicKey(key)

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

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

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

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

crypto.createSecretKey(key[, encoding])

• key <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• encoding <string> Кодировка строки, используемая, если key — строка.
• Возвращает: <KeyObject>

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

crypto.createSign(algorithm[, options])

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

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

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

crypto.createVerify(algorithm[, options])

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

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

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

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

• key <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> Закрытый ключ
• ciphertext <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• callback <Function>
  • err <Error>
  • sharedKey <Buffer>
• Возвращает: <Buffer>, если функция callback не указана.

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

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

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

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

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

crypto.diffieHellman(options[, callback])

• options <Object>
  • privateKey <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject>
  • publicKey <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject>
• callback <Function>
  • err <Error>
  • secret <Buffer>
• Возвращает: <Buffer>, если функция callback не указана.

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

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

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

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

crypto.encapsulate(key[, callback])

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

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

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

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

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

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

crypto.fips

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

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

crypto.generateKey(type, options, callback)

• 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>
  • err <Error>
  • key <KeyObject>

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

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

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

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

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

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

crypto.generateKeyPair(type, options, callback)

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

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

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

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

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

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, которому будет передано значение undefined в err, а также publicKey / privateKey, представляющие сгенерированную пару ключей.

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

crypto.generateKeyPairSync(type, options)

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

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

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

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

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

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

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

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

crypto.generateKeySync(type, options)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

crypto.generatePrimeSync(size[, options])

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

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

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

Параметры options.add и options.rem можно использовать для задания дополнительных требований, например, для 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>.

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

crypto.getCipherInfo(nameOrNid[, options])

• nameOrNid <string> | <number> Имя или nid шифра, сведения о котором нужно получить.
• options <Object>
  • keyLength <number> Длина тестового ключа.
  • ivLength <number> Длина тестового IV.
• Возвращает: <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() возвращает стандартные значения для таких шифров. Чтобы проверить, допустима ли заданная длина ключа или IV для данного шифра, используйте параметры keyLength и ivLength. Если заданные значения недопустимы, будет возвращено undefined.

crypto.getCiphers()

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

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

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

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

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

crypto.getCurves()

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

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

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

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

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

crypto.getDiffieHellman(groupName)

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

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

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

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

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

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

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

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

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

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

crypto.getFips()

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

crypto.getHashes()

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

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

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

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

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

crypto.getRandomValues(typedArray)

• typedArray <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer>
• Возвращает: <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> Возвращает typedArray.

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

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

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

Вспомогательная функция для однократного создания дайджеста данных. При хешировании небольшого объема данных (<= 5MB), доступных сразу, она может работать быстрее, чем объектный интерфейс crypto.createHash(). Если объем данных может быть большим или данные передаются потоком, рекомендуется использовать вместо нее crypto.createHash().

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

Если options является строкой, она задает outputEncoding.

Пример:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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'

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

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

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

• password <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• salt <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• iterations <number>
• keylen <number>
• digest <string>
• callback <Function>
  • err <Error>
  • derivedKey <Buffer>

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

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

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

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

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

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

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

• password <string> | <Buffer> | <TypedArray> | <DataView>
• salt <string> | <Buffer> | <TypedArray> | <DataView>
• iterations <number>
• keylen <number>
• digest <string>
• Возвращает: <Buffer>

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

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

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

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

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

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

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

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

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

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

crypto.privateDecrypt(privateKey, buffer)

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

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

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

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

crypto.privateEncrypt(privateKey, buffer)

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

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

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

crypto.publicDecrypt(key, buffer)

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

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

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

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

crypto.publicEncrypt(key, buffer)

• key <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
  • key <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey> Открытый или закрытый ключ в кодировке PEM, <KeyObject> или <CryptoKey>.
  • oaepHash <string> Хеш-функция для заполнения OAEP и MGF1. По умолчанию: 'sha1'
  • oaepLabel <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> Метка для заполнения OAEP. Если она не указана, метка не используется.
  • passphrase <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> Необязательная парольная фраза для закрытого ключа.
  • padding <crypto.constants> Необязательное значение заполнения, определённое в crypto.constants; возможные значения: crypto.constants.RSA_NO_PADDING, crypto.constants.RSA_PKCS1_PADDING или crypto.constants.RSA_PKCS1_OAEP_PADDING.
  • encoding <string> Кодировка строки, используемая, когда buffer, key, oaepLabel или passphrase являются строками.
• buffer <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• Возвращает: <Buffer> Новый Buffer с зашифрованным содержимым.

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

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

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

crypto.randomBytes(size[, callback])

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• 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 не указана, будет выброшена ошибка.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• min <integer> Начало диапазона случайных чисел (включительно). По умолчанию: 0.
• max <integer> Конец диапазона случайных чисел (исключительно).
• callback <Function> function(err, n) {}.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

crypto.randomUUID([options])

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

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

crypto.randomUUIDv7([options])

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

Генерирует случайный UUID версии 7 по RFC 9562. UUID содержит метку времени Unix с точностью до миллисекунды в 48 старших битах, за которой следуют криптографически стойкие случайные биты в остальных полях, что делает его подходящим для использования в качестве ключа базы данных с сортировкой по времени. Встроенная метка времени зависит от немонотонных часов и не гарантирует строгого возрастания.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

const {
  scryptSync,
} = await import('node:crypto');
// Using the factory defaults.

const key1 = scryptSync('password', 'salt', 64);
console.log(key1.toString('hex'));  // '3745e48...08d59ae'
// Using a custom N parameter. Must be a power of two.
const key2 = scryptSync('password', 'salt', 64, { N: 1024 });
console.log(key2.toString('hex'));  // '3745e48...aa39b34'

const {
  scryptSync,
} = require('node:crypto');
// Using the factory defaults.

const key1 = scryptSync('password', 'salt', 64);
console.log(key1.toString('hex'));  // '3745e48...08d59ae'
// Using a custom N parameter. Must be a power of two.
const key2 = scryptSync('password', 'salt', 64, { N: 1024 });
console.log(key2.toString('hex'));  // '3745e48...aa39b34'

crypto.secureHeapUsed()

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

crypto.setEngine(engine[, flags])

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

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

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

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

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

crypto.setFips(bool)