hpke 0.5.0 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE.md +21 -0
- package/README.md +123 -58
- package/index.d.ts +1797 -0
- package/index.d.ts.map +1 -0
- package/index.js +4190 -0
- package/index.ts +4190 -0
- package/package.json +68 -38
- package/LICENSE +0 -375
- package/pkg/node/.gitignore +0 -1
- package/pkg/node/LICENSE +0 -375
- package/pkg/node/README.md +0 -83
- package/pkg/node/hpke_dispatch.d.ts +0 -241
- package/pkg/node/hpke_dispatch.js +0 -812
- package/pkg/node/hpke_dispatch_bg.wasm +0 -0
- package/pkg/node/hpke_dispatch_bg.wasm.d.ts +0 -32
- package/pkg/node/index.spec.ts +0 -82
- package/pkg/node/package.json +0 -21
- package/pkg/web/.gitignore +0 -1
- package/pkg/web/LICENSE +0 -375
- package/pkg/web/README.md +0 -83
- package/pkg/web/hpke_dispatch.d.ts +0 -297
- package/pkg/web/hpke_dispatch.js +0 -852
- package/pkg/web/hpke_dispatch_bg.wasm +0 -0
- package/pkg/web/hpke_dispatch_bg.wasm.d.ts +0 -32
- package/pkg/web/index.mjs +0 -2
- package/pkg/web/index.mjs.map +0 -7
- package/pkg/web/index.ts +0 -5
- package/pkg/web/package.json +0 -22
package/index.d.ts
ADDED
|
@@ -0,0 +1,1797 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Hybrid Public Key Encryption (HPKE) implementation for JavaScript runtimes.
|
|
3
|
+
*
|
|
4
|
+
* Implements an authenticated encryption encapsulation format that combines a semi-static
|
|
5
|
+
* asymmetric key exchange with a symmetric cipher. This was originally defined in an Informational
|
|
6
|
+
* document on the IRTF stream as [RFC 9180](https://www.rfc-editor.org/rfc/rfc9180.html) and is now
|
|
7
|
+
* being republished as a Standards Track document of the IETF as
|
|
8
|
+
* [draft-ietf-hpke-hpke](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-02).
|
|
9
|
+
*
|
|
10
|
+
* HPKE provides a variant of public key encryption for arbitrary-sized plaintexts using a recipient
|
|
11
|
+
* public key.
|
|
12
|
+
*
|
|
13
|
+
* @module hpke
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
* @group Core
|
|
58
|
+
*/
|
|
59
|
+
declare class SenderContext {
|
|
60
|
+
#private;
|
|
61
|
+
constructor(suite: Triple, mode: number, key: Uint8Array, base_nonce: Uint8Array, exporter_secret: Uint8Array);
|
|
62
|
+
/** @returns The mode (0x00 = Base, 0x01 = PSK) for this context. */
|
|
63
|
+
get mode(): number;
|
|
64
|
+
/**
|
|
65
|
+
* @returns The sequence number for this context's next {@link Seal}, initially zero, increments
|
|
66
|
+
* automatically with each successful {@link Seal}. The sequence number provides AEAD nonce
|
|
67
|
+
* uniqueness. The maximum supported sequence number in this implementation is `2^53-1`.
|
|
68
|
+
*/
|
|
69
|
+
get seq(): number;
|
|
70
|
+
/**
|
|
71
|
+
* Encrypts plaintext with additional authenticated data. Each successful call automatically
|
|
72
|
+
* increments the sequence number to ensure nonce uniqueness.
|
|
73
|
+
*
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
* @param plaintext - Plaintext to encrypt
|
|
90
|
+
* @param aad - Additional authenticated data
|
|
91
|
+
*
|
|
92
|
+
* @returns A Promise that resolves to the ciphertext. The ciphertext is {@link Nt} bytes longer
|
|
93
|
+
* than the plaintext.
|
|
94
|
+
*/
|
|
95
|
+
Seal(plaintext: Uint8Array, aad?: Uint8Array): Promise<Uint8Array>;
|
|
96
|
+
/**
|
|
97
|
+
* Exports a secret using a variable-length pseudorandom function (PRF).
|
|
98
|
+
*
|
|
99
|
+
* The exported secret is indistinguishable from a uniformly random bitstring of equal length.
|
|
100
|
+
*
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
* @param exporterContext - Context for domain separation
|
|
114
|
+
* @param length - Desired length of exported secret in bytes
|
|
115
|
+
*
|
|
116
|
+
* @returns A Promise that resolves to the exported secret.
|
|
117
|
+
*/
|
|
118
|
+
Export(exporterContext: Uint8Array, length: number): Promise<Uint8Array>;
|
|
119
|
+
/**
|
|
120
|
+
* @returns The length in bytes of an authentication tag for the AEAD algorithm used by this
|
|
121
|
+
* context.
|
|
122
|
+
*/
|
|
123
|
+
get Nt(): number;
|
|
124
|
+
}
|
|
125
|
+
export type { SenderContext };
|
|
126
|
+
/**
|
|
127
|
+
* Context for decrypting multiple messages and exporting secrets on the recipient side.
|
|
128
|
+
*
|
|
129
|
+
* `RecipientContext` instance is obtained from {@link CipherSuite.SetupRecipient}.
|
|
130
|
+
*
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
|
|
143
|
+
* @group Core
|
|
144
|
+
*/
|
|
145
|
+
declare class RecipientContext {
|
|
146
|
+
#private;
|
|
147
|
+
constructor(suite: Triple, mode: number, key: Uint8Array, base_nonce: Uint8Array, exporter_secret: Uint8Array);
|
|
148
|
+
/** @returns The mode (0x00 = Base, 0x01 = PSK) for this context. */
|
|
149
|
+
get mode(): number;
|
|
150
|
+
/**
|
|
151
|
+
* @returns The sequence number for this context's next {@link Open}, initially zero, increments
|
|
152
|
+
* automatically with each successful {@link Open}. The sequence number provides AEAD nonce
|
|
153
|
+
* uniqueness. The maximum supported sequence number in this implementation is `2^53-1`.
|
|
154
|
+
*/
|
|
155
|
+
get seq(): number;
|
|
156
|
+
/**
|
|
157
|
+
* Decrypts ciphertext with additional authenticated data.
|
|
158
|
+
*
|
|
159
|
+
* Applications must ensure that ciphertexts are presented to `Open` in the exact order they were
|
|
160
|
+
* produced by the sender.
|
|
161
|
+
*
|
|
162
|
+
|
|
163
|
+
|
|
164
|
+
|
|
165
|
+
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
|
|
177
|
+
* @param ciphertext - Ciphertext to decrypt
|
|
178
|
+
* @param aad - Additional authenticated data
|
|
179
|
+
*
|
|
180
|
+
* @returns A Promise that resolves to the decrypted plaintext.
|
|
181
|
+
*/
|
|
182
|
+
Open(ciphertext: Uint8Array, aad?: Uint8Array): Promise<Uint8Array>;
|
|
183
|
+
/**
|
|
184
|
+
* Exports a secret using a variable-length pseudorandom function (PRF).
|
|
185
|
+
*
|
|
186
|
+
* The exported secret is indistinguishable from a uniformly random bitstring of equal length.
|
|
187
|
+
*
|
|
188
|
+
|
|
189
|
+
|
|
190
|
+
|
|
191
|
+
|
|
192
|
+
|
|
193
|
+
|
|
194
|
+
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
|
|
198
|
+
|
|
199
|
+
|
|
200
|
+
* @param exporterContext - Context for domain separation
|
|
201
|
+
* @param length - Desired length of exported secret in bytes
|
|
202
|
+
*
|
|
203
|
+
* @returns A Promise that resolves to the exported secret.
|
|
204
|
+
*/
|
|
205
|
+
Export(exporterContext: Uint8Array, length: number): Promise<Uint8Array>;
|
|
206
|
+
}
|
|
207
|
+
export type { RecipientContext };
|
|
208
|
+
/**
|
|
209
|
+
* Hybrid Public Key Encryption (HPKE) suite combining a KEM, KDF, and AEAD.
|
|
210
|
+
*
|
|
211
|
+
* Implements an authenticated encryption encapsulation format that combines a semi-static
|
|
212
|
+
* asymmetric key exchange with a symmetric cipher. This was originally defined in an Informational
|
|
213
|
+
* document on the IRTF stream as [RFC 9180](https://www.rfc-editor.org/rfc/rfc9180.html) and is now
|
|
214
|
+
* being republished as a Standards Track document of the IETF as
|
|
215
|
+
* [draft-ietf-hpke-hpke](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-02).
|
|
216
|
+
*
|
|
217
|
+
* HPKE provides a variant of public key encryption for arbitrary-sized plaintexts using a recipient
|
|
218
|
+
* public key. It supports two modes:
|
|
219
|
+
*
|
|
220
|
+
* - Base mode: Encryption to a public key without sender authentication
|
|
221
|
+
* - PSK mode: Encryption with pre-shared key authentication
|
|
222
|
+
*
|
|
223
|
+
* The cipher suite consists of:
|
|
224
|
+
*
|
|
225
|
+
* - KEM: Key Encapsulation Mechanism for establishing shared secrets
|
|
226
|
+
* - KDF: Key Derivation Function for deriving symmetric keys
|
|
227
|
+
* - AEAD: Authenticated Encryption with Additional Data for encryption
|
|
228
|
+
*
|
|
229
|
+
* @group Core
|
|
230
|
+
*/
|
|
231
|
+
export declare class CipherSuite {
|
|
232
|
+
#private;
|
|
233
|
+
/**
|
|
234
|
+
* Creates a new HPKE cipher suite by combining a Key Encapsulation Mechanism (KEM), Key
|
|
235
|
+
* Derivation Function (KDF), and an Authenticated Encryption with Associated Data (AEAD)
|
|
236
|
+
* algorithm.
|
|
237
|
+
*
|
|
238
|
+
* A cipher suite defines the complete cryptographic configuration for HPKE operations. The choice
|
|
239
|
+
* of algorithms affects security properties, performance, and compatibility across different
|
|
240
|
+
* platforms and runtimes.
|
|
241
|
+
*
|
|
242
|
+
|
|
243
|
+
|
|
244
|
+
|
|
245
|
+
|
|
246
|
+
|
|
247
|
+
|
|
248
|
+
|
|
249
|
+
|
|
250
|
+
|
|
251
|
+
|
|
252
|
+
|
|
253
|
+
|
|
254
|
+
|
|
255
|
+
|
|
256
|
+
|
|
257
|
+
|
|
258
|
+
|
|
259
|
+
|
|
260
|
+
|
|
261
|
+
|
|
262
|
+
|
|
263
|
+
|
|
264
|
+
|
|
265
|
+
|
|
266
|
+
|
|
267
|
+
|
|
268
|
+
|
|
269
|
+
|
|
270
|
+
|
|
271
|
+
|
|
272
|
+
|
|
273
|
+
|
|
274
|
+
|
|
275
|
+
|
|
276
|
+
|
|
277
|
+
|
|
278
|
+
|
|
279
|
+
|
|
280
|
+
|
|
281
|
+
|
|
282
|
+
|
|
283
|
+
|
|
284
|
+
* @param KEM - KEM implementation factory. Must return an object conforming to the {@link KEM}
|
|
285
|
+
* interface.
|
|
286
|
+
* @param KDF - KDF implementation factory. Must return an object conforming to the {@link KDF}
|
|
287
|
+
* interface.
|
|
288
|
+
* @param AEAD - AEAD implementation factory. Must return an object conforming to the {@link AEAD}
|
|
289
|
+
* interface.
|
|
290
|
+
* @see {@link KEMFactory Available KEMs}
|
|
291
|
+
* @see {@link KDFFactory Available KDFs}
|
|
292
|
+
* @see {@link AEADFactory Available AEADs}
|
|
293
|
+
*/
|
|
294
|
+
constructor(KEM: KEMFactory, KDF: KDFFactory, AEAD: AEADFactory);
|
|
295
|
+
/**
|
|
296
|
+
* Provides read-only access to this suite's KEM identifier, name, and other attributes.
|
|
297
|
+
*
|
|
298
|
+
* @returns An object with this suite's Key Encapsulation Mechanism (KEM) properties.
|
|
299
|
+
*/
|
|
300
|
+
get KEM(): {
|
|
301
|
+
/** The identifier of this suite's KEM */
|
|
302
|
+
id: number;
|
|
303
|
+
/** The name of this suite's KEM */
|
|
304
|
+
name: string;
|
|
305
|
+
/** The length in bytes of this suite's KEM produced shared secret */
|
|
306
|
+
Nsecret: number;
|
|
307
|
+
/** The length in bytes of this suite's KEM produced encapsulated secret */
|
|
308
|
+
Nenc: number;
|
|
309
|
+
/** The length in bytes of this suite's KEM public key */
|
|
310
|
+
Npk: number;
|
|
311
|
+
/** The length in bytes of this suite's KEM private key */
|
|
312
|
+
Nsk: number;
|
|
313
|
+
};
|
|
314
|
+
/**
|
|
315
|
+
* Provides read-only access to this suite's KDF identifier, name, and other attributes.
|
|
316
|
+
*
|
|
317
|
+
* @returns An object with this suite's Key Derivation Function (KDF) properties.
|
|
318
|
+
*/
|
|
319
|
+
get KDF(): {
|
|
320
|
+
/** The identifier of this suite's KDF */
|
|
321
|
+
id: number;
|
|
322
|
+
/** The name of this suite's KDF */
|
|
323
|
+
name: string;
|
|
324
|
+
/**
|
|
325
|
+
* When 1, this suite's KDF is a one-stage (Derive) KDF.
|
|
326
|
+
*
|
|
327
|
+
* When 2, this suite's KDF is a two-stage (Extract and Expand) KDF.
|
|
328
|
+
*/
|
|
329
|
+
stages: 1 | 2;
|
|
330
|
+
/**
|
|
331
|
+
* For one-stage KDF: The security strength of this suite's KDF, in bytes.
|
|
332
|
+
*
|
|
333
|
+
* For two-stage KDF: The output size of this suite's KDF Extract() function in bytes.
|
|
334
|
+
*/
|
|
335
|
+
Nh: number;
|
|
336
|
+
};
|
|
337
|
+
/**
|
|
338
|
+
* Provides read-only access to this suite's AEAD identifier, name, and other attributes.
|
|
339
|
+
*
|
|
340
|
+
* @returns An object with this suite's Authenticated Encryption with Associated Data (AEAD)
|
|
341
|
+
* cipher properties.
|
|
342
|
+
*/
|
|
343
|
+
get AEAD(): {
|
|
344
|
+
/** The identifier of this suite's AEAD */
|
|
345
|
+
id: number;
|
|
346
|
+
/** The name of this suite's AEAD */
|
|
347
|
+
name: string;
|
|
348
|
+
/** The length in bytes of a key for this suite's AEAD */
|
|
349
|
+
Nk: number;
|
|
350
|
+
/** The length in bytes of a nonce for this suite's AEAD */
|
|
351
|
+
Nn: number;
|
|
352
|
+
/** The length in bytes of an authentication tag for this suite's AEAD */
|
|
353
|
+
Nt: number;
|
|
354
|
+
};
|
|
355
|
+
/**
|
|
356
|
+
* Generates a random key pair for this CipherSuite. By default, private keys are generated as
|
|
357
|
+
* non-extractable (their value cannot be exported).
|
|
358
|
+
*
|
|
359
|
+
* @category Key Management
|
|
360
|
+
|
|
361
|
+
|
|
362
|
+
|
|
363
|
+
|
|
364
|
+
|
|
365
|
+
|
|
366
|
+
|
|
367
|
+
* @param extractable - Whether the generated key pair's private key should be extractable (e.g.
|
|
368
|
+
* by {@link SerializePrivateKey}) (default: false)
|
|
369
|
+
*
|
|
370
|
+
* @returns A Promise that resolves to a generated key pair.
|
|
371
|
+
*/
|
|
372
|
+
GenerateKeyPair(extractable?: boolean): Promise<KeyPair>;
|
|
373
|
+
/**
|
|
374
|
+
* Deterministically derives a key pair for this CipherSuite from input keying material. By
|
|
375
|
+
* default, private keys are derived as non-extractable (their value cannot be exported).
|
|
376
|
+
*
|
|
377
|
+
* An `ikm` input MUST NOT be reused elsewhere, particularly not with `DeriveKeyPair()` of a
|
|
378
|
+
* different KEM.
|
|
379
|
+
*
|
|
380
|
+
* @category Key Management
|
|
381
|
+
|
|
382
|
+
|
|
383
|
+
|
|
384
|
+
|
|
385
|
+
|
|
386
|
+
|
|
387
|
+
|
|
388
|
+
|
|
389
|
+
* @param ikm - Input keying material (must be at least {@link CipherSuite.KEM Nsk} bytes)
|
|
390
|
+
* @param extractable - Whether the derived key pair's private key should be extractable (e.g. by
|
|
391
|
+
* {@link SerializePrivateKey}) (default: false)
|
|
392
|
+
*
|
|
393
|
+
* @returns A Promise that resolves to the derived key pair.
|
|
394
|
+
*/
|
|
395
|
+
DeriveKeyPair(ikm: Uint8Array, extractable?: boolean): Promise<KeyPair>;
|
|
396
|
+
/**
|
|
397
|
+
* Serializes an extractable private key to bytes.
|
|
398
|
+
*
|
|
399
|
+
* @category Key Management
|
|
400
|
+
|
|
401
|
+
|
|
402
|
+
|
|
403
|
+
|
|
404
|
+
|
|
405
|
+
|
|
406
|
+
|
|
407
|
+
|
|
408
|
+
* @param privateKey - Private key to serialize
|
|
409
|
+
*
|
|
410
|
+
* @returns A Promise that resolves to the serialized private key.
|
|
411
|
+
*/
|
|
412
|
+
SerializePrivateKey(privateKey: Key): Promise<Uint8Array>;
|
|
413
|
+
/**
|
|
414
|
+
* Serializes a public key to bytes.
|
|
415
|
+
*
|
|
416
|
+
* @category Key Management
|
|
417
|
+
|
|
418
|
+
|
|
419
|
+
|
|
420
|
+
|
|
421
|
+
|
|
422
|
+
|
|
423
|
+
|
|
424
|
+
|
|
425
|
+
* @param publicKey - Public key to serialize
|
|
426
|
+
*
|
|
427
|
+
* @returns A Promise that resolves to the serialized public key.
|
|
428
|
+
*/
|
|
429
|
+
SerializePublicKey(publicKey: Key): Promise<Uint8Array>;
|
|
430
|
+
/**
|
|
431
|
+
* Deserializes a private key from bytes. By default, private keys are deserialized as
|
|
432
|
+
* non-extractable (their value cannot be exported).
|
|
433
|
+
*
|
|
434
|
+
* @category Key Management
|
|
435
|
+
|
|
436
|
+
|
|
437
|
+
|
|
438
|
+
|
|
439
|
+
|
|
440
|
+
|
|
441
|
+
|
|
442
|
+
|
|
443
|
+
* @param privateKey - Serialized private key
|
|
444
|
+
* @param extractable - Whether the deserialized private key should be extractable (e.g. by
|
|
445
|
+
* {@link SerializePrivateKey}) (default: false)
|
|
446
|
+
*
|
|
447
|
+
* @returns A Promise that resolves to the deserialized private key.
|
|
448
|
+
*/
|
|
449
|
+
DeserializePrivateKey(privateKey: Uint8Array, extractable?: boolean): Promise<Key>;
|
|
450
|
+
/**
|
|
451
|
+
* Deserializes a public key from bytes. Public keys are always deserialized as extractable (their
|
|
452
|
+
* value can be exported, e.g. by {@link SerializePublicKey}).
|
|
453
|
+
*
|
|
454
|
+
* @category Key Management
|
|
455
|
+
|
|
456
|
+
|
|
457
|
+
|
|
458
|
+
|
|
459
|
+
|
|
460
|
+
|
|
461
|
+
|
|
462
|
+
|
|
463
|
+
* @param publicKey - Serialized public key
|
|
464
|
+
*
|
|
465
|
+
* @returns A Promise that resolves to the deserialized public key.
|
|
466
|
+
*/
|
|
467
|
+
DeserializePublicKey(publicKey: Uint8Array): Promise<Key>;
|
|
468
|
+
/**
|
|
469
|
+
* Single-shot API for encrypting a single message. It combines context setup and encryption in
|
|
470
|
+
* one call.
|
|
471
|
+
*
|
|
472
|
+
* Mode selection:
|
|
473
|
+
*
|
|
474
|
+
* - If the options `psk` and `pskId` are omitted: Base mode (unauthenticated)
|
|
475
|
+
* - If the options `psk` and `pskId` are provided: PSK mode (authenticated with pre-shared key)
|
|
476
|
+
*
|
|
477
|
+
* @category Single-Shot APIs
|
|
478
|
+
|
|
479
|
+
|
|
480
|
+
|
|
481
|
+
|
|
482
|
+
|
|
483
|
+
|
|
484
|
+
|
|
485
|
+
|
|
486
|
+
|
|
487
|
+
|
|
488
|
+
|
|
489
|
+
* @param publicKey - Recipient's public key
|
|
490
|
+
* @param plaintext - Plaintext to encrypt
|
|
491
|
+
* @param options - Options
|
|
492
|
+
* @param options.aad - Additional authenticated data passed to the AEAD
|
|
493
|
+
* @param options.info - Application-supplied information
|
|
494
|
+
* @param options.psk - Pre-shared key (for PSK modes)
|
|
495
|
+
* @param options.pskId - Pre-shared key identifier (for PSK modes)
|
|
496
|
+
*
|
|
497
|
+
* @returns A Promise that resolves to an object containing the encapsulated secret and
|
|
498
|
+
* ciphertext. The ciphertext is {@link CipherSuite.AEAD Nt} bytes longer than the plaintext. The
|
|
499
|
+
* encapsulated secret is {@link CipherSuite.KEM Nenc} bytes.
|
|
500
|
+
*/
|
|
501
|
+
Seal(publicKey: Key, plaintext: Uint8Array, options?: {
|
|
502
|
+
aad?: Uint8Array;
|
|
503
|
+
info?: Uint8Array;
|
|
504
|
+
psk?: Uint8Array;
|
|
505
|
+
pskId?: Uint8Array;
|
|
506
|
+
}): Promise<{
|
|
507
|
+
encapsulatedSecret: Uint8Array;
|
|
508
|
+
ciphertext: Uint8Array;
|
|
509
|
+
}>;
|
|
510
|
+
/**
|
|
511
|
+
* Single-shot API for decrypting a single message.
|
|
512
|
+
*
|
|
513
|
+
* It combines context setup and decryption in one call.
|
|
514
|
+
*
|
|
515
|
+
* Mode selection:
|
|
516
|
+
*
|
|
517
|
+
* - If the options `psk` and `pskId` are omitted: Base mode (unauthenticated)
|
|
518
|
+
* - If the options `psk` and `pskId` are provided: PSK mode (authenticated with pre-shared key)
|
|
519
|
+
*
|
|
520
|
+
* @category Single-Shot APIs
|
|
521
|
+
|
|
522
|
+
|
|
523
|
+
|
|
524
|
+
|
|
525
|
+
|
|
526
|
+
|
|
527
|
+
|
|
528
|
+
|
|
529
|
+
|
|
530
|
+
|
|
531
|
+
|
|
532
|
+
|
|
533
|
+
|
|
534
|
+
* @param privateKey - Recipient's private key or key pair
|
|
535
|
+
* @param encapsulatedSecret - Encapsulated secret from the sender
|
|
536
|
+
* @param ciphertext - Ciphertext to decrypt
|
|
537
|
+
* @param options - Options
|
|
538
|
+
* @param options.aad - Additional authenticated data
|
|
539
|
+
* @param options.info - Application-supplied information
|
|
540
|
+
* @param options.psk - Pre-shared key (for PSK mode)
|
|
541
|
+
* @param options.pskId - Pre-shared key identifier (for PSK mode)
|
|
542
|
+
*
|
|
543
|
+
* @returns A Promise that resolves to the decrypted plaintext.
|
|
544
|
+
*/
|
|
545
|
+
Open(privateKey: Key | KeyPair, encapsulatedSecret: Uint8Array, ciphertext: Uint8Array, options?: {
|
|
546
|
+
aad?: Uint8Array;
|
|
547
|
+
info?: Uint8Array;
|
|
548
|
+
psk?: Uint8Array;
|
|
549
|
+
pskId?: Uint8Array;
|
|
550
|
+
}): Promise<Uint8Array>;
|
|
551
|
+
/**
|
|
552
|
+
* Single-shot API for deriving a secret known only to sender and recipient.
|
|
553
|
+
*
|
|
554
|
+
* It combines context setup and secret export in one call.
|
|
555
|
+
*
|
|
556
|
+
* The exported secret is indistinguishable from a uniformly random bitstring of equal length.
|
|
557
|
+
*
|
|
558
|
+
* @category Single-Shot APIs
|
|
559
|
+
|
|
560
|
+
|
|
561
|
+
|
|
562
|
+
|
|
563
|
+
|
|
564
|
+
|
|
565
|
+
|
|
566
|
+
|
|
567
|
+
|
|
568
|
+
|
|
569
|
+
|
|
570
|
+
|
|
571
|
+
|
|
572
|
+
|
|
573
|
+
|
|
574
|
+
* @param publicKey - Recipient's public key
|
|
575
|
+
* @param exporterContext - Context of the export operation
|
|
576
|
+
* @param length - Desired length of exported secret in bytes
|
|
577
|
+
* @param options - Options
|
|
578
|
+
* @param options.info - Application-supplied information
|
|
579
|
+
* @param options.psk - Pre-shared key (for PSK modes)
|
|
580
|
+
* @param options.pskId - Pre-shared key identifier (for PSK modes)
|
|
581
|
+
*
|
|
582
|
+
* @returns A Promise that resolves to an object containing the encapsulated secret and the
|
|
583
|
+
* exported secret.
|
|
584
|
+
*/
|
|
585
|
+
SendExport(publicKey: Key, exporterContext: Uint8Array, length: number, options?: {
|
|
586
|
+
info?: Uint8Array;
|
|
587
|
+
psk?: Uint8Array;
|
|
588
|
+
pskId?: Uint8Array;
|
|
589
|
+
}): Promise<{
|
|
590
|
+
encapsulatedSecret: Uint8Array;
|
|
591
|
+
exportedSecret: Uint8Array;
|
|
592
|
+
}>;
|
|
593
|
+
/**
|
|
594
|
+
* Single-shot API for receiving an exported secret.
|
|
595
|
+
*
|
|
596
|
+
* It combines context setup and secret export in one call.
|
|
597
|
+
*
|
|
598
|
+
* @category Single-Shot APIs
|
|
599
|
+
|
|
600
|
+
|
|
601
|
+
|
|
602
|
+
|
|
603
|
+
|
|
604
|
+
|
|
605
|
+
|
|
606
|
+
|
|
607
|
+
|
|
608
|
+
|
|
609
|
+
|
|
610
|
+
|
|
611
|
+
|
|
612
|
+
|
|
613
|
+
|
|
614
|
+
|
|
615
|
+
|
|
616
|
+
|
|
617
|
+
|
|
618
|
+
* @param privateKey - Recipient's private key or key pair
|
|
619
|
+
* @param encapsulatedSecret - Encapsulated secret from the sender
|
|
620
|
+
* @param exporterContext - Context of the export operation
|
|
621
|
+
* @param length - Desired length of exported secret in bytes
|
|
622
|
+
* @param options - Options
|
|
623
|
+
* @param options.info - Application-supplied information
|
|
624
|
+
* @param options.psk - Pre-shared key (for PSK mode)
|
|
625
|
+
* @param options.pskId - Pre-shared key identifier (for PSK mode)
|
|
626
|
+
*
|
|
627
|
+
* @returns A Promise that resolves to the exported secret.
|
|
628
|
+
*/
|
|
629
|
+
ReceiveExport(privateKey: Key | KeyPair, encapsulatedSecret: Uint8Array, exporterContext: Uint8Array, length: number, options?: {
|
|
630
|
+
info?: Uint8Array;
|
|
631
|
+
psk?: Uint8Array;
|
|
632
|
+
pskId?: Uint8Array;
|
|
633
|
+
}): Promise<Uint8Array>;
|
|
634
|
+
/**
|
|
635
|
+
* Establishes a sender encryption context.
|
|
636
|
+
*
|
|
637
|
+
* Creates a context that can be used to encrypt multiple messages to the same recipient,
|
|
638
|
+
* amortizing the cost of the public key operations.
|
|
639
|
+
*
|
|
640
|
+
* Mode selection:
|
|
641
|
+
*
|
|
642
|
+
* - If the options `psk` and `pskId` are omitted: Base mode (unauthenticated)
|
|
643
|
+
* - If the options `psk` and `pskId` are provided: PSK mode (authenticated with pre-shared key)
|
|
644
|
+
*
|
|
645
|
+
* The returned context maintains a sequence number that increments with each encryption, ensuring
|
|
646
|
+
* nonce uniqueness.
|
|
647
|
+
*
|
|
648
|
+
* @category Encryption Context
|
|
649
|
+
|
|
650
|
+
|
|
651
|
+
|
|
652
|
+
|
|
653
|
+
|
|
654
|
+
|
|
655
|
+
|
|
656
|
+
|
|
657
|
+
|
|
658
|
+
|
|
659
|
+
|
|
660
|
+
|
|
661
|
+
|
|
662
|
+
|
|
663
|
+
|
|
664
|
+
|
|
665
|
+
|
|
666
|
+
|
|
667
|
+
* @param publicKey - Recipient's public key
|
|
668
|
+
* @param options - Options
|
|
669
|
+
* @param options.info - Application-supplied information
|
|
670
|
+
* @param options.psk - Pre-shared key (for PSK modes)
|
|
671
|
+
* @param options.pskId - Pre-shared key identifier (for PSK modes)
|
|
672
|
+
*
|
|
673
|
+
* @returns A Promise that resolves to an object containing the encapsulated secret and the sender
|
|
674
|
+
* context (`ctx`). The encapsulated secret is {@link CipherSuite.KEM Nenc} bytes.
|
|
675
|
+
*/
|
|
676
|
+
SetupSender(publicKey: Key, options?: {
|
|
677
|
+
info?: Uint8Array;
|
|
678
|
+
psk?: Uint8Array;
|
|
679
|
+
pskId?: Uint8Array;
|
|
680
|
+
}): Promise<{
|
|
681
|
+
encapsulatedSecret: Uint8Array;
|
|
682
|
+
ctx: SenderContext;
|
|
683
|
+
}>;
|
|
684
|
+
/**
|
|
685
|
+
* Establishes a recipient decryption context.
|
|
686
|
+
*
|
|
687
|
+
* Creates a context that can be used to decrypt multiple messages from the same sender.
|
|
688
|
+
*
|
|
689
|
+
* Mode selection:
|
|
690
|
+
*
|
|
691
|
+
* - If the options `psk` and `pskId` are omitted: Base mode (unauthenticated)
|
|
692
|
+
* - If the options `psk` and `pskId` are provided: PSK mode (authenticated with pre-shared key)
|
|
693
|
+
*
|
|
694
|
+
* @category Encryption Context
|
|
695
|
+
|
|
696
|
+
|
|
697
|
+
|
|
698
|
+
|
|
699
|
+
|
|
700
|
+
|
|
701
|
+
|
|
702
|
+
|
|
703
|
+
|
|
704
|
+
|
|
705
|
+
|
|
706
|
+
|
|
707
|
+
|
|
708
|
+
|
|
709
|
+
|
|
710
|
+
|
|
711
|
+
|
|
712
|
+
|
|
713
|
+
|
|
714
|
+
|
|
715
|
+
|
|
716
|
+
|
|
717
|
+
|
|
718
|
+
|
|
719
|
+
|
|
720
|
+
|
|
721
|
+
|
|
722
|
+
* @param privateKey - Recipient's private key or key pair
|
|
723
|
+
* @param encapsulatedSecret - Encapsulated secret from the sender
|
|
724
|
+
* @param options - Options
|
|
725
|
+
* @param options.info - Application-supplied information
|
|
726
|
+
* @param options.psk - Pre-shared key (for PSK mode)
|
|
727
|
+
* @param options.pskId - Pre-shared key identifier (for PSK mode)
|
|
728
|
+
*
|
|
729
|
+
* @returns A Promise that resolves to the recipient context.
|
|
730
|
+
*/
|
|
731
|
+
SetupRecipient(privateKey: Key | KeyPair, encapsulatedSecret: Uint8Array, options?: {
|
|
732
|
+
info?: Uint8Array;
|
|
733
|
+
psk?: Uint8Array;
|
|
734
|
+
pskId?: Uint8Array;
|
|
735
|
+
}): Promise<RecipientContext>;
|
|
736
|
+
}
|
|
737
|
+
/**
|
|
738
|
+
* Error thrown when input validation fails.
|
|
739
|
+
*
|
|
740
|
+
* @ignore
|
|
741
|
+
* @group Errors
|
|
742
|
+
*/
|
|
743
|
+
export declare class ValidationError extends Error {
|
|
744
|
+
constructor(message?: string, options?: {
|
|
745
|
+
cause?: unknown;
|
|
746
|
+
});
|
|
747
|
+
}
|
|
748
|
+
/**
|
|
749
|
+
* Error thrown when key deserialization fails.
|
|
750
|
+
*
|
|
751
|
+
* @ignore
|
|
752
|
+
* @group Errors
|
|
753
|
+
*/
|
|
754
|
+
export declare class DeserializeError extends Error {
|
|
755
|
+
constructor(message?: string, options?: {
|
|
756
|
+
cause?: unknown;
|
|
757
|
+
});
|
|
758
|
+
}
|
|
759
|
+
/**
|
|
760
|
+
* Error thrown when encapsulation operation fails.
|
|
761
|
+
*
|
|
762
|
+
* @ignore
|
|
763
|
+
* @group Errors
|
|
764
|
+
*/
|
|
765
|
+
export declare class EncapError extends Error {
|
|
766
|
+
constructor(message?: string, options?: {
|
|
767
|
+
cause?: unknown;
|
|
768
|
+
});
|
|
769
|
+
}
|
|
770
|
+
/**
|
|
771
|
+
* Error thrown when decapsulation operation fails.
|
|
772
|
+
*
|
|
773
|
+
* @ignore
|
|
774
|
+
* @group Errors
|
|
775
|
+
*/
|
|
776
|
+
export declare class DecapError extends Error {
|
|
777
|
+
constructor(message?: string, options?: {
|
|
778
|
+
cause?: unknown;
|
|
779
|
+
});
|
|
780
|
+
}
|
|
781
|
+
/**
|
|
782
|
+
* Error thrown when AEAD decryption (open) operation fails.
|
|
783
|
+
*
|
|
784
|
+
* @ignore
|
|
785
|
+
* @group Errors
|
|
786
|
+
*/
|
|
787
|
+
export declare class OpenError extends Error {
|
|
788
|
+
constructor(message?: string, options?: {
|
|
789
|
+
cause?: unknown;
|
|
790
|
+
});
|
|
791
|
+
}
|
|
792
|
+
/**
|
|
793
|
+
* Error thrown when the message sequence number limit is reached.
|
|
794
|
+
*
|
|
795
|
+
* @ignore
|
|
796
|
+
* @group Errors
|
|
797
|
+
*/
|
|
798
|
+
export declare class MessageLimitReachedError extends Error {
|
|
799
|
+
constructor(message?: string, options?: {
|
|
800
|
+
cause?: unknown;
|
|
801
|
+
});
|
|
802
|
+
}
|
|
803
|
+
/**
|
|
804
|
+
* Error thrown when key pair derivation fails.
|
|
805
|
+
*
|
|
806
|
+
* @ignore
|
|
807
|
+
* @group Errors
|
|
808
|
+
*/
|
|
809
|
+
export declare class DeriveKeyPairError extends Error {
|
|
810
|
+
constructor(message?: string, options?: {
|
|
811
|
+
cause?: unknown;
|
|
812
|
+
});
|
|
813
|
+
}
|
|
814
|
+
/**
|
|
815
|
+
* Error thrown when the runtime doesn't support an algorithm.
|
|
816
|
+
*
|
|
817
|
+
* @ignore
|
|
818
|
+
* @group Errors
|
|
819
|
+
*/
|
|
820
|
+
export declare class NotSupportedError extends Error {
|
|
821
|
+
constructor(message?: string, options?: {
|
|
822
|
+
cause?: unknown;
|
|
823
|
+
});
|
|
824
|
+
}
|
|
825
|
+
interface Triple {
|
|
826
|
+
readonly id: Uint8Array;
|
|
827
|
+
readonly KEM: Readonly<KEM>;
|
|
828
|
+
readonly KDF: Readonly<KDF>;
|
|
829
|
+
readonly AEAD: Readonly<AEAD>;
|
|
830
|
+
}
|
|
831
|
+
/** Mode identifier for Base mode */
|
|
832
|
+
export declare const MODE_BASE = 0;
|
|
833
|
+
/** Mode identifier for PSK mode */
|
|
834
|
+
export declare const MODE_PSK = 1;
|
|
835
|
+
/**
|
|
836
|
+
* Factory function that returns a KEM implementation.
|
|
837
|
+
*
|
|
838
|
+
* The following [Web Cryptography](https://www.w3.org/TR/webcrypto-2/)-based implementations are
|
|
839
|
+
* exported by this module:
|
|
840
|
+
*
|
|
841
|
+
* Traditional:
|
|
842
|
+
*
|
|
843
|
+
* - {@link KEM_DHKEM_P256_HKDF_SHA256 | DHKEM(P-256, HKDF-SHA256)}
|
|
844
|
+
* - {@link KEM_DHKEM_P384_HKDF_SHA384 | DHKEM(P-384, HKDF-SHA384)}
|
|
845
|
+
* - {@link KEM_DHKEM_P521_HKDF_SHA512 | DHKEM(P-521, HKDF-SHA512)}
|
|
846
|
+
* - {@link KEM_DHKEM_X25519_HKDF_SHA256 | DHKEM(X25519, HKDF-SHA256)}
|
|
847
|
+
* - {@link KEM_DHKEM_X448_HKDF_SHA512 | DHKEM(X448, HKDF-SHA512)}
|
|
848
|
+
*
|
|
849
|
+
* Post-quantum/Traditional (PQ/T Hybrid):
|
|
850
|
+
*
|
|
851
|
+
* - {@link KEM_MLKEM768_P256 | MLKEM768-P256}
|
|
852
|
+
* - {@link KEM_MLKEM768_X25519 | MLKEM768-X25519 (aka X-Wing)}
|
|
853
|
+
* - {@link KEM_MLKEM1024_P384 | MLKEM1024-P384}
|
|
854
|
+
*
|
|
855
|
+
* Post-quantum (PQ):
|
|
856
|
+
*
|
|
857
|
+
* - {@link KEM_ML_KEM_512 | ML-KEM-512}
|
|
858
|
+
* - {@link KEM_ML_KEM_768 | ML-KEM-768}
|
|
859
|
+
* - {@link KEM_ML_KEM_1024 | ML-KEM-1024}
|
|
860
|
+
*
|
|
861
|
+
* > [!TIP]\
|
|
862
|
+
* > {@link CipherSuite} is not limited to using only these exported KEM implementations. Any function
|
|
863
|
+
* > returning an object conforming to the {@link KEM} interface can be used. Such implementations not
|
|
864
|
+
* > reliant on Web Cryptography are exported by
|
|
865
|
+
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
866
|
+
*/
|
|
867
|
+
export type KEMFactory = () => Readonly<KEM>;
|
|
868
|
+
/**
|
|
869
|
+
* Factory function that returns a KDF implementation.
|
|
870
|
+
*
|
|
871
|
+
* The following [Web Cryptography](https://www.w3.org/TR/webcrypto-2/)-based implementations are
|
|
872
|
+
* exported by this module:
|
|
873
|
+
*
|
|
874
|
+
* - {@link KDF_HKDF_SHA256 | HKDF-SHA256}
|
|
875
|
+
* - {@link KDF_HKDF_SHA384 | HKDF-SHA384}
|
|
876
|
+
* - {@link KDF_HKDF_SHA512 | HKDF-SHA512}
|
|
877
|
+
* - {@link KDF_SHAKE128 | SHAKE128}
|
|
878
|
+
* - {@link KDF_SHAKE256 | SHAKE256}
|
|
879
|
+
*
|
|
880
|
+
* > [!TIP]\
|
|
881
|
+
* > {@link CipherSuite} is not limited to using only these exported KDF implementations. Any function
|
|
882
|
+
* > returning an object conforming to the {@link KDF} interface can be used. Such implementations not
|
|
883
|
+
* > reliant on Web Cryptography are exported by
|
|
884
|
+
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
885
|
+
*/
|
|
886
|
+
export type KDFFactory = () => Readonly<KDF>;
|
|
887
|
+
/**
|
|
888
|
+
* Factory function that returns an AEAD implementation.
|
|
889
|
+
*
|
|
890
|
+
* The following [Web Cryptography](https://www.w3.org/TR/webcrypto-2/)-based implementations are
|
|
891
|
+
* exported by this module:
|
|
892
|
+
*
|
|
893
|
+
* - {@link AEAD_AES_128_GCM | AES-128-GCM}
|
|
894
|
+
* - {@link AEAD_AES_256_GCM | AES-256-GCM}
|
|
895
|
+
* - {@link AEAD_ChaCha20Poly1305 | ChaCha20Poly1305}
|
|
896
|
+
* - {@link AEAD_EXPORT_ONLY | Export-only}
|
|
897
|
+
*
|
|
898
|
+
* > [!TIP]\
|
|
899
|
+
* > {@link CipherSuite} is not limited to using only these exported AEAD implementations. Any function
|
|
900
|
+
* > returning an object conforming to the {@link AEAD} interface can be used. Such implementations not
|
|
901
|
+
* > reliant on Web Cryptography are exported by
|
|
902
|
+
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
903
|
+
*/
|
|
904
|
+
export type AEADFactory = () => Readonly<AEAD>;
|
|
905
|
+
/**
|
|
906
|
+
* Represents a cryptographic key pair consisting of a public key and private key.
|
|
907
|
+
*
|
|
908
|
+
* These keys are used throughout HPKE for key encapsulation mechanisms (KEM). Key pairs are
|
|
909
|
+
* randomly generated using {@link CipherSuite.GenerateKeyPair} or deterministically derived from a
|
|
910
|
+
* seed using {@link CipherSuite.DeriveKeyPair}.
|
|
911
|
+
*
|
|
912
|
+
* Key Usage:
|
|
913
|
+
*
|
|
914
|
+
* - Public Key: Used by senders for encryption operations (passed to {@link CipherSuite.SetupSender}
|
|
915
|
+
* or {@link CipherSuite.Seal}). These keys are distributed by recipients.
|
|
916
|
+
* - Private Key: Used by recipients for decryption operations (passed to
|
|
917
|
+
* {@link CipherSuite.SetupRecipient} or {@link CipherSuite.Open}). These are not distributed and
|
|
918
|
+
* kept private.
|
|
919
|
+
*/
|
|
920
|
+
export interface KeyPair {
|
|
921
|
+
/** The public key, used for encryption operations. */
|
|
922
|
+
readonly publicKey: Readonly<Key>;
|
|
923
|
+
/** The private key, used for decryption operations. */
|
|
924
|
+
readonly privateKey: Readonly<Key>;
|
|
925
|
+
}
|
|
926
|
+
/**
|
|
927
|
+
* A minimal key representation interface.
|
|
928
|
+
*
|
|
929
|
+
* This interface is designed to be compatible with Web Cryptography's CryptoKey objects while
|
|
930
|
+
* allowing for custom key implementations that may not have all CryptoKey properties. It includes
|
|
931
|
+
* only the essential properties needed for HPKE operations and validations.
|
|
932
|
+
*/
|
|
933
|
+
export interface Key {
|
|
934
|
+
/** The key algorithm properties */
|
|
935
|
+
readonly algorithm: {
|
|
936
|
+
/** The algorithm identifier for the key. */
|
|
937
|
+
name: string;
|
|
938
|
+
};
|
|
939
|
+
/** Whether the key material can be extracted. */
|
|
940
|
+
readonly extractable: boolean;
|
|
941
|
+
/** The type of key: 'private' or 'public' */
|
|
942
|
+
readonly type: 'private' | 'public' | (string & {});
|
|
943
|
+
}
|
|
944
|
+
/**
|
|
945
|
+
* Concatenates multiple Uint8Array buffers into a single Uint8Array. It's exported for use in
|
|
946
|
+
* custom KEM, KDF, or AEAD implementations.
|
|
947
|
+
*
|
|
948
|
+
* @param buffers - Variable number of Uint8Array buffers to concatenate
|
|
949
|
+
*
|
|
950
|
+
* @returns A new Uint8Array containing all input buffers concatenated in order
|
|
951
|
+
* @group Utilities
|
|
952
|
+
*/
|
|
953
|
+
export declare function concat(...buffers: Uint8Array[]): Uint8Array;
|
|
954
|
+
/**
|
|
955
|
+
* Encodes an ASCII string into a Uint8Array.
|
|
956
|
+
*
|
|
957
|
+
* This utility function converts ASCII strings to byte arrays. It's exported for use in custom KEM,
|
|
958
|
+
* KDF, or AEAD implementations.
|
|
959
|
+
*
|
|
960
|
+
* @param string - ASCII string to encode
|
|
961
|
+
*
|
|
962
|
+
* @returns A Uint8Array containing the ASCII byte values
|
|
963
|
+
* @group Utilities
|
|
964
|
+
*/
|
|
965
|
+
export declare function encode(string: string): Uint8Array;
|
|
966
|
+
/**
|
|
967
|
+
* Performs labeled key derivation for one-stage KDFs.
|
|
968
|
+
*
|
|
969
|
+
* This function implements the LabeledDerive operation as specified in the HPKE specification for
|
|
970
|
+
* use with one-stage KDFs. It constructs a labeled input by concatenating:
|
|
971
|
+
*
|
|
972
|
+
* - The input keying material (`ikm`)
|
|
973
|
+
* - The version string "HPKE-v1"
|
|
974
|
+
* - The suite identifier (`suite_id`)
|
|
975
|
+
* - A length-prefixed label
|
|
976
|
+
* - The desired output length as a 2-byte encoding
|
|
977
|
+
* - Additional context
|
|
978
|
+
*
|
|
979
|
+
* The labeled input is then passed to the KDF's Derive function to produce L bytes of output. This
|
|
980
|
+
* ensures domain separation between different uses of the KDF in HPKE.
|
|
981
|
+
*
|
|
982
|
+
* @group Utilities
|
|
983
|
+
*/
|
|
984
|
+
export declare function LabeledDerive(KDF: Pick<KDF, 'Derive'>, suite_id: Uint8Array, ikm: Uint8Array, label: Uint8Array, context: Uint8Array, L: number): Promise<Uint8Array>;
|
|
985
|
+
/**
|
|
986
|
+
* Key Derivation Function (KDF) implementation interface.
|
|
987
|
+
*
|
|
988
|
+
* This implementation interface defines the contract for additional KDF implementations to be
|
|
989
|
+
* usable with {@link CipherSuite}. While this module provides built-in KDF implementations based on
|
|
990
|
+
* [Web Cryptography](https://www.w3.org/TR/webcrypto-2/), this interface is exported to allow
|
|
991
|
+
* custom KDF implementations that may not rely on Web Cryptography (e.g., using native bindings,
|
|
992
|
+
* alternative crypto libraries, or specialized hardware).
|
|
993
|
+
*
|
|
994
|
+
* Custom KDF implementations must conform to this interface to be compatible with
|
|
995
|
+
* {@link CipherSuite} and its APIs.
|
|
996
|
+
*
|
|
997
|
+
* KDF implementations are either one-stage or two-stage:
|
|
998
|
+
*
|
|
999
|
+
* - One-stage KDFs only implement {@link Derive}. The {@link Extract} and {@link Expand} methods will
|
|
1000
|
+
* not be called and may be no-op implementations.
|
|
1001
|
+
* - Two-stage KDFs only implement {@link Extract} and {@link Expand}. The {@link Derive} method will not
|
|
1002
|
+
* be called and may be a no-op implementation.
|
|
1003
|
+
*
|
|
1004
|
+
|
|
1005
|
+
|
|
1006
|
+
|
|
1007
|
+
|
|
1008
|
+
|
|
1009
|
+
|
|
1010
|
+
|
|
1011
|
+
|
|
1012
|
+
|
|
1013
|
+
|
|
1014
|
+
|
|
1015
|
+
|
|
1016
|
+
|
|
1017
|
+
|
|
1018
|
+
|
|
1019
|
+
|
|
1020
|
+
|
|
1021
|
+
|
|
1022
|
+
|
|
1023
|
+
|
|
1024
|
+
|
|
1025
|
+
|
|
1026
|
+
|
|
1027
|
+
|
|
1028
|
+
|
|
1029
|
+
|
|
1030
|
+
|
|
1031
|
+
|
|
1032
|
+
|
|
1033
|
+
|
|
1034
|
+
|
|
1035
|
+
|
|
1036
|
+
|
|
1037
|
+
|
|
1038
|
+
|
|
1039
|
+
|
|
1040
|
+
|
|
1041
|
+
|
|
1042
|
+
|
|
1043
|
+
|
|
1044
|
+
|
|
1045
|
+
|
|
1046
|
+
|
|
1047
|
+
|
|
1048
|
+
|
|
1049
|
+
|
|
1050
|
+
* @see [HPKE Cryptographic Dependencies](https://www.ietf.org/archive/id/draft-ietf-hpke-hpke-02.html#section-4)
|
|
1051
|
+
*/
|
|
1052
|
+
export interface KDF {
|
|
1053
|
+
/** KDF algorithm identifier */
|
|
1054
|
+
readonly id: number;
|
|
1055
|
+
/** Type discriminator, always 'KDF' */
|
|
1056
|
+
readonly type: 'KDF';
|
|
1057
|
+
/** Human-readable name of the KDF algorithm */
|
|
1058
|
+
readonly name: string;
|
|
1059
|
+
/**
|
|
1060
|
+
* For one-stage KDFs, the security strength of the KDF in bytes.
|
|
1061
|
+
*
|
|
1062
|
+
* For two-stage KDFs, the output size of the {@link Extract} function in bytes.
|
|
1063
|
+
*/
|
|
1064
|
+
readonly Nh: number;
|
|
1065
|
+
/** Number of stages (1 or 2) indicating one-stage or two-stage KDF */
|
|
1066
|
+
readonly stages: 1 | 2;
|
|
1067
|
+
/**
|
|
1068
|
+
* Extracts a pseudorandom key from input keying material.
|
|
1069
|
+
*
|
|
1070
|
+
* @param salt - Salt value
|
|
1071
|
+
* @param ikm - Input keying material
|
|
1072
|
+
*
|
|
1073
|
+
* @returns A promise resolving to the pseudorandom key
|
|
1074
|
+
*/
|
|
1075
|
+
Extract(salt: Uint8Array, ikm: Uint8Array): Promise<Uint8Array>;
|
|
1076
|
+
/**
|
|
1077
|
+
* Expands a pseudorandom key to the desired length.
|
|
1078
|
+
*
|
|
1079
|
+
* @param prk - Pseudorandom key
|
|
1080
|
+
* @param info - Context and application-specific information
|
|
1081
|
+
* @param L - Desired length of output keying material in bytes
|
|
1082
|
+
*
|
|
1083
|
+
* @returns A promise resolving to the output keying material
|
|
1084
|
+
*/
|
|
1085
|
+
Expand(prk: Uint8Array, info: Uint8Array, L: number): Promise<Uint8Array>;
|
|
1086
|
+
/**
|
|
1087
|
+
* Derives output keying material directly from labeled input keying material.
|
|
1088
|
+
*
|
|
1089
|
+
* @param labeled_ikm - Labeled input keying material
|
|
1090
|
+
* @param L - Desired length of output keying material in bytes
|
|
1091
|
+
*
|
|
1092
|
+
* @returns A promise resolving to the output keying material
|
|
1093
|
+
*/
|
|
1094
|
+
Derive(labeled_ikm: Uint8Array, L: number): Promise<Uint8Array>;
|
|
1095
|
+
}
|
|
1096
|
+
/**
|
|
1097
|
+
* Performs labeled extraction for two-stage KDFs.
|
|
1098
|
+
*
|
|
1099
|
+
* This function implements the LabeledExtract operation as specified in the HPKE specification for
|
|
1100
|
+
* use with two-stage KDFs. It constructs a labeled input by concatenating:
|
|
1101
|
+
*
|
|
1102
|
+
* - The version string "HPKE-v1"
|
|
1103
|
+
* - The suite identifier (`suite_id`)
|
|
1104
|
+
* - The label
|
|
1105
|
+
* - The input keying material (`ikm`)
|
|
1106
|
+
*
|
|
1107
|
+
* The labeled input is then passed to the KDF's Extract function along with the salt to produce a
|
|
1108
|
+
* pseudorandom key. This ensures domain separation between different uses of the KDF in HPKE.
|
|
1109
|
+
*
|
|
1110
|
+
* @group Utilities
|
|
1111
|
+
*/
|
|
1112
|
+
export declare function LabeledExtract(KDF: Pick<KDF, 'Extract'>, suite_id: Uint8Array, salt: Uint8Array, label: Uint8Array, ikm: Uint8Array): Promise<Uint8Array>;
|
|
1113
|
+
/**
|
|
1114
|
+
* Performs labeled expansion for two-stage KDFs.
|
|
1115
|
+
*
|
|
1116
|
+
* This function implements the LabeledExpand operation as specified in the HPKE specification for
|
|
1117
|
+
* use with two-stage KDFs. It constructs a labeled info string by concatenating:
|
|
1118
|
+
*
|
|
1119
|
+
* - The desired output length as a 2-byte encoding
|
|
1120
|
+
* - The version string "HPKE-v1"
|
|
1121
|
+
* - The suite identifier (`suite_id`)
|
|
1122
|
+
* - The label
|
|
1123
|
+
* - Additional info context
|
|
1124
|
+
*
|
|
1125
|
+
* The labeled info is then passed to the KDF's Expand function along with the pseudorandom key to
|
|
1126
|
+
* produce L bytes of output keying material. This ensures domain separation between different uses
|
|
1127
|
+
* of the KDF in HPKE.
|
|
1128
|
+
*
|
|
1129
|
+
* @group Utilities
|
|
1130
|
+
*/
|
|
1131
|
+
export declare function LabeledExpand(KDF: Pick<KDF, 'Expand'>, suite_id: Uint8Array, prk: Uint8Array, label: Uint8Array, info: Uint8Array, L: number): Promise<Uint8Array>;
|
|
1132
|
+
/**
|
|
1133
|
+
* Key Encapsulation Mechanism (KEM) implementation interface.
|
|
1134
|
+
*
|
|
1135
|
+
* This implementation interface defines the contract for additional KEM implementations to be
|
|
1136
|
+
* usable with {@link CipherSuite}. While this module provides built-in KEM implementations based on
|
|
1137
|
+
* [Web Cryptography](https://www.w3.org/TR/webcrypto-2/), this interface is exported to allow
|
|
1138
|
+
* custom KEM implementations that may not rely on Web Cryptography (e.g., using native bindings,
|
|
1139
|
+
* alternative crypto libraries, or specialized hardware).
|
|
1140
|
+
*
|
|
1141
|
+
* Custom KEM implementations must conform to this interface to be compatible with
|
|
1142
|
+
* {@link CipherSuite} and its APIs.
|
|
1143
|
+
*
|
|
1144
|
+
|
|
1145
|
+
|
|
1146
|
+
|
|
1147
|
+
|
|
1148
|
+
|
|
1149
|
+
|
|
1150
|
+
|
|
1151
|
+
|
|
1152
|
+
|
|
1153
|
+
|
|
1154
|
+
|
|
1155
|
+
|
|
1156
|
+
|
|
1157
|
+
|
|
1158
|
+
|
|
1159
|
+
|
|
1160
|
+
|
|
1161
|
+
|
|
1162
|
+
|
|
1163
|
+
|
|
1164
|
+
|
|
1165
|
+
|
|
1166
|
+
|
|
1167
|
+
|
|
1168
|
+
|
|
1169
|
+
|
|
1170
|
+
|
|
1171
|
+
|
|
1172
|
+
|
|
1173
|
+
|
|
1174
|
+
|
|
1175
|
+
|
|
1176
|
+
|
|
1177
|
+
|
|
1178
|
+
|
|
1179
|
+
|
|
1180
|
+
|
|
1181
|
+
|
|
1182
|
+
|
|
1183
|
+
|
|
1184
|
+
|
|
1185
|
+
|
|
1186
|
+
|
|
1187
|
+
|
|
1188
|
+
|
|
1189
|
+
|
|
1190
|
+
|
|
1191
|
+
|
|
1192
|
+
|
|
1193
|
+
|
|
1194
|
+
|
|
1195
|
+
|
|
1196
|
+
|
|
1197
|
+
|
|
1198
|
+
|
|
1199
|
+
|
|
1200
|
+
|
|
1201
|
+
|
|
1202
|
+
|
|
1203
|
+
|
|
1204
|
+
|
|
1205
|
+
|
|
1206
|
+
|
|
1207
|
+
|
|
1208
|
+
|
|
1209
|
+
|
|
1210
|
+
|
|
1211
|
+
|
|
1212
|
+
|
|
1213
|
+
|
|
1214
|
+
|
|
1215
|
+
|
|
1216
|
+
|
|
1217
|
+
|
|
1218
|
+
|
|
1219
|
+
|
|
1220
|
+
|
|
1221
|
+
|
|
1222
|
+
|
|
1223
|
+
* @see [HPKE Cryptographic Dependencies](https://www.ietf.org/archive/id/draft-ietf-hpke-hpke-02.html#section-4)
|
|
1224
|
+
*/
|
|
1225
|
+
export interface KEM {
|
|
1226
|
+
/** KEM algorithm identifier */
|
|
1227
|
+
readonly id: number;
|
|
1228
|
+
/** Type discriminator, always 'KEM' */
|
|
1229
|
+
readonly type: 'KEM';
|
|
1230
|
+
/** Human-readable name of the KEM algorithm */
|
|
1231
|
+
readonly name: string;
|
|
1232
|
+
/** Length in bytes of a KEM shared secret produced by this KEM */
|
|
1233
|
+
readonly Nsecret: number;
|
|
1234
|
+
/** Length in bytes of an encapsulated secret produced by this KEM */
|
|
1235
|
+
readonly Nenc: number;
|
|
1236
|
+
/** Length in bytes of a public key for this KEM */
|
|
1237
|
+
readonly Npk: number;
|
|
1238
|
+
/** Length in bytes of a private key for this KEM */
|
|
1239
|
+
readonly Nsk: number;
|
|
1240
|
+
/**
|
|
1241
|
+
* Derives a key pair deterministically from input keying material.
|
|
1242
|
+
*
|
|
1243
|
+
* @param ikm - Input keying material already validated to be at least {@link Nsk} bytes
|
|
1244
|
+
* @param extractable - Whether the private key should be extractable
|
|
1245
|
+
*
|
|
1246
|
+
* @returns A promise resolving to a {@link KeyPair}
|
|
1247
|
+
*/
|
|
1248
|
+
DeriveKeyPair(ikm: Uint8Array, extractable: boolean): Promise<KeyPair>;
|
|
1249
|
+
/**
|
|
1250
|
+
* Generates a random key pair.
|
|
1251
|
+
*
|
|
1252
|
+
* @param extractable - Whether the private key should be extractable
|
|
1253
|
+
*
|
|
1254
|
+
* @returns A promise resolving to a {@link KeyPair}
|
|
1255
|
+
*/
|
|
1256
|
+
GenerateKeyPair(extractable: boolean): Promise<KeyPair>;
|
|
1257
|
+
/**
|
|
1258
|
+
* Serializes a public key to bytes.
|
|
1259
|
+
*
|
|
1260
|
+
* @param key - The public Key to serialize
|
|
1261
|
+
*
|
|
1262
|
+
* @returns A promise resolving to the serialized public key
|
|
1263
|
+
*/
|
|
1264
|
+
SerializePublicKey(key: Key): Promise<Uint8Array>;
|
|
1265
|
+
/**
|
|
1266
|
+
* Deserializes a public key from bytes.
|
|
1267
|
+
*
|
|
1268
|
+
* @param key - The serialized public key already validated to be at least {@link Npk} bytes
|
|
1269
|
+
*
|
|
1270
|
+
* @returns A promise resolving to a {@link !Key} or a Key interface-conforming object
|
|
1271
|
+
*/
|
|
1272
|
+
DeserializePublicKey(key: Uint8Array): Promise<Key>;
|
|
1273
|
+
/**
|
|
1274
|
+
* Serializes a private key to bytes.
|
|
1275
|
+
*
|
|
1276
|
+
* @param key - The private Key to serialize
|
|
1277
|
+
*
|
|
1278
|
+
* @returns A promise resolving to the serialized private key
|
|
1279
|
+
*/
|
|
1280
|
+
SerializePrivateKey(key: Key): Promise<Uint8Array>;
|
|
1281
|
+
/**
|
|
1282
|
+
* Deserializes a private key from bytes.
|
|
1283
|
+
*
|
|
1284
|
+
* @param key - The serialized private key already validated to be at least {@link Nsk} bytes
|
|
1285
|
+
* @param extractable - Whether the private key should be extractable
|
|
1286
|
+
*
|
|
1287
|
+
* @returns A promise resolving to a {@link !Key} or a Key interface-conforming object
|
|
1288
|
+
*/
|
|
1289
|
+
DeserializePrivateKey(key: Uint8Array, extractable: boolean): Promise<Key>;
|
|
1290
|
+
/**
|
|
1291
|
+
* Encapsulates a shared secret to a recipient's public key.
|
|
1292
|
+
*
|
|
1293
|
+
* This is the sender-side operation that generates an ephemeral key pair, performs the KEM
|
|
1294
|
+
* operation, and returns both the shared secret and the encapsulated secret to send to the
|
|
1295
|
+
* recipient.
|
|
1296
|
+
*
|
|
1297
|
+
* @param pkR - The recipient's public key
|
|
1298
|
+
*
|
|
1299
|
+
* @returns A promise resolving to an object containing the shared secret and encapsulated secret
|
|
1300
|
+
*/
|
|
1301
|
+
Encap(pkR: Key): Promise<{
|
|
1302
|
+
shared_secret: Uint8Array;
|
|
1303
|
+
enc: Uint8Array;
|
|
1304
|
+
}>;
|
|
1305
|
+
/**
|
|
1306
|
+
* Decapsulates a shared secret using a recipient's private key.
|
|
1307
|
+
*
|
|
1308
|
+
* This is the recipient-side operation that uses the private key to extract the shared secret
|
|
1309
|
+
* from the encapsulated secret.
|
|
1310
|
+
*
|
|
1311
|
+
* @param enc - The encapsulated secret of {@link Nenc} length
|
|
1312
|
+
* @param skR - The recipient's private key
|
|
1313
|
+
* @param pkR - The recipient's public key (when user input to {@link CipherSuite.SetupRecipient}
|
|
1314
|
+
* is a {@link KeyPair})
|
|
1315
|
+
*
|
|
1316
|
+
* @returns A promise resolving to the shared secret
|
|
1317
|
+
*/
|
|
1318
|
+
Decap(enc: Uint8Array, skR: Key, pkR: Key | undefined): Promise<Uint8Array>;
|
|
1319
|
+
}
|
|
1320
|
+
/**
|
|
1321
|
+
* Authenticated Encryption with Associated Data (AEAD) implementation interface.
|
|
1322
|
+
*
|
|
1323
|
+
* This implementation interface defines the contract for additional AEAD implementations to be
|
|
1324
|
+
* usable with {@link CipherSuite}. While this module provides built-in AEAD implementations based on
|
|
1325
|
+
* [Web Cryptography](https://www.w3.org/TR/webcrypto-2/), this interface is exported to allow
|
|
1326
|
+
* custom AEAD implementations that may not rely on Web Cryptography (e.g., using native bindings,
|
|
1327
|
+
* alternative crypto libraries, or specialized hardware).
|
|
1328
|
+
*
|
|
1329
|
+
* Custom AEAD implementations must conform to this interface to be compatible with
|
|
1330
|
+
* {@link CipherSuite} and its APIs.
|
|
1331
|
+
*
|
|
1332
|
+
|
|
1333
|
+
|
|
1334
|
+
|
|
1335
|
+
|
|
1336
|
+
|
|
1337
|
+
|
|
1338
|
+
|
|
1339
|
+
|
|
1340
|
+
|
|
1341
|
+
|
|
1342
|
+
|
|
1343
|
+
|
|
1344
|
+
|
|
1345
|
+
|
|
1346
|
+
|
|
1347
|
+
|
|
1348
|
+
|
|
1349
|
+
|
|
1350
|
+
|
|
1351
|
+
|
|
1352
|
+
|
|
1353
|
+
|
|
1354
|
+
|
|
1355
|
+
|
|
1356
|
+
|
|
1357
|
+
|
|
1358
|
+
|
|
1359
|
+
|
|
1360
|
+
|
|
1361
|
+
|
|
1362
|
+
|
|
1363
|
+
|
|
1364
|
+
|
|
1365
|
+
|
|
1366
|
+
|
|
1367
|
+
|
|
1368
|
+
|
|
1369
|
+
|
|
1370
|
+
|
|
1371
|
+
|
|
1372
|
+
|
|
1373
|
+
* @see [HPKE Cryptographic Dependencies](https://www.ietf.org/archive/id/draft-ietf-hpke-hpke-02.html#section-4)
|
|
1374
|
+
*/
|
|
1375
|
+
export interface AEAD {
|
|
1376
|
+
/** AEAD algorithm identifier */
|
|
1377
|
+
readonly id: number;
|
|
1378
|
+
/** Type discriminator, always 'AEAD' */
|
|
1379
|
+
readonly type: 'AEAD';
|
|
1380
|
+
/** Human-readable name of the AEAD algorithm */
|
|
1381
|
+
readonly name: string;
|
|
1382
|
+
/** Length in bytes of a key for this AEAD */
|
|
1383
|
+
readonly Nk: number;
|
|
1384
|
+
/** Length in bytes of a nonce for this AEAD */
|
|
1385
|
+
readonly Nn: number;
|
|
1386
|
+
/** Length in bytes of the authentication tag for this AEAD */
|
|
1387
|
+
readonly Nt: number;
|
|
1388
|
+
/**
|
|
1389
|
+
* Encrypts and authenticates plaintext with associated data.
|
|
1390
|
+
*
|
|
1391
|
+
* @param key - The encryption key of {@link Nk} bytes
|
|
1392
|
+
* @param nonce - The nonce of {@link Nn} bytes
|
|
1393
|
+
* @param aad - Additional authenticated data
|
|
1394
|
+
* @param pt - Plaintext to encrypt
|
|
1395
|
+
*
|
|
1396
|
+
* @returns A promise resolving to the ciphertext with authentication tag appended
|
|
1397
|
+
*/
|
|
1398
|
+
Seal(key: Uint8Array, nonce: Uint8Array, aad: Uint8Array, pt: Uint8Array): Promise<Uint8Array>;
|
|
1399
|
+
/**
|
|
1400
|
+
* Decrypts and verifies ciphertext with associated data.
|
|
1401
|
+
*
|
|
1402
|
+
* @param key - The decryption key of {@link Nk} bytes
|
|
1403
|
+
* @param nonce - The nonce of {@link Nn} bytes
|
|
1404
|
+
* @param aad - Additional authenticated data
|
|
1405
|
+
* @param ct - Ciphertext with authentication tag appended
|
|
1406
|
+
*
|
|
1407
|
+
* @returns A promise resolving to the decrypted plaintext
|
|
1408
|
+
*/
|
|
1409
|
+
Open(key: Uint8Array, nonce: Uint8Array, aad: Uint8Array, ct: Uint8Array): Promise<Uint8Array>;
|
|
1410
|
+
}
|
|
1411
|
+
/**
|
|
1412
|
+
* Integer to Octet String Primitive (I2OSP) as defined in RFC 8017. Converts a non-negative integer
|
|
1413
|
+
* into a byte string of specified length. It's exported for use in custom KEM, KDF, or AEAD
|
|
1414
|
+
* implementations.
|
|
1415
|
+
*
|
|
1416
|
+
* @param n - Non-negative integer to convert
|
|
1417
|
+
* @param w - Desired length of output in bytes
|
|
1418
|
+
*
|
|
1419
|
+
* @returns A Uint8Array of length w containing the big-endian representation of n
|
|
1420
|
+
* @group Utilities
|
|
1421
|
+
*/
|
|
1422
|
+
export declare function I2OSP(n: number, w: number): Uint8Array;
|
|
1423
|
+
/**
|
|
1424
|
+
* Export-only AEAD mode.
|
|
1425
|
+
*
|
|
1426
|
+
* A special AEAD mode that disables encryption/decryption operations and only allows key export
|
|
1427
|
+
* functionality. Used when HPKE is employed solely for key agreement and derivation, not for
|
|
1428
|
+
* message encryption. Cannot be used with Seal/Open operations.
|
|
1429
|
+
*
|
|
1430
|
+
* This is a factory function that must be passed to the {@link CipherSuite} constructor.
|
|
1431
|
+
*
|
|
1432
|
+
* @group AEAD Algorithms
|
|
1433
|
+
*/
|
|
1434
|
+
export declare const AEAD_EXPORT_ONLY: AEADFactory;
|
|
1435
|
+
/**
|
|
1436
|
+
* HKDF-SHA256 key derivation function.
|
|
1437
|
+
*
|
|
1438
|
+
* A two-stage KDF using HMAC-based Extract-and-Expand as specified in RFC 5869. Uses SHA-256 as the
|
|
1439
|
+
* hash function with an output length (Nh) of 32 bytes.
|
|
1440
|
+
*
|
|
1441
|
+
* Depends on the following Web Cryptography algorithms being supported in the runtime:
|
|
1442
|
+
*
|
|
1443
|
+
* - HMAC with SHA-256
|
|
1444
|
+
*
|
|
1445
|
+
* This is a factory function that must be passed to the {@link CipherSuite} constructor.
|
|
1446
|
+
*
|
|
1447
|
+
* > [!TIP]\
|
|
1448
|
+
* > An implementation of this algorithm not reliant on Web Cryptography is also exported by
|
|
1449
|
+
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
1450
|
+
*
|
|
1451
|
+
* @group KDF Algorithms
|
|
1452
|
+
*/
|
|
1453
|
+
export declare const KDF_HKDF_SHA256: KDFFactory;
|
|
1454
|
+
/**
|
|
1455
|
+
* HKDF-SHA384 key derivation function.
|
|
1456
|
+
*
|
|
1457
|
+
* A two-stage KDF using HMAC-based Extract-and-Expand as specified in RFC 5869. Uses SHA-384 as the
|
|
1458
|
+
* hash function with an output length (Nh) of 48 bytes.
|
|
1459
|
+
*
|
|
1460
|
+
* Depends on the following Web Cryptography algorithms being supported in the runtime:
|
|
1461
|
+
*
|
|
1462
|
+
* - HMAC with SHA-384
|
|
1463
|
+
*
|
|
1464
|
+
* This is a factory function that must be passed to the {@link CipherSuite} constructor.
|
|
1465
|
+
*
|
|
1466
|
+
* > [!TIP]\
|
|
1467
|
+
* > An implementation of this algorithm not reliant on Web Cryptography is also exported by
|
|
1468
|
+
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
1469
|
+
*
|
|
1470
|
+
* @group KDF Algorithms
|
|
1471
|
+
*/
|
|
1472
|
+
export declare const KDF_HKDF_SHA384: KDFFactory;
|
|
1473
|
+
/**
|
|
1474
|
+
* HKDF-SHA512 key derivation function.
|
|
1475
|
+
*
|
|
1476
|
+
* A two-stage KDF using HMAC-based Extract-and-Expand as specified in RFC 5869. Uses SHA-512 as the
|
|
1477
|
+
* hash function with an output length (Nh) of 64 bytes.
|
|
1478
|
+
*
|
|
1479
|
+
* Depends on the following Web Cryptography algorithms being supported in the runtime:
|
|
1480
|
+
*
|
|
1481
|
+
* - HMAC with SHA-512
|
|
1482
|
+
*
|
|
1483
|
+
* This is a factory function that must be passed to the {@link CipherSuite} constructor.
|
|
1484
|
+
*
|
|
1485
|
+
* > [!TIP]\
|
|
1486
|
+
* > An implementation of this algorithm not reliant on Web Cryptography is also exported by
|
|
1487
|
+
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
1488
|
+
*
|
|
1489
|
+
* @group KDF Algorithms
|
|
1490
|
+
*/
|
|
1491
|
+
export declare const KDF_HKDF_SHA512: KDFFactory;
|
|
1492
|
+
/**
|
|
1493
|
+
* SHAKE128 key derivation function.
|
|
1494
|
+
*
|
|
1495
|
+
* A one-stage KDF using the SHAKE128 extendable-output function (XOF) with an output length (Nh) of
|
|
1496
|
+
* 32 bytes.
|
|
1497
|
+
*
|
|
1498
|
+
* Depends on the following Web Cryptography algorithms being supported in the runtime:
|
|
1499
|
+
*
|
|
1500
|
+
* - SHAKE128 (cSHAKE128 without any parameters) digest
|
|
1501
|
+
*
|
|
1502
|
+
* This is a factory function that must be passed to the {@link CipherSuite} constructor.
|
|
1503
|
+
*
|
|
1504
|
+
* > [!TIP]\
|
|
1505
|
+
* > An implementation of this algorithm not reliant on Web Cryptography is also exported by
|
|
1506
|
+
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
1507
|
+
*
|
|
1508
|
+
* @group KDF Algorithms
|
|
1509
|
+
*/
|
|
1510
|
+
export declare const KDF_SHAKE128: KDFFactory;
|
|
1511
|
+
/**
|
|
1512
|
+
* SHAKE256 key derivation function.
|
|
1513
|
+
*
|
|
1514
|
+
* A one-stage KDF using the SHAKE256 extendable-output function (XOF) with an output length (Nh) of
|
|
1515
|
+
* 64 bytes.
|
|
1516
|
+
*
|
|
1517
|
+
* Depends on the following Web Cryptography algorithms being supported in the runtime:
|
|
1518
|
+
*
|
|
1519
|
+
* - SHAKE256 (cSHAKE256 without any parameters) digest
|
|
1520
|
+
*
|
|
1521
|
+
* This is a factory function that must be passed to the {@link CipherSuite} constructor.
|
|
1522
|
+
*
|
|
1523
|
+
* > [!TIP]\
|
|
1524
|
+
* > An implementation of this algorithm not reliant on Web Cryptography is also exported by
|
|
1525
|
+
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
1526
|
+
*
|
|
1527
|
+
* @group KDF Algorithms
|
|
1528
|
+
*/
|
|
1529
|
+
export declare const KDF_SHAKE256: KDFFactory;
|
|
1530
|
+
/**
|
|
1531
|
+
* Diffie-Hellman Key Encapsulation Mechanism using NIST P-256 curve and HKDF-SHA256.
|
|
1532
|
+
*
|
|
1533
|
+
* A Diffie-Hellman based KEM using the NIST P-256 elliptic curve (also known as secp256r1) with
|
|
1534
|
+
* HKDF-SHA256 for key derivation.
|
|
1535
|
+
*
|
|
1536
|
+
* Depends on the following Web Cryptography algorithms being supported in the runtime:
|
|
1537
|
+
*
|
|
1538
|
+
* - ECDH with P-256 curve
|
|
1539
|
+
* - HMAC with SHA-256 (for HKDF)
|
|
1540
|
+
*
|
|
1541
|
+
* This is a factory function that must be passed to the {@link CipherSuite} constructor.
|
|
1542
|
+
*
|
|
1543
|
+
* > [!TIP]\
|
|
1544
|
+
* > An implementation of this algorithm not reliant on Web Cryptography is also exported by
|
|
1545
|
+
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
1546
|
+
*
|
|
1547
|
+
* @group KEM Algorithms
|
|
1548
|
+
*/
|
|
1549
|
+
export declare const KEM_DHKEM_P256_HKDF_SHA256: KEMFactory;
|
|
1550
|
+
/**
|
|
1551
|
+
* Diffie-Hellman Key Encapsulation Mechanism using NIST P-384 curve and HKDF-SHA384.
|
|
1552
|
+
*
|
|
1553
|
+
* A Diffie-Hellman based KEM using the NIST P-384 elliptic curve (also known as secp384r1) with
|
|
1554
|
+
* HKDF-SHA384 for key derivation.
|
|
1555
|
+
*
|
|
1556
|
+
* Depends on the following Web Cryptography algorithms being supported in the runtime:
|
|
1557
|
+
*
|
|
1558
|
+
* - ECDH with P-384 curve
|
|
1559
|
+
* - HMAC with SHA-384 (for HKDF)
|
|
1560
|
+
*
|
|
1561
|
+
* This is a factory function that must be passed to the {@link CipherSuite} constructor.
|
|
1562
|
+
*
|
|
1563
|
+
* > [!TIP]\
|
|
1564
|
+
* > An implementation of this algorithm not reliant on Web Cryptography is also exported by
|
|
1565
|
+
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
1566
|
+
*
|
|
1567
|
+
* @group KEM Algorithms
|
|
1568
|
+
*/
|
|
1569
|
+
export declare const KEM_DHKEM_P384_HKDF_SHA384: KEMFactory;
|
|
1570
|
+
/**
|
|
1571
|
+
* Diffie-Hellman Key Encapsulation Mechanism using NIST P-521 curve and HKDF-SHA512.
|
|
1572
|
+
*
|
|
1573
|
+
* A Diffie-Hellman based KEM using the NIST P-521 elliptic curve (also known as secp521r1) with
|
|
1574
|
+
* HKDF-SHA512 for key derivation.
|
|
1575
|
+
*
|
|
1576
|
+
* Depends on the following Web Cryptography algorithms being supported in the runtime:
|
|
1577
|
+
*
|
|
1578
|
+
* - ECDH with P-521 curve
|
|
1579
|
+
* - HMAC with SHA-512 (for HKDF)
|
|
1580
|
+
*
|
|
1581
|
+
* This is a factory function that must be passed to the {@link CipherSuite} constructor.
|
|
1582
|
+
*
|
|
1583
|
+
* > [!TIP]\
|
|
1584
|
+
* > An implementation of this algorithm not reliant on Web Cryptography is also exported by
|
|
1585
|
+
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
1586
|
+
*
|
|
1587
|
+
* @group KEM Algorithms
|
|
1588
|
+
*/
|
|
1589
|
+
export declare const KEM_DHKEM_P521_HKDF_SHA512: KEMFactory;
|
|
1590
|
+
/**
|
|
1591
|
+
* Diffie-Hellman Key Encapsulation Mechanism using Curve25519 and HKDF-SHA256.
|
|
1592
|
+
*
|
|
1593
|
+
* A Diffie-Hellman based KEM using the X25519 elliptic curve (Curve25519 for ECDH) with HKDF-SHA256
|
|
1594
|
+
* for key derivation.
|
|
1595
|
+
*
|
|
1596
|
+
* Depends on the following Web Cryptography algorithms being supported in the runtime:
|
|
1597
|
+
*
|
|
1598
|
+
* - X25519 key agreement
|
|
1599
|
+
* - HMAC with SHA-256 (for HKDF)
|
|
1600
|
+
*
|
|
1601
|
+
* This is a factory function that must be passed to the {@link CipherSuite} constructor.
|
|
1602
|
+
*
|
|
1603
|
+
* > [!TIP]\
|
|
1604
|
+
* > An implementation of this algorithm not reliant on Web Cryptography is also exported by
|
|
1605
|
+
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
1606
|
+
*
|
|
1607
|
+
* @group KEM Algorithms
|
|
1608
|
+
*/
|
|
1609
|
+
export declare const KEM_DHKEM_X25519_HKDF_SHA256: KEMFactory;
|
|
1610
|
+
/**
|
|
1611
|
+
* Diffie-Hellman Key Encapsulation Mechanism using Curve448 and HKDF-SHA512.
|
|
1612
|
+
*
|
|
1613
|
+
* A Diffie-Hellman based KEM using the X448 elliptic curve (Curve448 for ECDH) with HKDF-SHA512 for
|
|
1614
|
+
* key derivation.
|
|
1615
|
+
*
|
|
1616
|
+
* Depends on the following Web Cryptography algorithms being supported in the runtime:
|
|
1617
|
+
*
|
|
1618
|
+
* - X448 key agreement
|
|
1619
|
+
* - HMAC with SHA-512 (for HKDF)
|
|
1620
|
+
*
|
|
1621
|
+
* This is a factory function that must be passed to the {@link CipherSuite} constructor.
|
|
1622
|
+
*
|
|
1623
|
+
* > [!TIP]\
|
|
1624
|
+
* > An implementation of this algorithm not reliant on Web Cryptography is also exported by
|
|
1625
|
+
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
1626
|
+
*
|
|
1627
|
+
* @group KEM Algorithms
|
|
1628
|
+
*/
|
|
1629
|
+
export declare const KEM_DHKEM_X448_HKDF_SHA512: KEMFactory;
|
|
1630
|
+
/**
|
|
1631
|
+
* Module-Lattice-Based Key Encapsulation Mechanism (ML-KEM-512).
|
|
1632
|
+
*
|
|
1633
|
+
* A post-quantum KEM based on structured lattices (FIPS 203 / CRYSTALS-Kyber).
|
|
1634
|
+
*
|
|
1635
|
+
* Depends on the following Web Cryptography algorithms being supported in the runtime:
|
|
1636
|
+
*
|
|
1637
|
+
* - ML-KEM-512 key encapsulation
|
|
1638
|
+
* - SHAKE256 (cSHAKE256 without any parameters) digest on the recipient for key derivation
|
|
1639
|
+
*
|
|
1640
|
+
* This is a factory function that must be passed to the {@link CipherSuite} constructor.
|
|
1641
|
+
*
|
|
1642
|
+
* > [!TIP]\
|
|
1643
|
+
* > An implementation of this algorithm not reliant on Web Cryptography is also exported by
|
|
1644
|
+
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
1645
|
+
*
|
|
1646
|
+
* @group KEM Algorithms
|
|
1647
|
+
*/
|
|
1648
|
+
export declare const KEM_ML_KEM_512: KEMFactory;
|
|
1649
|
+
/**
|
|
1650
|
+
* Module-Lattice-Based Key Encapsulation Mechanism (ML-KEM-768).
|
|
1651
|
+
*
|
|
1652
|
+
* A post-quantum KEM based on structured lattices (FIPS 203 / CRYSTALS-Kyber).
|
|
1653
|
+
*
|
|
1654
|
+
* Depends on the following Web Cryptography algorithms being supported in the runtime:
|
|
1655
|
+
*
|
|
1656
|
+
* - ML-KEM-768 key encapsulation
|
|
1657
|
+
* - SHAKE256 (cSHAKE256 without any parameters) digest on the recipient for key derivation
|
|
1658
|
+
*
|
|
1659
|
+
* This is a factory function that must be passed to the {@link CipherSuite} constructor.
|
|
1660
|
+
*
|
|
1661
|
+
* > [!TIP]\
|
|
1662
|
+
* > An implementation of this algorithm not reliant on Web Cryptography is also exported by
|
|
1663
|
+
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
1664
|
+
*
|
|
1665
|
+
* @group KEM Algorithms
|
|
1666
|
+
*/
|
|
1667
|
+
export declare const KEM_ML_KEM_768: KEMFactory;
|
|
1668
|
+
/**
|
|
1669
|
+
* Module-Lattice-Based Key Encapsulation Mechanism (ML-KEM-1024).
|
|
1670
|
+
*
|
|
1671
|
+
* A post-quantum KEM based on structured lattices (FIPS 203 / CRYSTALS-Kyber).
|
|
1672
|
+
*
|
|
1673
|
+
* Depends on the following Web Cryptography algorithms being supported in the runtime:
|
|
1674
|
+
*
|
|
1675
|
+
* - ML-KEM-1024 key encapsulation
|
|
1676
|
+
* - SHAKE256 (cSHAKE256 without any parameters) digest on the recipient for key derivation
|
|
1677
|
+
*
|
|
1678
|
+
* This is a factory function that must be passed to the {@link CipherSuite} constructor.
|
|
1679
|
+
*
|
|
1680
|
+
* > [!TIP]\
|
|
1681
|
+
* > An implementation of this algorithm not reliant on Web Cryptography is also exported by
|
|
1682
|
+
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
1683
|
+
*
|
|
1684
|
+
* @group KEM Algorithms
|
|
1685
|
+
*/
|
|
1686
|
+
export declare const KEM_ML_KEM_1024: KEMFactory;
|
|
1687
|
+
/**
|
|
1688
|
+
* AES-128-GCM Authenticated Encryption with Associated Data (AEAD).
|
|
1689
|
+
*
|
|
1690
|
+
* Uses AES in Galois/Counter Mode with 128-bit keys.
|
|
1691
|
+
*
|
|
1692
|
+
* Depends on the following Web Cryptography algorithms being supported in the runtime:
|
|
1693
|
+
*
|
|
1694
|
+
* - AES-GCM encryption and decryption
|
|
1695
|
+
*
|
|
1696
|
+
* This is a factory function that must be passed to the {@link CipherSuite} constructor.
|
|
1697
|
+
*
|
|
1698
|
+
* > [!TIP]\
|
|
1699
|
+
* > An implementation of this algorithm not reliant on Web Cryptography is also exported by
|
|
1700
|
+
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
1701
|
+
*
|
|
1702
|
+
* @group AEAD Algorithms
|
|
1703
|
+
*/
|
|
1704
|
+
export declare const AEAD_AES_128_GCM: AEADFactory;
|
|
1705
|
+
/**
|
|
1706
|
+
* AES-256-GCM Authenticated Encryption with Associated Data (AEAD).
|
|
1707
|
+
*
|
|
1708
|
+
* Uses AES in Galois/Counter Mode with 256-bit keys.
|
|
1709
|
+
*
|
|
1710
|
+
* Depends on the following Web Cryptography algorithms being supported in the runtime:
|
|
1711
|
+
*
|
|
1712
|
+
* - AES-GCM encryption and decryption
|
|
1713
|
+
*
|
|
1714
|
+
* This is a factory function that must be passed to the {@link CipherSuite} constructor.
|
|
1715
|
+
*
|
|
1716
|
+
* > [!TIP]\
|
|
1717
|
+
* > An implementation of this algorithm not reliant on Web Cryptography is also exported by
|
|
1718
|
+
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
1719
|
+
*
|
|
1720
|
+
* @group AEAD Algorithms
|
|
1721
|
+
*/
|
|
1722
|
+
export declare const AEAD_AES_256_GCM: AEADFactory;
|
|
1723
|
+
/**
|
|
1724
|
+
* ChaCha20-Poly1305 Authenticated Encryption with Associated Data (AEAD).
|
|
1725
|
+
*
|
|
1726
|
+
* Uses ChaCha20 stream cipher with Poly1305 MAC.
|
|
1727
|
+
*
|
|
1728
|
+
* Depends on the following Web Cryptography algorithms being supported in the runtime:
|
|
1729
|
+
*
|
|
1730
|
+
* - ChaCha20-Poly1305 encryption and decryption
|
|
1731
|
+
*
|
|
1732
|
+
* This is a factory function that must be passed to the {@link CipherSuite} constructor.
|
|
1733
|
+
*
|
|
1734
|
+
* > [!TIP]\
|
|
1735
|
+
* > An implementation of this algorithm not reliant on Web Cryptography is also exported by
|
|
1736
|
+
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
1737
|
+
*
|
|
1738
|
+
* @group AEAD Algorithms
|
|
1739
|
+
*/
|
|
1740
|
+
export declare const AEAD_ChaCha20Poly1305: AEADFactory;
|
|
1741
|
+
/**
|
|
1742
|
+
* Hybrid KEM combining ML-KEM-768 with X25519 (MLKEM768-X25519 aka X-Wing).
|
|
1743
|
+
*
|
|
1744
|
+
* Depends on the following Web Cryptography algorithms being supported in the runtime:
|
|
1745
|
+
*
|
|
1746
|
+
* - ML-KEM-768 key encapsulation
|
|
1747
|
+
* - X25519 key agreement
|
|
1748
|
+
* - SHA3-256 digest
|
|
1749
|
+
* - SHAKE256 (cSHAKE256 without any parameters) digest on the recipient side for seed expansion
|
|
1750
|
+
*
|
|
1751
|
+
* This is a factory function that must be passed to the {@link CipherSuite} constructor.
|
|
1752
|
+
*
|
|
1753
|
+
* > [!TIP]\
|
|
1754
|
+
* > An implementation of this algorithm not reliant on Web Cryptography is also exported by
|
|
1755
|
+
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
1756
|
+
*
|
|
1757
|
+
* @group KEM Algorithms
|
|
1758
|
+
*/
|
|
1759
|
+
export declare const KEM_MLKEM768_X25519: KEMFactory;
|
|
1760
|
+
/**
|
|
1761
|
+
* Hybrid KEM combining ML-KEM-768 with P-256 (MLKEM768-P256).
|
|
1762
|
+
*
|
|
1763
|
+
* Depends on the following Web Cryptography algorithms being supported in the runtime:
|
|
1764
|
+
*
|
|
1765
|
+
* - ML-KEM-768 key encapsulation
|
|
1766
|
+
* - ECDH with P-256 curve
|
|
1767
|
+
* - SHA3-256 digest
|
|
1768
|
+
* - SHAKE256 (cSHAKE256 without any parameters) digest on the recipient side for seed expansion
|
|
1769
|
+
*
|
|
1770
|
+
* This is a factory function that must be passed to the {@link CipherSuite} constructor.
|
|
1771
|
+
*
|
|
1772
|
+
* > [!TIP]\
|
|
1773
|
+
* > An implementation of this algorithm not reliant on Web Cryptography is also exported by
|
|
1774
|
+
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
1775
|
+
*
|
|
1776
|
+
* @group KEM Algorithms
|
|
1777
|
+
*/
|
|
1778
|
+
export declare const KEM_MLKEM768_P256: KEMFactory;
|
|
1779
|
+
/**
|
|
1780
|
+
* Hybrid KEM combining ML-KEM-1024 with P-384 (MLKEM1024-P384).
|
|
1781
|
+
*
|
|
1782
|
+
* Depends on the following Web Cryptography algorithms being supported in the runtime:
|
|
1783
|
+
*
|
|
1784
|
+
* - ML-KEM-1024 key encapsulation
|
|
1785
|
+
* - ECDH with P-384 curve
|
|
1786
|
+
* - SHA3-256 digest
|
|
1787
|
+
* - SHAKE256 (cSHAKE256 without any parameters) digest on the recipient side for seed expansion
|
|
1788
|
+
*
|
|
1789
|
+
* This is a factory function that must be passed to the {@link CipherSuite} constructor.
|
|
1790
|
+
*
|
|
1791
|
+
* > [!TIP]\
|
|
1792
|
+
* > An implementation of this algorithm not reliant on Web Cryptography is also exported by
|
|
1793
|
+
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
1794
|
+
*
|
|
1795
|
+
* @group KEM Algorithms
|
|
1796
|
+
*/
|
|
1797
|
+
export declare const KEM_MLKEM1024_P384: KEMFactory;
|