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
}

Хэш-сумма

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
}

Матрица алгоритмов

Таблица описывает алгоритмы, поддерживаемые реализацией Web Crypto API в Node.js, и поддерживаемые для каждого из них 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'												✔

Класс: 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'			✔	✔

Класс: CryptoKeyPair

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

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

cryptoKeyPair.privateKey

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

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

cryptoKeyPair.publicKey

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

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

Класс: 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. В случае успеха возвращаемое promise будет разрешено с <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	Удалён экспорт JWK 'NODE-DSA'.
v15.0.0	Добавлено в: v15.0.0

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

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

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

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

Если format — 'jwk', и экспорт выполнен успешно, возвращаемое обещание будет разрешено с объектом 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: <булево>

• keyUsages: <массив строк> См. Использование ключей.

• Возвращает: <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	Удален импорт JWK 'NODE-DSA'.
v15.0.0	Добавлено в: v15.0.0

• format: <строка> Должен быть одним из 'raw', 'pkcs8', 'spki' или 'jwk'.

• keyData: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer> | <Объект>

• algorithm: <AlgorithmIdentifier> | <RsaHashedImportParams> | <EcKeyImportParams> | <HmacImportParams>

• extractable: <булево>

• keyUsages: <строка[]> См. Использование ключей.

• Возвращает: <Promise> Выполняется с <CryptoKey>

Метод subtle.importKey() пытается интерпретировать предоставленные keyData как заданный format для создания экземпляра <CryptoKey> с использованием предоставленных аргументов algorithm, extractable и keyUsages. Если импорт выполнен успешно, возвращаемое promise будет разрешено с созданным <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[]> См. Использование ключей.

• Возвращает: <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. Возвращаемое Promise разрешается со значением 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. В случае успеха возвращаемое Promise будет разрешено с <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'.

Класс: 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 представляет необязательные контекстные данные, которые нужно связать с сообщением. Реализация API Web Crypto Node.js поддерживает только контекст нулевой длины, что эквивалентно отсутствию контекста.

Класс: 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'

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

hmacKeyGenParams.length

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

• Тип: <number>

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

hmacKeyGenParams.name

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

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

Класс: Pbkdf2Params

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

pbkdb2Params.hash

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

• Тип: <string> | <Object>

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

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

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

pbkdf2Params.iterations

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

• Тип: <number>

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

pbkdf2Params.name

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

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

pbkdf2Params.salt

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

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

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

Класс: RsaHashedImportParams

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

rsaHashedImportParams.hash

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

• Тип: <string> | <Object>

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

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

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

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'

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

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>, содержащий целое без знака в формате big-endian, которое должно поместиться в 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>

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

Сноски