SubtleCrypto: метод encrypt()

Метод encrypt() интерфейса SubtleCrypto шифрует данные.

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

algorithm

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

• Для использования RSA-OAEP, передайте объект RsaOaepParams.
• Для использования AES-CTR, передайте объект AesCtrParams.
• Для использования AES-CBC, передайте объект AesCbcParams.
• Для использования AES-GCM, передайте объект AesGcmParams.

key

CryptoKey, содержащий ключ, который будет использоваться для шифрования.

data

ArrayBuffer, TypedArray или DataView, содержащие данные, которые нужно зашифровать (также известные как «открытый текст»).

Объект Promise, который выполнится с ArrayBuffer, содержащим «зашифрованный текст».

Обещание отклоняется при возникновении следующих исключений:

InvalidAccessError DOMException

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

OperationError DOMException

Возникает, когда операция не удалась по причине, специфичной для операции (например, параметры алгоритма неверных размеров или открытый текст AES-GCM длиннее, чем 2³⁹−256 байт).

API Web Crypto предоставляет четыре алгоритма, которые поддерживают операции encrypt() и decrypt().

Один из этих алгоритмов — RSA-OAEP — является криптосистемой с открытым ключом.

Три других алгоритма шифрования — симметричные алгоритмы, и все они основаны на том же базовом шифре AES (Advanced Encryption Standard). Разница между ними заключается в режиме. API Web Crypto поддерживает три различных режима AES:

• CTR (Режим счетчика)
• CBC (Режим цепочки блоков)
• GCM (Режим Галоа/счетчика)

Настоятельно рекомендуется использовать аутентифицированное шифрование, которое включает проверки, что зашифрованный текст не был изменён злоумышленником. Аутентификация помогает защитить от атак с выбором зашифрованного текста, в которых злоумышленник может попросить систему расшифровать произвольные сообщения и использовать результат для получения информации о секретном ключе. Хотя можно добавить аутентификацию к режимам CTR и CBC, они по умолчанию её не предоставляют, и при ручном её внедрении можно легко допустить небольшие, но серьёзные ошибки. Режим GCM предоставляет встроенную аутентификацию, и по этой причине он часто рекомендуется вместо других двух режимов AES.

Система шифрования с открытым ключом RSA-OAEP определена в RFC 3447.

Это AES в режиме счетчика, как определено в NIST SP800-38A.

AES — это блочный шифр, то есть он разбивает сообщение на блоки и шифрует его по блокам. В режиме CTR каждый раз, когда блок сообщения шифруется, смешивается дополнительный блок данных. Этот дополнительный блок называется «блок счетчика».

Значение блока счетчика не должно использоваться более одного раза с тем же ключом:

• Для сообщения длиной n блоков должен использоваться другой блок счетчика для каждого блока.
• Если один и тот же ключ используется для шифрования более одного сообщения, должен использоваться другой блок счетчика для всех блоков во всех сообщениях.

Обычно это достигается путём разделения начального значения блока счётчика на две конкатенированные части:

• Nonce (то есть число, которое может быть использовано только один раз). Часть nonce в блоке остается неизменной для каждого блока в сообщении. Каждый раз при шифровании нового сообщения выбирается новый nonce. Nonces не обязательно должны быть секретными, но они не должны повторно использоваться с одним и тем же ключом.
• Счетчик. Эта часть блока инкрементируется каждый раз, когда шифруется блок.

По существу: nonce должен гарантировать, что блоки счетчика не будут повторно использоваться из одного сообщения в другое, а счетчик — что блоки счетчика не будут повторно использоваться в одном сообщении.

Это AES в режиме цепочки блоков, как определено в NIST SP800-38A.

Это AES в режиме Галоа/счетчика, как определено в NIST SP800-38D.

Основное отличие этого режима от других заключается в том, что GCM является «аутентифицированным» режимом, то есть он включает проверки, что зашифрованный текст не был изменён злоумышленником.

Этот код получает содержимое текстового поля, кодирует его для шифрования и шифрует с помощью RSA-OAEP. См. полный код на GitHub.

function getMessageEncoding() {
  const messageBox = document.querySelector(".rsa-oaep #message");
  let message = messageBox.value;
  let enc = new TextEncoder();
  return enc.encode(message);
}

function encryptMessage(publicKey) {
  let encoded = getMessageEncoding();
  return window.crypto.subtle.encrypt(
    {
      name: "RSA-OAEP",
    },
    publicKey,
    encoded,
  );
}

Этот код получает содержимое текстового поля, кодирует его для шифрования и шифрует с использованием AES в режиме CTR. См. полный код на GitHub.

function getMessageEncoding() {
  const messageBox = document.querySelector(".aes-ctr #message");
  let message = messageBox.value;
  let enc = new TextEncoder();
  return enc.encode(message);
}

function encryptMessage(key) {
  let encoded = getMessageEncoding();
  // counter will be needed for decryption
  counter = window.crypto.getRandomValues(new Uint8Array(16));
  return window.crypto.subtle.encrypt(
    {
      name: "AES-CTR",
      counter,
      length: 64,
    },
    key,
    encoded,
  );
}

let iv = window.crypto.getRandomValues(new Uint8Array(16));
let key = window.crypto.getRandomValues(new Uint8Array(16));
let data = new Uint8Array(12345);
// crypto functions are wrapped in promises so we have to use await and make sure the function that
// contains this code is an async function
// encrypt function wants a cryptokey object
const key_encoded = await window.crypto.subtle.importKey(
  "raw",
  key.buffer,
  "AES-CTR",
  false,
  ["encrypt", "decrypt"],
);
const encrypted_content = await window.crypto.subtle.encrypt(
  {
    name: "AES-CTR",
    counter: iv,
    length: 128,
  },
  key_encoded,
  data,
);

// Uint8Array
console.log(encrypted_content);

Этот код получает содержимое текстового поля, кодирует его для шифрования и шифрует с использованием AES в режиме CBC. См. полный код на GitHub.

function getMessageEncoding() {
  const messageBox = document.querySelector(".aes-cbc #message");
  let message = messageBox.value;
  let enc = new TextEncoder();
  return enc.encode(message);
}

function encryptMessage(key) {
  let encoded = getMessageEncoding();
  // iv will be needed for decryption
  iv = window.crypto.getRandomValues(new Uint8Array(16));
  return window.crypto.subtle.encrypt(
    {
      name: "AES-CBC",
      iv: iv,
    },
    key,
    encoded,
  );
}

Этот код получает содержимое текстового поля, кодирует его для шифрования и шифрует с использованием AES в режиме GCM. См. полный код на GitHub.

function getMessageEncoding() {
  const messageBox = document.querySelector(".aes-gcm #message");
  const message = messageBox.value;
  const enc = new TextEncoder();
  return enc.encode(message);
}

function encryptMessage(key) {
  const encoded = getMessageEncoding();
  // iv will be needed for decryption
  const iv = window.crypto.getRandomValues(new Uint8Array(12));
  return window.crypto.subtle.encrypt(
    { name: "AES-GCM", iv: iv },
    key,
    encoded,
  );
}

• SubtleCrypto.decrypt().
• RFC 3447 определяет RSAOAEP.
• NIST SP800-38A определяет режим CTR.
• NIST SP800-38A определяет режим CBC.
• NIST SP800-38D определяет режим GCM.