INTEGRITY Документация

← Cloudflare Workers / workers / runtime-apis

Web Crypto

Контекст

Web Crypto API предоставляет набор низкоуровневых функций для типовых криптографических задач. Среда выполнения Workers реализует этот API полностью, но с некоторыми отличиями в поддерживаемые алгоритмы по сравнению с теми, что реализованы в большинстве браузеров.

Выполнение криптографических операций через Web Crypto API значительно быстрее, чем их выполнение исключительно на JavaScript. Если вам нужны криптографические операции с высокой нагрузкой на CPU, используйте для этого Web Crypto API.

Web Crypto API реализован через SubtleCrypto интерфейс, доступный через глобальный crypto.subtle привязку. Простой пример вычисления дайджеста (также известного как хеш):

const myText = new TextEncoder().encode('Hello world!');

const myDigest = await crypto.subtle.digest(
  {
    name: 'SHA-256',
  },
  myText // The data you want to hash as an ArrayBuffer
);

console.log(new Uint8Array(myDigest));

К распространённым сценариям использования относятся подписание запросов.

Конструкторы

Параметры

Использование

export default {
  async fetch(req) {
    // Fetch from origin
    const res = await fetch(req);

    // We need to read the body twice so we `tee` it (get two instances)
    const [bodyOne, bodyTwo] = res.body.tee();
    // Make a new response so we can set the headers (responses from `fetch` are immutable)
    const newRes = new Response(bodyOne, res);
    // Create a SHA-256 digest stream and pipe the body into it
    const digestStream = new crypto.DigestStream("SHA-256");
    bodyTwo.pipeTo(digestStream);
    // Get the final result
    const digest = await digestStream.digest;
    // Turn it into a hex string
    const hexString = [...new Uint8Array(digest)]
      .map(b => b.toString(16).padStart(2, '0'))
      .join('')
    // Set a header with the SHA-256 hash and return the response
    newRes.headers.set("x-content-digest", `SHA-256=${hexString}`);
    return newRes;
  }
}
export default {
  async fetch(req): Promise<Response> {
    // Fetch from origin
    const res = await fetch(req);

    // We need to read the body twice so we `tee` it (get two instances)
    const [bodyOne, bodyTwo] = res.body.tee();
    // Make a new response so we can set the headers (responses from `fetch` are immutable)
    const newRes = new Response(bodyOne, res);
    // Create a SHA-256 digest stream and pipe the body into it
    const digestStream = new crypto.DigestStream("SHA-256");
    bodyTwo.pipeTo(digestStream);
    // Get the final result
    const digest = await digestStream.digest;
    // Turn it into a hex string
    const hexString = [...new Uint8Array(digest)]
      .map(b => b.toString(16).padStart(2, '0'))
      .join('')
    // Set a header with the SHA-256 hash and return the response
    newRes.headers.set("x-content-digest", `SHA-256=${hexString}`);
    return newRes;
  }
} satisfies ExportedHandler;

Методы

Параметры

Методы SubtleCrypto

Доступ ко всем этим методам осуществляется через crypto.subtle ↗, который также подробно описан на MDN.

encrypt

Параметры

decrypt

Параметры

подписать

Параметры

подтвердить

Параметры

digest

Параметры

generateKey

Параметры

deriveKey

Параметры

deriveBits

Параметры

importKey

Параметры

exportKey

Параметры

wrapKey

Параметры

unwrapKey

Параметры

timingSafeEqual

Параметры

Поддерживаемые алгоритмы

Workers реализует все операции Стандарт WebCrypto ↗, как показано в следующей таблице.

Галочка (✓) означает, что данная функция считается полностью поддерживаемой согласно спецификации.
Значок x (✘) означает, что эта функция входит в спецификацию, но не реализована.
Если функция реализует операцию лишь частично, подробности указаны ниже.

Алгоритм sign()
verify()		 encrypt()
decrypt()		 digest() deriveBits()
deriveKey()		 generateKey() wrapKey()
unwrapKey()		 exportKey() importKey()
RSASSA PKCS1 v1.5 ✓ ✓ ✓ ✓
RSA PSS ✓ ✓ ✓ ✓
RSA OAEP ✓ ✓ ✓ ✓ ✓
ECDSA ✓ ✓ ✓ ✓
ECDH ✓ ✓ ✓ ✓
Ed255191 ✓ ✓ ✓ ✓
X255191 ✓ ✓ ✓ ✓
NODE ED255192 ✓ ✓ ✓ ✓
AES CTR ✓ ✓ ✓ ✓ ✓
AES CBC ✓ ✓ ✓ ✓ ✓
AES GCM ✓ ✓ ✓ ✓ ✓
AES KW ✓ ✓ ✓ ✓
HMAC ✓ ✓ ✓ ✓
SHA 1 ✓
SHA 256 ✓
SHA 384 ✓
SHA 512 ✓
MD53 ✓
HKDF ✓ ✓
PBKDF2 ✓ ✓

Сноски:

  1. Алгоритмы, указанные в Secure Curves API ↗.

  2. Устаревшая нестандартная реализация EdDSA поддерживается для кривой Ed25519 в дополнение к версии Secure Curves. Поскольку этот алгоритм нестандартный, при его использовании учитывайте следующее:

    • Используйте NODE-ED25519 в качестве алгоритма и namedCurve параметры.
    • В отличие от NodeJS, Cloudflare не поддерживает прямой импорт приватных ключей.
    • Реализация алгоритма может со временем меняться. Хотя Cloudflare не может гарантировать это на данный момент, компания будет стремиться сохранять обратную совместимость и совместимость с поведением NodeJS. О значимых изменениях совместимости будет сообщаться в примечаниях к выпуску и в этой документации для разработчиков.

  3. MD5 не входит в стандарт WebCrypto, но поддерживается в Cloudflare Workers для взаимодействия с устаревшими системами, которым требуется MD5. MD5 считается слабым алгоритмом. Не полагайтесь на MD5 для обеспечения безопасности.