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

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

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

const crypto = require('crypto');

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

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

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

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

Класс: Сертификат

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

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

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

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

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

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

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

const crypto = require('crypto');
const cipher = crypto.createCipher('aes192', 'a password');

let encrypted = '';
cipher.on('readable', () => {
  const data = cipher.read();
  if (data)
    encrypted += data.toString('hex');
});
cipher.on('end', () => {
  console.log(encrypted);
  // Prints: ca981be48e90867604588e75d04feabb63cc007a8f8ad89b10616ed84d815504
});

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

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

const crypto = require('crypto');
const fs = require('fs');
const cipher = crypto.createCipher('aes192', 'a password');

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 cipher = crypto.createCipher('aes192', 'a password');

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

cipher.final([outputEncoding])

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

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

cipher.setAAD(buffer)

• buffer <Буфер>
• Возвращает <Шифр> для цепочки вызовов методов.

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

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

cipher.getAuthTag()

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

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

cipher.setAutoPadding([autoPadding])

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

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

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

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

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

• data <строка> | <Буфер> | <Массив типов> | <DataView>
• inputEncoding <строка>
• outputEncoding <строка>
• Возвращает: <Буфер> | <строка>

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

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

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

Класс: Decipher

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

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

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

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

const crypto = require('crypto');
const decipher = crypto.createDecipher('aes192', 'a password');

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

const encrypted =
    'ca981be48e90867604588e75d04feabb63cc007a8f8ad89b10616ed84d815504';
decipher.write(encrypted, 'hex');
decipher.end();

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

const crypto = require('crypto');
const fs = require('fs');
const decipher = crypto.createDecipher('aes192', 'a password');

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 decipher = crypto.createDecipher('aes192', 'a password');

const encrypted =
    'ca981be48e90867604588e75d04feabb63cc007a8f8ad89b10616ed84d815504';
let decrypted = decipher.update(encrypted, 'hex', 'utf8');
decrypted += decipher.final('utf8');
console.log(decrypted);
// Prints: some clear text data

decipher.final([outputEncoding])

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

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

decipher.setAAD(buffer)

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

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

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

decipher.setAuthTag(buffer)

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

При использовании режима аутентифицированного шифрования (в настоящее время поддерживается только GCM), метод decipher.setAuthTag() используется для передачи полученного тега аутентификации. Если тег не предоставлен или текст шифра был изменён, decipher.final() выбросит ошибку, указывая на то, что текст шифра следует отбросить из-за неудачи аутентификации.

Обратите внимание, что эта версия Node.js не проверяет длину тегов аутентификации GCM. Такая проверка обязательно должна быть реализована приложениями и имеет важное значение для подлинности зашифрованных данных; в противном случае злоумышленник может использовать произвольно короткий тег аутентификации, чтобы увеличить вероятность успешной прохождения аутентификации (до 0,39%). Настоятельно рекомендуется связывать одно из значений 16, 15, 14, 13, 12, 8 или 4 байта с каждым ключом и допускать теги аутентификации только такой длины. См. NIST SP 800-38D.

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

decipher.setAutoPadding([autoPadding])

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

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

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

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

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

• data <строка> | <Буфер> | <Массив типов> | <DataView>
• inputEncoding <строка>
• outputEncoding <строка>
• Возвращает: <Буфер> | <строка>

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

outputEncoding определяет формат вывода зашифрованных данных и может быть 'latin1', 'ascii' или 'utf8'. Если 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 <строка> | <Buffer> | <TypedArray> | <DataView>
• inputEncoding <строка>
• outputEncoding <строка>
• Возвращает: <Buffer> | <строка>

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

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

diffieHellman.generateKeys([encoding])

• encoding <строка>
• Возвращает: <Buffer> | <строка>

Генерирует значения закрытого и открытого ключей Diffie-Hellman и возвращает открытый ключ в указанной encoding. Этот ключ должен быть передан другой стороне. Кодировка может быть 'latin1', 'hex', или 'base64'. Если encoding задан, возвращается строка; в противном случае возвращается Buffer.

diffieHellman.getGenerator([encoding])

• encoding <строка>
• Возвращает: <Buffer> | <строка>

Возвращает генератор Diffie-Hellman в указанной encoding, которая может быть 'latin1', 'hex', или 'base64'. Если encoding задан, возвращается строка; в противном случае возвращается Buffer.

diffieHellman.getPrime([encoding])

• encoding <строка>
• Возвращает: <Buffer> | <строка>

Возвращает простое число Diffie-Hellman в указанной encoding, которая может быть 'latin1', 'hex', или 'base64'. Если encoding задан, возвращается строка; в противном случае возвращается Buffer.

diffieHellman.getPrivateKey([encoding])

• encoding <строка>
• Возвращает: <Buffer> | <строка>

Возвращает закрытый ключ Diffie-Hellman в указанной encoding, которая может быть 'latin1', 'hex', или 'base64'. Если encoding задан, возвращается строка; в противном случае возвращается Buffer.

diffieHellman.getPublicKey([encoding])

• encoding <строка>
• Возвращает: <Buffer> | <строка>

Возвращает открытый ключ Diffie-Hellman в указанной encoding, которая может быть 'latin1', 'hex', или 'base64'. Если encoding задан, возвращается строка; в противном случае возвращается Buffer.

diffieHellman.setPrivateKey(privateKey[, encoding])

• privateKey <строка> | <Buffer> | <TypedArray> | <DataView>
• encoding <строка>

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

diffieHellman.setPublicKey(publicKey[, encoding])

• publicKey <строка> | <Buffer> | <TypedArray> | <DataView>
• encoding <строка>

Устанавливает открытый ключ Diffie-Hellman. Если аргумент encoding задан и равен 'latin1', 'hex', или 'base64', ожидается, что 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

Класс: 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.computeSecret(otherPublicKey[, inputEncoding][, outputEncoding])

• otherPublicKey <строка> | <Buffer> | <TypedArray> | <DataView>
• inputEncoding <строка>
• outputEncoding <строка>
• Возвращает: <Buffer> | <строка>

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

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

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

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

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

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

Аргумент encoding может быть 'latin1', 'hex', или 'base64'. Если encoding указано, возвращается строка; в противном случае возвращается Buffer.

ecdh.getPrivateKey([encoding])

• encoding <строка>
• Возвращает: <Буфер> | <строка> Закрытый ключ EC Diffie-Hellman в указанном формате encoding, который может быть 'latin1', 'hex', или 'base64'. Если encoding указано, возвращается строка; в противном случае возвращается Buffer.

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

• encoding <строка>
• format <строка> По умолчанию: uncompressed
• Возвращает: <Буфер> | <строка> Открытый ключ EC Diffie-Hellman в указанном формате encoding и format.

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

Аргумент encoding может быть 'latin1', 'hex', или 'base64'. Если encoding указан, возвращается строка; в противном случае возвращается Buffer.

ecdh.setPrivateKey(privateKey[, encoding])

• privateKey <строка> | <Буфер> | <Тип массива> | <DataView>
• encoding <строка>

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

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

ecdh.setPublicKey(publicKey[, encoding])

• publicKey <строка> | <Буфер> | <Тип массива> | <DataView>
• encoding <строка>

Устанавливает открытый ключ EC Diffie-Hellman. Кодировка ключа может быть 'latin1', 'hex' или 'base64'. Если 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');

// Note: This is a shortcut way to specify 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

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

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

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

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

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

hash.on('readable', () => {
  const data = hash.read();
  if (data) {
    console.log(data.toString('hex'));
    // Prints:
    //   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50
  }
});

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

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

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

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

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

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

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

hash.digest([encoding])

• encoding <строка>
• Возвращает: <Буфер> | <строка>

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

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

hash.update(data[, inputEncoding])

• data <строка> | <Буфер> | <Тип массива> | <DataView>
• inputEncoding <строка>

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

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

Класс: Hmac

Класс 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', () => {
  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 может быть 'hex', 'latin1' или 'base64'. Если encoding указан, возвращается строка; в противном случае возвращается Buffer.

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

hmac.update(data[, inputEncoding])

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

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

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

Класс: Sign

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

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

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

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

const crypto = require('crypto');
const sign = crypto.createSign('SHA256');

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

const privateKey = getPrivateKeySomehow();
console.log(sign.sign(privateKey, 'hex'));
// Prints: the calculated signature using the specified private key and
// SHA-256. For RSA keys, the algorithm is RSASSA-PKCS1-v1_5 (see padding
// parameter below for RSASSA-PSS). For EC keys, the algorithm is ECDSA.

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

const crypto = require('crypto');
const sign = crypto.createSign('SHA256');

sign.update('some data to sign');

const privateKey = getPrivateKeySomehow();
console.log(sign.sign(privateKey, 'hex'));
// Prints: the calculated signature

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

Пример: подпись с использованием устаревшего имени алгоритма подписи

const crypto = require('crypto');
const sign = crypto.createSign('RSA-SHA256');

sign.update('some data to sign');

const privateKey = getPrivateKeySomehow();
console.log(sign.sign(privateKey, 'hex'));
// Prints: the calculated signature

sign.sign(privateKey[, outputFormat])

• privateKey <строка> | <объект>
  • key <строка>
  • passphrase <строка>
• outputFormat <строка>
• Возвращает: <Буфер> | <строка>

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

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

• key: <строка> — ключ в формате PEM (необходим)
• passphrase: <строка> — пароль к ключу

• 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 (по умолчанию) устанавливает ее в максимально допустимое значение.

outputFormat может указать одну из 'latin1', 'hex' или 'base64'. Если outputFormat предоставлен, возвращается строка; в противном случае возвращается Buffer.

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

sign.update(data[, inputEncoding])

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

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

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

Класс: Verify

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

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

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

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

const crypto = require('crypto');
const verify = crypto.createVerify('SHA256');

verify.write('some data to sign');
verify.end();

const publicKey = getPublicKeySomehow();
const signature = getSignatureToVerify();
console.log(verify.verify(publicKey, signature));
// Prints: true or false

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

const crypto = require('crypto');
const verify = crypto.createVerify('SHA256');

verify.update('some data to sign');

const publicKey = getPublicKeySomehow();
const signature = getSignatureToVerify();
console.log(verify.verify(publicKey, signature));
// Prints: true or false

verify.update(data[, inputEncoding])

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

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

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

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

• object <строка> | <объект>
• signature <строка> | <Буфер> | <Массив типов> | <DataView>
• signatureFormat <строка>
• Возвращает: <булево> true или false в зависимости от валидности подписи для данных и открытого ключа.

Проверяет предоставленные данные с использованием заданного object и signature. Аргумент object может быть либо строкой, содержащей закодированный в PEM объект, который может быть открытым ключом RSA, открытым ключом DSA или сертификатом X.509, либо объектом с одним или несколькими из следующих свойств:

• key: <строка> - открытый ключ, закодированный в PEM (обязательно)

• 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_AUTO (по умолчанию) приводит к автоматическому определению длины.

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

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

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

crypto.constants

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

crypto.DEFAULT_ENCODING

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

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

Новые приложения должны ожидать, что по умолчанию будет 'buffer'. Это свойство может быть устаревшим в будущих версиях Node.js.

crypto.fips

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

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

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

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

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

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

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

В соответствии с рекомендацией OpenSSL использовать PBKDF2 вместо EVP_BytesToKey, рекомендуется разработчикам самостоятельно выводить ключ и IV, используя crypto.pbkdf2(), и использовать 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>
• options <Объект> stream.transform параметры
• Возвращает: <Шифр>

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

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

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

crypto.createCredentials(details)

• details <Объект> Идентично tls.createSecureContext().

Метод crypto.createCredentials() — устаревшая функция для создания и возврата tls.SecureContext. Не следует использовать. Замените её на tls.createSecureContext(), которая имеет те же самые аргументы и возвращаемое значение.

Возвращает tls.SecureContext, как будто был вызван tls.createSecureContext().

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

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

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

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

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

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

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

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

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

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

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

• prime <строка> | <Buffer> | <TypedArray> | <DataView>
• primeEncoding <строка>
• generator <число> | <строка> | <Buffer> | <TypedArray> | <DataView> По умолчанию: 2
• generatorEncoding <строка>

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

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

Аргументы primeEncoding и generatorEncoding могут быть 'latin1', 'hex', или 'base64'.

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

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

crypto.createDiffieHellman(primeLength[, generator])

• primeLength <число>
• generator <число> | <строка> | <Buffer> | <TypedArray> | <DataView> По умолчанию: 2

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

crypto.createECDH(curveName)

• curveName <строка>

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

crypto.createHash(algorithm[, options])

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

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

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

Пример: генерация 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', () => {
  const data = input.read();
  if (data)
    hash.update(data);
  else {
    console.log(`${hash.digest('hex')} ${filename}`);
  }
});

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

• algorithm <строка>
• key <строка> | <Buffer> | <TypedArray> | <DataView>
• options <Объект> stream.transform параметры
• Возвращает: <Hmac>

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

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

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

Пример: генерация 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', () => {
  const data = input.read();
  if (data)
    hmac.update(data);
  else {
    console.log(`${hmac.digest('hex')} ${filename}`);
  }
});

crypto.createSign(algorithm[, options])

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

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

crypto.createVerify(algorithm[, options])

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

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

crypto.getCiphers()

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

Пример:

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

crypto.getCurves()

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

Пример:

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

crypto.getDiffieHellman(groupName)

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

Создаёт объект обмена ключами с предварительно заданными параметрами. Поддерживаемые группы: '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.getHashes()

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

Пример:

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

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

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

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

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

Аргумент 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'
});

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

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

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

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

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

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

Аргумент 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'

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

crypto.privateDecrypt(privateKey, buffer)

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

Дешифрует buffer с помощью privateKey.

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

crypto.privateEncrypt(privateKey, buffer)

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

Шифрует buffer с помощью privateKey.

privateKey может быть объектом или строкой. Если privateKey является строкой, она обрабатывается как ключ без фразы и будет использовать RSA_PKCS1_PADDING.

crypto.publicDecrypt(key, buffer)

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

Расшифровывает buffer с помощью key.

key может быть объектом или строкой. Если key является строкой, она обрабатывается как ключ без фразы и будет использовать RSA_PKCS1_PADDING.

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

crypto.publicEncrypt(key, buffer)

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

Шифрует содержимое buffer с помощью key и возвращает новый Buffer с зашифрованным содержимым.

key может быть объектом или строкой. Если key является строкой, она обрабатывается как ключ без фразы и будет использовать 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 <Буфер> | <Uint8Array> Должен быть передан.
• offset <число> По умолчанию: 0
• size <число> По умолчанию: buffer.length - offset
• Возвращает: <Буфер>

Синхронная версия 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'));

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

• buffer <Буфер> | <Uint8Array> Должен быть передан.
• 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'));
});

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

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

crypto.setEngine(engine[, flags])

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

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

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

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

• crypto.constants.ENGINE_METHOD_RSA
• crypto.constants.ENGINE_METHOD_DSA
• crypto.constants.ENGINE_METHOD_DH
• crypto.constants.ENGINE_METHOD_RAND
• crypto.constants.ENGINE_METHOD_ECDH
• crypto.constants.ENGINE_METHOD_ECDSA
• crypto.constants.ENGINE_METHOD_CIPHERS
• crypto.constants.ENGINE_METHOD_DIGESTS
• crypto.constants.ENGINE_METHOD_STORE
• crypto.constants.ENGINE_METHOD_PKEY_METHS
• crypto.constants.ENGINE_METHOD_PKEY_ASN1_METHS
• crypto.constants.ENGINE_METHOD_ALL
• crypto.constants.ENGINE_METHOD_NONE

crypto.timingSafeEqual(a, b)

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

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

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

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

Примечания

API потоков устаревшего вида (до Node.js v0.10)

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

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

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

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

Поддержка слабых или уязвимых алгоритмов

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

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

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

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

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

Константы модуля Crypto

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

Опции OpenSSL

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

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

Константы шифрования Node.js