Создание ключей

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

const { subtle } = globalThis.crypto;

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

  return key;
} copy

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 };
} copy

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']);
} copy

const { subtle } = globalThis.crypto;

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

  return key;
} copy

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 };
} copy

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

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);
} copy

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

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;
} copy

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

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;
} copy

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

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;
} copy

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

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;
} copy

Хеширование

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;
} copy

crypto.subtle

• Тип: <SubtleCrypto>

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

crypto.getRandomValues(typedArray)

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

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

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

Если размер указанного typedArray превышает 65 536 байт, будет выброшена ошибка.

crypto.randomUUID()

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

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

cryptoKey.algorithm

• Тип: <KeyAlgorithm> | <RsaHashedKeyAlgorithm> | <EcKeyAlgorithm> | <AesKeyAlgorithm> | <HmacKeyAlgorithm>

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

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

cryptoKey.extractable

• Тип: <boolean>

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

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

cryptoKey.type

• Тип: <string> Одно из значений: 'secret', 'private' или 'public'.

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

cryptoKey.usages

• Тип: <string[]>

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

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

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

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

cryptoKeyPair.privateKey

• Тип: <CryptoKey> Объект <CryptoKey>, значение type которого будет 'private'.

cryptoKeyPair.publicKey

• Тип: <CryptoKey> Объект <CryptoKey>, значение type которого будет 'public'.

subtle.decrypt(algorithm, key, data)

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

• algorithm <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)

• algorithm <EcdhKeyDeriveParams> | <HkdfParams> | <Pbkdf2Params>
• baseKey <CryptoKey>
• derivedKeyAlgorithm <string> | <Algorithm> | <HmacImportParams> | <AesDerivedKeyParams>
• 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)

• algorithm <string> | <Algorithm>
• 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)

• 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)

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

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

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

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

Если format имеет значение 'jwk' и экспорт выполнен успешно, возвращённое обещание будет выполнено с объектом JavaScript, соответствующим спецификации JSON Web Key.

subtle.generateKey(algorithm, extractable, keyUsages)

• algorithm <string> | <Algorithm> | <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)

• format <string> Должно быть одним из значений 'raw', 'pkcs8', 'spki' или 'jwk'.
• keyData <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer> | <Object>

• algorithm <string> | <Algorithm> | <RsaHashedImportParams> | <EcKeyImportParams> | <HmacImportParams>

• extractable <boolean>
• keyUsages <string[]> См. Использование ключа.
• Возвращает: <Promise> При успешном выполнении возвращает <CryptoKey>.

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

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

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

subtle.sign(algorithm, key, data)

• algorithm <string> | <Algorithm> | <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)

• format <string> Должно быть одним из 'raw', 'pkcs8', 'spki' или 'jwk'.
• wrappedKey <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
• unwrappingKey <CryptoKey>

• unwrapAlgo <string> | <Algorithm> | <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>
• unwrappedKeyAlgo <string> | <Algorithm> | <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)

• algorithm <string> | <Algorithm> | <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)

• format <string> Должно быть одним из 'raw', 'pkcs8', 'spki' или 'jwk'.
• key <CryptoKey>
• wrappingKey <CryptoKey>
• wrapAlgo <string> | <Algorithm> | <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'

Класс: Algorithm

Класс: AesDerivedKeyParams

Класс: AesCbcParams

Класс: AesCtrParams

Класс: AesGcmParams

Класс: AesKeyAlgorithm

Класс: AesKeyGenParams

Класс: EcdhKeyDeriveParams

Класс: EcdsaParams

Класс: EcKeyAlgorithm

Класс: EcKeyGenParams

Класс: EcKeyImportParams

Класс: Ed448Params

Класс: HkdfParams

Класс: HmacImportParams

Класс: HmacKeyAlgorithm

Класс: HmacKeyGenParams

Класс: KeyAlgorithm

Класс: Pbkdf2Params

Класс: RsaHashedImportParams

Класс: RsaHashedKeyAlgorithm

Класс: RsaHashedKeyGenParams

Класс: RsaOaepParams

Класс: RsaPssParams