0
# Asymmetric Cryptography
1

2
Asymmetric cryptographic algorithms using key pairs (public and private keys) for encryption, decryption, digital signatures, and key agreement.
3

4
## Capabilities
5

6
### RSA Algorithms
7

8
RSA public-key cryptography for signatures and encryption with various padding schemes.
9

10
```typescript { .api }
11
/**
12
 * RSA key generation parameters
13
 */
14
interface RsaKeyGenParams extends Algorithm {
15
  name: "RSASSA-PKCS1-v1_5" | "RSA-PSS" | "RSA-OAEP" | "RSAES-PKCS1-v1_5";
16
  modulusLength: 1024 | 2048 | 3072 | 4096;
17
  publicExponent: Uint8Array; // Usually [1, 0, 1] for 65537
18
}
19

20
interface RsaHashedKeyGenParams extends RsaKeyGenParams {
21
  hash: "SHA-1" | "SHA-256" | "SHA-384" | "SHA-512";
22
}
23
```
24

25
### RSASSA-PKCS1-v1_5
26

27
RSA signatures with PKCS#1 v1.5 padding.
28

29
```typescript { .api }
30
interface RsaPkcs1Params extends Algorithm {
31
  name: "RSASSA-PKCS1-v1_5";
32
}
33
```
34

35
### RSA-PSS
36

37
RSA signatures with Probabilistic Signature Scheme padding.
38

39
```typescript { .api }
40
interface RsaPssParams extends Algorithm {
41
  name: "RSA-PSS";
42
  saltLength: number; // Salt length in bytes
43
}
44
```
45

46
### RSA-OAEP
47

48
RSA encryption with Optimal Asymmetric Encryption Padding.
49

50
```typescript { .api }
51
interface RsaOaepParams extends Algorithm {
52
  name: "RSA-OAEP";
53
  label?: BufferSource; // Optional label
54
}
55
```
56

57
### RSAES-PKCS1-v1_5
58

59
RSA encryption with PKCS#1 v1.5 padding (legacy compatibility).
60

61
```typescript { .api }
62
interface RsaEsParams extends Algorithm {
63
  name: "RSAES-PKCS1-v1_5";
64
}
65
```
66

67
**Usage Example:**
68

69
```typescript
70
// Generate RSA key pair
71
const keyPair = await crypto.subtle.generateKey(
72
  {
73
    name: "RSA-PSS",
74
    modulusLength: 2048,
75
    publicExponent: new Uint8Array([1, 0, 1]),
76
    hash: "SHA-256",
77
  },
78
  true,
79
  ["sign", "verify"]
80
);
81

82
// Sign data
83
const data = new TextEncoder().encode("Data to sign");
84
const signature = await crypto.subtle.sign(
85
  { name: "RSA-PSS", saltLength: 32 },
86
  keyPair.privateKey,
87
  data
88
);
89

90
// Verify signature
91
const isValid = await crypto.subtle.verify(
92
  { name: "RSA-PSS", saltLength: 32 },
93
  keyPair.publicKey,
94
  signature,
95
  data
96
);
97
```
98

99
### Elliptic Curve Algorithms
100

101
Elliptic Curve cryptography for efficient signatures and key agreement.
102

103
```typescript { .api }
104
/**
105
 * EC key generation parameters
106
 */
107
interface EcKeyGenParams extends Algorithm {
108
  name: "ECDSA" | "ECDH";
109
  namedCurve: "P-256" | "P-384" | "P-521" | "K-256" | string; // Includes Brainpool curves
110
}
111
```
112

113
### ECDSA (Elliptic Curve Digital Signature Algorithm)
114

115
Digital signatures using elliptic curve cryptography.
116

117
```typescript { .api }
118
interface EcdsaParams extends Algorithm {
119
  name: "ECDSA";
120
  hash: "SHA-1" | "SHA-256" | "SHA-384" | "SHA-512";
121
}
122
```
123

124
**Usage Example:**
125

126
```typescript
127
// Generate ECDSA key pair
128
const keyPair = await crypto.subtle.generateKey(
129
  { name: "ECDSA", namedCurve: "P-256" },
130
  true,
131
  ["sign", "verify"]
132
);
133

134
// Sign with ECDSA
135
const data = new TextEncoder().encode("Message to sign");
136
const signature = await crypto.subtle.sign(
137
  { name: "ECDSA", hash: "SHA-256" },
138
  keyPair.privateKey,
139
  data
140
);
141

142
// Verify ECDSA signature
143
const isValid = await crypto.subtle.verify(
144
  { name: "ECDSA", hash: "SHA-256" },
145
  keyPair.publicKey,
146
  signature,
147
  data
148
);
149
```
150

151
### ECDH (Elliptic Curve Diffie-Hellman)
152

153
Key agreement protocol for deriving shared secrets.
154

155
```typescript { .api }
156
interface EcdhKeyDeriveParams extends Algorithm {
157
  name: "ECDH";
158
  public: CryptoKey; // Other party's public key
159
}
160
```
161

162
**Usage Example:**
163

164
```typescript
165
// Generate key pairs for both parties
166
const aliceKeys = await crypto.subtle.generateKey(
167
  { name: "ECDH", namedCurve: "P-256" },
168
  false,
169
  ["deriveKey", "deriveBits"]
170
);
171

172
const bobKeys = await crypto.subtle.generateKey(
173
  { name: "ECDH", namedCurve: "P-256" },
174
  false,
175
  ["deriveKey", "deriveBits"]
176
);
177

178
// Derive shared key
179
const sharedKey = await crypto.subtle.deriveKey(
180
  { name: "ECDH", public: bobKeys.publicKey },
181
  aliceKeys.privateKey,
182
  { name: "AES-GCM", length: 256 },
183
  false,
184
  ["encrypt", "decrypt"]
185
);
186
```
187

188
## Supported Curves
189

190
### Standard Curves
191
- **P-256**: NIST P-256 (secp256r1)
192
- **P-384**: NIST P-384 (secp384r1)  
193
- **P-521**: NIST P-521 (secp521r1)
194
- **K-256**: secp256k1 (Bitcoin curve)
195

196
### Brainpool Curves
197
- **brainpoolP160r1**, **brainpoolP160t1**
198
- **brainpoolP192r1**, **brainpoolP192t1**
199
- **brainpoolP224r1**, **brainpoolP224t1**
200
- **brainpoolP256r1**, **brainpoolP256t1**
201
- **brainpoolP320r1**, **brainpoolP320t1**
202
- **brainpoolP384r1**, **brainpoolP384t1**
203
- **brainpoolP512r1**, **brainpoolP512t1**
204

205
## Key Classes
206

207
### RSA Key Classes
208

209
```typescript { .api }
210
class RsaPrivateKey extends AsymmetricKey {
211
  public algorithm: RsaHashedKeyAlgorithm;
212
  public type: "private";
213
  public usages: KeyUsage[];
214
  public extractable: boolean;
215
}
216

217
class RsaPublicKey extends AsymmetricKey {
218
  public algorithm: RsaHashedKeyAlgorithm;
219
  public type: "public"; 
220
  public usages: KeyUsage[];
221
  public extractable: boolean;
222
}
223

224
interface RsaHashedKeyAlgorithm extends KeyAlgorithm {
225
  name: "RSASSA-PKCS1-v1_5" | "RSA-PSS" | "RSA-OAEP" | "RSAES-PKCS1-v1_5";
226
  modulusLength: number;
227
  publicExponent: Uint8Array;
228
  hash: KeyAlgorithm;
229
}
230
```
231

232
### EC Key Classes
233

234
```typescript { .api }
235
class EcPrivateKey extends AsymmetricKey {
236
  public algorithm: EcKeyAlgorithm;
237
  public type: "private";
238
  public usages: KeyUsage[];
239
  public extractable: boolean;
240
}
241

242
class EcPublicKey extends AsymmetricKey {
243
  public algorithm: EcKeyAlgorithm;
244
  public type: "public";
245
  public usages: KeyUsage[];
246
  public extractable: boolean;
247
}
248

249
interface EcKeyAlgorithm extends KeyAlgorithm {
250
  name: "ECDSA" | "ECDH";
251
  namedCurve: string;
252
}
253
```