0
# @peculiar/webcrypto
1

2
A comprehensive WebCrypto polyfill for Node.js that implements the standard Web Cryptography API using native Node.js crypto capabilities. This library provides full compatibility with browser WebCrypto while offering extensive algorithm support including advanced cryptographic operations not typically available in browsers.
3

4
## Package Information
5

6
- **Package Name**: @peculiar/webcrypto
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @peculiar/webcrypto`
10

11
## Core Imports
12

13
```typescript
14
import { Crypto } from "@peculiar/webcrypto";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { Crypto } = require("@peculiar/webcrypto");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { Crypto } from "@peculiar/webcrypto";
27

28
const crypto = new Crypto();
29

30
// Generate a key pair
31
const keyPair = await crypto.subtle.generateKey(
32
  {
33
    name: "RSA-PSS",
34
    modulusLength: 2048,
35
    publicExponent: new Uint8Array([1, 0, 1]),
36
    hash: "SHA-256",
37
  },
38
  true,
39
  ["sign", "verify"]
40
);
41

42
// Sign data
43
const data = new TextEncoder().encode("Hello, World!");
44
const signature = await crypto.subtle.sign(
45
  {
46
    name: "RSA-PSS",
47
    saltLength: 32,
48
  },
49
  keyPair.privateKey,
50
  data
51
);
52

53
// Generate random values
54
const randomBytes = new Uint8Array(32);
55
crypto.getRandomValues(randomBytes);
56

57
// Generate additional random values
58
const moreRandomBytes = new Uint8Array(16);
59
crypto.getRandomValues(moreRandomBytes);
60
```
61

62
## Architecture
63

64
@peculiar/webcrypto is built on several key components:
65

66
- **Crypto Class**: Main entry point implementing the global Crypto interface with `subtle` property and utility methods
67
- **SubtleCrypto Implementation**: Comprehensive cryptographic operations using algorithm-specific providers
68
- **Algorithm Providers**: Specialized classes for each cryptographic algorithm (AES, RSA, ECDSA, etc.)
69
- **Key Classes**: Type-safe representations of cryptographic keys with proper serialization support
70
- **Platform Integration**: Conditional algorithm availability based on Node.js version and crypto capabilities
71

72
## Capabilities
73

74
### Core Cryptographic Interface
75

76
Main Crypto class providing WebCrypto API compatibility with random value generation and UUID creation.
77

78
```typescript { .api }
79
class Crypto implements globalThis.Crypto {
80
  public subtle: SubtleCrypto;
81
  getRandomValues<T extends ArrayBufferView | null>(array: T): T;
82
  randomUUID(): `${string}-${string}-${string}-${string}-${string}`;
83
}
84
```
85

86
[Core Interface](./crypto-interface.md)
87

88
### Symmetric Encryption
89

90
AES encryption in multiple modes (CBC, CTR, GCM, ECB) with key wrapping capabilities, plus legacy DES support.
91

92
```typescript { .api }
93
// AES key generation
94
interface AesKeyGenParams extends Algorithm {
95
  name: "AES-CBC" | "AES-CTR" | "AES-GCM" | "AES-ECB" | "AES-KW" | "AES-CMAC";
96
  length: 128 | 192 | 256;
97
}
98

99
// AES encryption parameters
100
interface AesGcmParams extends Algorithm {
101
  name: "AES-GCM";
102
  iv: BufferSource;
103
  additionalData?: BufferSource;
104
  tagLength?: 8 | 32 | 64 | 96 | 104 | 112 | 120 | 128;
105
}
106
```
107

108
[Symmetric Encryption](./symmetric-encryption.md)
109

110
### Asymmetric Cryptography
111

112
RSA operations (signatures, encryption, key wrapping) and Elliptic Curve cryptography (ECDSA, ECDH) with extensive curve support.
113

114
```typescript { .api }
115
// RSA key generation
116
interface RsaHashedKeyGenParams extends RsaKeyGenParams {
117
  name: "RSA-PSS" | "RSASSA-PKCS1-v1_5" | "RSA-OAEP";
118
  hash: "SHA-1" | "SHA-256" | "SHA-384" | "SHA-512";
119
}
120

121
// ECDSA key generation  
122
interface EcKeyGenParams extends Algorithm {
123
  name: "ECDSA" | "ECDH";
124
  namedCurve: "P-256" | "P-384" | "P-521" | "K-256" | string;
125
}
126
```
127

128
[Asymmetric Cryptography](./asymmetric-cryptography.md)
129

130
### Modern Cryptography
131

132
EdDSA signatures and Curve25519 key agreement for next-generation cryptographic applications (Node.js ≥14).
133

134
```typescript { .api }
135
// EdDSA key generation
136
interface EdDsaKeyGenParams extends Algorithm {
137
  name: "EdDSA";
138
  namedCurve: "Ed25519" | "Ed448";
139
}
140

141
// ECDH-ES key generation
142
interface EcdhEsKeyGenParams extends Algorithm {
143
  name: "ECDH-ES";
144
  namedCurve: "X25519" | "X448";
145
}
146
```
147

148
[Modern Cryptography](./modern-cryptography.md)
149

150
### Hash Functions
151

152
SHA family hash functions including SHA-3 variants and SHAKE extendable-output functions.
153

154
```typescript { .api }
155
// Hash algorithms
156
type HashAlgorithm = "SHA-1" | "SHA-256" | "SHA-384" | "SHA-512" | 
157
                    "SHA3-256" | "SHA3-384" | "SHA3-512" | 
158
                    "shake128" | "shake256";
159

160
// SHAKE parameters
161
interface ShakeParams extends Algorithm {
162
  name: "shake128" | "shake256";
163
  length: number;
164
}
165
```
166

167
[Hash Functions](./hash-functions.md)
168

169
### Key Derivation
170

171
PBKDF2 and HKDF key derivation functions with HMAC support for secure key management.
172

173
```typescript { .api }
174
// PBKDF2 parameters
175
interface Pbkdf2Params extends Algorithm {
176
  name: "PBKDF2";
177
  salt: BufferSource;
178
  iterations: number;
179
  hash: "SHA-1" | "SHA-256" | "SHA-384" | "SHA-512";
180
}
181

182
// HKDF parameters
183
interface HkdfParams extends Algorithm {
184
  name: "HKDF";
185
  hash: "SHA-1" | "SHA-256" | "SHA-384" | "SHA-512";
186
  salt: BufferSource;
187
  info: BufferSource;
188
}
189
```
190

191
[Key Derivation](./key-derivation.md)
192

193
## Supported Algorithms
194

195
### Symmetric Algorithms
196
- **AES**: CBC, CTR, GCM, ECB, KW (Key Wrap), CMAC
197
- **DES**: CBC (conditional), 3DES-EDE-CBC
198

199
### Asymmetric Algorithms  
200
- **RSA**: RSASSA-PKCS1-v1_5, RSA-PSS, RSA-OAEP, RSAES-PKCS1-v1_5
201
- **ECDSA**: P-256, P-384, P-521, K-256, Brainpool curves
202
- **ECDH**: P-256, P-384, P-521, K-256, Brainpool curves
203
- **EdDSA**: Ed25519, Ed448 (Node.js ≥14)
204
- **ECDH-ES**: X25519, X448 (Node.js ≥14)
205

206
### Hash Functions
207
- **SHA**: SHA-1, SHA-256, SHA-384, SHA-512
208
- **SHA-3**: SHA3-256, SHA3-384, SHA3-512 (conditional)
209
- **SHAKE**: SHAKE128, SHAKE256 (Node.js ≥12)
210

211
### Key Derivation
212
- **PBKDF2**: With SHA-1, SHA-256, SHA-384, SHA-512
213
- **HKDF**: With SHA-1, SHA-256, SHA-384, SHA-512
214
- **HMAC**: With SHA-1, SHA-256, SHA-384, SHA-512
215

216
### Supported Elliptic Curves
217
- **Standard**: P-256, P-384, P-521, K-256
218
- **Brainpool**: brainpoolP160r1, brainpoolP160t1, brainpoolP192r1, brainpoolP192t1, brainpoolP224r1, brainpoolP224t1, brainpoolP256r1, brainpoolP256t1, brainpoolP320r1, brainpoolP320t1, brainpoolP384r1, brainpoolP384t1, brainpoolP512r1, brainpoolP512t1
219
- **EdDSA**: Ed25519, Ed448
220
- **ECDH-ES**: X25519, X448
221

222
## Platform Requirements
223

224
- **Node.js**: ≥10.12.0
225
- **SHAKE functions**: Node.js ≥12
226
- **EdDSA/Curve25519**: Node.js ≥14
227
- **SHA-3 functions**: Platform-dependent crypto support