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

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

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

let crypto;
try {
  crypto = require('crypto');
} catch (err) {
  console.log('crypto support is disabled!');
}

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

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

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

Класс: Certificate

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

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

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

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

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

Модули MJS

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

Модули CJS

const { Certificate } = require('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, включающей открытый ключ и запрос.

Модули MJS

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

Модули CJS

const { Certificate } = require('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 — в противном случае.

Модули MJS

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

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

Модули CJS

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

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

API устаревшего интерфейса

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

new crypto.Certificate()

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

Модули MJS

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

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

Модули CJS

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

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

certificate.exportChallenge(spkac[, encoding])

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

Модули MJS

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

Модули CJS

const { Certificate } = require('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, включающей открытый ключ и запрос.

Модули MJS

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

Модули CJS

const { Certificate } = require('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 — в противном случае.

Модули MJS

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

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

Модули CJS

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

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

Класс: Cipher

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

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

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

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

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

Модули MJS

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

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

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

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

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

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

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

Модули CJS

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

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

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

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

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

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

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

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

Модули MJS

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

import {
  pipeline
} from 'stream';

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

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

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

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

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

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

Модули CJS

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

const {
  pipeline
} = require('stream');

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

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

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

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

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

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

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

Модули MJS

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

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

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

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

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

Модули CJS

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

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

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

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

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

cipher.final([outputEncoding])

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

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

cipher.getAuthTag()

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

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

cipher.setAAD(buffer[, options])

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

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

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

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

cipher.setAutoPadding([autoPadding])

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

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

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

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

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

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

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

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

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

Класс: Decipher

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

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

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

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

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

Модули MJS

import { Buffer } from 'buffer';
const {
  scryptSync,
  createDecipheriv
} = await import('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', () => {
  while (null !== (chunk = decipher.read())) {
    decrypted += chunk.toString('utf8');
  }
});
decipher.on('end', () => {
  console.log(decrypted);
  // Prints: some clear text data
});

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

Модули CJS

const {
  scryptSync,
  createDecipheriv,
} = require('crypto');
const { Buffer } = require('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', () => {
  while (null !== (chunk = decipher.read())) {
    decrypted += chunk.toString('utf8');
  }
});
decipher.on('end', () => {
  console.log(decrypted);
  // Prints: some clear text data
});

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

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

Модули MJS

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

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

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

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

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

Модули CJS

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

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

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

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

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

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

Модули MJS

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

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

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

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

Модули CJS

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

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

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

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

decipher.final([outputEncoding])

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

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

decipher.setAAD(buffer[, options])

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

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

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

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

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

decipher.setAuthTag(buffer[, encoding])

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

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

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

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

decipher.setAutoPadding([autoPadding])

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

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

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

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

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

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

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

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

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

Класс: DiffieHellman

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

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

Модули MJS

import assert from 'assert';

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

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

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

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

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

Модули CJS

const assert = require('assert');

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

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

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

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

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

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

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

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

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

diffieHellman.generateKeys([encoding])

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

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

diffieHellman.getGenerator([encoding])

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

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

diffieHellman.getPrime([encoding])

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

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

diffieHellman.getPrivateKey([encoding])

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

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

diffieHellman.getPublicKey([encoding])

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

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

diffieHellman.setPrivateKey(privateKey[, encoding])

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

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

diffieHellman.setPublicKey(publicKey[, encoding])

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

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

diffieHellman.verifyError

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

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

• DH_CHECK_P_NOT_SAFE_PRIME
• DH_CHECK_P_NOT_PRIME
• DH_UNABLE_TO_CHECK_GENERATOR
• DH_NOT_SUITABLE_GENERATOR

Класс: DiffieHellmanGroup

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

Модули MJS

const { createDiffieHellmanGroup } = await import('crypto');
const dh = createDiffieHellmanGroup('modp1');

Модули CJS

const { createDiffieHellmanGroup } = require('crypto');
const dh = createDiffieHellmanGroup('modp1');

Имя (например, 'modp1') взято из RFC 2412 (modp1 и 2) и RFC 3526:

$ perl -ne 'print "$1\n" if /"(modp\d+)"/' src/node_crypto_groups.h
modp1  #  768 bits
modp2  # 1024 bits
modp5  # 1536 bits
modp14 # 2048 bits
modp15 # etc.
modp16
modp17
modp18

Класс: ECDH

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

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

Модули MJS

import assert from 'assert';

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

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

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

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

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

Модули CJS

const assert = require('assert');

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

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

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

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

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

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

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

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

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

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

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

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

Модули MJS

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

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

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

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

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

Модули CJS

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ecdh.getPrivateKey([encoding])

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

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

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

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

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

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

ecdh.setPrivateKey(privateKey[, encoding])

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

Устанавливает приватный ключ EC Диффи-Хеллмана. Если 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() пытается сгенерировать открытую точку/ключ, соответствующую устанавливаемому закрытому ключу.

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

MJS модули

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

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

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

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

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

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

CJS модули

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

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

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

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

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

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

Класс: Hash

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

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

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

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

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

MJS модули

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

const hash = createHash('sha256');

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

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

CJS модули

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

const hash = createHash('sha256');

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

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

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

MJS модули

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

const hash = createHash('sha256');

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

CJS модули

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

const hash = createHash('sha256');

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

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

MJS модули

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

const hash = createHash('sha256');

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

CJS модули

const {
  createHash,
} = require('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() выбрасывается ошибка.

MJS модули

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

const hash = createHash('sha256');

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

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

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

// Etc.

CJS модули

// Calculate a rolling hash.
const {
  createHash,
} = require('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 больше нельзя использовать после вызова метода hash.digest(). Многократные вызовы приведут к ошибке.

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 в качестве потоков:

MJS модули

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

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

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

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

CJS модули

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

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

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

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

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

MJS модули

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

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

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

CJS модули

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

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

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

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

MJS модули

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

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

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

CJS модули

const {
  createHmac,
} = require('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 больше нельзя использовать после вызова hmac.digest(). Многократные вызовы к 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.

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

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

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

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

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

MJS модули

const { webcrypto, KeyObject } = await import('crypto');
const { subtle } = webcrypto;

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

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

CJS модули

const {
  webcrypto: {
    subtle,
  },
  KeyObject,
} = require('crypto');

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

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

keyObject.asymmetricKeyDetails

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

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

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

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

keyObject.asymmetricKeyType

• <строка>

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

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

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

keyObject.export([options])

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

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

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

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

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

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

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

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

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

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

keyObject.symmetricKeySize

• <число>

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

keyObject.type

• <строка>

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

Класс: Sign

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

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

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

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

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

Модули MJS

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

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

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

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

Модули CJS

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

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

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

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

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

Модули MJS

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

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

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

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

Модули CJS

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

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

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

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

sign.sign(privateKey[, outputEncoding])

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

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

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

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

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

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

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

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

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

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

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

sign.update(data[, inputEncoding])

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

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

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

Класс: Verify

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

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

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

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

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

verify.update(data[, inputEncoding])

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

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

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

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

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

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

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

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

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

• padding <целое> Дополнительный параметр заполнения для RSA, один из следующих:

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

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

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

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

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

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

Класс: X509Certificate

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

Модули MJS

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

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

console.log(x509.subject);

Модули CJS

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

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

console.log(x509.subject);

new X509Certificate(buffer)

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

x509.ca

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

x509.checkEmail(email[, options])

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

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

x509.checkHost(name[, options])

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

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

x509.checkIP(ip[, options])

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

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

x509.checkIssued(otherCert)

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

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

x509.checkPrivateKey(privateKey)

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

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

x509.fingerprint

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

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

x509.fingerprint256

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

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

x509.infoAccess

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

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

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

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

x509.issuer

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

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

x509.issuerCertificate

• Тип: <X509Certificate>

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

x509.keyUsage

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

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

x509.publicKey

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

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

x509.raw

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

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

x509.serialNumber

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

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

x509.subject

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

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

x509.subjectAltName

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

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

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

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

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

x509.toJSON()

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

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

x509.toLegacyObject()

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

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

x509.toString()

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

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

x509.validFrom

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

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

x509.validTo

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

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

x509.verify(publicKey)

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

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

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

crypto.constants

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

crypto.DEFAULT_ENCODING

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

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

Новые приложения должны ожидать, что кодировка по умолчанию — 'buffer'.

Это свойство устарело.

crypto.fips

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

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

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

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

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

crypto.checkPrimeSync(candidate[, options])

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

crypto.createDiffieHellman(primeLength[, generator])

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

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

crypto.createDiffieHellmanGroup(name)

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

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

crypto.createECDH(curveName)

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

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

crypto.createHash(algorithm[, options])

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

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

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

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

Модули MJS

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

const filename = argv[2];

const hash = createHash('sha256');

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

Модули CJS

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

const filename = argv[2];

const hash = createHash('sha256');

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

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

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

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

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

Значение key — это ключ HMAC, используемый для генерации криптографического хэша HMAC. Если это KeyObject, его тип должен быть secret.

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

Модули MJS

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

const filename = argv[2];

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

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

Модули CJS

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

const filename = argv[2];

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

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

crypto.createPrivateKey(key)

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

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

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

crypto.createPublicKey(key)

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

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

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

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

crypto.createSecretKey(key[, encoding])

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

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

crypto.createSign(algorithm[, options])

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

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

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

crypto.createVerify(algorithm[, options])

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

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

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

crypto.diffieHellman(options)

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

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

crypto.generateKey(type, options, callback)

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

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

Модули MJS

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

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

Модули CJS

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

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

crypto.generateKeyPair(type, options, callback)

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

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

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

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

Модули MJS

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

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

Модули CJS

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

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

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

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

crypto.generateKeyPairSync(type, options)

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

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

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

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

MJS-модули

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

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

CJS-модули

const {
  generateKeyPairSync,
} = require('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', минимальное значение равно 1, а максимальная длина равна 2³¹-1. Если значение не кратно 8, сгенерированный ключ будет усечен до Math.floor(length / 8).
    • Если type равно 'aes', длина должна быть одной из 128, 192, или 256.
• Возвращает: <KeyObject>

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

MJS-модули

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

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

CJS-модули

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

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

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 могут использоваться для выполнения дополнительных требований, например, для Диффи-Хеллмана:

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

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

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

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

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

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

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

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[]> Массив с именами поддерживаемых алгоритмов шифрования.

Модули MJS

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

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

Модули CJS

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

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

crypto.getCurves()

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

Модули MJS

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

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

Модули CJS

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

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

crypto.getDiffieHellman(groupName)

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

Создает предопределенный объект обмена ключами Диффи-Хеллмана. Поддерживаемые группы: 'modp1', 'modp2', 'modp5' (определены в RFC 2412, но см. Примечания) и 'modp14', 'modp15', 'modp16', 'modp17', 'modp18' (определены в RFC 3526). Возвращаемый объект имитирует интерфейс объектов, созданных методом crypto.createDiffieHellman(), но не позволит изменить ключи (например, с помощью diffieHellman.setPublicKey()). Преимущество использования этого метода состоит в том, что сторонам не нужно генерировать и обмениваться модулем группы заранее, что экономит процессорное время и время связи.

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

Модули MJS

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

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

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

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

Модули CJS

const {
  getDiffieHellman,
} = require('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 в противном случае. В будущей версии с изменением semver-major может измениться тип возвращаемого значения этого API на <boolean>.

crypto.getHashes()

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

Модули MJS

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

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

Модули CJS

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

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

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>. Любой из входных аргументов с неверными значениями или типами вызовет ошибку.

Модули MJS

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

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

Модули CJS

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

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

Модули MJS

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

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

Модули CJS

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

Обеспечивает асинхронную реализацию функции вывода ключа PBKDF2 (Password-Based Key Derivation Function 2). Выбранный алгоритм HMAC (digest) применяется для вывода ключа необходимой длины (keylen) из password, salt и iterations.

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

Если digest равно null, будет использоваться 'sha1'. Это поведение устарело, пожалуйста, укажите digest явно.

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

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

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

Модули MJS

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

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

Модули CJS

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

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

Свойство crypto.DEFAULT_ENCODING может использоваться для изменения способа передачи derivedKey в обратный вызов. Однако это свойство устарело и его следует избегать.

Модули MJS

import crypto from 'crypto';
crypto.DEFAULT_ENCODING = 'hex';
crypto.pbkdf2('secret', 'salt', 100000, 512, 'sha512', (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey);  // '3745e48...aa39b34'
});

Модули CJS

const crypto = require('crypto');
crypto.DEFAULT_ENCODING = 'hex';
crypto.pbkdf2('secret', 'salt', 100000, 512, 'sha512', (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey);  // '3745e48...aa39b34'
});

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

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

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

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

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

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

Если digest равно null, будет использоваться 'sha1'. Это поведение устарело, пожалуйста, укажите digest явно.

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

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

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

Модули MJS

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

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

Модули CJS

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

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

Свойство crypto.DEFAULT_ENCODING может использоваться для изменения способа возврата derivedKey. Однако это свойство устарело и его следует избегать.

Модули MJS

import crypto from 'crypto';
crypto.DEFAULT_ENCODING = 'hex';
const key = crypto.pbkdf2Sync('secret', 'salt', 100000, 512, 'sha512');
console.log(key);  // '3745e48...aa39b34'

Модули CJS

const crypto = require('crypto');
crypto.DEFAULT_ENCODING = 'hex';
const key = crypto.pbkdf2Sync('secret', 'salt', 100000, 512, 'sha512');
console.log(key);  // '3745e48...aa39b34'

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

crypto.privateDecrypt(privateKey, buffer)

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

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

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

crypto.privateEncrypt(privateKey, buffer)

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

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

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

crypto.publicDecrypt(key, buffer)

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

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

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

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

crypto.publicEncrypt(key, buffer)

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

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

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

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

crypto.randomBytes(size[, callback])

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

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

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

МОДУЛИ MJS

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

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

МОДУЛИ CJS

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

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

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

МОДУЛИ MJS

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

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

МОДУЛИ CJS

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

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

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

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

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

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

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

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

МОДУЛИ MJS

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

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

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

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

МОДУЛИ CJS

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

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

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

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

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

МОДУЛИ MJS

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

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

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

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

МОДУЛИ CJS

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

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

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

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

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

• buffer <ArrayBuffer> | <Buffer> | <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 не указана, будет выброшено исключение.

Модули MJS

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

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

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

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

Модули CJS

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

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

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

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

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

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

Модули MJS

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

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

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

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

Модули CJS

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

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

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

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

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

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

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

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

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

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

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

Модули MJS

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

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

Модули CJS

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

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

Модули MJS

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

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

Модули CJS

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

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

Модули MJS

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

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

Модули CJS

// With `min` argument
const {
  randomInt,
} = require('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.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> Верхняя граница памяти. Ошибка, когда (приблизительно) 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.

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

Модули MJS

const {
  scrypt
} = await import('crypto');

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

Модули CJS

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

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

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

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

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

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

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

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

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

МОДУЛИ MJS

const {
  scryptSync
} = await import('crypto');
// Using the factory defaults.

const key1 = scryptSync('password', 'salt', 64);
console.log(key1.toString('hex'));  // '3745e48...08d59ae'
// Using a custom N parameter. Must be a power of two.
const key2 = scryptSync('password', 'salt', 64, { N: 1024 });
console.log(key2.toString('hex'));  // '3745e48...aa39b34'

МОДУЛИ CJS

const {
  scryptSync,
} = require('crypto');
// Using the factory defaults.

const key1 = scryptSync('password', 'salt', 64);
console.log(key1.toString('hex'));  // '3745e48...08d59ae'
// Using a custom N parameter. Must be a power of two.
const key2 = scryptSync('password', 'salt', 64, { N: 1024 });
console.log(key2.toString('hex'));  // '3745e48...aa39b34'

crypto.secureHeapUsed()

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

crypto.setEngine(engine[, flags])

• engine <строка>
• flags <crypto.constants> По умолчанию: crypto.constants.ENGINE_METHOD_ALL

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

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

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

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

Нижеследующие флаги устарели в OpenSSL-1.1.0.

• crypto.constants.ENGINE_METHOD_ECDH
• crypto.constants.ENGINE_METHOD_ECDSA
• crypto.constants.ENGINE_METHOD_STORE

crypto.setFips(bool)

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

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

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

• algorithm <строка> | <null> | <неопределено>
• data <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• key <Объект> | <строка> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <Ключ> | <CryptoKey>
• callback <Функция>
  • err <Ошибка>
  • signature <Buffer>
• Возвращает: <Buffer>, если функция callback не указана.

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

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

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

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

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

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

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

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

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

crypto.timingSafeEqual(a, b)

• a <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• b <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• Возвращает: <boolean>

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

a и b должны оба быть Buffer, TypedArray или DataView и должны иметь одинаковую длину в байтах.

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

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

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

• algorithm <string> | <null> | <undefined>
• data <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• key <Object> | <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> | <CryptoKey>
• signature <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>
• callback <Function>
  • err <Error>
  • result <boolean>
• Возвращает: <boolean> true или false в зависимости от валидности подписи для данных и открытого ключа, если функция callback не указана.

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

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

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

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

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

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

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

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

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

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

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

crypto.webcrypto

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

Для получения подробностей см. документацию Web Crypto API.

Примечания

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

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

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

• Не все последовательности байтов являются допустимыми строками UTF-8. Поэтому, когда последовательность байтов длиной n извлекается из строки, ее энтропия, как правило, ниже, чем энтропия случайной или псевдослучайной n последовательности байтов. Например, ни одна строка UTF-8 не приведет к последовательности байтов c0 af. Секретные ключи практически всегда должны быть случайными или псевдослучайными последовательностями байтов.

• Аналогично, при преобразовании случайных или псевдослучайных последовательностей байтов в строки UTF-8, подпоследовательности, которые не представляют собой допустимые кодовые точки, могут быть заменены символом замены Юникода (U+FFFD). Таким образом, байтовое представление полученной строки Юникода может не совпадать с последовательностью байтов, из которой была создана строка.

  const original = [0xc0, 0xaf];
  const bytesAsString = Buffer.from(original).toString('utf8');
  const stringAsBytes = Buffer.from(bytesAsString, 'utf8');
  console.log(stringAsBytes);
  // Prints '<Buffer ef bf bd ef bf bd>'.

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

• Когда строки получены из пользовательского ввода, некоторые символы Юникода могут быть представлены несколькими эквивалентными способами, что приводит к различным последовательностям байтов. Например, при передаче пользовательского пароля в функцию вывода ключа, такую как PBKDF2 или scrypt, результат функции вывода ключа зависит от того, используются ли в строке составные или разложенные символы. Node.js не нормализует представления символов. Разработчики должны рассмотреть возможность использования String.prototype.normalize() для пользовательских входных данных перед их передачей в криптографические API.

API потоков старых версий (до Node.js 0.10)

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

Недавние изменения ECDH

Использование ECDH с нединамически сгенерированными парами ключей было упрощено. Теперь можно вызвать ecdh.setPrivateKey() с предварительно выбранным закрытым ключом, и связанная открытая точка (ключ) будет вычислена и сохранена в объекте. Это позволяет коду хранить и предоставлять только закрытую часть пары ключей EC.

ecdh.setPrivateKey() теперь также проверяет, что закрытый ключ является допустимым для выбранной кривой.

Метод ecdh.setPublicKey() теперь устарел, так как его включение в API не является полезным. Либо следует установить ранее сохраненный закрытый ключ, который автоматически сгенерирует связанный открытый ключ, либо следует вызвать ecdh.generateKeys(). Главным недостатком использования ecdh.setPublicKey() является то, что он может привести к несогласованному состоянию пары ключей ECDH.

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

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

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

В соответствии с рекомендациями NIST SP 800-131A:

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

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

Режим CCM

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

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

Модули MJS

import { Buffer } from 'buffer';
const {
  createCipheriv,
  createDecipheriv,
  randomBytes
} = await import('crypto');

const key = 'keykeykeykeykeykeykeykey';
const nonce = randomBytes(12);

const aad = Buffer.from('0123456789', 'hex');

const cipher = createCipheriv('aes-192-ccm', key, nonce, {
  authTagLength: 16
});
const plaintext = 'Hello world';
cipher.setAAD(aad, {
  plaintextLength: Buffer.byteLength(plaintext)
});
const ciphertext = cipher.update(plaintext, 'utf8');
cipher.final();
const tag = cipher.getAuthTag();

// Now transmit { ciphertext, nonce, tag }.

const decipher = createDecipheriv('aes-192-ccm', key, nonce, {
  authTagLength: 16
});
decipher.setAuthTag(tag);
decipher.setAAD(aad, {
  plaintextLength: ciphertext.length
});
const receivedPlaintext = decipher.update(ciphertext, null, 'utf8');

try {
  decipher.final();
} catch (err) {
  throw new Error('Authentication failed!', { cause: err });
}

console.log(receivedPlaintext);

Модули CJS

const {
  createCipheriv,
  createDecipheriv,
  randomBytes,
} = require('crypto');
const { Buffer } = require('buffer');

const key = 'keykeykeykeykeykeykeykey';
const nonce = randomBytes(12);

const aad = Buffer.from('0123456789', 'hex');

const cipher = createCipheriv('aes-192-ccm', key, nonce, {
  authTagLength: 16
});
const plaintext = 'Hello world';
cipher.setAAD(aad, {
  plaintextLength: Buffer.byteLength(plaintext)
});
const ciphertext = cipher.update(plaintext, 'utf8');
cipher.final();
const tag = cipher.getAuthTag();

// Now transmit { ciphertext, nonce, tag }.

const decipher = createDecipheriv('aes-192-ccm', key, nonce, {
  authTagLength: 16
});
decipher.setAuthTag(tag);
decipher.setAAD(aad, {
  plaintextLength: ciphertext.length
});
const receivedPlaintext = decipher.update(ciphertext, null, 'utf8');

try {
  decipher.final();
} catch (err) {
  throw new Error('Authentication failed!', { cause: err });
}

console.log(receivedPlaintext);

Константы криптографии

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

Параметры OpenSSL

Для получения подробностей см. список флагов SSL OP.

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

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

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