INTEGRITY Dokumentace

← Cloudflare Workers / workers / runtime-apis

Web Crypto

Kontext

Web Crypto API poskytuje sadu nízkoúrovňových funkcí pro běžné kryptografické úlohy. Workers runtime implementuje celý rozsah tohoto API, avšak s určitými rozdíly v podporované algoritmy ve srovnání s těmi, které jsou implementovány ve většině prohlížečů.

Kryptografické operace prováděné pomocí rozhraní Web Crypto API jsou výrazně rychlejší než jejich provádění čistě v JavaScriptu. Pokud potřebujete provádět výpočetně náročné kryptografické operace, zvažte použití rozhraní Web Crypto API.

Web Crypto API je implementované prostřednictvím SubtleCrypto rozhraní, dostupné přes globální crypto.subtle binding. Jednoduchý příklad výpočtu otisku (také nazývaného hash) vypadá takto:

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

Mezi běžná využití patří podepisování požadavků.

Konstruktory

Parametry

Použití

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;

Metody

Parametry

Metody SubtleCrypto

Ke všem těmto metodám se přistupuje přes crypto.subtle ↗, což je rovněž podrobně zdokumentováno na MDN.

šifrovat

Parametry

decrypt

Parametry

podepsat

Parametry

ověřit

Parametry

digest

Parametry

generateKey

Parametry

deriveKey

Parametry

deriveBits

Parametry

importKey

Parametry

exportKey

Parametry

wrapKey

Parametry

unwrapKey

Parametry

timingSafeEqual

Parametry

Podporované algoritmy

Workers implementuje všechny operace Standard WebCrypto ↗, jak ukazuje následující tabulka.

Zaškrtnutí (✓) znamená, že tato funkce je podle specifikace považována za plně podporovanou.
Znak x (✘) znamená, že tato funkce je součástí specifikace, ale není implementována.
Pokud funkce implementuje operaci pouze částečně, jsou uvedeny podrobnosti.

Algoritmus 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 ✓ ✓

Poznámky pod čarou:

  1. algoritmy podle specifikace v Secure Curves API ↗.

  2. Vedle verze Secure Curves je podporována i zastaralá nestandardní varianta EdDSA pro křivku Ed25519. Vzhledem k tomu, že tento algoritmus není standardní, mějte při jeho používání na paměti následující:

    • Použijte NODE-ED25519 jako algoritmus a namedCurve parametry.
    • Na rozdíl od NodeJS nebude Cloudflare podporovat přímý import privátních klíčů.
    • Implementace algoritmu se může časem měnit. Cloudflare to v tuto chvíli nemůže zaručit, bude se však snažit zachovat zpětnou kompatibilitu i soulad s chováním NodeJS. Veškeré významné poznámky ke kompatibilitě budou uvedeny v poznámkách k vydání a v této dokumentaci pro vývojáře.

  3. MD5 není součástí standardu WebCrypto, ale je v Cloudflare Workers podporován pro komunikaci se staršími systémy, které MD5 vyžadují. MD5 je považován za slabý algoritmus. Nespoléhejte se na MD5 z hlediska zabezpečení.