SubtleCrypto

interface

interface SubtleCrypto

This Web Crypto API interface provides a number of low-level cryptographic functions. It is accessed via the Crypto.subtle properties available in a window context (via globalThis.crypto).

variable

var SubtleCrypto: { … }

The constructor object for SubtleCrypto.

The SubtleCrypto instance is accessed via Crypto.subtle (crypto.subtle) rather than constructed directly, so calling the constructor throws.

Constructors

constructor

new SubtleCrypto(): never

Properties

prototype

readonly prototype: SubtleCrypto

Methods

generateKey

generateKey(algorithm: RsaHashedKeyGenParams | EcKeyGenParams, extractable: boolean, keyUsages: KeyUsage[]): Promise<CryptoKeyPair>

Generates an asymmetric cryptographic key pair for encryption, signing, or key exchange.

This overload is used for generating key pairs with RSA or elliptic curve algorithms.

Example

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

Example

// Elliptic curve (ECDSA) key pair generation
const key = await crypto.subtle.generateKey(
  {
    name: "ECDSA",
    namedCurve: "P-384",
  },
  true,
  ["sign", "verify"]
);

See also

generateKey(algorithm: AesKeyGenParams | HmacKeyGenParams, extractable: boolean, keyUsages: KeyUsage[]): Promise<CryptoKey>

Generates a symmetric cryptographic key for encryption, authentication, or hashing.

This overload is used for algorithms such as AES and HMAC.

Example

const key = await crypto.subtle.generateKey(
 {
   name: "AES-GCM",
   length: 256,
 },
 true,
 ["encrypt", "decrypt"]
);

Example

// HMAC key generation
const key = await crypto.subtle.generateKey(
 {
   name: "HMAC",
   hash: { name: "SHA-512" },
 },
 true,
 ["sign", "verify"]
);

See also

generateKey(algorithm: AlgorithmIdentifier, extractable: boolean, keyUsages: KeyUsage[]): Promise<CryptoKeyPair | CryptoKey>

Generates a cryptographic key or key pair for a given algorithm.

This generic overload handles any key generation request, returning either a symmetric key or an asymmetric key pair based on the provided algorithm.

See also

importKey

importKey(format: "jwk", keyData: JsonWebKey, algorithm: AlgorithmIdentifier | HmacImportParams | RsaHashedImportParams | EcKeyImportParams, extractable: boolean, keyUsages: KeyUsage[]): Promise<CryptoKey>

Imports a cryptographic key in JSON Web Key (JWK) format.

This method is used to import an asymmetric key (e.g., RSA or ECDSA) from a JWK object. JWK allows structured representation of keys, making them portable across different systems.

Example

// Import an ECDSA private signing key where `jwk` is an object describing a private key
crypto.subtle.importKey(
  "jwk",
  jwk,
  {
    name: "ECDSA",
    namedCurve: "P-384",
  },
  true,
  ["sign"],
);

See also

importKey(format: Exclude<KeyFormat, "jwk">, keyData: BufferSource, algorithm: AlgorithmIdentifier | HmacImportParams | RsaHashedImportParams | EcKeyImportParams, extractable: boolean, keyUsages: KeyUsage[]): Promise<CryptoKey>

Imports a cryptographic key in raw, PKCS8, or SPKI format.

This method is used to import symmetric keys (e.g., AES), private keys (PKCS8), or public keys (SPKI).

Example

// Import an AES-GCM secret key where `rawKey` is an ArrayBuffer string
crypto.subtle.importKey("raw", rawKey, "AES-GCM", true, [
  "encrypt",
  "decrypt",
]);

See also

exportKey

exportKey(format: "jwk", key: CryptoKey): Promise<JsonWebKey>

Exports a cryptographic key in JSON Web Key (JWK) format.

This method allows exporting an asymmetric key (e.g., RSA, ECDSA) into a JSON-based representation, making it easy to store and transfer across systems.

Example

await crypto.subtle.exportKey("jwk", key);

See also

exportKey(format: Exclude<KeyFormat, "jwk">, key: CryptoKey): Promise<ArrayBuffer>

Exports a cryptographic key in raw, PKCS8, or SPKI format.

This method is used to export symmetric keys (AES), private keys (PKCS8), or public keys (SPKI) in binary form.

Example

await crypto.subtle.exportKey("raw", key);

See also

sign

sign(algorithm: AlgorithmIdentifier | RsaPssParams | EcdsaParams, key: CryptoKey, data: BufferSource): Promise<ArrayBuffer>

Generates a digital signature using a private cryptographic key.

This method is used to sign data with an asymmetric key (e.g., RSA-PSS, ECDSA).

Example

await crypto.subtle.sign("ECDSA", key, data);

See also

verify

verify(algorithm: AlgorithmIdentifier | RsaPssParams | EcdsaParams, key: CryptoKey, signature: BufferSource, data: BufferSource): Promise<boolean>

Verifies a digital signature using a public cryptographic key.

This method checks whether a signature is valid for the given data.

Example

await crypto.subtle.verify("ECDSA", key, signature, data);

See also

digest

digest(algorithm: AlgorithmIdentifier, data: BufferSource): Promise<ArrayBuffer>

Computes a cryptographic hash (digest) of the given data.

This method is commonly used for verifying data integrity.

Example

// Compute the digest of given data using a cryptographic algorithm
await crypto.subtle.digest("SHA-256", data);

See also

encrypt

encrypt(algorithm: AlgorithmIdentifier | RsaOaepParams | AesCbcParams | AesGcmParams | AesCtrParams, key: CryptoKey, data: BufferSource): Promise<ArrayBuffer>

Encrypts data using a cryptographic key.

This method is used with both symmetric (AES) and asymmetric (RSA) encryption.

Example

await crypto.subtle.encrypt("RSA-OAEP", key, data);

See also

decrypt

decrypt(algorithm: AlgorithmIdentifier | RsaOaepParams | AesCbcParams | AesGcmParams | AesCtrParams, key: CryptoKey, data: BufferSource): Promise<ArrayBuffer>

Decrypts previously encrypted data using a cryptographic key.

Example

await crypto.subtle.decrypt("RSA-OAEP", key, data);

See also

deriveBits

deriveBits(algorithm: AlgorithmIdentifier | HkdfParams | Pbkdf2Params | EcdhKeyDeriveParams, baseKey: CryptoKey, length: number): Promise<ArrayBuffer>

This method is used to derive a key from a base key using a cryptographic algorithm.

Example

await crypto.subtle.deriveBits("HKDF", baseKey, length);

See also

deriveKey

deriveKey(algorithm: AlgorithmIdentifier | HkdfParams | Pbkdf2Params | EcdhKeyDeriveParams, baseKey: CryptoKey, derivedKeyType: AlgorithmIdentifier | AesDerivedKeyParams | HmacImportParams | HkdfParams | Pbkdf2Params, extractable: boolean, keyUsages: KeyUsage[]): Promise<CryptoKey>

This method is used to derive a secret key from a base or master key using a cryptographic algorithm. It returns a Promise which fulfils with an object of the new key.

Example

// Derive a key using an HKDF algorithm
await crypto.subtle.deriveKey("HKDF", baseKey, derivedKeyType, extractable, keyUsages);

See also

wrapKey

wrapKey(format: KeyFormat, key: CryptoKey, wrappingKey: CryptoKey, wrapAlgorithm: AlgorithmIdentifier | RsaOaepParams | AesCbcParams | AesCtrParams): Promise<ArrayBuffer>

Wraps (encrypts) a cryptographic key for secure storage or transmission

Example

await crypto.subtle.wrapKey("jwk", key, wrappingKey, "RSA-OAEP");

See also

unwrapKey

unwrapKey(format: KeyFormat, wrappedKey: BufferSource, unwrappingKey: CryptoKey, unwrapAlgorithm: AlgorithmIdentifier | RsaOaepParams | AesCbcParams | AesCtrParams, unwrappedKeyAlgorithm: AlgorithmIdentifier | HmacImportParams | RsaHashedImportParams | EcKeyImportParams, extractable: boolean, keyUsages: KeyUsage[]): Promise<CryptoKey>

Unwraps (decrypts) a previously wrapped key.

Example

// Unwrap an AES-GCM key wrapped with AES-KW
const unwrappedKey = await crypto.subtle.unwrapKey(
  "jwk", // Format of the key to import
  wrappedKey, // Encrypted key data as ArrayBuffer
  unwrappingKey, // CryptoKey used for unwrapping
  { name: "AES-KW" }, // Unwrapping algorithm
  { name: "AES-GCM", length: 256 }, // Algorithm for unwrapped key
  true, // Whether the unwrapped key is extractable
  ["encrypt", "decrypt"] // Allowed key usages
);

See also

supports

supports(operation: "encrypt" | "decrypt" | "sign" | "verify" | "digest" | "generateKey" | "deriveKey" | "deriveBits" | "importKey" | "exportKey" | "wrapKey" | "unwrapKey" | "encapsulateKey" | "encapsulateBits" | "decapsulateKey" | "decapsulateBits" | "getPublicKey", algorithm: string | object, lengthOrHash?: number | string | object | null): boolean

Synchronous feature detection for Web Crypto algorithm/operation combinations, per the WICG "Modern Algorithms in the Web Crypto API" proposal. Returns true when this runtime implements the requested combination, false otherwise.

The third argument is interpreted as the derived-bit length when it is a number (relevant for "deriveBits"), and as a related algorithm — e.g. the derived-key algorithm for "deriveKey", the wrapped/unwrapped key algorithm for "wrapKey" / "unwrapKey", or the shared-key algorithm for "encapsulateKey" / "decapsulateKey" — otherwise.

See also