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

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

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

Используйте require('crypto') для доступа к этому модулю.

const crypto = require('crypto');

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

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

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

let crypto;
try {
  crypto = require('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)

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

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

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

Certificate.verifySpkac(spkac)

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

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

API предыдущих версий

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

new crypto.Certificate()

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

const crypto = require('crypto');

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

certificate.exportChallenge(spkac)

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

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

certificate.exportPublicKey(spkac)

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

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

certificate.verifySpkac(spkac)

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

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

Класс: Cipher

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

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

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

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

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

const crypto = require('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 async `crypto.scrypt()` instead.
const key = crypto.scryptSync(password, 'salt', 24);
// Use `crypto.randomBytes()` to generate a random iv instead of the static iv
// shown here.
const iv = Buffer.alloc(16, 0); // Initialization vector.

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

let encrypted = '';
cipher.on('readable', () => {
  let chunk;
  while (null !== (chunk = cipher.read())) {
    encrypted += chunk.toString('hex');
  }
});
cipher.on('end', () => {
  console.log(encrypted);
  // Prints: e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa
});

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

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

const crypto = require('crypto');
const fs = require('fs');

const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';
// Use the async `crypto.scrypt()` instead.
const key = crypto.scryptSync(password, 'salt', 24);
// Use `crypto.randomBytes()` to generate a random iv instead of the static iv
// shown here.
const iv = Buffer.alloc(16, 0); // Initialization vector.

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

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

input.pipe(cipher).pipe(output);

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

const crypto = require('crypto');

const algorithm = 'aes-192-cbc';
const password = 'Password used to generate key';
// Use the async `crypto.scrypt()` instead.
const key = crypto.scryptSync(password, 'salt', 24);
// Use `crypto.randomBytes` to generate a random iv instead of the static iv
// shown here.
const iv = Buffer.alloc(16, 0); // Initialization vector.

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

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

cipher.final([outputEncoding])

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

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

cipher.setAAD(buffer[, options])

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

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

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

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

cipher.getAuthTag()

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

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

cipher.setAutoPadding([autoPadding])

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

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

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

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

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

const crypto = require('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 = crypto.scryptSync(password, 'salt', 24);
// The IV is usually passed along with the ciphertext.
const iv = Buffer.alloc(16, 0); // Initialization vector.

const decipher = crypto.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 и потоков с использованием метода pipe:

const crypto = require('crypto');
const fs = require('fs');

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

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

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

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

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

const crypto = require('crypto');

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

const decipher = crypto.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 указан, возвращается строка. Если outputEncoding не указан, возвращается Buffer.

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

decipher.setAAD(buffer[, options])

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

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

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

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

decipher.setAuthTag(buffer)

• buffer <Буфер> | <TypedArray> | <DataView>
• Возвращает: <Дешифратор> для цепочки методов.

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

decipher.setAutoPadding([autoPadding])

• autoPadding <boolean> По умолчанию: true
• Возвращает: <Дешифратор> для цепочки методов.

Когда данные были зашифрованы без стандартного заполнения блоков, вызов 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().

const crypto = require('crypto');
const assert = require('assert');

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

// Generate Bob's keys...
const bob = crypto.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 <строка> | <Буфер> | <TypedArray> | <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 <строка> | <Буфер> | <TypedArray> | <DataView>
• encoding <строка> Кодировка строки privateKey.

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

diffieHellman.setPublicKey(publicKey[, encoding])

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

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

diffieHellman.verifyError

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

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

• DH_CHECK_P_NOT_SAFE_PRIME
• DH_CHECK_P_NOT_PRIME
• DH_UNABLE_TO_CHECK_GENERATOR
• DH_NOT_SUITABLE_GENERATOR

Класс: DiffieHellmanGroup

Класс DiffieHellmanGroup принимает известную группу modp в качестве аргумента, но в остальном работает так же, как и DiffieHellman.

const name = 'modp1';
const dh = crypto.createDiffieHellmanGroup(name);

name взято из 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().

const crypto = require('crypto');
const assert = require('assert');

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

// Generate Bob's keys...
const bob = crypto.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 <строка> | <Буфер> | <Массив типов> | <DataView>
• curve <строка>
• inputEncoding <строка> Кодировка строки key.
• outputEncoding <строка> Кодировка возвращаемого значения.
• format <строка> По умолчанию: 'uncompressed'
• Возвращает: <Буфер> | <строка>

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

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

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

Если inputEncoding не задан, key должен быть Buffer, TypedArray или DataView.

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

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

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

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

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

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

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

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

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

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

ecdh.getPrivateKey([encoding])

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

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

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

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

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

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

ecdh.setPrivateKey(privateKey[, encoding])

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

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

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

ecdh.setPublicKey(publicKey[, encoding])

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

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

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

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

const crypto = require('crypto');
const alice = crypto.createECDH('secp256k1');
const bob = crypto.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(
  crypto.createHash('sha256').update('alice', 'utf8').digest()
);

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

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

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

Класс: Hash

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

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

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

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

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

const crypto = require('crypto');
const hash = crypto.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 и потоков:

const crypto = require('crypto');
const fs = require('fs');
const hash = crypto.createHash('sha256');

const input = fs.createReadStream('test.js');
input.pipe(hash).pipe(process.stdout);

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

const crypto = require('crypto');
const hash = crypto.createHash('sha256');

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

hash.copy([options])

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

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

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

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

// Calculate a rolling hash.
const crypto = require('crypto');
const hash = crypto.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 в качестве потоков:

const crypto = require('crypto');
const hmac = crypto.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 и потоков:

const crypto = require('crypto');
const fs = require('fs');
const hmac = crypto.createHmac('sha256', 'a secret');

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

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

const crypto = require('crypto');
const hmac = crypto.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.

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

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

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: <Объект>
• Возвращает: <строка> | <Буфер>

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

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

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

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

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

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

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

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

const crypto = require('crypto');

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

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

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

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

const crypto = require('crypto');

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

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

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

sign.sign(privateKey[, outputEncoding])

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

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

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

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

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

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

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

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

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

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

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

sign.update(data[, inputEncoding])

• data <строка> | <Буфер> | <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 <Объект> | <строка> | <Буфер> | <Объект ключа>
  • dsaEncoding <строка>
  • padding <целое число>
  • saltLength <целое число>
• signature <строка> | <Буфер> | <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() приведут к ошибке.

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

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

crypto.constants

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

crypto.DEFAULT_ENCODING

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

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

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

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

crypto.fips

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

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

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

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

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

Аргумент 'aes-128-ccm' управляет поведением потока и является необязательным, за исключением случаев использования шифра в режиме 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 <строка> | <Буфер> | <Массив с типом данных> | <DataView> | <Объект ключа>
• iv <строка> | <Буфер> | <Массив с типом данных> | <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 — вектор инициализации (IV). Оба аргумента должны быть строками, закодированными в 'utf8', буферами, TypedArray, или DataView. key может быть необязательно KeyObject типа secret. Если шифру не нужен вектор инициализации, iv может быть null.

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

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

• algorithm <строка>
• password <строка> | <Буфер> | <Массив с типом данных> | <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 <строка> | <Буфер> | <Массив типов> | <DataView> | <Объект ключа>
• iv <строка> | <Буфер> | <Массив типов> | <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.

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

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

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

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

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

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

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

crypto.createDiffieHellman(primeLength[, generator])

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

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

crypto.createDiffieHellmanGroup(name)

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

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

crypto.createECDH(curveName)

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

Создаёт объект обмена ключами эллиптических кривых 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 суммы файла

const filename = process.argv[2];
const crypto = require('crypto');
const fs = require('fs');

const hash = crypto.createHash('sha256');

const input = fs.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 <строка> | <Буфер> | <Массив типов> | <DataView> | <Объект ключа>
• options <Объект> stream.transform параметры
• Возвращает: <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.

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

const filename = process.argv[2];
const crypto = require('crypto');
const fs = require('fs');

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

const input = fs.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 <Объект> | <строка> | <Буфер>
  • key: <строка> | <Буфер> Материал ключа в формате PEM или DER.
  • format: <строка> Должен быть 'pem' или 'der'. По умолчанию: 'pem'.
  • type: <строка> Должен быть 'pkcs1', 'pkcs8' или 'sec1'. Этот параметр нужен только если format 'der', и игнорируется если 'pem'.
  • passphrase: <строка> | <Буфер> Пароль для расшифрования.
• Возвращает: <Объект ключа>

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

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

crypto.createPublicKey(key)

• key <Объект> | <строка> | <Буфер> | <Объект ключа>
  • key: <строка> | <Буфер>
  • format: <строка> Должен быть 'pem' или 'der'. По умолчанию: 'pem'.
  • type: <строка> Должен быть 'pkcs1' или 'spki'. Этот параметр нужен только если format 'der'.
• Возвращает: <Объект ключа>

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

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

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

crypto.createSecretKey(key)

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

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

crypto.createSign(algorithm[, options])

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

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

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

crypto.createVerify(algorithm[, options])

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

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

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

crypto.diffieHellman(options)

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

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

crypto.generateKeyPair(type, options, callback)

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

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

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

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

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()ed версия, он возвращает Promise для Object с publicKey и privateKey свойствами.

crypto.generateKeyPairSync(type, options)

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

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

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

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

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

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

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

crypto.getCurves()

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

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

crypto.getDiffieHellman(groupName)

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

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

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

const crypto = require('crypto');
const alice = crypto.getDiffieHellman('modp14');
const bob = crypto.getDiffieHellman('modp14');

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

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

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

crypto.getFips()

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

crypto.getHashes()

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

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

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

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

Предоставляет асинхронную реализацию функции вывода парольной ключа 2 (PBKDF2). Выбранный алгоритм 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.

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

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

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.

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

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

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

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

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

crypto.privateEncrypt(privateKey, buffer)

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

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

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

crypto.publicDecrypt(key, buffer)

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

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

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

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

crypto.publicEncrypt(key, buffer)

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

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

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

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

crypto.randomBytes(size[, callback])

• size <число>
• callback <Функция>
  • err <Ошибка>
  • buf <Буфер>
• Возвращает: <Буфер>, если функция callback не указана.

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

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

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

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

// Synchronous
const buf = crypto.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 <Буфер> | <Массив типов> | <DataView> Должен быть указан.
• offset <число> По умолчанию: 0
• size <число> По умолчанию: buffer.length - offset
• Возвращает: <Буфер> | <Массив типов> | <DataView> Объект, переданный в качестве аргумента buffer.

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

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

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

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

В качестве TypedArray можно передать любой объект DataView.

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

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

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

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

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

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

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

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

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

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

В качестве TypedArray можно передать любой объект DataView.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

const crypto = require('crypto');
// Using the factory defaults.
crypto.scrypt('secret', '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.
crypto.scrypt('secret', 'salt', 64, { N: 1024 }, (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // '3745e48...aa39b34'
});

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

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

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

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

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

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

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

crypto.setEngine(engine[, flags])

• engine <string>
• 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 <boolean> true для включения режима FIPS.

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

crypto.sign(algorithm, data, key)

• algorithm <string> | <null> | <undefined>
• data <Buffer> | <TypedArray> | <DataView>
• key <Object> | <string> | <Buffer> | <KeyObject>
• Возвращает: <Buffer>

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

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

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

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

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

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

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

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

crypto.timingSafeEqual(a, b)

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

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

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

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

crypto.verify(algorithm, data, key, signature)

• algorithm <string> | <null> | <undefined>
• data <Buffer> | <TypedArray> | <DataView>
• key <Object> | <string> | <Buffer> | <KeyObject>
• signature <Buffer> | <TypedArray> | <DataView>
• Возвращает: <boolean>

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

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

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

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

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

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

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

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

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

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

Примечания

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() для вычисления или проверки тега аутентификации.

const crypto = require('crypto');

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

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

const cipher = crypto.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 = crypto.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) {
  console.error('Authentication failed!');
  return;
}

console.log(receivedPlaintext);

Константы криптографии

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

Параметры OpenSSL

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

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

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

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