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

Возможна ситуация, когда 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, возвращается строка. Если кодировка не указана, возвращается Buffer.

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

cipher.getAuthTag()

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

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

cipher.setAAD(buffer[, options])

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

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

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

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

cipher.setAutoPadding([autoPadding])

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

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

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

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

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

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

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

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

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

Класс: Decipher

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

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

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

Методы crypto.createDecipher() или crypto.createDecipheriv() используются для создания экземпляров Decipher. Объекты 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 и потоков с передачей данных:

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 <Буфер> | <Массив с типом данных> | <DataView>
• options <Объект> stream.transform параметры
  • plaintextLength <число>
• Возвращает: <Decipher> для цепочки вызовов методов.

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

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

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

decipher.setAuthTag(buffer)

• buffer <Буфер> | <Массив с типом данных> | <DataView>
• Возвращает: <Decipher> для цепочки вызовов методов.

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

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

decipher.setAutoPadding([autoPadding])

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

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

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

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

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

• data <строка> | <Буфер> | <Массив с типом данных> | <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.

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

• DH_CHECK_P_NOT_SAFE_PRIME
• DH_CHECK_P_NOT_PRIME
• DH_UNABLE_TO_CHECK_GENERATOR
• DH_NOT_SUITABLE_GENERATOR

Класс: DiffieHellmanGroup

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

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

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

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

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

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

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

Генерирует значения ключей 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 <строка> | <Буфер> | <TypedArray> | <DataView>
• encoding <строка> Кодировка строки privateKey.

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

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

ecdh.setPublicKey(publicKey[, encoding])

• publicKey <строка> | <Буфер> | <TypedArray> | <DataView>
• encoding <строка> Кодировка 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).setEncoding('hex').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 <Объект> stream.transform параметры
• Возвращает: <Хэш>

Создаёт новый объект 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 <строка> Кодировка возвращаемого значения.
• Возвращает: <Буфер> | <строка>

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

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

hash.update(data[, inputEncoding])

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

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

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

Класс: Hmac

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

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

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

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

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

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

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

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

hmac.update(data[, inputEncoding])

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

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

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

Класс: KeyObject

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

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

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

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

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

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

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

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

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

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

sign.update(data[, inputEncoding])

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

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

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

Класс: Verify

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

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

• В качестве потока stream с записью, где записанные данные используются для проверки по предоставленной подписи, или
• Используя методы 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.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.

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

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

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

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

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

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

• algorithm <строка>
• key <строка> | <Буфер> | <Тип массива> | <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 обычно просто добавляются к зашифрованным сообщениям без шифрования. Может показаться противоречивым, что что-то должно быть непредсказуемым и уникальным, но не обязательно секретным; помните, что злоумышленник не должен уметь предсказывать значение 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>

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

crypto.createHash(algorithm[, options])

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

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

Доступные алгоритмы зависят от версии OpenSSL на платформе. Примеры: '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 управляет поведением потока.

Доступные алгоритмы зависят от версии 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 <Буфер> | <Тип массива> | <DataView>
• Возвращает: <Объект ключа>

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

crypto.createSign(algorithm[, options])

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

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

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

crypto.createVerify(algorithm[, options])

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

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

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

crypto.diffieHellman(options)

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

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

crypto.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: <строка> Имя группы Диффи-Хеллмана (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() версия, она возвращает Promise для Object с publicKey и privateKey свойствами.

crypto.generateKeyPairSync(type, options)

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

Генерирует новую пару асимметричных ключей заданного type. В настоящее время поддерживаются RSA, 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()

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

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

crypto.getCurves()

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

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

crypto.getDiffieHellman(groupName)

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

Создает предварительно определенный объект обмена ключами 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()

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

crypto.getHashes()

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

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

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

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

Обеспечивает асинхронную реализацию функции производного ключа Password-Based Key Derivation Function 2 (PBKDF2). Выбранный алгоритм HMAC digest, указанный в 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 <Объект> | <строка> | <Буфер> | <Объект_ключа>
  • oaepHash <строка> Функция хеширования для использования в заполнении OAEP и MGF1. По умолчанию: 'sha1'
  • oaepLabel <Буфер> | <Массив_типов> | <DataView> Метка для использования в заполнении OAEP. Если не указана, метка не используется.
  • padding <crypto.constants> Необязательное значение заполнения, определенное в crypto.constants, которое может быть: crypto.constants.RSA_NO_PADDING, crypto.constants.RSA_PKCS1_PADDING, или crypto.constants.RSA_PKCS1_OAEP_PADDING.
• buffer <Буфер> | <Массив_типов> | <DataView>
• Возвращает: <Буфер> Новый Buffer с дешифрованным содержимым.

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

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

crypto.privateEncrypt(privateKey, buffer)

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

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

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

crypto.publicDecrypt(key, buffer)

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

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

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

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

crypto.publicEncrypt(key, buffer)

• key <Объект> | <строка> | <Буфер> | <Объект ключа>
  • key <строка> | <Буфер> | <Объект ключа> PEM-кодированный открытый или закрытый ключ.
  • oaepHash <строка> Функция хеширования для использования при заполнении OAEP и MGF1. По умолчанию: 'sha1'
  • oaepLabel <Буфер> | <TypedArray> | <DataView> Метка для использования при заполнении OAEP. Если не указано, метка не используется.
  • passphrase <строка> | <Буфер> Необязательный пароль для закрытого ключа.
  • padding <crypto.constants> Необязательное значение заполнения, определённое в crypto.constants, которое может быть: crypto.constants.RSA_NO_PADDING, crypto.constants.RSA_PKCS1_PADDING, или crypto.constants.RSA_PKCS1_OAEP_PADDING.
• buffer <Буфер> | <TypedArray> | <DataView>
• Возвращает: <Буфер> Новый 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 <Буфер> | <TypedArray> | <DataView> Должен быть предоставлен.
• offset <число> По умолчанию: 0
• size <число> По умолчанию: buffer.length - offset
• Возвращает: <Буфер> | <TypedArray> | <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'));

В качестве buffer могут быть переданы экземпляры 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 экземпляр может быть передан в качестве buffer.

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.randomUUID([options])

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

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

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

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

Предоставляет асинхронную реализацию 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('password', 'salt', 64, (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // '3745e48...08d59ae'
});
// Using a custom N parameter. Must be a power of two.
crypto.scrypt('password', 'salt', 64, { N: 1024 }, (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // '3745e48...aa39b34'
});

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

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

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

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

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

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

const crypto = require('crypto');
// Using the factory defaults.
const key1 = crypto.scryptSync('password', 'salt', 64);
console.log(key1.toString('hex'));  // '3745e48...08d59ae'
// Using a custom N parameter. Must be a power of two.
const key2 = crypto.scryptSync('password', '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 или секретных значений, таких как аутентификационные куки или capability urls.

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

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

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

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

• algorithm <строка> | <null> | <undefined>
• data <Буфер> | <TypedArray> | <DataView>
• key <Объект> | <строка> | <Буфер> | <Объект ключа>
• signature <Буфер> | <TypedArray> | <DataView>
• Возвращает: <логическое значение>

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

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

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

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

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

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

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

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

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

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

Примечания

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

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

Недавние изменения 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