0
# Core Cryptographic Interface
1

2
The main `Crypto` class provides WebCrypto API compatibility with additional utility methods for random value generation and UUID creation.
3

4
## Capabilities
5

6
### Crypto Class
7

8
Main cryptographic interface implementing the global Crypto standard.
9

10
```typescript { .api }
11
/**
12
 * Main cryptographic interface implementing globalThis.Crypto
13
 * Provides access to cryptographic operations and random utilities
14
 */
15
class Crypto implements globalThis.Crypto {
16
  /** SubtleCrypto interface for cryptographic operations */
17
  public subtle: SubtleCrypto;
18
  
19
  /**
20
   * Fill array with cryptographically secure random values
21
   * @param array - ArrayBufferView to fill with random data
22
   * @returns The same array filled with random values
23
   */
24
  getRandomValues<T extends ArrayBufferView | null>(array: T): T;
25
  
26
}
27
```
28

29
**Usage Examples:**
30

31
```typescript
32
import { Crypto } from "@peculiar/webcrypto";
33

34
const crypto = new Crypto();
35

36
// Generate random bytes
37
const buffer = new Uint8Array(32);
38
crypto.getRandomValues(buffer);
39
console.log("Random bytes:", Array.from(buffer));
40

41
// Generate more random data
42
const moreBytes = new Uint8Array(16);
43
crypto.getRandomValues(moreBytes);
44
console.log("More random bytes:", Array.from(moreBytes));
45

46
// Access cryptographic operations
47
const keyPair = await crypto.subtle.generateKey(
48
  { name: "ECDSA", namedCurve: "P-256" },
49
  true,
50
  ["sign", "verify"]
51
);
52
```
53

54
### CryptoKey Class
55

56
Represents cryptographic keys with algorithm metadata and usage constraints.
57

58
```typescript { .api }
59
/**
60
 * Represents a cryptographic key
61
 * Implements the globalThis.CryptoKey interface
62
 */
63
class CryptoKey implements globalThis.CryptoKey {
64
  /** Algorithm information for this key */
65
  public algorithm: KeyAlgorithm;
66
  
67
  /** Whether the key can be exported */
68
  public extractable: boolean;
69
  
70
  /** Key type: "secret", "private", or "public" */
71
  public type: KeyType;
72
  
73
  /** Array of allowed operations for this key */
74
  public usages: KeyUsage[];
75
}
76
```
77

78
### SubtleCrypto Interface
79

80
The SubtleCrypto interface provides cryptographic operations. All methods are asynchronous and return Promises.
81

82
```typescript { .api }
83
/**
84
 * Cryptographic operations interface
85
 * Extends webcrypto-core SubtleCrypto with algorithm providers
86
 */
87
class SubtleCrypto extends core.SubtleCrypto {
88
  /**
89
   * Generate cryptographic key or key pair
90
   * @param algorithm - Algorithm parameters for key generation
91
   * @param extractable - Whether the key can be exported
92
   * @param keyUsages - Allowed operations for the key
93
   * @returns Promise resolving to CryptoKey or CryptoKeyPair
94
   */
95
  generateKey(
96
    algorithm: AlgorithmIdentifier,
97
    extractable: boolean,
98
    keyUsages: KeyUsage[]
99
  ): Promise<CryptoKey | CryptoKeyPair>;
100

101
  /**
102
   * Import cryptographic key from external format
103
   * @param format - Key format ("raw", "pkcs8", "spki", "jwk")
104
   * @param keyData - Key data in specified format
105
   * @param algorithm - Algorithm parameters for imported key
106
   * @param extractable - Whether the key can be exported
107
   * @param keyUsages - Allowed operations for the key
108
   * @returns Promise resolving to CryptoKey
109
   */
110
  importKey(
111
    format: KeyFormat,
112
    keyData: BufferSource | JsonWebKey,
113
    algorithm: AlgorithmIdentifier,
114
    extractable: boolean,
115
    keyUsages: KeyUsage[]
116
  ): Promise<CryptoKey>;
117

118
  /**
119
   * Export cryptographic key to external format
120
   * @param format - Desired export format
121
   * @param key - Key to export
122
   * @returns Promise resolving to exported key data
123
   */
124
  exportKey(format: KeyFormat, key: CryptoKey): Promise<ArrayBuffer | JsonWebKey>;
125

126
  /**
127
   * Encrypt data using specified algorithm and key
128
   * @param algorithm - Encryption algorithm and parameters
129
   * @param key - Encryption key
130
   * @param data - Data to encrypt
131
   * @returns Promise resolving to encrypted data
132
   */
133
  encrypt(
134
    algorithm: AlgorithmIdentifier,
135
    key: CryptoKey,
136
    data: BufferSource
137
  ): Promise<ArrayBuffer>;
138

139
  /**
140
   * Decrypt data using specified algorithm and key
141
   * @param algorithm - Decryption algorithm and parameters
142
   * @param key - Decryption key
143
   * @param data - Data to decrypt
144
   * @returns Promise resolving to decrypted data
145
   */
146
  decrypt(
147
    algorithm: AlgorithmIdentifier,
148
    key: CryptoKey,
149
    data: BufferSource
150
  ): Promise<ArrayBuffer>;
151

152
  /**
153
   * Generate digital signature for data
154
   * @param algorithm - Signature algorithm and parameters
155
   * @param key - Private key for signing
156
   * @param data - Data to sign
157
   * @returns Promise resolving to signature
158
   */
159
  sign(
160
    algorithm: AlgorithmIdentifier,
161
    key: CryptoKey,
162
    data: BufferSource
163
  ): Promise<ArrayBuffer>;
164

165
  /**
166
   * Verify digital signature
167
   * @param algorithm - Signature algorithm and parameters
168
   * @param key - Public key for verification  
169
   * @param signature - Signature to verify
170
   * @param data - Original data
171
   * @returns Promise resolving to verification result
172
   */
173
  verify(
174
    algorithm: AlgorithmIdentifier,
175
    key: CryptoKey,
176
    signature: BufferSource,
177
    data: BufferSource
178
  ): Promise<boolean>;
179

180
  /**
181
   * Compute hash digest of data
182
   * @param algorithm - Hash algorithm
183
   * @param data - Data to hash
184
   * @returns Promise resolving to hash digest
185
   */
186
  digest(algorithm: AlgorithmIdentifier, data: BufferSource): Promise<ArrayBuffer>;
187

188
  /**
189
   * Wrap (encrypt) a cryptographic key
190
   * @param format - Format of key to wrap
191
   * @param key - Key to wrap
192
   * @param wrappingKey - Key used for wrapping
193
   * @param wrapAlgorithm - Wrapping algorithm
194
   * @returns Promise resolving to wrapped key data
195
   */
196
  wrapKey(
197
    format: KeyFormat,
198
    key: CryptoKey,
199
    wrappingKey: CryptoKey,
200
    wrapAlgorithm: AlgorithmIdentifier
201
  ): Promise<ArrayBuffer>;
202

203
  /**
204
   * Unwrap (decrypt) a cryptographic key
205
   * @param format - Format of wrapped key
206
   * @param wrappedKey - Wrapped key data
207
   * @param unwrappingKey - Key used for unwrapping
208
   * @param unwrapAlgorithm - Unwrapping algorithm
209
   * @param unwrappedKeyAlgorithm - Algorithm for unwrapped key
210
   * @param extractable - Whether unwrapped key can be exported
211
   * @param keyUsages - Allowed operations for unwrapped key
212
   * @returns Promise resolving to unwrapped CryptoKey
213
   */
214
  unwrapKey(
215
    format: KeyFormat,
216
    wrappedKey: BufferSource,
217
    unwrappingKey: CryptoKey,
218
    unwrapAlgorithm: AlgorithmIdentifier,
219
    unwrappedKeyAlgorithm: AlgorithmIdentifier,
220
    extractable: boolean,
221
    keyUsages: KeyUsage[]
222
  ): Promise<CryptoKey>;
223

224
  /**
225
   * Derive raw bits from key using key derivation algorithm
226
   * @param algorithm - Key derivation algorithm and parameters
227
   * @param baseKey - Base key for derivation
228
   * @param length - Number of bits to derive
229
   * @returns Promise resolving to derived bits
230
   */
231
  deriveBits(
232
    algorithm: AlgorithmIdentifier,
233
    baseKey: CryptoKey,
234
    length: number
235
  ): Promise<ArrayBuffer>;
236

237
  /**
238
   * Derive new key from base key using key derivation algorithm
239
   * @param algorithm - Key derivation algorithm and parameters
240
   * @param baseKey - Base key for derivation
241
   * @param derivedKeyType - Algorithm for derived key
242
   * @param extractable - Whether derived key can be exported
243
   * @param keyUsages - Allowed operations for derived key
244
   * @returns Promise resolving to derived CryptoKey
245
   */
246
  deriveKey(
247
    algorithm: AlgorithmIdentifier,
248
    baseKey: CryptoKey,
249
    derivedKeyType: AlgorithmIdentifier,
250
    extractable: boolean,
251
    keyUsages: KeyUsage[]
252
  ): Promise<CryptoKey>;
253
}
254
```
255

256
## Types
257

258
```typescript { .api }
259
type KeyFormat = "raw" | "pkcs8" | "spki" | "jwk";
260

261
type KeyType = "secret" | "private" | "public";
262

263
type KeyUsage = "encrypt" | "decrypt" | "sign" | "verify" | "deriveKey" | "deriveBits" | "wrapKey" | "unwrapKey";
264

265
interface KeyAlgorithm {
266
  name: string;
267
}
268

269
interface CryptoKeyPair {
270
  privateKey: CryptoKey;
271
  publicKey: CryptoKey;
272
}
273

274
interface Algorithm {
275
  name: string;
276
}
277

278
type AlgorithmIdentifier = Algorithm | string;
279

280
interface JsonWebKey {
281
  alg?: string;
282
  crv?: string;
283
  d?: string;
284
  dp?: string;
285
  dq?: string;
286
  e?: string;
287
  ext?: boolean;
288
  k?: string;
289
  key_ops?: string[];
290
  kty?: string;
291
  n?: string;
292
  oth?: RsaOtherPrimesInfo[];
293
  p?: string;
294
  q?: string;
295
  qi?: string;
296
  use?: string;
297
  x?: string;
298
  y?: string;
299
}
300

301
interface RsaOtherPrimesInfo {
302
  d?: string;
303
  r?: string;
304
  t?: string;
305
}
306
```