Web Cryptography API

Relevant source files

• ext/crypto/00_crypto.js
• ext/crypto/decrypt.rs
• ext/crypto/ed25519.rs
• ext/crypto/encrypt.rs
• ext/crypto/export_key.rs
• ext/crypto/generate_key.rs
• ext/crypto/import_key.rs
• ext/crypto/key_store.rs
• ext/crypto/lib.rs
• ext/crypto/mldsa.rs
• ext/crypto/mlkem.rs
• ext/crypto/shared.rs
• ext/crypto/x25519.rs
• ext/crypto/x448.rs
• tests/unit/webcrypto_mldsa_test.ts
• tests/unit/webcrypto_test.ts
• tests/wpt/runner/expectations/WebCryptoAPI.json

The Web Cryptography API provides cryptographic operations in web applications. Deno's implementation is located in the deno_crypto extension ext/crypto/lib.rs114-134 which provides the Crypto interface with a subtle property exposing SubtleCrypto for advanced cryptographic operations.

The implementation bridges JavaScript API calls to Rust-based cryptographic operations using the deno_core ops system. Cryptographic primitives are provided by aws-lc-rs, rsa, p256, p384, p521, x25519_dalek, and related crates.

Key Components:

• Crypto interface: Provides getRandomValues(), randomUUID(), and the subtle property ext/crypto/00_crypto.js22-24
• SubtleCrypto interface: Methods for cryptographic operations (encrypt, decrypt, sign, verify, digest, key management) ext/crypto/00_crypto.js530-1233
• CryptoKey class: Represents cryptographic keys with type, algorithm, usages, and extractability ext/crypto/00_crypto.js67-98
• Rust ops: Low-level cryptographic operations implemented in Rust and exposed via the deno_crypto extension ext/crypto/lib.rs116-124

Sources: ext/crypto/00_crypto.js3-15 ext/crypto/lib.rs1-134

Architecture

The Web Crypto API implementation follows a layered architecture where JavaScript API calls are validated, normalized, and delegated to Rust operations. Most operations are implemented as methods on cppgc-wrapped Rust classes ext/crypto/00_crypto.js3-10

Web Crypto API Flow

Sources: ext/crypto/00_crypto.js3-15 ext/crypto/00_crypto.js821-956 ext/crypto/lib.rs107-113

CryptoKey Class

The CryptoKey class ext/crypto/00_crypto.js67-98 represents a cryptographic key. The type, extractable, usages, and algorithm getters all live in Rust ext/crypto/00_crypto.js67-70

Key Storage: The actual key material is stored in RawKeyData ext/crypto/shared.rs85-97 which owns its bytes in Rust rather than borrowing from JavaScript. This allows the key material to live in Rust—held alive by the cppgc handle—instead of being passed back and forth to JavaScript ext/crypto/shared.rs70-76

Key Construction: Keys are minted via cppgc instances. Structured-clone resurrection is handled by CryptoKey.fromCloneData(data) which parses snapshots back into freshly-minted instances ext/crypto/00_crypto.js100-109

Properties:

• type: Read-only, returns KeyType ("secret", "private", "public") ext/crypto/lib.rs248-252
• extractable: Read-only boolean.
• algorithm: Returns the algorithm used to generate or import the key.
• usages: Returns an array of allowed operations.

Sources: ext/crypto/00_crypto.js67-109 ext/crypto/shared.rs70-97 ext/crypto/lib.rs248-252

SubtleCrypto Interface

The SubtleCrypto class ext/crypto/00_crypto.js530-1233 provides methods for cryptographic operations. Deno uses makeAsyncForwarder to ensure methods like importKey and unwrapKey return Promises even when the underlying Rust implementation runs synchronously ext/crypto/00_crypto.js144-162

Method Categories:

Category	Methods	Purpose
Digest	digest()	Hash data
Encryption	encrypt(), decrypt()	Symmetric/asymmetric encryption
Signatures	sign(), verify()	Create and verify signatures
Key Management	generateKey(), importKey(), exportKey()	Key lifecycle
Key Derivation	deriveBits(), deriveKey()	Derive keys from base material
Key Wrapping	wrapKey(), unwrapKey()	Wrap keys for transport

Sources: ext/crypto/00_crypto.js144-178 ext/crypto/00_crypto.js530-1233

Cryptographic Operations

Digest Operation

The digest() method computes cryptographic hashes. It delegates to Rust per-algorithm helpers.

Supported Hash Algorithms: SHA-1, SHA-256, SHA-384, SHA-512, SHA3-256, SHA3-384, SHA3-512 ext/crypto/shared.rs27-42

The Rust implementation uses crates like sha2 and sha3 ext/crypto/lib.rs39-45

Sources: ext/crypto/shared.rs27-42 ext/crypto/lib.rs39-45

Encryption and Decryption

Encryption and decryption are implemented in ext/crypto/encrypt.rs and ext/crypto/decrypt.rs.

Supported Algorithms:

• RSA-OAEP: Uses the rsa crate with configurable hash functions ext/crypto/encrypt.rs74-127
• AES-CBC: Uses cbc and aes crates with PKCS#7 padding ext/crypto/encrypt.rs129-164
• AES-GCM: Uses aes-gcm crate with support for 12 or 16 byte IVs ext/crypto/encrypt.rs202-231

AES-GCM Encryption Flow:

1. JavaScript calls subtle.encrypt().
2. Rust receives RawKeyData.
3. encrypt_aes_gcm extracts the secret key ext/crypto/encrypt.rs210
4. encrypt_aes_gcm_general performs the operation using encrypt_in_place_detached ext/crypto/encrypt.rs172-200
5. The tag is truncated to the specified tag_length and appended to the ciphertext ext/crypto/encrypt.rs233-235

Sources: ext/crypto/encrypt.rs74-235 ext/crypto/decrypt.rs1-156

Signing and Verification

Signing and verification support RSA, ECDSA, HMAC, and Ed25519.

Ed25519 Implementation:

• Sign: ed25519_sign_into uses Ed25519KeyPair::from_seed_unchecked and signs the data ext/crypto/ed25519.rs42-53
• Verify: ed25519_verify uses aws_lc_rs::signature::UnparsedPublicKey ext/crypto/ed25519.rs57-68

ECDSA Implementation: Uses p256, p384, and p521 crates for curve-specific operations ext/crypto/lib.rs13-23

Sources: ext/crypto/ed25519.rs42-68 ext/crypto/lib.rs13-23

Key Management

Key Generation

Keys are generated in Rust and returned as raw bytes to be wrapped in a CryptoKey.

RSA Generation: generate_rsa validates the public exponent (allowing only 3 and 65537) ext/crypto/generate_key.rs44-47 and uses RsaPrivateKey::new_with_exp ext/crypto/generate_key.rs89-91

HMAC Generation: generate_hmac defaults the key length to the hash's block size if not provided ext/crypto/generate_key.rs144-183

Sources: ext/crypto/generate_key.rs44-91 ext/crypto/generate_key.rs144-183

Key Import

importKey() supports multiple formats: raw, pkcs8, spki, and jwk.

Import Process:

1. KeyDataWire is received from JavaScript and converted to KeyData ext/crypto/import_key.rs166-199
2. op_crypto_import_key_inner dispatches to algorithm-specific importers like import_key_rsassa or import_key_ec ext/crypto/import_key.rs245-254

JWK RSA Import: Parses n, e, d, p, q, dp, dq, qi from the JWK structure ext/crypto/import_key.rs104-113

Sources: ext/crypto/import_key.rs104-113 ext/crypto/import_key.rs166-254

Key Export

exportKey() converts RawKeyData back into the requested format.

RSA Export:

• SPKI: Wraps the RSA public key in a SubjectPublicKeyInfo structure with the OID 1.2.840.113549.1.1.1 ext/crypto/export_key.rs155-172
• PKCS#8: Wraps the private key in a PrivateKeyInfo structure ext/crypto/export_key.rs174-204
• JWK: Encodes components to Base64URL using uint_to_b64 ext/crypto/export_key.rs206-230

Sources: ext/crypto/export_key.rs155-230

Diffie-Hellman (X25519 & X448)

Deno implements Curve25519 (X25519) and Curve448 (X448) for key derivation.

X25519:

• Uses x25519_dalek for the Montgomery ladder ext/crypto/x25519.rs33
• x25519_derive_bits computes the shared secret and checks for the Montgomery identity (low-order point) to prevent attacks ext/crypto/x25519.rs51-65

X448:

• Implements the X448 function from RFC 7748 ext/crypto/x448.rs34-42
• Handles the specific clamping requirements where the top bit (447) must be set ext/crypto/x448.rs38

Sources: ext/crypto/x25519.rs33-65 ext/crypto/x448.rs34-42

Error Handling

Deno defines a comprehensive CryptoError enum that maps Rust errors to WebIDL exceptions ext/crypto/lib.rs137-236

Rust Error	DOMException Class
EncryptionError	DOMExceptionOperationError
DecryptionError	DOMExceptionOperationError
ArrayBufferViewLengthExceeded	DOMExceptionQuotaExceededError
TypedArrayNotInteger	DOMExceptionTypeMismatchError
UnsupportedDigestAlgorithm	DOMExceptionNotSupportedError

Sources: ext/crypto/lib.rs137-236