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

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

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

const crypto = require('crypto');

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

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

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

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

Класс: Certificate

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

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

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

Certificate.exportChallenge(spkac)

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

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

Certificate.exportPublicKey(spkac[, encoding])

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

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

Certificate.verifySpkac(spkac)

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

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

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

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

new crypto.Certificate()

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

const crypto = require('crypto');

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

certificate.exportChallenge(spkac)

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

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

certificate.exportPublicKey(spkac)

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

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

certificate.verifySpkac(spkac)

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

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

Класс: Cipher

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

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

Методы crypto.createCipher() или crypto.createCipheriv() используются для создания экземпляров Cipher. Объекты 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.setAAD(buffer[, options])

• buffer <Буфер>

• options <Объект> stream.transform опции

  • plaintextLength <число>
• Возвращает: <Cipher> для цепочки методов.

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

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

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

cipher.getAuthTag()

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

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

cipher.setAutoPadding([autoPadding])

• autoPadding <логическое значение> По умолчанию: 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 задан, аргумент data представляет собой строку с указанной кодировкой. Если аргумент inputEncoding не задан, аргумент data должен быть Buffer, TypedArray, или DataView. Если data является Buffer, TypedArray, или DataView, тогда inputEncoding игнорируется.

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

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

Класс: Расшифровщик

Экземпляры класса 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 <число>
• Возвращает: <Расшифровщик> для цепочки методов.

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

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

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

decipher.setAuthTag(buffer)

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

При использовании режима аутентифицированного шифрования (GCM, CCM и OCB в настоящее время поддерживаются), метод 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 <boolean> По умолчанию: true
• Возвращает: <Decipher> для цепочки методов.

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

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

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

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

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

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

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

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

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

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

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

diffieHellman.generateKeys(encoding)

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

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

diffieHellman.getGenerator(encoding)

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

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

diffieHellman.getPrime(encoding)

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

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

diffieHellman.getPrivateKey(encoding)

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

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

diffieHellman.getPublicKey(encoding)

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

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

diffieHellman.setPrivateKey(privateKey[, encoding])

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

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

diffieHellman.setPublicKey(publicKey[, encoding])

• publicKey <string> | <Buffer> | <TypedArray> | <DataView>
• encoding <string> Кодировка строки 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

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

Преобразует открытый ключ EC Диффи-Хеллмана, указанный 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 <string> | <Buffer> | <TypedArray> | <DataView>
• inputEncoding <string> Кодировка строки otherPublicKey.
• outputEncoding <string> Кодировка возвращаемого значения.
• Возвращает: <Buffer> | <string>

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

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

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

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

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

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

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

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

ecdh.getPrivateKey(encoding)

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

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

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

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

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

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

ecdh.setPrivateKey(privateKey[, encoding])

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

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

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

ecdh.setPublicKey(publicKey[, encoding])

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

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

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

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

const crypto = require('crypto');
const alice = crypto.createECDH('secp256k1');
const bob = crypto.createECDH('secp256k1');

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

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

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

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

Класс: Hash

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

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

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

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

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

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

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

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

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

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

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

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

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

hash.digest(кодировка)

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

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

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

hash.update(data[, inputEncoding])

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

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

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

Класс: Hmac

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

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

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

hmac.update(data[, inputEncoding])

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

Обновляет содержимое Hmac с заданным data, кодировка которого задана в inputEncoding. Если 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[, outputEncoding])

• privateKey <строка> | <Объект>

  • key <строка>
  • passphrase <строка>
  • padding <целое число>
  • saltLength <целое число>
• outputEncoding <строка> Кодировка значения, возвращаемого методом.
• Возвращает: <Буфер> | <строка>

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

Если 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

Класс 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 <строка> Кодировка кодирования строки data.

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

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

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

• object <строка> | <Объект>
• signature <строка> | <Буфер> | <TypedArray> | <DataView>
• signatureEncoding <строка> Кодировка строки signature.
• Возвращает: <логическое значение> 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 — предварительно рассчитанная подпись данных в формате 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])[src]

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

Создаёт и возвращает объект 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])[src]

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

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

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

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

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

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

crypto.createCredentials(details)

• details <Объект> Идентично tls.createSecureContext().
• Возвращает: <tls.SecureContext>

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

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

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

• 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 рекомендуется разработчикам самостоятельно выводить ключ и вектор инициализации, используя crypto.scrypt(), и использовать crypto.createDecipheriv() для создания объекта Decipher.

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

• algorithm <строка>
• key <строка> | <Буфер> | <Массив типов> | <DataView>
• iv <строка> | <Буфер> | <Массив типов> | <DataView>
• 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. Если шифру не нужен вектор инициализации, iv может быть null.

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

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

• 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])[src]

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

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

crypto.createECDH(curveName)[src]

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

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

crypto.createHash(algorithm[, options])[src]

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

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

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

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

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

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

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

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

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

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

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

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

Пример: генерация 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.createSign(algorithm[, options])[src]

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

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

crypto.createVerify(algorithm[, options])[src]

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

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

crypto.generateKeyPair(type, options, callback)

• type: <строка> Должно быть 'rsa', 'dsa' или 'ec'.

• options: <Объект>

  • modulusLength: <число> Размер ключа в битах (RSA, DSA).
  • publicExponent: <число> Общественный показатель (RSA). По умолчанию: 0x10001.
  • divisorLength: <число> Размер q в битах (DSA).
  • namedCurve: <строка> Имя кривой для использования (EC).

  • publicKeyEncoding: <Объект>

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

  • privateKeyEncoding: <Объект>

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

• callback: <Функция>

  • err: <Ошибка>
  • publicKey: <строка> | <Буфер>
  • privateKey: <строка> | <Буфер>

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

Рекомендуется кодировать открытые ключи как '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, представляющие сгенерированную пару ключей. При выборе кодирования PEM результат будет строкой, в противном случае — буфером, содержащим данные, закодированные как DER. Обратите внимание, что сам Node.js не принимает DER, он поддерживается только для взаимодействия с другими библиотеками, такими как WebCrypto.

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

crypto.generateKeyPairSync(type, options)

• type: <строка> Должно быть 'rsa', 'dsa' или 'ec'.

• options: <Объект>

  • modulusLength: <число> Размер ключа в битах (RSA, DSA).
  • publicExponent: <число> Общественный показатель (RSA). По умолчанию: 0x10001.
  • divisorLength: <число> Размер q в битах (DSA).
  • namedCurve: <строка> Имя кривой для использования (EC).

  • publicKeyEncoding: <Объект>

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

  • privateKeyEncoding: <Объект>

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

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

  • publicKey: <строка> | <Буфер>
  • privateKey: <строка> | <Буфер>

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

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

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

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

crypto.getCiphers()

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

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

crypto.getCurves()

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

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

crypto.getDiffieHellman(groupName)

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

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

• Возвращает: <булево> true тогда и только тогда, когда в настоящее время используется совместимый с FIPS крипто-провайдер.

crypto.getHashes()

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

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

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

• password <строка> | <Буфер> | <Тип массива> | <DataView>
• salt <строка> | <Буфер> | <Тип массива> | <DataView>
• iterations <число>
• keylen <число>
• digest <строка>

• callback <Функция>

  • err <Ошибка>
  • derivedKey <Буфер>

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

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

Если digest равно null, 'sha1' будет использовано. Это поведение будет устаревшим в будущих версиях Node.js.

Аргумент 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' будет использовано. Это поведение будет устаревшим в будущих версиях Node.js.

Аргумент 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 <Объект> | <строка>

  • key <строка> Закодированный в PEM закрытый ключ.
  • 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 с помощью privateKey. buffer ранее был зашифрован с помощью соответствующего открытого ключа, например, с помощью crypto.publicEncrypt().

privateKey может быть объектом или строкой. Если privateKey является строкой, она обрабатывается как ключ без фразы доступа и будет использовать 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 <Буфер> | <TypedArray> | <DataView>
• Возвращает: <Буфер> Новый Buffer с зашифрованным содержимым.

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

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

crypto.publicDecrypt(key, buffer)

• key <Объект> | <строка>

  • key <строка> Закодированный в PEM открытый или закрытый ключ.
  • 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 может быть объектом или строкой. Если key является строкой, она обрабатывается как ключ без фразы доступа и будет использовать RSA_PKCS1_PADDING.

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

crypto.publicEncrypt(key, buffer)

• key <Объект> | <строка>

  • key <строка> Закодированный в PEM открытый или закрытый ключ.
  • 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 может быть объектом или строкой. Если 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 <Буфер> | <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'));

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

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 <Буфер> | <TypedArray> | <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.scrypt(password, salt, keylen[, options], callback)

• password <строка> | <Буфер> | <TypedArray> | <DataView>
• salt <строка> | <Буфер> | <TypedArray> | <DataView>
• keylen <число>

• options <Объект>

  • cost <число> Параметр затрат ЦП/памяти. Должен быть степенью двойки, большей
  • N <число> Параметр затрат ЦП/памяти. Должен быть степенью двойки, большей, чем один. По умолчанию: 16384.
  • blockSize <число> Параметр размера блока. По умолчанию: 8.
  • parallelization <число> Параметр распараллеливания. По умолчанию: 1.
  • N <число> Псевдоним для cost. Может быть указан только один из них.
  • r <число> Псевдоним для blockSize. Может быть указан только один из них.
  • p <число> Верхний предел памяти. Ошибка, когда (приблизительно) 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('secret', 'salt', 64, (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // '3745e48...08d59ae'
});
// Using a custom N parameter. Must be a power of two.
crypto.scrypt('secret', 'salt', 64, { N: 1024 }, (err, derivedKey) => {
  if (err) throw err;
  console.log(derivedKey.toString('hex'));  // '3745e48...aa39b34'
});

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

• password <string> | <Buffer> | <TypedArray> | <DataView>
• salt <string> | <Buffer> | <TypedArray> | <DataView>
• keylen <number>

• options <Object>

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

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

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

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

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

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

crypto.setEngine(engine[, flags])

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

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

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

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

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

Нижеперечисленные флаги устарели в OpenSSL-1.1.0.

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

crypto.setFips(bool)

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

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

crypto.timingSafeEqual(a, b)

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

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

a и b должны быть буферами, массивами или объектами Buffer, и они должны иметь одинаковую длину.

Использование 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 больше не приемлемы там, где требуется стойкость к коллизиям, например, в цифровых подписях.
• Рекомендуется, чтобы ключ, используемый с алгоритмами 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. Это не требуется, если 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!');
}

console.log(receivedPlaintext);

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

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

Опции OpenSSL

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

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

Константы Node.js Crypto