Web Crypto API

[История]

Версия	Изменения
v23.5.0	Алгоритмы `Ed25519` и `X25519` теперь стабильны.
v19.0.0	Больше не является экспериментальным, за исключением алгоритмов `Ed25519`, `Ed448`, `X25519` и `X448`.
v20.0.0, v18.17.0	Аргументы теперь приводятся и проверяются в соответствии с их определениями WebIDL, как и в других реализациях Web Crypto API.
v18.4.0, v16.17.0	Удален проприетарный формат импорта/экспорта `'node.keyObject'`.
v18.4.0, v16.17.0	Удалены проприетарные алгоритмы `'NODE-DSA'`, `'NODE-DH'` и `'NODE-SCRYPT'`.
v18.4.0, v16.17.0	Добавлены алгоритмы `'Ed25519'`, `'Ed448'`, `'X25519'` и `'X448'`.
v18.4.0, v16.17.0	Удалены проприетарные алгоритмы `'NODE-ED25519'` и `'NODE-ED448'`.
v18.4.0, v16.17.0	Удалены проприетарные именованные кривые `'NODE-X25519'` и `'NODE-X448'` из алгоритма `'ECDH'`.

[Стабильно: 2 - Стабильно]

Стабильно: 2 Стабильность: 2 - Стабильно

Node.js предоставляет реализацию стандартного Web Crypto API.

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

const { subtle } = globalThis.crypto;

(async function() {

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

  const enc = new TextEncoder();
  const message = enc.encode('I love cupcakes');

  const digest = await subtle.sign({
    name: 'HMAC',
  }, key, message);

})();

Примеры

Генерация ключей

Класс <SubtleCrypto> может использоваться для генерации симметричных (секретных) ключей или асимметричных пар ключей (открытый ключ и закрытый ключ).

AES ключи

const { subtle } = globalThis.crypto;

async function generateAesKey(length = 256) {
  const key = await subtle.generateKey({
    name: 'AES-CBC',
    length,
  }, true, ['encrypt', 'decrypt']);

  return key;
}

Пары ключей ECDSA

const { subtle } = globalThis.crypto;

async function generateEcKey(namedCurve = 'P-521') {
  const {
    publicKey,
    privateKey,
  } = await subtle.generateKey({
    name: 'ECDSA',
    namedCurve,
  }, true, ['sign', 'verify']);

  return { publicKey, privateKey };
}

Пары ключей Ed25519/X25519

const { subtle } = globalThis.crypto;

async function generateEd25519Key() {
  return subtle.generateKey({
    name: 'Ed25519',
  }, true, ['sign', 'verify']);
}

async function generateX25519Key() {
  return subtle.generateKey({
    name: 'X25519',
  }, true, ['deriveKey']);
}

Ключи HMAC

const { subtle } = globalThis.crypto;

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

  return key;
}

Пары ключей RSA

const { subtle } = globalThis.crypto;
const publicExponent = new Uint8Array([1, 0, 1]);

async function generateRsaKey(modulusLength = 2048, hash = 'SHA-256') {
  const {
    publicKey,
    privateKey,
  } = await subtle.generateKey({
    name: 'RSASSA-PKCS1-v1_5',
    modulusLength,
    publicExponent,
    hash,
  }, true, ['sign', 'verify']);

  return { publicKey, privateKey };
}

Шифрование и дешифрование

const crypto = globalThis.crypto;

async function aesEncrypt(plaintext) {
  const ec = new TextEncoder();
  const key = await generateAesKey();
  const iv = crypto.getRandomValues(new Uint8Array(16));

  const ciphertext = await crypto.subtle.encrypt({
    name: 'AES-CBC',
    iv,
  }, key, ec.encode(plaintext));

  return {
    key,
    iv,
    ciphertext,
  };
}

async function aesDecrypt(ciphertext, key, iv) {
  const dec = new TextDecoder();
  const plaintext = await crypto.subtle.decrypt({
    name: 'AES-CBC',
    iv,
  }, key, ciphertext);

  return dec.decode(plaintext);
}

Экспорт и импорт ключей

const { subtle } = globalThis.crypto;

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

  return subtle.exportKey(format, key);
}

async function importHmacKey(keyData, format = 'jwk', hash = 'SHA-512') {
  const key = await subtle.importKey(format, keyData, {
    name: 'HMAC',
    hash,
  }, true, ['sign', 'verify']);

  return key;
}

Упаковка и распаковка ключей

const { subtle } = globalThis.crypto;

async function generateAndWrapHmacKey(format = 'jwk', hash = 'SHA-512') {
  const [
    key,
    wrappingKey,
  ] = await Promise.all([
    subtle.generateKey({
      name: 'HMAC', hash,
    }, true, ['sign', 'verify']),
    subtle.generateKey({
      name: 'AES-KW',
      length: 256,
    }, true, ['wrapKey', 'unwrapKey']),
  ]);

  const wrappedKey = await subtle.wrapKey(format, key, wrappingKey, 'AES-KW');

  return { wrappedKey, wrappingKey };
}

async function unwrapHmacKey(
  wrappedKey,
  wrappingKey,
  format = 'jwk',
  hash = 'SHA-512') {

  const key = await subtle.unwrapKey(
    format,
    wrappedKey,
    wrappingKey,
    'AES-KW',
    { name: 'HMAC', hash },
    true,
    ['sign', 'verify']);

  return key;
}

Подпись и проверка

const { subtle } = globalThis.crypto;

async function sign(key, data) {
  const ec = new TextEncoder();
  const signature =
    await subtle.sign('RSASSA-PKCS1-v1_5', key, ec.encode(data));
  return signature;
}

async function verify(key, signature, data) {
  const ec = new TextEncoder();
  const verified =
    await subtle.verify(
      'RSASSA-PKCS1-v1_5',
      key,
      signature,
      ec.encode(data));
  return verified;
}

Получение битов и ключей

const { subtle } = globalThis.crypto;

async function pbkdf2(pass, salt, iterations = 1000, length = 256) {
  const ec = new TextEncoder();
  const key = await subtle.importKey(
    'raw',
    ec.encode(pass),
    'PBKDF2',
    false,
    ['deriveBits']);
  const bits = await subtle.deriveBits({
    name: 'PBKDF2',
    hash: 'SHA-512',
    salt: ec.encode(salt),
    iterations,
  }, key, length);
  return bits;
}

async function pbkdf2Key(pass, salt, iterations = 1000, length = 256) {
  const ec = new TextEncoder();
  const keyMaterial = await subtle.importKey(
    'raw',
    ec.encode(pass),
    'PBKDF2',
    false,
    ['deriveKey']);
  const key = await subtle.deriveKey({
    name: 'PBKDF2',
    hash: 'SHA-512',
    salt: ec.encode(salt),
    iterations,
  }, keyMaterial, {
    name: 'AES-GCM',
    length,
  }, true, ['encrypt', 'decrypt']);
  return key;
}

Digest

const { subtle } = globalThis.crypto;

async function digest(data, algorithm = 'SHA-512') {
  const ec = new TextEncoder();
  const digest = await subtle.digest(algorithm, ec.encode(data));
  return digest;
}

Algorithm matrix

Таблица подробно описывает алгоритмы, поддерживаемые реализацией Node.js Web Crypto API, и API, поддерживаемые для каждого из них:

Алгоритм	`generateKey`	`exportKey`	`importKey`	`encrypt`	`decrypt`	`wrapKey`	`unwrapKey`	`deriveBits`	`deriveKey`	`sign`	`verify`	`digest`
`'RSASSA-PKCS1-v1_5'`	✔	✔	✔							✔	✔
`'RSA-PSS'`	✔	✔	✔							✔	✔
`'RSA-OAEP'`	✔	✔	✔	✔	✔	✔	✔
`'ECDSA'`	✔	✔	✔							✔	✔
`'Ed25519'`	✔	✔	✔							✔	✔
`'Ed448'`	✔	✔	✔							✔	✔
`'ECDH'`	✔	✔	✔					✔	✔
`'X25519'`	✔	✔	✔					✔	✔
`'X448'`	✔	✔	✔					✔	✔
`'AES-CTR'`	✔	✔	✔	✔	✔	✔	✔
`'AES-CBC'`	✔	✔	✔	✔	✔	✔	✔
`'AES-GCM'`	✔	✔	✔	✔	✔	✔	✔
`'AES-KW'`	✔	✔	✔			✔	✔
`'HMAC'`	✔	✔	✔							✔	✔
`'HKDF'`		✔	✔					✔	✔
`'PBKDF2'`		✔	✔					✔	✔
`'SHA-1'`												✔
`'SHA-256'`												✔
`'SHA-384'`												✔
`'SHA-512'`												✔

Class: `Crypto`

Добавлено в: v15.0.0

globalThis.crypto является экземпляром класса Crypto. Crypto - это синглтон, который предоставляет доступ к остальной части криптографического API.

`crypto.subtle`

Добавлено в: v15.0.0

Тип: <SubtleCrypto>

Предоставляет доступ к API SubtleCrypto.

`crypto.getRandomValues(typedArray)`

Добавлено в: v15.0.0

typedArray <Buffer> | <TypedArray>
Возвращает: <Buffer> | <TypedArray>

Генерирует криптографически стойкие случайные значения. Данный typedArray заполняется случайными значениями и возвращается ссылка на typedArray.

Данный typedArray должен быть целочисленным экземпляром <TypedArray>, т.е. Float32Array и Float64Array не принимаются.

Будет выдана ошибка, если данный typedArray больше 65 536 байт.

`crypto.randomUUID()`

Добавлено в: v16.7.0

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

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

Класс: `CryptoKey`

Добавлено в: v15.0.0

`cryptoKey.algorithm`

Добавлено в: v15.0.0

Тип: <AesKeyGenParams> | <RsaHashedKeyGenParams> | <EcKeyGenParams> | <HmacKeyGenParams>

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

Только для чтения.

`cryptoKey.extractable`

Добавлено в: v15.0.0

Тип: <boolean>

Если true, <CryptoKey> может быть извлечен с использованием subtleCrypto.exportKey() или subtleCrypto.wrapKey().

Только для чтения.

`cryptoKey.type`

Добавлено в: v15.0.0

Тип: <string> Одно из 'secret', 'private' или 'public'.

Строка, определяющая, является ли ключ симметричным ('secret') или асимметричным ('private' или 'public') ключом.

`cryptoKey.usages`

Добавлено в: v15.0.0

Тип: <string[]>

Массив строк, определяющих операции, для которых может использоваться ключ.

Возможные варианты использования:

'encrypt' - Ключ может использоваться для шифрования данных.
'decrypt' - Ключ может использоваться для дешифрования данных.
'sign' - Ключ может использоваться для создания цифровых подписей.
'verify' - Ключ может использоваться для проверки цифровых подписей.
'deriveKey' - Ключ может использоваться для получения нового ключа.
'deriveBits' - Ключ может использоваться для получения битов.
'wrapKey' - Ключ может использоваться для обертывания другого ключа.
'unwrapKey' - Ключ может использоваться для распаковки другого ключа.

Допустимые варианты использования ключа зависят от алгоритма ключа (определяется cryptokey.algorithm.name).

Тип ключа	`'encrypt'`	`'decrypt'`	`'sign'`	`'verify'`	`'deriveKey'`	`'deriveBits'`	`'wrapKey'`	`'unwrapKey'`
`'AES-CBC'`	✔	✔					✔	✔
`'AES-CTR'`	✔	✔					✔	✔
`'AES-GCM'`	✔	✔					✔	✔
`'AES-KW'`							✔	✔
`'ECDH'`					✔	✔
`'X25519'`					✔	✔
`'X448'`					✔	✔
`'ECDSA'`			✔	✔
`'Ed25519'`			✔	✔
`'Ed448'`			✔	✔
`'HDKF'`					✔	✔
`'HMAC'`			✔	✔
`'PBKDF2'`					✔	✔
`'RSA-OAEP'`	✔	✔					✔	✔
`'RSA-PSS'`			✔	✔
`'RSASSA-PKCS1-v1_5'`			✔	✔

Class: `CryptoKeyPair`

Добавлено в версии: v15.0.0

CryptoKeyPair — это простой объект-словарь со свойствами publicKey и privateKey, представляющий асимметричную пару ключей.

`cryptoKeyPair.privateKey`

Добавлено в версии: v15.0.0

Тип: <CryptoKey> A <CryptoKey>, у которого type будет 'private'.

`cryptoKeyPair.publicKey`

Добавлено в версии: v15.0.0

Тип: <CryptoKey> A <CryptoKey>, у которого type будет 'public'.

Class: `SubtleCrypto`

Добавлено в версии: v15.0.0

`subtle.decrypt(algorithm, key, data)`

Добавлено в версии: v15.0.0

algorithm: <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>
key: <CryptoKey>
data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
Возвращает: <Promise> Выполняется с <ArrayBuffer>

Используя метод и параметры, указанные в algorithm, и ключевой материал, предоставленный key, subtle.decrypt() пытается расшифровать предоставленные data. В случае успеха возвращаемый промис будет разрешен с <ArrayBuffer>, содержащим результирующий открытый текст.

В настоящее время поддерживаются следующие алгоритмы:

'RSA-OAEP'
'AES-CTR'
'AES-CBC'
'AES-GCM'

`subtle.deriveBits(algorithm, baseKey[, length])`

[История]

Версия	Изменения
v22.5.0, v20.17.0	Параметр length теперь необязателен для `'ECDH'`, `'X25519'` и `'X448'`.
v18.4.0, v16.17.0	Добавлены алгоритмы `'X25519'` и `'X448'`.
v15.0.0	Добавлено в: v15.0.0

algorithm: <AlgorithmIdentifier> | <EcdhKeyDeriveParams> | <HkdfParams> | <Pbkdf2Params>
baseKey: <CryptoKey>
length: <number> | <null> По умолчанию: null
Возвращает: <Promise> Исполняется с <ArrayBuffer>

Используя метод и параметры, указанные в algorithm, и ключевой материал, предоставленный baseKey, subtle.deriveBits() пытается сгенерировать length бит.

Когда length не указан или null, генерируется максимальное количество битов для данного алгоритма. Это разрешено для алгоритмов 'ECDH', 'X25519' и 'X448', для других алгоритмов length должен быть числом.

В случае успеха возвращенный промис будет разрешен с <ArrayBuffer>, содержащим сгенерированные данные.

В настоящее время поддерживаются следующие алгоритмы:

'ECDH'
'X25519'
'X448'
'HKDF'
'PBKDF2'

`subtle.deriveKey(algorithm, baseKey, derivedKeyAlgorithm, extractable, keyUsages)`

[История]

Версия	Изменения
v18.4.0, v16.17.0	Добавлены алгоритмы `'X25519'` и `'X448'`.
v15.0.0	Добавлено в: v15.0.0

algorithm: <AlgorithmIdentifier> | <EcdhKeyDeriveParams> | <HkdfParams> | <Pbkdf2Params>
baseKey: <CryptoKey>
derivedKeyAlgorithm: <HmacKeyGenParams> | <AesKeyGenParams>
extractable: <boolean>
keyUsages: <string[]> См. Использование ключей.
Возвращает: <Promise> Исполняется с <CryptoKey>

Используя метод и параметры, указанные в algorithm, и ключевой материал, предоставленный baseKey, subtle.deriveKey() пытается сгенерировать новый <CryptoKey> на основе метода и параметров в derivedKeyAlgorithm.

Вызов subtle.deriveKey() эквивалентен вызову subtle.deriveBits() для генерации необработанного ключевого материала, а затем передаче результата в метод subtle.importKey(), используя параметры deriveKeyAlgorithm, extractable и keyUsages в качестве входных данных.

В настоящее время поддерживаются следующие алгоритмы:

'ECDH'
'X25519'
'X448'
'HKDF'
'PBKDF2'

`subtle.digest(algorithm, data)`

Добавлено в: v15.0.0

algorithm: <string> | <Object>
data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
Возвращает: <Promise>, разрешается с <ArrayBuffer>

Используя метод, указанный в algorithm, subtle.digest() пытается сгенерировать дайджест data. В случае успеха возвращаемый промис разрешается с <ArrayBuffer>, содержащим вычисленный дайджест.

Если algorithm предоставлен как <string>, то он должен быть одним из:

'SHA-1'
'SHA-256'
'SHA-384'
'SHA-512'

Если algorithm предоставлен как <Object>, то он должен иметь свойство name, значение которого является одним из вышеперечисленных.

`subtle.encrypt(algorithm, key, data)`

Добавлено в: v15.0.0

algorithm: <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>
key: <CryptoKey>
data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
Возвращает: <Promise>, разрешается с <ArrayBuffer>

Используя метод и параметры, указанные в algorithm, и ключевой материал, предоставленный key, subtle.encrypt() пытается зашифровать data. В случае успеха возвращаемый промис разрешается с <ArrayBuffer>, содержащим зашифрованный результат.

В настоящее время поддерживаются следующие алгоритмы:

'RSA-OAEP'
'AES-CTR'
'AES-CBC'
'AES-GCM'

`subtle.exportKey(format, key)`

[История]

Версия	Изменения
v18.4.0, v16.17.0	Добавлены алгоритмы `'Ed25519'`, `'Ed448'`, `'X25519'` и `'X448'`.
v15.9.0	Удален экспорт `'NODE-DSA'` JWK.
v15.0.0	Добавлено в: v15.0.0

format: <string> Должен быть одним из 'raw', 'pkcs8', 'spki' или 'jwk'.
key: <CryptoKey>
Возвращает: <Promise> Исполняется с <ArrayBuffer> | <Object>.

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

Если <CryptoKey> не является извлекаемым, возвращенный promise будет отклонен.

Когда format является либо 'pkcs8', либо 'spki', и экспорт успешен, возвращенный promise будет разрешен с помощью <ArrayBuffer>, содержащего экспортированные данные ключа.

Когда format равен 'jwk', и экспорт успешен, возвращенный promise будет разрешен с помощью объекта JavaScript, соответствующего спецификации JSON Web Key.

Тип ключа	`'spki'`	`'pkcs8'`	`'jwk'`	`'raw'`
`'AES-CBC'`			✔	✔
`'AES-CTR'`			✔	✔
`'AES-GCM'`			✔	✔
`'AES-KW'`			✔	✔
`'ECDH'`	✔	✔	✔	✔
`'ECDSA'`	✔	✔	✔	✔
`'Ed25519'`	✔	✔	✔	✔
`'Ed448'`	✔	✔	✔	✔
`'HDKF'`
`'HMAC'`			✔	✔
`'PBKDF2'`
`'RSA-OAEP'`	✔	✔	✔
`'RSA-PSS'`	✔	✔	✔
`'RSASSA-PKCS1-v1_5'`	✔	✔	✔

`subtle.generateKey(algorithm, extractable, keyUsages)`

Добавлено в: v15.0.0

algorithm: <AlgorithmIdentifier> | <RsaHashedKeyGenParams> | <EcKeyGenParams> | <HmacKeyGenParams> | <AesKeyGenParams>
extractable: <boolean>
keyUsages: <string[]> См. Использование ключей.
Возвращает: <Promise> Исполняется с <CryptoKey> | <CryptoKeyPair>

Используя метод и параметры, указанные в algorithm, subtle.generateKey() пытается сгенерировать новый ключевой материал. В зависимости от используемого метода, метод может генерировать либо один <CryptoKey>, либо <CryptoKeyPair>.

Поддерживаемые алгоритмы генерации <CryptoKeyPair> (открытый и закрытый ключ) включают:

'RSASSA-PKCS1-v1_5'
'RSA-PSS'
'RSA-OAEP'
'ECDSA'
'Ed25519'
'Ed448'
'ECDH'
'X25519'
'X448'

Поддерживаемые алгоритмы генерации <CryptoKey> (секретный ключ) включают:

'HMAC'
'AES-CTR'
'AES-CBC'
'AES-GCM'
'AES-KW'

`subtle.importKey(format, keyData, algorithm, extractable, keyUsages)`

[История изменений]

Версия	Изменения
v18.4.0, v16.17.0	Добавлены алгоритмы `'Ed25519'`, `'Ed448'`, `'X25519'` и `'X448'`.
v15.9.0	Удален импорт `'NODE-DSA'` JWK.
v15.0.0	Добавлено в версии: v15.0.0

format: <string> Должно быть одним из 'raw', 'pkcs8', 'spki' или 'jwk'.
keyData: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer> | <Object>
algorithm: <AlgorithmIdentifier> | <RsaHashedImportParams> | <EcKeyImportParams> | <HmacImportParams>
extractable: <boolean>
keyUsages: <string[]> См. Использование ключей.
Возвращает: <Promise> Завершается экземпляром <CryptoKey>

Метод subtle.importKey() пытается интерпретировать предоставленные keyData как заданный format, чтобы создать экземпляр <CryptoKey>, используя предоставленные аргументы algorithm, extractable и keyUsages. Если импорт успешен, возвращаемый промис будет разрешен созданным <CryptoKey>.

При импорте ключа 'PBKDF2' extractable должно быть false.

В настоящее время поддерживаемые алгоритмы включают:

Тип ключа	`'spki'`	`'pkcs8'`	`'jwk'`	`'raw'`
`'AES-CBC'`			✔	✔
`'AES-CTR'`			✔	✔
`'AES-GCM'`			✔	✔
`'AES-KW'`			✔	✔
`'ECDH'`	✔	✔	✔	✔
`'X25519'`	✔	✔	✔	✔
`'X448'`	✔	✔	✔	✔
`'ECDSA'`	✔	✔	✔	✔
`'Ed25519'`	✔	✔	✔	✔
`'Ed448'`	✔	✔	✔	✔
`'HDKF'`				✔
`'HMAC'`			✔	✔
`'PBKDF2'`				✔
`'RSA-OAEP'`	✔	✔	✔
`'RSA-PSS'`	✔	✔	✔
`'RSASSA-PKCS1-v1_5'`	✔	✔	✔

`subtle.sign(algorithm, key, data)`

[История]

Версия	Изменения
v18.4.0, v16.17.0	Добавлены алгоритмы `'Ed25519'` и `'Ed448'`.
v15.0.0	Добавлено в: v15.0.0

algorithm: <AlgorithmIdentifier> | <RsaPssParams> | <EcdsaParams> | <Ed448Params>
key: <CryptoKey>
data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
Возвращает: <Promise> Исполняется с <ArrayBuffer>, содержащим сгенерированную подпись.

Используя метод и параметры, заданные algorithm, и ключевой материал, предоставленный key, subtle.sign() пытается сгенерировать криптографическую подпись data. В случае успеха возвращаемый промис разрешается с <ArrayBuffer>, содержащим сгенерированную подпись.

В настоящее время поддерживаются следующие алгоритмы:

'RSASSA-PKCS1-v1_5'
'RSA-PSS'
'ECDSA'
'Ed25519'
'Ed448'
'HMAC'

`subtle.unwrapKey(format, wrappedKey, unwrappingKey, unwrapAlgo, unwrappedKeyAlgo, extractable, keyUsages)`

Добавлено в: v15.0.0

format: <string> Должен быть одним из: 'raw', 'pkcs8', 'spki' или 'jwk'.
wrappedKey: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
unwrappingKey: <CryptoKey>
unwrapAlgo: <AlgorithmIdentifier> | <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>
unwrappedKeyAlgo: <AlgorithmIdentifier> | <RsaHashedImportParams> | <EcKeyImportParams> | <HmacImportParams>
extractable: <boolean>
keyUsages: <string[]> См. Key usages.
Возвращает: <Promise> Исполняется с <CryptoKey>

В криптографии "обертывание ключа" относится к экспорту и последующему шифрованию ключевого материала. Метод subtle.unwrapKey() пытается расшифровать обернутый ключ и создать экземпляр <CryptoKey>. Это эквивалентно сначала вызову subtle.decrypt() для зашифрованных данных ключа (с использованием аргументов wrappedKey, unwrapAlgo и unwrappingKey в качестве входных данных), а затем передаче результатов в метод subtle.importKey(), используя аргументы unwrappedKeyAlgo, extractable и keyUsages в качестве входных данных. В случае успеха возвращаемый промис разрешается с объектом <CryptoKey>.

В настоящее время поддерживаются следующие алгоритмы обертывания:

'RSA-OAEP'
'AES-CTR'
'AES-CBC'
'AES-GCM'
'AES-KW'

Поддерживаемые алгоритмы для развернутого ключа включают:

'RSASSA-PKCS1-v1_5'
'RSA-PSS'
'RSA-OAEP'
'ECDSA'
'Ed25519'
'Ed448'
'ECDH'
'X25519'
'X448'
'HMAC'
'AES-CTR'
'AES-CBC'
'AES-GCM'
'AES-KW'

`subtle.verify(algorithm, key, signature, data)`

[История]

Версия	Изменения
v18.4.0, v16.17.0	Добавлены алгоритмы `'Ed25519'` и `'Ed448'`.
v15.0.0	Добавлено в: v15.0.0

algorithm: <AlgorithmIdentifier> | <RsaPssParams> | <EcdsaParams> | <Ed448Params>
key: <CryptoKey>
signature: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
Возвращает: <Promise> Исполняется с <boolean>

Используя метод и параметры, указанные в algorithm, и ключевой материал, предоставленный key, subtle.verify() пытается проверить, является ли signature действительной криптографической подписью data. Возвращенный промис разрешается либо true, либо false.

В настоящее время поддерживаются следующие алгоритмы:

'RSASSA-PKCS1-v1_5'
'RSA-PSS'
'ECDSA'
'Ed25519'
'Ed448'
'HMAC'

`subtle.wrapKey(format, key, wrappingKey, wrapAlgo)`

Добавлено в: v15.0.0

format: <string> Должен быть одним из 'raw', 'pkcs8', 'spki' или 'jwk'.
key: <CryptoKey>
wrappingKey: <CryptoKey>
wrapAlgo: <AlgorithmIdentifier> | <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>
Возвращает: <Promise> Исполняется с <ArrayBuffer>

В криптографии "упаковка ключа" относится к экспорту и последующему шифрованию ключевого материала. Метод subtle.wrapKey() экспортирует ключевой материал в формат, идентифицированный format, затем шифрует его с использованием метода и параметров, указанных в wrapAlgo, и ключевого материала, предоставленного wrappingKey. Это эквивалентно вызову subtle.exportKey() с использованием format и key в качестве аргументов, а затем передаче результата методу subtle.encrypt() с использованием wrappingKey и wrapAlgo в качестве входных данных. В случае успеха возвращенный промис будет разрешен с <ArrayBuffer>, содержащим зашифрованные данные ключа.

В настоящее время поддерживаются следующие алгоритмы упаковки:

'RSA-OAEP'
'AES-CTR'
'AES-CBC'
'AES-GCM'
'AES-KW'

Параметры алгоритма

Объекты параметров алгоритма определяют методы и параметры, используемые различными методами <SubtleCrypto>. Хотя здесь они описываются как «классы», они являются простыми объектами словаря JavaScript.

Класс: `AlgorithmIdentifier`

Добавлено в: v18.4.0, v16.17.0

`algorithmIdentifier.name`

Добавлено в: v18.4.0, v16.17.0

Тип: <string>

Класс: `AesCbcParams`

Добавлено в: v15.0.0

`aesCbcParams.iv`

Добавлено в: v15.0.0

Тип: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

Предоставляет вектор инициализации. Он должен быть ровно 16 байт в длину и должен быть непредсказуемым и криптографически случайным.

`aesCbcParams.name`

Добавлено в: v15.0.0

Тип: <string> Должен быть 'AES-CBC'.

Класс: `AesCtrParams`

Добавлено в: v15.0.0

`aesCtrParams.counter`

Добавлено в: v15.0.0

Тип: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

Начальное значение блока счетчика. Он должен быть ровно 16 байт в длину.

Метод AES-CTR использует самые правые length биты блока в качестве счетчика, а остальные биты в качестве nonce.

`aesCtrParams.length`

Добавлено в: v15.0.0

Тип: <number> Количество битов в aesCtrParams.counter, которые будут использоваться в качестве счетчика.

`aesCtrParams.name`

Добавлено в: v15.0.0

Тип: <string> Должно быть 'AES-CTR'.

Class: `AesGcmParams`

Добавлено в: v15.0.0

`aesGcmParams.additionalData`

Добавлено в: v15.0.0

Тип: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer> | <undefined>

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

`aesGcmParams.iv`

Добавлено в: v15.0.0

Тип: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

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

В идеале это детерминированное 12-байтное значение, которое вычисляется таким образом, чтобы гарантированно быть уникальным для всех вызовов, использующих один и тот же ключ. В качестве альтернативы вектор инициализации может состоять как минимум из 12 криптографически случайных байтов. Для получения дополнительной информации о построении векторов инициализации для AES-GCM см. Раздел 8 NIST SP 800-38D.

`aesGcmParams.name`

Добавлено в: v15.0.0

Тип: <string> Должно быть 'AES-GCM'.

`aesGcmParams.tagLength`

Добавлено в версии: v15.0.0

Тип: <number> Размер в битах сгенерированного тега аутентификации. Это значение должно быть одним из 32, 64, 96, 104, 112, 120 или 128. По умолчанию: 128.

Класс: `AesKeyGenParams`

Добавлено в версии: v15.0.0

`aesKeyGenParams.length`

Добавлено в версии: v15.0.0

Тип: <number>

Длина AES ключа для генерации. Должна быть 128, 192 или 256.

`aesKeyGenParams.name`

Добавлено в версии: v15.0.0

Тип: <string> Должно быть одним из 'AES-CBC', 'AES-CTR', 'AES-GCM' или 'AES-KW'

Класс: `EcdhKeyDeriveParams`

Добавлено в версии: v15.0.0

`ecdhKeyDeriveParams.name`

Добавлено в версии: v15.0.0

Тип: <string> Должно быть 'ECDH', 'X25519' или 'X448'.

`ecdhKeyDeriveParams.public`

Добавлено в версии: v15.0.0

Тип: <CryptoKey>

Производное ключа ECDH работает, принимая в качестве входных данных закрытый ключ одной стороны и открытый ключ другой стороны — используя оба для генерации общего секретного ключа. Свойству ecdhKeyDeriveParams.public присваивается открытый ключ другой стороны.

Класс: `EcdsaParams`

Добавлено в версии: v15.0.0

`ecdsaParams.hash`

Добавлено в версии: v15.0.0

Тип: <string> | <Object>

Если представлено как <string>, значение должно быть одним из:

'SHA-1'
'SHA-256'
'SHA-384'
'SHA-512'

Если представлено как <Object>, объект должен иметь свойство name, значение которого является одним из перечисленных выше значений.

`ecdsaParams.name`

Добавлено в: v15.0.0

Тип: <string> Должно быть 'ECDSA'.

Класс: `EcKeyGenParams`

Добавлено в: v15.0.0

`ecKeyGenParams.name`

Добавлено в: v15.0.0

Тип: <string> Должно быть одним из 'ECDSA' или 'ECDH'.

`ecKeyGenParams.namedCurve`

Добавлено в: v15.0.0

Тип: <string> Должно быть одним из 'P-256', 'P-384', 'P-521'.

Класс: `EcKeyImportParams`

Добавлено в: v15.0.0

`ecKeyImportParams.name`

Добавлено в: v15.0.0

Тип: <string> Должно быть одним из 'ECDSA' или 'ECDH'.

`ecKeyImportParams.namedCurve`

Добавлено в: v15.0.0

Тип: <string> Должно быть одним из 'P-256', 'P-384', 'P-521'.

Класс: `Ed448Params`

Добавлено в: v15.0.0

`ed448Params.name`

Добавлено в: v18.4.0, v16.17.0

Тип: <string> Должно быть 'Ed448'.

`ed448Params.context`

Добавлено в: v18.4.0, v16.17.0

Тип: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer> | <undefined>

Элемент context представляет собой дополнительные контекстные данные, связанные с сообщением. Реализация Node.js Web Crypto API поддерживает только контекст нулевой длины, что эквивалентно полному отсутствию контекста.

Класс: `HkdfParams`

Добавлено в версии: v15.0.0

`hkdfParams.hash`

Добавлено в версии: v15.0.0

Тип: <string> | <Object>

Если представлено в виде <string>, значение должно быть одним из:

'SHA-1'
'SHA-256'
'SHA-384'
'SHA-512'

Если представлено в виде <Object>, объект должен иметь свойство name, значение которого является одним из вышеперечисленных значений.

`hkdfParams.info`

Добавлено в версии: v15.0.0

Тип: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

Предоставляет контекстно-зависимый ввод для алгоритма HKDF, специфичный для приложения. Может быть нулевой длины, но должен быть предоставлен.

`hkdfParams.name`

Добавлено в версии: v15.0.0

Тип: <string> Должен быть 'HKDF'.

`hkdfParams.salt`

Добавлено в версии: v15.0.0

Тип: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

Значение соли значительно повышает устойчивость алгоритма HKDF. Оно должно быть случайным или псевдослучайным и иметь ту же длину, что и выходные данные дайджест-функции (например, при использовании 'SHA-256' в качестве дайджеста, соль должна содержать 256 бит случайных данных).

Класс: `HmacImportParams`

Добавлено в: v15.0.0

`hmacImportParams.hash`

Добавлено в: v15.0.0

Тип: <string> | <Object>

Если представлено как <string>, значение должно быть одним из:

'SHA-1'
'SHA-256'
'SHA-384'
'SHA-512'

Если представлено как <Object>, объект должен иметь свойство name, значение которого является одним из вышеперечисленных значений.

`hmacImportParams.length`

Добавлено в: v15.0.0

Тип: <number>

Необязательное количество бит в ключе HMAC. Это необязательно и в большинстве случаев должно быть опущено.

`hmacImportParams.name`

Добавлено в: v15.0.0

Тип: <string> Должно быть 'HMAC'.

Класс: `HmacKeyGenParams`

Добавлено в: v15.0.0

`hmacKeyGenParams.hash`

Добавлено в: v15.0.0

Тип: <string> | <Object>

Если представлено как <string>, значение должно быть одним из:

'SHA-1'
'SHA-256'
'SHA-384'
'SHA-512'

`hmacKeyGenParams.length`

Добавлено в: v15.0.0

Тип: <number>

Количество бит для генерации ключа HMAC. Если опущено, длина будет определяться используемым алгоритмом хеширования. Это необязательно и в большинстве случаев должно быть опущено.

`hmacKeyGenParams.name`

Добавлено в: v15.0.0

Type: <string> Должно быть 'HMAC'.

Класс: `Pbkdf2Params`

Добавлено в: v15.0.0

`pbkdb2Params.hash`

Добавлено в: v15.0.0

Type: <string> | <Object>

Если представлено как <string>, то значение должно быть одним из:

'SHA-1'
'SHA-256'
'SHA-384'
'SHA-512'

`pbkdf2Params.iterations`

Добавлено в: v15.0.0

Type: <number>

Количество итераций, которые алгоритм PBKDF2 должен выполнить при получении битов.

`pbkdf2Params.name`

Добавлено в: v15.0.0

Type: <string> Должно быть 'PBKDF2'.

`pbkdf2Params.salt`

Добавлено в: v15.0.0

Type: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

Должно быть не менее 16 случайных или псевдослучайных байтов.

Класс: `RsaHashedImportParams`

Добавлено в: v15.0.0

`rsaHashedImportParams.hash`

Добавлено в: v15.0.0

Type: <string> | <Object>

Если представлено как <string>, то значение должно быть одним из:

'SHA-1'
'SHA-256'
'SHA-384'
'SHA-512'

`rsaHashedImportParams.name`

Добавлено в: v15.0.0

Тип: <string> Должно быть одним из 'RSASSA-PKCS1-v1_5', 'RSA-PSS' или 'RSA-OAEP'.

Класс: `RsaHashedKeyGenParams`

Добавлено в: v15.0.0

`rsaHashedKeyGenParams.hash`

Добавлено в: v15.0.0

Тип: <string> | <Object>

Если представлено в виде <string>, значение должно быть одним из:

'SHA-1'
'SHA-256'
'SHA-384'
'SHA-512'

`rsaHashedKeyGenParams.modulusLength`

Добавлено в: v15.0.0

Тип: <number>

Длина в битах RSA модуля. В качестве наилучшей практики, должно быть не менее 2048.

`rsaHashedKeyGenParams.name`

Добавлено в: v15.0.0

Тип: <string> Должно быть одним из 'RSASSA-PKCS1-v1_5', 'RSA-PSS' или 'RSA-OAEP'.

`rsaHashedKeyGenParams.publicExponent`

Добавлено в: v15.0.0

Тип: <Uint8Array>

Открытый показатель RSA. Это должен быть <Uint8Array>, содержащий большое конечное, беззнаковое целое число, которое должно помещаться в 32 бита. <Uint8Array> может содержать произвольное количество ведущих нулевых битов. Значение должно быть простым числом. Если нет причин использовать другое значение, используйте new Uint8Array([1, 0, 1]) (65537) в качестве открытого показателя.

Класс: `RsaOaepParams`

Добавлено в: v15.0.0

`rsaOaepParams.label`

Добавлено в: v15.0.0

Тип: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

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

Параметр rsaOaepParams.label является необязательным.

`rsaOaepParams.name`

Добавлено в: v15.0.0

Тип: <string> должен быть 'RSA-OAEP'.

Класс: `RsaPssParams`

Добавлено в: v15.0.0

`rsaPssParams.name`

Добавлено в: v15.0.0

Тип: <string> Должен быть 'RSA-PSS'.

`rsaPssParams.saltLength`

Добавлено в: v15.0.0

Тип: <number>

Длина (в байтах) случайной соли для использования.

Web Crypto API ​

Примеры ​

Генерация ключей ​

AES ключи ​

Пары ключей ECDSA ​

Пары ключей Ed25519/X25519 ​

Ключи HMAC ​

Пары ключей RSA ​

Шифрование и дешифрование ​

Экспорт и импорт ключей ​

Упаковка и распаковка ключей ​

Подпись и проверка ​

Получение битов и ключей ​

Digest ​

Algorithm matrix ​

Class: Crypto ​

crypto.subtle ​

crypto.getRandomValues(typedArray) ​

crypto.randomUUID() ​

Класс: CryptoKey ​

cryptoKey.algorithm ​

cryptoKey.extractable ​

cryptoKey.type ​

cryptoKey.usages ​

Class: CryptoKeyPair ​

cryptoKeyPair.privateKey ​

cryptoKeyPair.publicKey ​

Class: SubtleCrypto ​

subtle.decrypt(algorithm, key, data) ​

subtle.deriveBits(algorithm, baseKey[, length]) ​

subtle.deriveKey(algorithm, baseKey, derivedKeyAlgorithm, extractable, keyUsages) ​

subtle.digest(algorithm, data) ​

subtle.encrypt(algorithm, key, data) ​

subtle.exportKey(format, key) ​

subtle.generateKey(algorithm, extractable, keyUsages) ​

subtle.importKey(format, keyData, algorithm, extractable, keyUsages) ​

subtle.sign(algorithm, key, data) ​

subtle.unwrapKey(format, wrappedKey, unwrappingKey, unwrapAlgo, unwrappedKeyAlgo, extractable, keyUsages) ​

subtle.verify(algorithm, key, signature, data) ​

subtle.wrapKey(format, key, wrappingKey, wrapAlgo) ​

Параметры алгоритма ​

Класс: AlgorithmIdentifier ​

algorithmIdentifier.name ​

Класс: AesCbcParams ​

aesCbcParams.iv ​

aesCbcParams.name ​

Класс: AesCtrParams ​

aesCtrParams.counter ​

aesCtrParams.length ​

aesCtrParams.name ​

Class: AesGcmParams ​

aesGcmParams.additionalData ​

aesGcmParams.iv ​

aesGcmParams.name ​

aesGcmParams.tagLength ​

Класс: AesKeyGenParams ​

aesKeyGenParams.length ​

aesKeyGenParams.name ​

Класс: EcdhKeyDeriveParams ​

ecdhKeyDeriveParams.name ​

ecdhKeyDeriveParams.public ​

Класс: EcdsaParams ​

ecdsaParams.hash ​

ecdsaParams.name ​

Класс: EcKeyGenParams ​

ecKeyGenParams.name ​

ecKeyGenParams.namedCurve ​

Класс: EcKeyImportParams ​

ecKeyImportParams.name ​

ecKeyImportParams.namedCurve ​

Класс: Ed448Params ​

ed448Params.name ​

ed448Params.context ​

Класс: HkdfParams ​

hkdfParams.hash ​

hkdfParams.info ​

hkdfParams.name ​

hkdfParams.salt ​

Класс: HmacImportParams ​

hmacImportParams.hash ​

Web Crypto API

Примеры

Генерация ключей

AES ключи

Пары ключей ECDSA

Пары ключей Ed25519/X25519

Ключи HMAC

Пары ключей RSA

Шифрование и дешифрование

Экспорт и импорт ключей

Упаковка и распаковка ключей

Подпись и проверка

Получение битов и ключей

Digest

Algorithm matrix

Class: `Crypto`

`crypto.subtle`

`crypto.getRandomValues(typedArray)`

`crypto.randomUUID()`

Класс: `CryptoKey`

`cryptoKey.algorithm`

`cryptoKey.extractable`

`cryptoKey.type`

`cryptoKey.usages`

Class: `CryptoKeyPair`

`cryptoKeyPair.privateKey`

`cryptoKeyPair.publicKey`

Class: `SubtleCrypto`

`subtle.decrypt(algorithm, key, data)`

`subtle.deriveBits(algorithm, baseKey[, length])`

`subtle.deriveKey(algorithm, baseKey, derivedKeyAlgorithm, extractable, keyUsages)`

`subtle.digest(algorithm, data)`

`subtle.encrypt(algorithm, key, data)`

`subtle.exportKey(format, key)`

`subtle.generateKey(algorithm, extractable, keyUsages)`

`subtle.importKey(format, keyData, algorithm, extractable, keyUsages)`

`subtle.sign(algorithm, key, data)`

`subtle.unwrapKey(format, wrappedKey, unwrappingKey, unwrapAlgo, unwrappedKeyAlgo, extractable, keyUsages)`

`subtle.verify(algorithm, key, signature, data)`

`subtle.wrapKey(format, key, wrappingKey, wrapAlgo)`

Параметры алгоритма

Класс: `AlgorithmIdentifier`

`algorithmIdentifier.name`

Класс: `AesCbcParams`

`aesCbcParams.iv`

`aesCbcParams.name`

Класс: `AesCtrParams`

`aesCtrParams.counter`

`aesCtrParams.length`

`aesCtrParams.name`

Class: `AesGcmParams`

`aesGcmParams.additionalData`

`aesGcmParams.iv`

`aesGcmParams.name`

`aesGcmParams.tagLength`

Класс: `AesKeyGenParams`

`aesKeyGenParams.length`

`aesKeyGenParams.name`

Класс: `EcdhKeyDeriveParams`

`ecdhKeyDeriveParams.name`

`ecdhKeyDeriveParams.public`

Класс: `EcdsaParams`

`ecdsaParams.hash`

`ecdsaParams.name`

Класс: `EcKeyGenParams`

`ecKeyGenParams.name`

`ecKeyGenParams.namedCurve`

Класс: `EcKeyImportParams`

`ecKeyImportParams.name`

`ecKeyImportParams.namedCurve`

Класс: `Ed448Params`

`ed448Params.name`

`ed448Params.context`

Класс: `HkdfParams`

`hkdfParams.hash`

`hkdfParams.info`

`hkdfParams.name`

`hkdfParams.salt`

Класс: `HmacImportParams`

`hmacImportParams.hash`