The Web Crypto API

Use the built-in crypto tools, not your own

Cryptography is the maths that keeps data secret and stops anyone from changing it unseen. Web Crypto is a set of cryptography tools built into every browser and into Node.js. Experts wrote and tested these tools. Use them. Do not invent your own.

Web Crypto works on bytes. A byte is a whole number from 0 to 255. You keep bytes in a typed array, such as a Uint8Array. The Typed arrays lesson explains them. To turn text into bytes, you use TextEncoder from Text encoding.

Most Web Crypto tools take a moment to finish. So they return a promise: a value that arrives later. You wait for it with await. See Promises and async/await if that is new.

With Web Crypto, front-end code can:

• make secure random values;
• make a hash, a short summary that changes when the data changes;
• check that a message came from the right sender and was not changed;
• encrypt data (hide it) and decrypt it (unhide it);
• sign data and check signatures;
• import and export keys.

These five tools are easy to mix up. Each row of the table says what one tool does, and what it does not do.

Where you will meet these tools on the site:

• CSRF, cookies & tokens makes random tokens and hashes a login secret.
• Supply-chain security uses hashes to check that a downloaded file was not changed.
• IndexedDB can store keys whose bytes no code can read. You will see this near the end.
• Web Storage is a bad place for keys and long-lived login tokens.

Random values are the first place where front-end code often goes wrong. Math.random() is fine for animations and games. It is not safe for secrets, because an attacker can work out its next values. So never use Math.random() for:

• login tokens or session IDs;
• password reset links;
• CSRF tokens;
• PKCE verifiers, the random secret an app sends when you log in with another site;
• encryption keys;
• any ID that an attacker must not guess.

Web Crypto has two safe tools instead:

• crypto.randomUUID() makes a random ID in the standard UUID format: 36 characters in five groups, such as 3b241101-e2bb-4255-8caf-4136c566a962.
• crypto.getRandomValues(array) fills a typed array with random bytes. You can turn the bytes into a token or a key.

1const requestId = crypto.randomUUID();2const tokenBytes = crypto.getRandomValues(new Uint8Array(16));3console.log(requestId.split("-")[2][0]);4console.log(tokenBytes.byteLength);

Line 1 makes a UUID. Line 2 makes 16 random bytes. Line 3 prints the first character of the UUID's third group. It is always 4, because this kind of UUID is called version 4. Line 4 prints 16, the number of bytes.

The bytes are not text yet. The next example turns them into a token you can send or store.

1function bytesToHex(bytes) {2  return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");3}4 5function randomToken(byteLength = 16, cryptoImpl = crypto) {6  const bytes = new Uint8Array(byteLength);7  cryptoImpl.getRandomValues(bytes);8  return bytesToHex(bytes);9}10 11const fixedCrypto = {12  getRandomValues(bytes) {13    bytes.set([0xde, 0xad, 0xbe, 0xef].slice(0, bytes.length));14    return bytes;15  },16};17 18console.log(randomToken(4, fixedCrypto));19console.log(randomToken(16).length);20console.log("differs every run");

In plain words:

• Lines 1 to 3: bytesToHex writes each byte as two hex characters. Hex uses the digits 0 to 9 and the letters a to f.
• Line 5: randomToken takes a length and a random source. The source is crypto unless you pass another one.
• Line 6 makes an array of empty bytes. Line 7 fills it with random bytes.
• Lines 11 to 16: fixedCrypto is a fake source. It always gives the bytes de, ad, be, ef, so tests always get the same output.
• Line 18 uses the fake source and prints deadbeef.
• Line 19 uses the real crypto and prints 32: 16 bytes become 32 hex characters. The token itself is different on every run.

What matters is that nobody can guess the token. The hex format is only there so you can read it.

1const uuid = crypto.randomUUID();2const v4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;3console.log(v4.test(uuid));4console.log(uuid.slice(14, 15));5console.log("differs every run");

A version 4 UUID has two fixed spots. The third group starts with 4. The fourth group starts with 8, 9, a, or b. The regular expression on line 2 checks exactly that.

The UUID is different on every run. So line 3 checks its shape instead of comparing it with one fixed string, and prints true. Line 4 prints the 15th character, which is the 4.

One call to getRandomValues can fill at most 65,536 bytes. Line 1 below fills exactly 65,536 bytes, which works. Line 3 asks for one byte more, so it throws an error. Lines 5 and 6 print the error's name and message. If you need more bytes, fill them in smaller pieces.

1console.log("65536 bytes", crypto.getRandomValues(new Uint8Array(65536)).length);2try {3  crypto.getRandomValues(new Uint8Array(65537));4} catch (error) {5  console.log(error.name);6  console.log(error.message);7}

Say you want a fair random whole number from 0 to 9. A 32-bit random sample is a number from 0 to 4,294,967,295. That makes 2³² = 4,294,967,296 possible samples.

A common idea is sample % 10: the remainder after dividing by 10. But 4,294,967,296 does not divide evenly by 10. So the results 0 to 5 each come from one more sample than the results 6 to 9. They turn up a tiny bit more often. This unfairness is called bias.

Rejection sampling removes the bias. The code sets a limit: the biggest multiple of 10 that fits, 4,294,967,290. Any sample at or above the limit is thrown away, and the code draws again. Only 6 of the 4,294,967,296 samples are ever thrown away.

Step through the code below. It uses a fake random source, so the draws are always the same: first 4,294,967,294, then 8.

1function randomInt(max, source = crypto) {Run2  const range = 0x100000000;3  const limit = Math.floor(range / max) * max;4  const sample = new Uint32Array(1);5  do {6    source.getRandomValues(sample);7  } while (sample[0] >= limit);8  return sample[0] % max;9}10 11const fake = {12  getRandomValues(array) {13    array[0] = array[0] === 0 ? 4294967294 : 8;14    return array;15  },16};17 18console.log(randomInt(10, fake));

The two cards below count how many samples lead to each result.

A hash function turns any data into a short result of a fixed size. The result is called a digest. A hash function is:

• the same every time: the same bytes always give the same digest;
• one-way: you cannot get the data back from the digest;
• fixed in size: SHA-256 always gives 32 bytes, for one letter or a huge file.

To hash text, take three steps:

1. Turn the text into bytes with TextEncoder.
2. Hash the bytes with crypto.subtle.digest, and await the result.
3. Write the digest as hex, so you can read it.

You met hex and other ways to show bytes in Text encoding & Base64.

1async function sha256Hex(message) {2  const bytes = new TextEncoder().encode(message);3  const digest = await crypto.subtle.digest("SHA-256", bytes);4  return [...new Uint8Array(digest)]5    .map((byte) => byte.toString(16).padStart(2, "0"))6    .join("");7}8 9sha256Hex("abc").then(console.log);

Line 2 turns the text into bytes. Line 3 hashes the bytes. Lines 4 to 6 write each byte as two hex characters. Line 9 hashes "abc" and prints the digest.

The SHA-256 digest of "abc" is a well-known test answer: ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad. If your code prints anything else, the bytes or the hex step are wrong.

Try it below. Change one letter in a message, and count how many hex characters of its digest change.

1async function sha256Hex(message) {2  const bytes = new TextEncoder().encode(message);3  const digest = await crypto.subtle.digest("SHA-256", bytes);4  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");5}

Hashes are useful for:

• Subresource Integrity: the browser checks that a downloaded script was not changed;
• cache keys: a short name for a piece of content;
• comparing content without storing the content itself.

A hash is not encryption. There is no way to turn a digest back into the data.

A plain hash tells you that the bytes match. It does not tell you who made the hash, because anyone can hash anything. HMAC mixes a secret key into the hash. Only someone who knows the secret can make the right result. Web Crypto calls that result a signature.

When an HMAC signature checks out, you know two things:

• the message came from someone who knows the secret;
• nobody changed the message on the way.

Webhooks often use HMAC. A webhook is a message that one server sends to another, such as a payment service telling your server that a payment went through.

1async function hmacHex(message, secret) {2  const encoder = new TextEncoder();3  const key = await crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign", "verify"]);4  const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(message));5  return [...new Uint8Array(signature)].map((byte) => byte.toString(16).padStart(2, "0")).join("");6}7 8async function verifyHmac(message, secret, hex) {9  const encoder = new TextEncoder();10  const key = await crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);11  const signature = Uint8Array.from(hex.match(/../g), (pair) => parseInt(pair, 16));12  return crypto.subtle.verify("HMAC", key, signature, encoder.encode(message));13}14 15(async () => {16  const message = "The quick brown fox jumps over the lazy dog";17  const signature = await hmacHex(message, "key");18  console.log(signature);19  console.log(await verifyHmac(message, "key", signature));20  console.log(await verifyHmac(message + "!", "key", signature));21})();

In plain words:

• Line 3 turns the secret text "key" into a CryptoKey, the object Web Crypto uses for keys.
• Line 4 signs the message. Line 5 writes the signature as hex.
• Line 11 turns the hex back into bytes. Line 12 checks the signature against the message.
• Line 18 prints the signature.
• Line 19 prints true, because the message is the original.
• Line 20 prints false, because one ! was added to the message.

Let crypto.subtle.verify do the check. Do not compare signature strings yourself. HMAC proves who sent a message, but it does not hide it. Anyone can still read the message.

Passwords need a different tool. Do not store SHA-256(password). SHA-256 is built to be fast. That helps attackers: they can try billions of guesses per second.

Instead, hash passwords on the server with a slow password hash, such as Argon2id, bcrypt, or scrypt. Web Crypto has two key derivation functions (KDFs): tools that turn a password or a secret into a key. They are PBKDF2 and HKDF.

PBKDF2 is slow on purpose: it repeats its work many times. Each repeat is called an iteration. If you must use PBKDF2 with SHA-256, OWASP (a web security project) says to use 600,000 iterations or more in new apps. The examples below use only 1,000 iterations, so they finish quickly in your browser.

A salt is a random value mixed in with the password. It makes each result different, even for two people with the same password. A salt is not secret. Make a new salt for each password or each encrypted record. Store it next to the result, together with the settings you used.

1async function deriveDemoKey(password, salt, iterations = 1000) {2  const encoder = new TextEncoder();3  const baseKey = await crypto.subtle.importKey("raw", encoder.encode(password), "PBKDF2", false, ["deriveBits"]);4  const bits = await crypto.subtle.deriveBits(5    { name: "PBKDF2", hash: "SHA-256", salt: encoder.encode(salt), iterations },6    baseKey,7    256,8  );9  return [...new Uint8Array(bits)].map((byte) => byte.toString(16).padStart(2, "0")).join("");10}11 12deriveDemoKey("correct horse battery staple", "demo-salt", 1000).then((hex) => {13  console.log(hex);14  console.log("demo iterations only");15});

Line 3 turns the password into a CryptoKey. Lines 4 to 8 derive 256 bits (32 bytes) from it. Line 5 passes in the salt and the iteration count. Line 12 runs it with 1,000 iterations. Line 13 prints the result as hex. Line 14 prints a reminder that 1,000 is only for the demo.

The next example turns a password into an AES key for encryption. The key is non-extractable: code can use it, but can never read its bytes.

1async function deriveAesKey(password) {2  const salt = crypto.getRandomValues(new Uint8Array(16));3  const passwordBytes = new TextEncoder().encode(password);4  const passwordKey = await crypto.subtle.importKey("raw", passwordBytes, "PBKDF2", false, ["deriveKey"]);5  const key = await crypto.subtle.deriveKey(6    { name: "PBKDF2", hash: "SHA-256", salt, iterations: 1000 },7    passwordKey,8    { name: "AES-GCM", length: 256 },9    false,10    ["encrypt", "decrypt"],11  );12  return { salt, key };13}14 15deriveAesKey("tea").then(({ salt, key }) => {16  console.log(salt.byteLength);17  console.log(key.algorithm.name);18  console.log("store salt with encrypted data");19});

Line 2 makes a new 16-byte salt. Line 4 turns the password into a CryptoKey. Lines 5 to 7 derive the AES key from it, using the salt. Line 9, false, makes the key non-extractable.

The code prints 16 (the salt size), then AES-GCM (the key's algorithm), then a reminder: store the salt openly next to the encrypted data. Do not use this for login passwords. Hash those on the server with a password-hashing library.

AES-GCM is the main Web Crypto tool for encryption. It uses one shared key to both encrypt and decrypt. A few words you will see:

• plaintext: the readable message.
• ciphertext: the scrambled bytes you get after encrypting.
• IV (initialization vector): 12 bytes you pick for each message. It is not secret, but it must be new for every message you encrypt with the same key.
• tag: 16 bytes that AES-GCM adds to the end of the ciphertext. Decrypt uses the tag to check that nothing was changed.

Never use the same IV twice with the same key. That can leak the messages, and it lets attackers change them without being caught. Store the IV next to the ciphertext.

The step-through below uses a fixed key and IV, so it gives the same output every time. Never reuse those demo bytes in real code.

1async function aesGcmDemo() {2  const keyBytes = new Uint8Array([...Array(32).keys()]);Run3  const iv = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]);4  const key = await crypto.subtle.importKey("raw", keyBytes, "AES-GCM", false, ["encrypt", "decrypt"]);5  const encoded = new TextEncoder().encode("meet at noon");6  const ciphertext = await crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, encoded);7  const plaintext = await crypto.subtle.decrypt({ name: "AES-GCM", iv }, key, ciphertext);8  const hex = [...new Uint8Array(ciphertext)].map((byte) => byte.toString(16).padStart(2, "0")).join("");9  console.log(hex);10  console.log(new TextDecoder().decode(plaintext));11}12 13aesGcmDemo();

The playground below keeps one key and makes a new random IV each time you click Encrypt. Random IVs make a repeat very unlikely, but not impossible. So limit how many messages one key encrypts, and then switch to a new key.

1async function encryptMessage(text, key) {2  const activeKey = key ?? await crypto.subtle.generateKey({ name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]);3  const iv = crypto.getRandomValues(new Uint8Array(12));4  const ciphertext = await crypto.subtle.encrypt({ name: "AES-GCM", iv }, activeKey, new TextEncoder().encode(text));5  return { key: activeKey, iv, ciphertext: new Uint8Array(ciphertext) };6}7 8async function decryptMessage(record) {9  const bytes = await crypto.subtle.decrypt({ name: "AES-GCM", iv: record.iv }, record.key, record.ciphertext);10  return new TextDecoder().decode(bytes);11}

When the last byte is changed, decrypt rejects with OperationError. That error is the safety check doing its job. Do not catch it and carry on as if the text were fine.

AES-GCM uses one shared key. Two other tools use a key pair instead: a public key you can share, and a private key you keep.

• RSA-OAEP can encrypt small secrets, such as a random AES key.
• ECDH lets two sides agree on a shared secret. You then pass that secret to a KDF to make a key.

Real systems usually use these two only to share or agree on an AES key. AES-GCM then encrypts the actual data.

Encryption hides a message. Signing does something else: it proves who approved the message. A signature uses a key pair:

• the private key belongs only to the author, and makes the signature;
• the public key can go to anyone, and checks the signature.

The message itself can stay public.

ECDSA with the P-256 curve works wherever Web Crypto works. Ed25519 is a newer way to sign. Chrome 154 and Node 22.23.1 support it, but older browsers may not. So your code should first check that it works. This check is called feature detection.

1async function supportsEd25519() {2  try {3    const pair = await crypto.subtle.generateKey({ name: "Ed25519" }, true, ["sign", "verify"]);4    const message = new TextEncoder().encode("hello");5    const signature = await crypto.subtle.sign({ name: "Ed25519" }, pair.privateKey, message);6    const ok = await crypto.subtle.verify({ name: "Ed25519" }, pair.publicKey, signature, message);7    return ok && signature.byteLength === 64;8  } catch {9    return false;10  }11}12 13async function ecdsaDemo() {14  const message = new TextEncoder().encode("ship release 42");15  const pair = await crypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, true, ["sign", "verify"]);16  const signature = await crypto.subtle.sign({ name: "ECDSA", hash: "SHA-256" }, pair.privateKey, message);17  console.log(await supportsEd25519());18  console.log(await crypto.subtle.verify({ name: "ECDSA", hash: "SHA-256" }, pair.publicKey, signature, message));19  console.log(await crypto.subtle.verify({ name: "ECDSA", hash: "SHA-256" }, pair.publicKey, signature, new TextEncoder().encode("ship release 43")));20}21 22ecdsaDemo();

In plain words:

• Lines 1 to 11: supportsEd25519 tries to make an Ed25519 key pair (line 3), sign (line 5), and verify (line 6). If any step throws, it returns false.
• Line 15 makes an ECDSA key pair. Line 16 signs "ship release 42" with the private key.
• Line 17 prints true when Ed25519 works.
• Line 18 prints true: the public key confirms the signature.
• Line 19 prints false: the message changed to "ship release 43".

With signatures, anyone can check package files, update lists, or approvals without knowing a secret. A signature does not hide the message. If the message is private, encrypt it as well.

Web Crypto does not usually give you a key's raw bytes. It gives you a CryptoKey object. A CryptoKey has these properties:

• type: secret for a shared key, or public or private for one half of a key pair.
• extractable: true if code may export (read out) the key's bytes.
• algorithm: which tool the key is for, such as AES-GCM.
• usages: what the key may do, such as encrypt or verify.

These properties keep you safe. A key made only for verify cannot sign. A non-extractable key cannot be exported as bytes.

1async function inspectKeys() {2  const aesKey = await crypto.subtle.generateKey({ name: "AES-GCM", length: 256 }, true, ["encrypt", "decrypt"]);3  console.log(aesKey.type + " " + aesKey.extractable + " " + aesKey.usages.join(","));4  console.log((await crypto.subtle.exportKey("raw", aesKey)).byteLength);5  console.log((await crypto.subtle.exportKey("jwk", aesKey)).kty);6 7  const pair = await crypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, true, ["sign", "verify"]);8  console.log((await crypto.subtle.exportKey("spki", pair.publicKey)).byteLength > 0);9  console.log((await crypto.subtle.exportKey("pkcs8", pair.privateKey)).byteLength > 0);10}11 12inspectKeys();

In plain words:

• Line 2 makes an AES key that can be exported.
• Line 3 prints secret true encrypt,decrypt.
• Line 4 exports the key as raw bytes and prints 32.
• Line 5 exports it as a JSON Web Key and prints its kind, oct, which means a shared key.
• Line 7 makes an ECDSA key pair.
• Lines 8 and 9 export the public key and the private key. Both print true, because both exports hold bytes.

Each row of the table is one way to hold or export a key: its name, what it holds, and when to use it.

A key that cannot be exported can still be saved. IndexedDB, the browser's database, can store the CryptoKey object itself. Your page code never sees the raw bytes. That is safer than putting key bytes in localStorage.

The code below is only a sketch, so it has no Run button. A real app needs its own IndexedDB setup.

1async function makeStoredKey() {2  const key = await crypto.subtle.generateKey(3    { name: "AES-GCM", length: 256 },4    false,5    ["encrypt", "decrypt"],6  );7  // Store the non-extractable CryptoKey object itself, not raw key bytes.8  const db = await openIndexedDbSomewhere();9  await db.put("keys", key, "message-key");10  return key.extractable;11}

Line 4, false, makes the key non-extractable. Lines 8 and 9 open a database and save the key object. openIndexedDbSomewhere stands in for your own database code.

If you do export a key, pick the format by the kind of key:

• raw for the bytes of a shared key;
• jwk for a JSON Web Key;
• spki for a public key;
• pkcs8 for a private key.

Exporting a private key should be rare. Encrypt it when you store it, and keep it out of normal page code when you can.

What not to do

• Do not write your own crypto. Use the tested tools and standard ways of combining them.
• Do not use ECB mode. ECB is an old AES mode that leaves patterns in the data visible. Web Crypto does not offer it; use AES-GCM.
• Do not reuse an AES-GCM IV with the same key. Make a new 12-byte IV for each message.
• Do not store keys in localStorage. In an XSS attack, an attacker's script runs in your page and can read it. Use non-extractable keys in IndexedDB, or keep keys on the server.
• Do not mix up encoding, hashing, encryption, and signing. Each one answers a different question.

Each row of the table is one common mistake, why it is wrong, and what to do instead.

Key takeaways

• Use crypto.getRandomValues and crypto.randomUUID for anything an attacker must not guess. Never use Math.random for secrets.
• For a fair random number in a range, throw away draws at or above the limit before you use %.
• crypto.subtle works on bytes and returns promises. Turn text into bytes before you hash, sign, or encrypt it.
• SHA-256 always gives the same 32 bytes for the same data, and you cannot undo it. HMAC adds a secret key, so it also proves who sent the message.
• Never store plain SHA-256 password hashes. Hash passwords slowly on the server. The 1,000 PBKDF2 iterations here are only for quick demos.
• AES-GCM needs a new 12-byte IV for each message with the same key. If anything was changed, decrypt must fail.
• A CryptoKey says what it is for and whether its bytes can be read out. Pick the export format by the kind of key.
• Keep keys out of storage that page scripts can read. Use non-extractable keys in IndexedDB, or keep keys on the server.

Final definition: Web Crypto gives JavaScript tested tools for random bytes, hashes, HMAC, encryption, signatures, key derivation, and keys. Your job is to pick the right tool, give it bytes, and follow the rules for keys and IVs.

Up next: Measuring performance. There you move from keeping users safe to finding out which code is slow.