Subtle (WebCrypto)

The SubtleCrypto interface allows you to perform cryptographic operations using the standardized W3C Web Cryptography API.

Theory
Module Methods
Real-World Examples

Theory

The WebCrypto API differs from the Node.js API in two main ways:

Asynchronous Promises: All operations (encrypt, verify, etc.) return Promises. This reflects the intense nature of crypto operations and prevents UI blocking.
Unextractable Keys: A CryptoKey object is a handle to a key. If marked extractable: false, the raw key bytes can never be accessed by JavaScript code, protecting it from XSS attacks.

Module Methods

encrypt(algorithm, key, data)

Encrypts data.

Parameters:

Prop

Type

decrypt(algorithm, key, data)

Decrypts data.

sign(algorithm, key, data)

Generates a digital signature.

verify(algorithm, key, signature, data)

Verifies a digital signature. Returns true or false.

digest(algorithm, data)

Generates a hash digest (e.g., SHA-256).

generateKey(algorithm, extractable, keyUsages)

Generates a new key or key pair.

Example (RSA-OAEP):

const keyPair = await subtle.generateKey(
  {
    name: "RSA-OAEP",
    modulusLength: 4096,
    publicExponent: new Uint8Array([1, 0, 1]),
    hash: "SHA-256"
  },
  true,
  ["encrypt", "decrypt"]
);

importKey(format, keyData, algorithm, extractable, keyUsages)

Imports a key (raw, pkcs8, spki, jwk).

exportKey(format, key)

Exports a key (if extractable).

Real-World Examples

End-to-End Encryption

Symmetric encryption with a random key.

import { subtle } from 'react-native-quick-crypto';

async function secureMessage(msg: string) {
    // Generate Key
    const key = await subtle.generateKey(
        { name: "AES-GCM", length: 256 },
        true,
        ["encrypt", "decrypt"]
    );
    
    // Encrypt
    const iv = QuickCrypto.getRandomValues(new Uint8Array(12));
    const encoded = new TextEncoder().encode(msg);
    
    const ciphertext = await subtle.encrypt(
        { name: "AES-GCM", iv: iv },
        key,
        encoded
    );
    
    return { key, iv, ciphertext };
}

JWT Verification

Importing a public key from a JWK to verify a token.

async function verifyToken(token: string, jwk: any) {
    const pubKey = await subtle.importKey(
        "jwk",
        jwk,
        { name: "ECDSA", namedCurve: "P-256" },
        false,
        ["verify"]
    );
    
    const [header, payload, sigBase64] = token.split('.');
    const data = new TextEncoder().encode(`${header}.${payload}`);
    const signature = Buffer.from(sigBase64, 'base64');
    
    return await subtle.verify(
        { name: "ECDSA", hash: "SHA-256" },
        pubKey,
        signature,
        data
    );
}