hpke 1.1.2 → 1.1.4
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/README.md +3 -3
- package/index.d.ts +148 -100
- package/index.d.ts.map +1 -1
- package/index.js +148 -64
- package/index.ts +248 -164
- package/package.json +20 -15
package/index.ts
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
* asymmetric key exchange with a symmetric cipher. This was originally defined in an Informational
|
|
6
6
|
* document on the IRTF stream as [RFC 9180](https://www.rfc-editor.org/rfc/rfc9180.html) and is now
|
|
7
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-
|
|
8
|
+
* [draft-ietf-hpke-hpke](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04).
|
|
9
9
|
*
|
|
10
10
|
* HPKE provides a variant of public key encryption for arbitrary-sized plaintexts using a recipient
|
|
11
11
|
* public key.
|
|
@@ -42,11 +42,11 @@
|
|
|
42
42
|
// HPKE Context Classes - Sender and Recipient Contexts
|
|
43
43
|
// ============================================================================
|
|
44
44
|
|
|
45
|
-
/** @see [ComputeNonce](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
45
|
+
/** @see [ComputeNonce](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.2) */
|
|
46
46
|
function ComputeNonce(base_nonce: Uint8Array, seq: number, Nn: number): Uint8Array {
|
|
47
47
|
// Equivalent to xor(base_nonce, I2OSP(seq, Nn)) but avoids allocating the
|
|
48
48
|
// intermediate seq_bytes array and fuses the two byte-wise passes into one.
|
|
49
|
-
// seq
|
|
49
|
+
// seq stays exact because IncrementSeq caps it at Number.MAX_SAFE_INTEGER.
|
|
50
50
|
const nonce = new Uint8Array(Nn)
|
|
51
51
|
nonce.set(base_nonce)
|
|
52
52
|
let s = seq
|
|
@@ -57,18 +57,21 @@ function ComputeNonce(base_nonce: Uint8Array, seq: number, Nn: number): Uint8Arr
|
|
|
57
57
|
return nonce
|
|
58
58
|
}
|
|
59
59
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
// seq
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
60
|
+
function MaxSeq(Nn: number): number {
|
|
61
|
+
// HPKE limits seq to the largest integer encodable in Nn bytes. This
|
|
62
|
+
// implementation stores seq as a JS number, so it uses the stricter limit.
|
|
63
|
+
return Math.min(2 ** (8 * Nn) - 1, Number.MAX_SAFE_INTEGER)
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/** @see [Context.IncrementSeq](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.2) */
|
|
67
|
+
function IncrementSeq(seq: number, maxSeq: number): number {
|
|
68
|
+
if (seq >= maxSeq) {
|
|
66
69
|
throw new MessageLimitReachedError('Sequence number overflow')
|
|
67
70
|
}
|
|
68
71
|
return ++seq
|
|
69
72
|
}
|
|
70
73
|
|
|
71
|
-
/** @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
74
|
+
/** @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.3) */
|
|
72
75
|
async function ContextExport(
|
|
73
76
|
suite: Triple,
|
|
74
77
|
exporterSecret: Uint8Array,
|
|
@@ -126,13 +129,14 @@ class SenderContext {
|
|
|
126
129
|
#key: Uint8Array
|
|
127
130
|
#base_nonce: Uint8Array
|
|
128
131
|
#exporter_secret: Uint8Array
|
|
129
|
-
#mode:
|
|
132
|
+
#mode: Mode
|
|
130
133
|
#seq: number = 0
|
|
134
|
+
#max_seq: number
|
|
131
135
|
#mutex?: Mutex
|
|
132
136
|
|
|
133
137
|
constructor(
|
|
134
138
|
suite: Triple,
|
|
135
|
-
mode:
|
|
139
|
+
mode: Mode,
|
|
136
140
|
key: Uint8Array,
|
|
137
141
|
base_nonce: Uint8Array,
|
|
138
142
|
exporter_secret: Uint8Array,
|
|
@@ -142,6 +146,7 @@ class SenderContext {
|
|
|
142
146
|
this.#key = key
|
|
143
147
|
this.#base_nonce = base_nonce
|
|
144
148
|
this.#exporter_secret = exporter_secret
|
|
149
|
+
this.#max_seq = MaxSeq(suite.AEAD.Nn)
|
|
145
150
|
}
|
|
146
151
|
|
|
147
152
|
/**
|
|
@@ -149,14 +154,15 @@ class SenderContext {
|
|
|
149
154
|
* @see {@link MODE_BASE}
|
|
150
155
|
* @see {@link MODE_PSK}
|
|
151
156
|
*/
|
|
152
|
-
get mode():
|
|
157
|
+
get mode(): Mode {
|
|
153
158
|
return this.#mode
|
|
154
159
|
}
|
|
155
160
|
|
|
156
161
|
/**
|
|
157
162
|
* @returns The sequence number for this context's next {@link Seal}, initially zero, increments
|
|
158
163
|
* automatically with each successful {@link Seal}. The sequence number provides AEAD nonce
|
|
159
|
-
* uniqueness. The maximum supported sequence number
|
|
164
|
+
* uniqueness. The maximum supported sequence number is the lower of the AEAD nonce-size limit
|
|
165
|
+
* and `2^53-1`.
|
|
160
166
|
*/
|
|
161
167
|
get seq(): number {
|
|
162
168
|
return this.#seq
|
|
@@ -186,7 +192,7 @@ class SenderContext {
|
|
|
186
192
|
*
|
|
187
193
|
* @returns A Promise that resolves to the ciphertext. The ciphertext is {@link Nt} bytes longer
|
|
188
194
|
* than the plaintext.
|
|
189
|
-
* @see [Context.Seal](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
195
|
+
* @see [Context.Seal](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.2)
|
|
190
196
|
*/
|
|
191
197
|
async Seal(plaintext: Uint8Array, aad?: Uint8Array): Promise<Uint8Array> {
|
|
192
198
|
checkUint8Array(plaintext, 'plaintext')
|
|
@@ -206,7 +212,7 @@ class SenderContext {
|
|
|
206
212
|
aad,
|
|
207
213
|
plaintext,
|
|
208
214
|
)
|
|
209
|
-
this.#seq = IncrementSeq(this.#seq)
|
|
215
|
+
this.#seq = IncrementSeq(this.#seq, this.#max_seq)
|
|
210
216
|
return ct
|
|
211
217
|
} finally {
|
|
212
218
|
release()
|
|
@@ -234,7 +240,7 @@ class SenderContext {
|
|
|
234
240
|
* @param length - Desired length of exported secret in bytes
|
|
235
241
|
*
|
|
236
242
|
* @returns A Promise that resolves to the exported secret.
|
|
237
|
-
* @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
243
|
+
* @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.3)
|
|
238
244
|
*/
|
|
239
245
|
async Export(exporterContext: Uint8Array, length: number): Promise<Uint8Array> {
|
|
240
246
|
return await ContextExport(this.#suite, this.#exporter_secret, exporterContext, length)
|
|
@@ -274,13 +280,14 @@ class RecipientContext {
|
|
|
274
280
|
#key: Uint8Array
|
|
275
281
|
#base_nonce: Uint8Array
|
|
276
282
|
#exporter_secret: Uint8Array
|
|
277
|
-
#mode:
|
|
283
|
+
#mode: Mode
|
|
278
284
|
#seq: number = 0
|
|
285
|
+
#max_seq: number
|
|
279
286
|
#mutex?: Mutex
|
|
280
287
|
|
|
281
288
|
constructor(
|
|
282
289
|
suite: Triple,
|
|
283
|
-
mode:
|
|
290
|
+
mode: Mode,
|
|
284
291
|
key: Uint8Array,
|
|
285
292
|
base_nonce: Uint8Array,
|
|
286
293
|
exporter_secret: Uint8Array,
|
|
@@ -290,6 +297,7 @@ class RecipientContext {
|
|
|
290
297
|
this.#key = key
|
|
291
298
|
this.#base_nonce = base_nonce
|
|
292
299
|
this.#exporter_secret = exporter_secret
|
|
300
|
+
this.#max_seq = MaxSeq(suite.AEAD.Nn)
|
|
293
301
|
}
|
|
294
302
|
|
|
295
303
|
/**
|
|
@@ -297,14 +305,15 @@ class RecipientContext {
|
|
|
297
305
|
* @see {@link MODE_BASE}
|
|
298
306
|
* @see {@link MODE_PSK}
|
|
299
307
|
*/
|
|
300
|
-
get mode():
|
|
308
|
+
get mode(): Mode {
|
|
301
309
|
return this.#mode
|
|
302
310
|
}
|
|
303
311
|
|
|
304
312
|
/**
|
|
305
313
|
* @returns The sequence number for this context's next {@link Open}, initially zero, increments
|
|
306
314
|
* automatically with each successful {@link Open}. The sequence number provides AEAD nonce
|
|
307
|
-
* uniqueness. The maximum supported sequence number
|
|
315
|
+
* uniqueness. The maximum supported sequence number is the lower of the AEAD nonce-size limit
|
|
316
|
+
* and `2^53-1`.
|
|
308
317
|
*/
|
|
309
318
|
get seq(): number {
|
|
310
319
|
return this.#seq
|
|
@@ -335,7 +344,7 @@ class RecipientContext {
|
|
|
335
344
|
* @param aad - Additional authenticated data
|
|
336
345
|
*
|
|
337
346
|
* @returns A Promise that resolves to the decrypted plaintext.
|
|
338
|
-
* @see [Context.Open](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
347
|
+
* @see [Context.Open](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.2)
|
|
339
348
|
*/
|
|
340
349
|
async Open(ciphertext: Uint8Array, aad?: Uint8Array): Promise<Uint8Array> {
|
|
341
350
|
checkUint8Array(ciphertext, 'ciphertext')
|
|
@@ -364,7 +373,7 @@ class RecipientContext {
|
|
|
364
373
|
|
|
365
374
|
throw new OpenError('AEAD decryption failed', { cause })
|
|
366
375
|
}
|
|
367
|
-
this.#seq = IncrementSeq(this.#seq)
|
|
376
|
+
this.#seq = IncrementSeq(this.#seq, this.#max_seq)
|
|
368
377
|
return pt
|
|
369
378
|
} finally {
|
|
370
379
|
release()
|
|
@@ -392,7 +401,7 @@ class RecipientContext {
|
|
|
392
401
|
* @param length - Desired length of exported secret in bytes
|
|
393
402
|
*
|
|
394
403
|
* @returns A Promise that resolves to the exported secret.
|
|
395
|
-
* @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
404
|
+
* @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.3)
|
|
396
405
|
*/
|
|
397
406
|
async Export(exporterContext: Uint8Array, length: number): Promise<Uint8Array> {
|
|
398
407
|
return await ContextExport(this.#suite, this.#exporter_secret, exporterContext, length)
|
|
@@ -423,7 +432,7 @@ const validate = <T extends { type: string }>(factory: () => T, type: string): T
|
|
|
423
432
|
* asymmetric key exchange with a symmetric cipher. This was originally defined in an Informational
|
|
424
433
|
* document on the IRTF stream as [RFC 9180](https://www.rfc-editor.org/rfc/rfc9180.html) and is now
|
|
425
434
|
* being republished as a Standards Track document of the IETF as
|
|
426
|
-
* [draft-ietf-hpke-hpke](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
435
|
+
* [draft-ietf-hpke-hpke](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04).
|
|
427
436
|
*
|
|
428
437
|
* HPKE provides a variant of public key encryption for arbitrary-sized plaintexts using a recipient
|
|
429
438
|
* public key. It supports two modes:
|
|
@@ -437,10 +446,11 @@ const validate = <T extends { type: string }>(factory: () => T, type: string): T
|
|
|
437
446
|
* - KDF: Key Derivation Function for deriving symmetric keys
|
|
438
447
|
* - AEAD: Authenticated Encryption with Additional Data for encryption
|
|
439
448
|
*
|
|
449
|
+
* @typeParam K - Key representation produced and consumed by the suite's KEM
|
|
440
450
|
* @group Core
|
|
441
451
|
*/
|
|
442
|
-
export class CipherSuite {
|
|
443
|
-
#suite: Triple
|
|
452
|
+
export class CipherSuite<K extends Key = Key> {
|
|
453
|
+
#suite: Triple<K>
|
|
444
454
|
|
|
445
455
|
/**
|
|
446
456
|
* Creates a new HPKE cipher suite by combining a Key Encapsulation Mechanism (KEM), Key
|
|
@@ -503,7 +513,7 @@ export class CipherSuite {
|
|
|
503
513
|
* @see {@link KDFFactory Available KDFs}
|
|
504
514
|
* @see {@link AEADFactory Available AEADs}
|
|
505
515
|
*/
|
|
506
|
-
constructor(KEM: KEMFactory
|
|
516
|
+
constructor(KEM: KEMFactory<K>, KDF: KDFFactory, AEAD: AEADFactory) {
|
|
507
517
|
const kem = validate(KEM, 'KEM')
|
|
508
518
|
const kdf = validate(KDF, 'KDF')
|
|
509
519
|
const aead = validate(AEAD, 'AEAD')
|
|
@@ -523,17 +533,17 @@ export class CipherSuite {
|
|
|
523
533
|
*/
|
|
524
534
|
get KEM(): {
|
|
525
535
|
/** The identifier of this suite's KEM */
|
|
526
|
-
id: number
|
|
536
|
+
readonly id: number
|
|
527
537
|
/** The name of this suite's KEM */
|
|
528
|
-
name: string
|
|
538
|
+
readonly name: string
|
|
529
539
|
/** The length in bytes of this suite's KEM produced shared secret */
|
|
530
|
-
Nsecret: number
|
|
540
|
+
readonly Nsecret: number
|
|
531
541
|
/** The length in bytes of this suite's KEM produced encapsulated secret */
|
|
532
|
-
Nenc: number
|
|
542
|
+
readonly Nenc: number
|
|
533
543
|
/** The length in bytes of this suite's KEM public key */
|
|
534
|
-
Npk: number
|
|
544
|
+
readonly Npk: number
|
|
535
545
|
/** The length in bytes of this suite's KEM private key */
|
|
536
|
-
Nsk: number
|
|
546
|
+
readonly Nsk: number
|
|
537
547
|
} {
|
|
538
548
|
return {
|
|
539
549
|
id: this.#suite.KEM.id,
|
|
@@ -552,21 +562,21 @@ export class CipherSuite {
|
|
|
552
562
|
*/
|
|
553
563
|
get KDF(): {
|
|
554
564
|
/** The identifier of this suite's KDF */
|
|
555
|
-
id: number
|
|
565
|
+
readonly id: number
|
|
556
566
|
/** The name of this suite's KDF */
|
|
557
|
-
name: string
|
|
567
|
+
readonly name: string
|
|
558
568
|
/**
|
|
559
569
|
* When 1, this suite's KDF is a one-stage (Derive) KDF.
|
|
560
570
|
*
|
|
561
571
|
* When 2, this suite's KDF is a two-stage (Extract and Expand) KDF.
|
|
562
572
|
*/
|
|
563
|
-
stages: 1 | 2
|
|
573
|
+
readonly stages: 1 | 2
|
|
564
574
|
/**
|
|
565
575
|
* For one-stage KDF: The security strength of this suite's KDF, in bytes.
|
|
566
576
|
*
|
|
567
577
|
* For two-stage KDF: The output size of this suite's KDF Extract() function in bytes.
|
|
568
578
|
*/
|
|
569
|
-
Nh: number
|
|
579
|
+
readonly Nh: number
|
|
570
580
|
} {
|
|
571
581
|
return {
|
|
572
582
|
id: this.#suite.KDF.id,
|
|
@@ -584,15 +594,15 @@ export class CipherSuite {
|
|
|
584
594
|
*/
|
|
585
595
|
get AEAD(): {
|
|
586
596
|
/** The identifier of this suite's AEAD */
|
|
587
|
-
id: number
|
|
597
|
+
readonly id: number
|
|
588
598
|
/** The name of this suite's AEAD */
|
|
589
|
-
name: string
|
|
599
|
+
readonly name: string
|
|
590
600
|
/** The length in bytes of a key for this suite's AEAD */
|
|
591
|
-
Nk: number
|
|
601
|
+
readonly Nk: number
|
|
592
602
|
/** The length in bytes of a nonce for this suite's AEAD */
|
|
593
|
-
Nn: number
|
|
603
|
+
readonly Nn: number
|
|
594
604
|
/** The length in bytes of an authentication tag for this suite's AEAD */
|
|
595
|
-
Nt: number
|
|
605
|
+
readonly Nt: number
|
|
596
606
|
} {
|
|
597
607
|
return {
|
|
598
608
|
id: this.#suite.AEAD.id,
|
|
@@ -620,7 +630,7 @@ export class CipherSuite {
|
|
|
620
630
|
*
|
|
621
631
|
* @returns A Promise that resolves to a generated key pair.
|
|
622
632
|
*/
|
|
623
|
-
async GenerateKeyPair(extractable?: boolean): Promise<KeyPair
|
|
633
|
+
async GenerateKeyPair(extractable?: boolean): Promise<KeyPair<K>> {
|
|
624
634
|
extractable ??= false
|
|
625
635
|
checkExtractable(extractable)
|
|
626
636
|
return await this.#suite.KEM.GenerateKeyPair(extractable)
|
|
@@ -653,7 +663,7 @@ export class CipherSuite {
|
|
|
653
663
|
*
|
|
654
664
|
* @returns A Promise that resolves to the derived key pair.
|
|
655
665
|
*/
|
|
656
|
-
async DeriveKeyPair(ikm: Uint8Array, extractable?: boolean): Promise<KeyPair
|
|
666
|
+
async DeriveKeyPair(ikm: Uint8Array, extractable?: boolean): Promise<KeyPair<K>> {
|
|
657
667
|
extractable ??= false
|
|
658
668
|
checkExtractable(extractable)
|
|
659
669
|
checkUint8Array(ikm, 'ikm')
|
|
@@ -686,7 +696,7 @@ export class CipherSuite {
|
|
|
686
696
|
*
|
|
687
697
|
* @returns A Promise that resolves to the serialized private key.
|
|
688
698
|
*/
|
|
689
|
-
async SerializePrivateKey(privateKey:
|
|
699
|
+
async SerializePrivateKey(privateKey: K): Promise<Uint8Array> {
|
|
690
700
|
isKey(privateKey, 'private', true)
|
|
691
701
|
|
|
692
702
|
return await this.#suite.KEM.SerializePrivateKey(privateKey)
|
|
@@ -708,7 +718,7 @@ export class CipherSuite {
|
|
|
708
718
|
*
|
|
709
719
|
* @returns A Promise that resolves to the serialized public key.
|
|
710
720
|
*/
|
|
711
|
-
async SerializePublicKey(publicKey:
|
|
721
|
+
async SerializePublicKey(publicKey: K): Promise<Uint8Array> {
|
|
712
722
|
isKey(publicKey, 'public', true)
|
|
713
723
|
|
|
714
724
|
return await this.#suite.KEM.SerializePublicKey(publicKey)
|
|
@@ -733,7 +743,7 @@ export class CipherSuite {
|
|
|
733
743
|
*
|
|
734
744
|
* @returns A Promise that resolves to the deserialized private key.
|
|
735
745
|
*/
|
|
736
|
-
async DeserializePrivateKey(privateKey: Uint8Array, extractable?: boolean): Promise<
|
|
746
|
+
async DeserializePrivateKey(privateKey: Uint8Array, extractable?: boolean): Promise<K> {
|
|
737
747
|
extractable ??= false
|
|
738
748
|
checkExtractable(extractable)
|
|
739
749
|
checkUint8Array(privateKey, 'privateKey')
|
|
@@ -768,7 +778,7 @@ export class CipherSuite {
|
|
|
768
778
|
*
|
|
769
779
|
* @returns A Promise that resolves to the deserialized public key.
|
|
770
780
|
*/
|
|
771
|
-
async DeserializePublicKey(publicKey: Uint8Array): Promise<
|
|
781
|
+
async DeserializePublicKey(publicKey: Uint8Array): Promise<K> {
|
|
772
782
|
checkUint8Array(publicKey, 'publicKey')
|
|
773
783
|
|
|
774
784
|
try {
|
|
@@ -816,10 +826,10 @@ export class CipherSuite {
|
|
|
816
826
|
* @returns A Promise that resolves to an object containing the encapsulated secret and
|
|
817
827
|
* ciphertext. The ciphertext is {@link CipherSuite.AEAD Nt} bytes longer than the plaintext. The
|
|
818
828
|
* encapsulated secret is {@link CipherSuite.KEM Nenc} bytes.
|
|
819
|
-
* @see [Single-Shot Encryption](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
829
|
+
* @see [Single-Shot Encryption](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-6.1)
|
|
820
830
|
*/
|
|
821
831
|
async Seal(
|
|
822
|
-
publicKey:
|
|
832
|
+
publicKey: K,
|
|
823
833
|
plaintext: Uint8Array,
|
|
824
834
|
options?: { aad?: Uint8Array; info?: Uint8Array; psk?: Uint8Array; pskId?: Uint8Array },
|
|
825
835
|
): Promise<{ encapsulatedSecret: Uint8Array; ciphertext: Uint8Array }> {
|
|
@@ -865,10 +875,10 @@ export class CipherSuite {
|
|
|
865
875
|
* @param options.pskId - Pre-shared key identifier (for PSK mode)
|
|
866
876
|
*
|
|
867
877
|
* @returns A Promise that resolves to the decrypted plaintext.
|
|
868
|
-
* @see [Single-Shot Decryption](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
878
|
+
* @see [Single-Shot Decryption](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-6.1)
|
|
869
879
|
*/
|
|
870
880
|
async Open(
|
|
871
|
-
privateKey:
|
|
881
|
+
privateKey: K | KeyPair<K>,
|
|
872
882
|
encapsulatedSecret: Uint8Array,
|
|
873
883
|
ciphertext: Uint8Array,
|
|
874
884
|
options?: { aad?: Uint8Array; info?: Uint8Array; psk?: Uint8Array; pskId?: Uint8Array },
|
|
@@ -913,10 +923,10 @@ export class CipherSuite {
|
|
|
913
923
|
*
|
|
914
924
|
* @returns A Promise that resolves to an object containing the encapsulated secret and the
|
|
915
925
|
* exported secret.
|
|
916
|
-
* @see [Single-Shot Secret Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
926
|
+
* @see [Single-Shot Secret Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-6.2)
|
|
917
927
|
*/
|
|
918
928
|
async SendExport(
|
|
919
|
-
publicKey:
|
|
929
|
+
publicKey: K,
|
|
920
930
|
exporterContext: Uint8Array,
|
|
921
931
|
length: number,
|
|
922
932
|
options?: { info?: Uint8Array; psk?: Uint8Array; pskId?: Uint8Array },
|
|
@@ -961,10 +971,10 @@ export class CipherSuite {
|
|
|
961
971
|
* @param options.pskId - Pre-shared key identifier (for PSK mode)
|
|
962
972
|
*
|
|
963
973
|
* @returns A Promise that resolves to the exported secret.
|
|
964
|
-
* @see [Single-Shot Secret Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
974
|
+
* @see [Single-Shot Secret Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-6.2)
|
|
965
975
|
*/
|
|
966
976
|
async ReceiveExport(
|
|
967
|
-
privateKey:
|
|
977
|
+
privateKey: K | KeyPair<K>,
|
|
968
978
|
encapsulatedSecret: Uint8Array,
|
|
969
979
|
exporterContext: Uint8Array,
|
|
970
980
|
length: number,
|
|
@@ -1015,10 +1025,10 @@ export class CipherSuite {
|
|
|
1015
1025
|
*
|
|
1016
1026
|
* @returns A Promise that resolves to an object containing the encapsulated secret and the sender
|
|
1017
1027
|
* context (`ctx`). The encapsulated secret is {@link CipherSuite.KEM Nenc} bytes.
|
|
1018
|
-
* @see [SetupBaseS / SetupPSKS](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
1028
|
+
* @see [SetupBaseS / SetupPSKS](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.1.1)
|
|
1019
1029
|
*/
|
|
1020
1030
|
async SetupSender(
|
|
1021
|
-
publicKey:
|
|
1031
|
+
publicKey: K,
|
|
1022
1032
|
options?: { info?: Uint8Array; psk?: Uint8Array; pskId?: Uint8Array },
|
|
1023
1033
|
): Promise<{ encapsulatedSecret: Uint8Array; ctx: SenderContext }> {
|
|
1024
1034
|
isKey(publicKey, 'public')
|
|
@@ -1096,10 +1106,10 @@ export class CipherSuite {
|
|
|
1096
1106
|
* @param options.pskId - Pre-shared key identifier (for PSK mode)
|
|
1097
1107
|
*
|
|
1098
1108
|
* @returns A Promise that resolves to the recipient context.
|
|
1099
|
-
* @see [SetupBaseR / SetupPSKR](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
1109
|
+
* @see [SetupBaseR / SetupPSKR](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.1.1)
|
|
1100
1110
|
*/
|
|
1101
1111
|
async SetupRecipient(
|
|
1102
|
-
privateKey:
|
|
1112
|
+
privateKey: K | KeyPair<K>,
|
|
1103
1113
|
encapsulatedSecret: Uint8Array,
|
|
1104
1114
|
options?: { info?: Uint8Array; psk?: Uint8Array; pskId?: Uint8Array },
|
|
1105
1115
|
): Promise<RecipientContext> {
|
|
@@ -1132,7 +1142,7 @@ export class CipherSuite {
|
|
|
1132
1142
|
return new RecipientContext(this.#suite, mode, key, base_nonce, exporter_secret)
|
|
1133
1143
|
}
|
|
1134
1144
|
|
|
1135
|
-
#extractRecipientKeys(skR:
|
|
1145
|
+
#extractRecipientKeys(skR: K | KeyPair<K>): { skR: K; pkR: K | undefined } {
|
|
1136
1146
|
if (isKeyPair(skR)) {
|
|
1137
1147
|
return { skR: skR.privateKey, pkR: skR.publicKey }
|
|
1138
1148
|
}
|
|
@@ -1270,9 +1280,9 @@ export class NotSupportedError extends Error {
|
|
|
1270
1280
|
// Type Definitions and Interfaces
|
|
1271
1281
|
// ============================================================================
|
|
1272
1282
|
|
|
1273
|
-
interface Triple {
|
|
1283
|
+
interface Triple<K extends Key = Key> {
|
|
1274
1284
|
readonly id: Uint8Array
|
|
1275
|
-
readonly KEM: Readonly<KEM
|
|
1285
|
+
readonly KEM: Readonly<KEM<K>>
|
|
1276
1286
|
readonly KDF: Readonly<KDF>
|
|
1277
1287
|
readonly AEAD: Readonly<AEAD>
|
|
1278
1288
|
}
|
|
@@ -1283,7 +1293,7 @@ interface Triple {
|
|
|
1283
1293
|
* Base mode provides encryption to a public key without sender authentication. The recipient cannot
|
|
1284
1294
|
* verify who encrypted the message, only that someone with access to their public key did.
|
|
1285
1295
|
*
|
|
1286
|
-
* @see [HPKE Modes](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
1296
|
+
* @see [HPKE Modes](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5)
|
|
1287
1297
|
*/
|
|
1288
1298
|
export const MODE_BASE = 0x00
|
|
1289
1299
|
|
|
@@ -1294,10 +1304,13 @@ export const MODE_BASE = 0x00
|
|
|
1294
1304
|
* sender and recipient must possess the same PSK and PSK ID. This provides implicit sender
|
|
1295
1305
|
* authentication.
|
|
1296
1306
|
*
|
|
1297
|
-
* @see [HPKE Modes](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
1307
|
+
* @see [HPKE Modes](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5)
|
|
1298
1308
|
*/
|
|
1299
1309
|
export const MODE_PSK = 0x01
|
|
1300
1310
|
|
|
1311
|
+
/** Mode supported by this implementation. */
|
|
1312
|
+
export type Mode = typeof MODE_BASE | typeof MODE_PSK
|
|
1313
|
+
|
|
1301
1314
|
/**
|
|
1302
1315
|
* Factory function that returns a KEM implementation.
|
|
1303
1316
|
*
|
|
@@ -1329,8 +1342,10 @@ export const MODE_PSK = 0x01
|
|
|
1329
1342
|
* > returning an object conforming to the {@link KEM} interface can be used. Such implementations not
|
|
1330
1343
|
* > reliant on Web Cryptography are exported by
|
|
1331
1344
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
1345
|
+
*
|
|
1346
|
+
* @typeParam K - Key representation produced and consumed by the KEM
|
|
1332
1347
|
*/
|
|
1333
|
-
export type KEMFactory = () => Readonly<KEM
|
|
1348
|
+
export type KEMFactory<K extends Key = Key> = () => Readonly<KEM<K>>
|
|
1334
1349
|
|
|
1335
1350
|
/**
|
|
1336
1351
|
* Factory function that returns a KDF implementation.
|
|
@@ -1387,12 +1402,14 @@ export type AEADFactory = () => Readonly<AEAD>
|
|
|
1387
1402
|
* - Private Key: Used by recipients for decryption operations (passed to
|
|
1388
1403
|
* {@link CipherSuite.SetupRecipient} or {@link CipherSuite.Open}). These are not distributed and
|
|
1389
1404
|
* kept private.
|
|
1405
|
+
*
|
|
1406
|
+
* @typeParam K - Key representation contained in the pair
|
|
1390
1407
|
*/
|
|
1391
|
-
export interface KeyPair {
|
|
1408
|
+
export interface KeyPair<K extends Key = Key> {
|
|
1392
1409
|
/** The public key, used for encryption operations. */
|
|
1393
|
-
readonly publicKey: Readonly<
|
|
1410
|
+
readonly publicKey: Readonly<K>
|
|
1394
1411
|
/** The private key, used for decryption operations. */
|
|
1395
|
-
readonly privateKey: Readonly<
|
|
1412
|
+
readonly privateKey: Readonly<K>
|
|
1396
1413
|
}
|
|
1397
1414
|
|
|
1398
1415
|
/**
|
|
@@ -1419,6 +1436,34 @@ export interface Key {
|
|
|
1419
1436
|
readonly type: 'private' | 'public' | (string & {})
|
|
1420
1437
|
}
|
|
1421
1438
|
|
|
1439
|
+
/**
|
|
1440
|
+
* A Web Cryptography key as declared by the host runtime.
|
|
1441
|
+
*
|
|
1442
|
+
* This aliases the key type returned by the host's `SubtleCrypto.generateKey()` API when it is
|
|
1443
|
+
* exposed on `globalThis`. A structural fallback is used otherwise, keeping the package portable to
|
|
1444
|
+
* runtimes and TypeScript projects that do not include DOM or Node.js ambient types.
|
|
1445
|
+
*/
|
|
1446
|
+
export type CryptoKey = typeof globalThis extends {
|
|
1447
|
+
crypto: { subtle: { generateKey(...args: any[]): Promise<infer R> } }
|
|
1448
|
+
}
|
|
1449
|
+
? Extract<R, { type: string }>
|
|
1450
|
+
: CryptoKeyStructuralFallback
|
|
1451
|
+
|
|
1452
|
+
/**
|
|
1453
|
+
* Used as {@link CryptoKey} when the host runtime's `crypto` global is not exposed on `typeof
|
|
1454
|
+
* globalThis`, including when it is absent from ambient types or declared with `const` or `let`. It
|
|
1455
|
+
* remains structurally compatible with host {@link !CryptoKey} declarations so values flow freely to
|
|
1456
|
+
* and from {@link !SubtleCrypto} APIs.
|
|
1457
|
+
*
|
|
1458
|
+
* @internal
|
|
1459
|
+
*/
|
|
1460
|
+
interface CryptoKeyStructuralFallback {
|
|
1461
|
+
readonly algorithm: { name: string }
|
|
1462
|
+
readonly extractable: boolean
|
|
1463
|
+
readonly type: string
|
|
1464
|
+
readonly usages: string[]
|
|
1465
|
+
}
|
|
1466
|
+
|
|
1422
1467
|
// ============================================================================
|
|
1423
1468
|
// Utility Functions
|
|
1424
1469
|
// ============================================================================
|
|
@@ -1516,7 +1561,7 @@ function lengthPrefixed(x: Uint8Array): Uint8Array {
|
|
|
1516
1561
|
* ensures domain separation between different uses of the KDF in HPKE.
|
|
1517
1562
|
*
|
|
1518
1563
|
* @group Utilities
|
|
1519
|
-
* @see [LabeledDerive](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-
|
|
1564
|
+
* @see [LabeledDerive](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-5)
|
|
1520
1565
|
*/
|
|
1521
1566
|
export async function LabeledDerive(
|
|
1522
1567
|
KDF: Pick<KDF, 'Derive'>,
|
|
@@ -1530,7 +1575,7 @@ export async function LabeledDerive(
|
|
|
1530
1575
|
return await KDF.Derive(labeled_ikm, L)
|
|
1531
1576
|
}
|
|
1532
1577
|
|
|
1533
|
-
/** @see [Export_OneStage](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-
|
|
1578
|
+
/** @see [Export_OneStage](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-5) */
|
|
1534
1579
|
async function Export_OneStage(
|
|
1535
1580
|
KDF: KDF,
|
|
1536
1581
|
suite_id: Uint8Array,
|
|
@@ -1542,7 +1587,7 @@ async function Export_OneStage(
|
|
|
1542
1587
|
return await LabeledDerive(KDF, suite_id, exporter_secret, L_sec, exporter_context, L)
|
|
1543
1588
|
}
|
|
1544
1589
|
|
|
1545
|
-
/** @see [CombineSecrets_OneStage](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-
|
|
1590
|
+
/** @see [CombineSecrets_OneStage](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-5) */
|
|
1546
1591
|
async function CombineSecrets_OneStage(
|
|
1547
1592
|
suite: Triple,
|
|
1548
1593
|
mode: number,
|
|
@@ -1599,7 +1644,7 @@ function checkExtractable(extractable: unknown): asserts extractable is boolean
|
|
|
1599
1644
|
}
|
|
1600
1645
|
}
|
|
1601
1646
|
|
|
1602
|
-
/** @see [KeySchedule (CombineSecrets)](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
1647
|
+
/** @see [KeySchedule (CombineSecrets)](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.1) */
|
|
1603
1648
|
async function CombineSecrets_TwoStage(
|
|
1604
1649
|
suite: Triple,
|
|
1605
1650
|
mode: number,
|
|
@@ -1642,7 +1687,7 @@ async function CombineSecrets_TwoStage(
|
|
|
1642
1687
|
return { key, base_nonce, exporter_secret }
|
|
1643
1688
|
}
|
|
1644
1689
|
|
|
1645
|
-
/** @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
1690
|
+
/** @see [Context.Export](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.3) */
|
|
1646
1691
|
async function Export_TwoStage(
|
|
1647
1692
|
KDF: KDF,
|
|
1648
1693
|
suite_id: Uint8Array,
|
|
@@ -1719,7 +1764,7 @@ async function Export_TwoStage(
|
|
|
1719
1764
|
* )
|
|
1720
1765
|
* ```
|
|
1721
1766
|
*
|
|
1722
|
-
* @see [HPKE Key Derivation Functions](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
1767
|
+
* @see [HPKE Key Derivation Functions](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.2)
|
|
1723
1768
|
*/
|
|
1724
1769
|
export interface KDF {
|
|
1725
1770
|
/** KDF algorithm identifier */
|
|
@@ -1792,7 +1837,7 @@ export interface KDF {
|
|
|
1792
1837
|
* pseudorandom key. This ensures domain separation between different uses of the KDF in HPKE.
|
|
1793
1838
|
*
|
|
1794
1839
|
* @group Utilities
|
|
1795
|
-
* @see [LabeledExtract](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
1840
|
+
* @see [LabeledExtract](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.4)
|
|
1796
1841
|
*/
|
|
1797
1842
|
export async function LabeledExtract(
|
|
1798
1843
|
KDF: Pick<KDF, 'Extract'>,
|
|
@@ -1822,7 +1867,7 @@ export async function LabeledExtract(
|
|
|
1822
1867
|
* of the KDF in HPKE.
|
|
1823
1868
|
*
|
|
1824
1869
|
* @group Utilities
|
|
1825
|
-
* @see [LabeledExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
1870
|
+
* @see [LabeledExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.4)
|
|
1826
1871
|
*/
|
|
1827
1872
|
export async function LabeledExpand(
|
|
1828
1873
|
KDF: Pick<KDF, 'Expand'>,
|
|
@@ -1931,9 +1976,10 @@ export async function LabeledExpand(
|
|
|
1931
1976
|
* )
|
|
1932
1977
|
* ```
|
|
1933
1978
|
*
|
|
1934
|
-
* @
|
|
1979
|
+
* @typeParam K - Key representation produced and consumed by the KEM
|
|
1980
|
+
* @see [HPKE Key Encapsulation Mechanisms](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.1)
|
|
1935
1981
|
*/
|
|
1936
|
-
export interface KEM {
|
|
1982
|
+
export interface KEM<K extends Key = Key> {
|
|
1937
1983
|
/** KEM algorithm identifier */
|
|
1938
1984
|
readonly id: number
|
|
1939
1985
|
|
|
@@ -1963,7 +2009,7 @@ export interface KEM {
|
|
|
1963
2009
|
*
|
|
1964
2010
|
* @returns A promise resolving to a {@link KeyPair}
|
|
1965
2011
|
*/
|
|
1966
|
-
DeriveKeyPair(ikm: Uint8Array, extractable: boolean): Promise<KeyPair
|
|
2012
|
+
DeriveKeyPair(ikm: Uint8Array, extractable: boolean): Promise<KeyPair<K>>
|
|
1967
2013
|
|
|
1968
2014
|
/**
|
|
1969
2015
|
* Generates a random key pair.
|
|
@@ -1972,7 +2018,7 @@ export interface KEM {
|
|
|
1972
2018
|
*
|
|
1973
2019
|
* @returns A promise resolving to a {@link KeyPair}
|
|
1974
2020
|
*/
|
|
1975
|
-
GenerateKeyPair(extractable: boolean): Promise<KeyPair
|
|
2021
|
+
GenerateKeyPair(extractable: boolean): Promise<KeyPair<K>>
|
|
1976
2022
|
|
|
1977
2023
|
/**
|
|
1978
2024
|
* Serializes a public key to bytes.
|
|
@@ -1981,7 +2027,7 @@ export interface KEM {
|
|
|
1981
2027
|
*
|
|
1982
2028
|
* @returns A promise resolving to the serialized public key
|
|
1983
2029
|
*/
|
|
1984
|
-
SerializePublicKey(key:
|
|
2030
|
+
SerializePublicKey(key: K): Promise<Uint8Array>
|
|
1985
2031
|
|
|
1986
2032
|
/**
|
|
1987
2033
|
* Deserializes a public key from bytes.
|
|
@@ -1990,7 +2036,7 @@ export interface KEM {
|
|
|
1990
2036
|
*
|
|
1991
2037
|
* @returns A promise resolving to a {@link !Key} or a Key interface-conforming object
|
|
1992
2038
|
*/
|
|
1993
|
-
DeserializePublicKey(key: Uint8Array): Promise<
|
|
2039
|
+
DeserializePublicKey(key: Uint8Array): Promise<K>
|
|
1994
2040
|
|
|
1995
2041
|
/**
|
|
1996
2042
|
* Serializes a private key to bytes.
|
|
@@ -1999,7 +2045,7 @@ export interface KEM {
|
|
|
1999
2045
|
*
|
|
2000
2046
|
* @returns A promise resolving to the serialized private key
|
|
2001
2047
|
*/
|
|
2002
|
-
SerializePrivateKey(key:
|
|
2048
|
+
SerializePrivateKey(key: K): Promise<Uint8Array>
|
|
2003
2049
|
|
|
2004
2050
|
/**
|
|
2005
2051
|
* Deserializes a private key from bytes.
|
|
@@ -2009,7 +2055,7 @@ export interface KEM {
|
|
|
2009
2055
|
*
|
|
2010
2056
|
* @returns A promise resolving to a {@link !Key} or a Key interface-conforming object
|
|
2011
2057
|
*/
|
|
2012
|
-
DeserializePrivateKey(key: Uint8Array, extractable: boolean): Promise<
|
|
2058
|
+
DeserializePrivateKey(key: Uint8Array, extractable: boolean): Promise<K>
|
|
2013
2059
|
|
|
2014
2060
|
/**
|
|
2015
2061
|
* Encapsulates a shared secret to a recipient's public key.
|
|
@@ -2022,7 +2068,7 @@ export interface KEM {
|
|
|
2022
2068
|
*
|
|
2023
2069
|
* @returns A promise resolving to an object containing the shared secret and encapsulated secret
|
|
2024
2070
|
*/
|
|
2025
|
-
Encap(pkR:
|
|
2071
|
+
Encap(pkR: K): Promise<{ shared_secret: Uint8Array; enc: Uint8Array }>
|
|
2026
2072
|
|
|
2027
2073
|
/**
|
|
2028
2074
|
* Decapsulates a shared secret using a recipient's private key.
|
|
@@ -2037,10 +2083,10 @@ export interface KEM {
|
|
|
2037
2083
|
*
|
|
2038
2084
|
* @returns A promise resolving to the shared secret
|
|
2039
2085
|
*/
|
|
2040
|
-
Decap(enc: Uint8Array, skR:
|
|
2086
|
+
Decap(enc: Uint8Array, skR: K, pkR: K | undefined): Promise<Uint8Array>
|
|
2041
2087
|
}
|
|
2042
2088
|
|
|
2043
|
-
function isKeyPair(skR:
|
|
2089
|
+
function isKeyPair<K extends Key>(skR: K | KeyPair<K>): skR is KeyPair<K> {
|
|
2044
2090
|
if (!skR || typeof skR !== 'object') return false
|
|
2045
2091
|
if ('publicKey' in skR && 'privateKey' in skR) {
|
|
2046
2092
|
const pkR = skR.publicKey
|
|
@@ -2133,7 +2179,7 @@ function isKey(key: unknown, type: string, extractable?: boolean): asserts key i
|
|
|
2133
2179
|
* )
|
|
2134
2180
|
* ```
|
|
2135
2181
|
*
|
|
2136
|
-
* @see [HPKE AEAD Encryption Algorithm](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
2182
|
+
* @see [HPKE AEAD Encryption Algorithm](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.3)
|
|
2137
2183
|
*/
|
|
2138
2184
|
export interface AEAD {
|
|
2139
2185
|
/** AEAD algorithm identifier */
|
|
@@ -2157,12 +2203,18 @@ export interface AEAD {
|
|
|
2157
2203
|
/**
|
|
2158
2204
|
* Encrypts and authenticates plaintext with associated data.
|
|
2159
2205
|
*
|
|
2206
|
+
* Implementations must enforce the AEAD algorithm's per-invocation plaintext length limit (P_MAX)
|
|
2207
|
+
* before encryption. HPKE's explicit error list maps `MessageLimitReachedError` to context
|
|
2208
|
+
* sequence number overflow; it does not prescribe a specific error for P_MAX violations. Report
|
|
2209
|
+
* them as ordinary input range errors, such as `RangeError`.
|
|
2210
|
+
*
|
|
2160
2211
|
* @param key - The encryption key of {@link Nk} bytes
|
|
2161
2212
|
* @param nonce - The nonce of {@link Nn} bytes
|
|
2162
2213
|
* @param aad - Additional authenticated data
|
|
2163
2214
|
* @param pt - Plaintext to encrypt
|
|
2164
2215
|
*
|
|
2165
2216
|
* @returns A promise resolving to the ciphertext with authentication tag appended
|
|
2217
|
+
* @see [Context.Seal P_MAX handling](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.2)
|
|
2166
2218
|
*/
|
|
2167
2219
|
Seal(key: Uint8Array, nonce: Uint8Array, aad: Uint8Array, pt: Uint8Array): Promise<Uint8Array>
|
|
2168
2220
|
|
|
@@ -2223,7 +2275,7 @@ function KDFStages(KDF: KDF): 1 | 2 {
|
|
|
2223
2275
|
throw new Error('unreachable')
|
|
2224
2276
|
}
|
|
2225
2277
|
|
|
2226
|
-
/** @see [KeySchedule](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
2278
|
+
/** @see [KeySchedule](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.1) */
|
|
2227
2279
|
async function KeySchedule(
|
|
2228
2280
|
suite: Triple,
|
|
2229
2281
|
mode: number,
|
|
@@ -2246,7 +2298,7 @@ async function KeySchedule(
|
|
|
2246
2298
|
return await CombineSecrets(suite, mode, shared_secret, info, psk, pskId)
|
|
2247
2299
|
}
|
|
2248
2300
|
|
|
2249
|
-
/** @see [VerifyPSKInputs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
2301
|
+
/** @see [VerifyPSKInputs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-5.1) */
|
|
2250
2302
|
function VerifyPSKInputs(psk: Uint8Array, psk_id: Uint8Array) {
|
|
2251
2303
|
if (psk.byteLength && psk_id.byteLength) {
|
|
2252
2304
|
if (psk.byteLength < 32) {
|
|
@@ -2266,6 +2318,8 @@ const NotApplicable = () => {
|
|
|
2266
2318
|
}
|
|
2267
2319
|
|
|
2268
2320
|
const EXPORT_ONLY = 0xffff
|
|
2321
|
+
const AES_GCM_P_MAX = 2 ** 36 - 31
|
|
2322
|
+
const CHACHA20_POLY1305_P_MAX = 2 ** 38 - 64
|
|
2269
2323
|
/**
|
|
2270
2324
|
* Export-only AEAD mode.
|
|
2271
2325
|
*
|
|
@@ -2276,7 +2330,7 @@ const EXPORT_ONLY = 0xffff
|
|
|
2276
2330
|
* This is a factory function that must be passed to the {@link CipherSuite} constructor.
|
|
2277
2331
|
*
|
|
2278
2332
|
* @group AEAD Algorithms
|
|
2279
|
-
* @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
2333
|
+
* @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.3)
|
|
2280
2334
|
*/
|
|
2281
2335
|
export const AEAD_EXPORT_ONLY: AEADFactory = function (): AEAD {
|
|
2282
2336
|
return {
|
|
@@ -2402,7 +2456,7 @@ function HKDF_SHARED(): KDF_BASE {
|
|
|
2402
2456
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
2403
2457
|
*
|
|
2404
2458
|
* @group KDF Algorithms
|
|
2405
|
-
* @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
2459
|
+
* @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.2)
|
|
2406
2460
|
*/
|
|
2407
2461
|
export const KDF_HKDF_SHA256: KDFFactory = function (): HKDF {
|
|
2408
2462
|
return { id: 0x0001, type: 'KDF', name: 'HKDF-SHA256', Nh: 32, hash: 'SHA-256', ...HKDF_SHARED() }
|
|
@@ -2425,7 +2479,7 @@ export const KDF_HKDF_SHA256: KDFFactory = function (): HKDF {
|
|
|
2425
2479
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
2426
2480
|
*
|
|
2427
2481
|
* @group KDF Algorithms
|
|
2428
|
-
* @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
2482
|
+
* @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.2)
|
|
2429
2483
|
*/
|
|
2430
2484
|
export const KDF_HKDF_SHA384: KDFFactory = function (): HKDF {
|
|
2431
2485
|
return { id: 0x0002, type: 'KDF', name: 'HKDF-SHA384', Nh: 48, hash: 'SHA-384', ...HKDF_SHARED() }
|
|
@@ -2448,7 +2502,7 @@ export const KDF_HKDF_SHA384: KDFFactory = function (): HKDF {
|
|
|
2448
2502
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
2449
2503
|
*
|
|
2450
2504
|
* @group KDF Algorithms
|
|
2451
|
-
* @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
2505
|
+
* @see [HPKE KDF Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.2)
|
|
2452
2506
|
*/
|
|
2453
2507
|
export const KDF_HKDF_SHA512: KDFFactory = function (): HKDF {
|
|
2454
2508
|
return { id: 0x0003, type: 'KDF', name: 'HKDF-SHA512', Nh: 64, hash: 'SHA-512', ...HKDF_SHARED() }
|
|
@@ -2496,7 +2550,7 @@ function SHAKE_SHARED(): KDF_BASE {
|
|
|
2496
2550
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
2497
2551
|
*
|
|
2498
2552
|
* @group KDF Algorithms
|
|
2499
|
-
* @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-
|
|
2553
|
+
* @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-5)
|
|
2500
2554
|
*/
|
|
2501
2555
|
export const KDF_SHAKE128: KDFFactory = function (): SHAKE {
|
|
2502
2556
|
return {
|
|
@@ -2526,7 +2580,7 @@ export const KDF_SHAKE128: KDFFactory = function (): SHAKE {
|
|
|
2526
2580
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
2527
2581
|
*
|
|
2528
2582
|
* @group KDF Algorithms
|
|
2529
|
-
* @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-
|
|
2583
|
+
* @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-5)
|
|
2530
2584
|
*/
|
|
2531
2585
|
export const KDF_SHAKE256: KDFFactory = function (): SHAKE {
|
|
2532
2586
|
return {
|
|
@@ -2556,7 +2610,7 @@ export const KDF_SHAKE256: KDFFactory = function (): SHAKE {
|
|
|
2556
2610
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
2557
2611
|
*
|
|
2558
2612
|
* @group KDF Algorithms
|
|
2559
|
-
* @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-
|
|
2613
|
+
* @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-5)
|
|
2560
2614
|
*/
|
|
2561
2615
|
export const KDF_TurboSHAKE128: KDFFactory = function (): SHAKE {
|
|
2562
2616
|
return {
|
|
@@ -2586,7 +2640,7 @@ export const KDF_TurboSHAKE128: KDFFactory = function (): SHAKE {
|
|
|
2586
2640
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
2587
2641
|
*
|
|
2588
2642
|
* @group KDF Algorithms
|
|
2589
|
-
* @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-
|
|
2643
|
+
* @see [HPKE-PQ One-Stage KDFs](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-5)
|
|
2590
2644
|
*/
|
|
2591
2645
|
export const KDF_TurboSHAKE256: KDFFactory = function (): SHAKE {
|
|
2592
2646
|
return {
|
|
@@ -2641,8 +2695,8 @@ function checkNotAllZeros(buffer: Uint8Array): void {
|
|
|
2641
2695
|
}
|
|
2642
2696
|
}
|
|
2643
2697
|
|
|
2644
|
-
type KEM_BASE = Pick<
|
|
2645
|
-
KEM
|
|
2698
|
+
type KEM_BASE<K extends Key = Key> = Pick<
|
|
2699
|
+
KEM<K>,
|
|
2646
2700
|
| 'GenerateKeyPair'
|
|
2647
2701
|
| 'DeriveKeyPair'
|
|
2648
2702
|
| 'SerializePublicKey'
|
|
@@ -2653,7 +2707,7 @@ type KEM_BASE = Pick<
|
|
|
2653
2707
|
| 'Decap'
|
|
2654
2708
|
>
|
|
2655
2709
|
|
|
2656
|
-
interface DHKEM extends KEM {
|
|
2710
|
+
interface DHKEM extends KEM<CryptoKey> {
|
|
2657
2711
|
readonly suite_id: Uint8Array
|
|
2658
2712
|
readonly Ndh: number
|
|
2659
2713
|
readonly kdf: KDF
|
|
@@ -2692,22 +2746,19 @@ function b64u(input: string): Uint8Array {
|
|
|
2692
2746
|
// KEM (Key Encapsulation Mechanism) - DHKEM Helper Functions
|
|
2693
2747
|
// ============================================================================
|
|
2694
2748
|
|
|
2695
|
-
/** @see [DeriveKeyPair
|
|
2696
|
-
async function
|
|
2749
|
+
/** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1.3) */
|
|
2750
|
+
async function DeriveKeyPairBytes(
|
|
2697
2751
|
DHKEM: DHKEM,
|
|
2698
|
-
suite_id: Uint8Array,
|
|
2699
2752
|
ikm: Uint8Array,
|
|
2700
|
-
|
|
2753
|
+
label: Uint8Array,
|
|
2754
|
+
context: Uint8Array,
|
|
2701
2755
|
) {
|
|
2702
|
-
|
|
2703
|
-
|
|
2704
|
-
|
|
2705
|
-
|
|
2706
|
-
|
|
2707
|
-
|
|
2708
|
-
I2OSP(counter, 1),
|
|
2709
|
-
DHKEM.Nsk,
|
|
2710
|
-
)
|
|
2756
|
+
if (KDFStages(DHKEM.kdf) === 1) {
|
|
2757
|
+
return await LabeledDerive(DHKEM.kdf, DHKEM.suite_id, ikm, label, context, DHKEM.Nsk)
|
|
2758
|
+
}
|
|
2759
|
+
|
|
2760
|
+
const dkp_prk = await LabeledExtract(DHKEM.kdf, DHKEM.suite_id, new Uint8Array(), L_dkp_prk, ikm)
|
|
2761
|
+
return await LabeledExpand(DHKEM.kdf, DHKEM.suite_id, dkp_prk, label, context, DHKEM.Nsk)
|
|
2711
2762
|
}
|
|
2712
2763
|
|
|
2713
2764
|
function OS2IP(x: Uint8Array): bigint {
|
|
@@ -2752,7 +2803,23 @@ function assertCryptoKey(key: Key): asserts key is CryptoKey {
|
|
|
2752
2803
|
}
|
|
2753
2804
|
}
|
|
2754
2805
|
|
|
2755
|
-
/** @see [ExtractAndExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
2806
|
+
/** @see [ExtractAndExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.5) */
|
|
2807
|
+
async function ExtractAndExpand_OneStage(
|
|
2808
|
+
DHKEM: DHKEM,
|
|
2809
|
+
dh: Uint8Array,
|
|
2810
|
+
kem_context: Uint8Array,
|
|
2811
|
+
): Promise<Uint8Array> {
|
|
2812
|
+
return await LabeledDerive(
|
|
2813
|
+
DHKEM.kdf,
|
|
2814
|
+
DHKEM.suite_id,
|
|
2815
|
+
dh,
|
|
2816
|
+
L_shared_secret,
|
|
2817
|
+
kem_context,
|
|
2818
|
+
DHKEM.Nsecret,
|
|
2819
|
+
)
|
|
2820
|
+
}
|
|
2821
|
+
|
|
2822
|
+
/** @see [ExtractAndExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.5) */
|
|
2756
2823
|
async function ExtractAndExpand_TwoStage(
|
|
2757
2824
|
DHKEM: DHKEM,
|
|
2758
2825
|
dh: Uint8Array,
|
|
@@ -2769,11 +2836,23 @@ async function ExtractAndExpand_TwoStage(
|
|
|
2769
2836
|
)
|
|
2770
2837
|
}
|
|
2771
2838
|
|
|
2839
|
+
/** @see [ExtractAndExpand](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-4.5) */
|
|
2840
|
+
async function ExtractAndExpand(
|
|
2841
|
+
DHKEM: DHKEM,
|
|
2842
|
+
dh: Uint8Array,
|
|
2843
|
+
kem_context: Uint8Array,
|
|
2844
|
+
): Promise<Uint8Array> {
|
|
2845
|
+
const Fn = KDFStages(DHKEM.kdf) === 1 ? ExtractAndExpand_OneStage : ExtractAndExpand_TwoStage
|
|
2846
|
+
return await Fn(DHKEM, dh, kem_context)
|
|
2847
|
+
}
|
|
2848
|
+
|
|
2772
2849
|
// ============================================================================
|
|
2773
2850
|
// KEM (Key Encapsulation Mechanism) - DHKEM Shared Implementation
|
|
2774
2851
|
// ============================================================================
|
|
2775
2852
|
|
|
2776
|
-
function DHKEM_SHARED(): Required<
|
|
2853
|
+
function DHKEM_SHARED(): Required<
|
|
2854
|
+
Omit<KEM_BASE<CryptoKey>, 'DeriveKeyPair' | 'DeserializePrivateKey'>
|
|
2855
|
+
> {
|
|
2777
2856
|
return {
|
|
2778
2857
|
async GenerateKeyPair(this: DHKEM, extractable) {
|
|
2779
2858
|
return (await subtle(
|
|
@@ -2819,7 +2898,7 @@ function DHKEM_SHARED(): Required<Omit<KEM_BASE, 'DeriveKeyPair' | 'DeserializeP
|
|
|
2819
2898
|
const enc = await this.SerializePublicKey(pkE)
|
|
2820
2899
|
const pkRm = await this.SerializePublicKey(pkR)
|
|
2821
2900
|
const kem_context = concat(enc, pkRm)
|
|
2822
|
-
const shared_secret = await
|
|
2901
|
+
const shared_secret = await ExtractAndExpand(this, dh, kem_context)
|
|
2823
2902
|
return { shared_secret, enc }
|
|
2824
2903
|
},
|
|
2825
2904
|
async Decap(this: DHKEM, enc, skR, pkR) {
|
|
@@ -2846,7 +2925,7 @@ function DHKEM_SHARED(): Required<Omit<KEM_BASE, 'DeriveKeyPair' | 'DeserializeP
|
|
|
2846
2925
|
|
|
2847
2926
|
const pkRm = await this.SerializePublicKey(pkR)
|
|
2848
2927
|
const kem_context = concat(enc, pkRm)
|
|
2849
|
-
const shared_secret = await
|
|
2928
|
+
const shared_secret = await ExtractAndExpand(this, dh, kem_context)
|
|
2850
2929
|
return shared_secret
|
|
2851
2930
|
},
|
|
2852
2931
|
}
|
|
@@ -3057,7 +3136,7 @@ async function DeserializePrivateKeyNist(
|
|
|
3057
3136
|
return privateKey
|
|
3058
3137
|
}
|
|
3059
3138
|
|
|
3060
|
-
/** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
3139
|
+
/** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1.3) */
|
|
3061
3140
|
async function DeriveKeyPairNist(
|
|
3062
3141
|
this: DHKEM & NistCurveConfig,
|
|
3063
3142
|
ikm: Uint8Array,
|
|
@@ -3070,7 +3149,7 @@ async function DeriveKeyPairNist(
|
|
|
3070
3149
|
if (counter > 255) {
|
|
3071
3150
|
throw new DeriveKeyPairError('Key derivation exceeded maximum iterations')
|
|
3072
3151
|
}
|
|
3073
|
-
candidate = await
|
|
3152
|
+
candidate = await DeriveKeyPairBytes(this, ikm, L_candidate, I2OSP(counter, 1))
|
|
3074
3153
|
candidate[0] = candidate[0]! & this.bitmask
|
|
3075
3154
|
sk = OS2IP(candidate)
|
|
3076
3155
|
counter = counter + 1
|
|
@@ -3105,10 +3184,9 @@ async function GetKeyPairNist(
|
|
|
3105
3184
|
// KEM (Key Encapsulation Mechanism) - DHKEM X Curve Implementations
|
|
3106
3185
|
// ============================================================================
|
|
3107
3186
|
|
|
3108
|
-
/** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
3187
|
+
/** @see [DeriveKeyPair](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1.3) */
|
|
3109
3188
|
async function DeriveKeyPairX(this: DHKEM, ikm: Uint8Array, extractable: boolean) {
|
|
3110
|
-
const
|
|
3111
|
-
const sk = await LabeledExpand(this.kdf, this.suite_id, dkp_prk, L_sk, new Uint8Array(), this.Nsk)
|
|
3189
|
+
const sk = await DeriveKeyPairBytes(this, ikm, L_sk, new Uint8Array())
|
|
3112
3190
|
return await createKeyPairFromPrivateKey(this, sk, extractable)
|
|
3113
3191
|
}
|
|
3114
3192
|
|
|
@@ -3145,9 +3223,10 @@ const P256: NistCurveConfig = {
|
|
|
3145
3223
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
3146
3224
|
*
|
|
3147
3225
|
* @group KEM Algorithms
|
|
3148
|
-
* @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
3226
|
+
* @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1)
|
|
3149
3227
|
*/
|
|
3150
|
-
export const KEM_DHKEM_P256_HKDF_SHA256: KEMFactory = function (): DHKEM &
|
|
3228
|
+
export const KEM_DHKEM_P256_HKDF_SHA256: KEMFactory<CryptoKey> = function (): DHKEM &
|
|
3229
|
+
NistCurveConfig {
|
|
3151
3230
|
const id = 0x0010
|
|
3152
3231
|
const name = 'DHKEM(P-256, HKDF-SHA256)'
|
|
3153
3232
|
const kdf = KDF_HKDF_SHA256()
|
|
@@ -3200,9 +3279,10 @@ const P384: NistCurveConfig = {
|
|
|
3200
3279
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
3201
3280
|
*
|
|
3202
3281
|
* @group KEM Algorithms
|
|
3203
|
-
* @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
3282
|
+
* @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1)
|
|
3204
3283
|
*/
|
|
3205
|
-
export const KEM_DHKEM_P384_HKDF_SHA384: KEMFactory = function (): DHKEM &
|
|
3284
|
+
export const KEM_DHKEM_P384_HKDF_SHA384: KEMFactory<CryptoKey> = function (): DHKEM &
|
|
3285
|
+
NistCurveConfig {
|
|
3206
3286
|
const id = 0x0011
|
|
3207
3287
|
const name = 'DHKEM(P-384, HKDF-SHA384)'
|
|
3208
3288
|
const kdf = KDF_HKDF_SHA384()
|
|
@@ -3255,9 +3335,10 @@ const P521: NistCurveConfig = {
|
|
|
3255
3335
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
3256
3336
|
*
|
|
3257
3337
|
* @group KEM Algorithms
|
|
3258
|
-
* @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
3338
|
+
* @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1)
|
|
3259
3339
|
*/
|
|
3260
|
-
export const KEM_DHKEM_P521_HKDF_SHA512: KEMFactory = function (): DHKEM &
|
|
3340
|
+
export const KEM_DHKEM_P521_HKDF_SHA512: KEMFactory<CryptoKey> = function (): DHKEM &
|
|
3341
|
+
NistCurveConfig {
|
|
3261
3342
|
const id = 0x0012
|
|
3262
3343
|
const name = 'DHKEM(P-521, HKDF-SHA512)'
|
|
3263
3344
|
const kdf = KDF_HKDF_SHA512()
|
|
@@ -3301,9 +3382,11 @@ export const KEM_DHKEM_P521_HKDF_SHA512: KEMFactory = function (): DHKEM & NistC
|
|
|
3301
3382
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
3302
3383
|
*
|
|
3303
3384
|
* @group KEM Algorithms
|
|
3304
|
-
* @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
3385
|
+
* @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1)
|
|
3305
3386
|
*/
|
|
3306
|
-
export const KEM_DHKEM_X25519_HKDF_SHA256: KEMFactory = function (): DHKEM & {
|
|
3387
|
+
export const KEM_DHKEM_X25519_HKDF_SHA256: KEMFactory<CryptoKey> = function (): DHKEM & {
|
|
3388
|
+
pkcs8: Uint8Array
|
|
3389
|
+
} {
|
|
3307
3390
|
const id = 0x0020
|
|
3308
3391
|
const name = 'DHKEM(X25519, HKDF-SHA256)'
|
|
3309
3392
|
const kdf = KDF_HKDF_SHA256()
|
|
@@ -3348,9 +3431,11 @@ export const KEM_DHKEM_X25519_HKDF_SHA256: KEMFactory = function (): DHKEM & { p
|
|
|
3348
3431
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
3349
3432
|
*
|
|
3350
3433
|
* @group KEM Algorithms
|
|
3351
|
-
* @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
3434
|
+
* @see [HPKE KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.1)
|
|
3352
3435
|
*/
|
|
3353
|
-
export const KEM_DHKEM_X448_HKDF_SHA512: KEMFactory = function (): DHKEM & {
|
|
3436
|
+
export const KEM_DHKEM_X448_HKDF_SHA512: KEMFactory<CryptoKey> = function (): DHKEM & {
|
|
3437
|
+
pkcs8: Uint8Array
|
|
3438
|
+
} {
|
|
3354
3439
|
const id = 0x0021
|
|
3355
3440
|
const name = 'DHKEM(X448, HKDF-SHA512)'
|
|
3356
3441
|
const kdf = KDF_HKDF_SHA512()
|
|
@@ -3381,13 +3466,13 @@ export const KEM_DHKEM_X448_HKDF_SHA512: KEMFactory = function (): DHKEM & { pkc
|
|
|
3381
3466
|
// KEM (Key Encapsulation Mechanism) - ML-KEM Types and Implementation
|
|
3382
3467
|
// ============================================================================
|
|
3383
3468
|
|
|
3384
|
-
interface MLKEM extends KEM {
|
|
3469
|
+
interface MLKEM extends KEM<CryptoKey> {
|
|
3385
3470
|
readonly suite_id: Uint8Array
|
|
3386
3471
|
readonly algorithm: Readonly<KeyAlgorithm>
|
|
3387
3472
|
readonly kdf: KDF
|
|
3388
3473
|
}
|
|
3389
3474
|
|
|
3390
|
-
function MLKEM_SHARED(): KEM_BASE {
|
|
3475
|
+
function MLKEM_SHARED(): KEM_BASE<CryptoKey> {
|
|
3391
3476
|
return {
|
|
3392
3477
|
async DeriveKeyPair(this: MLKEM, ikm, extractable) {
|
|
3393
3478
|
const dk = await LabeledDerive(
|
|
@@ -3497,9 +3582,9 @@ function MLKEM_SHARED(): KEM_BASE {
|
|
|
3497
3582
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
3498
3583
|
*
|
|
3499
3584
|
* @group KEM Algorithms
|
|
3500
|
-
* @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-
|
|
3585
|
+
* @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-3)
|
|
3501
3586
|
*/
|
|
3502
|
-
export const KEM_ML_KEM_512: KEMFactory = function (): MLKEM {
|
|
3587
|
+
export const KEM_ML_KEM_512: KEMFactory<CryptoKey> = function (): MLKEM {
|
|
3503
3588
|
const id = 0x0040
|
|
3504
3589
|
const name = 'ML-KEM-512'
|
|
3505
3590
|
const kdf = KDF_SHAKE256()
|
|
@@ -3537,9 +3622,9 @@ export const KEM_ML_KEM_512: KEMFactory = function (): MLKEM {
|
|
|
3537
3622
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
3538
3623
|
*
|
|
3539
3624
|
* @group KEM Algorithms
|
|
3540
|
-
* @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-
|
|
3625
|
+
* @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-3)
|
|
3541
3626
|
*/
|
|
3542
|
-
export const KEM_ML_KEM_768: KEMFactory = function (): MLKEM {
|
|
3627
|
+
export const KEM_ML_KEM_768: KEMFactory<CryptoKey> = function (): MLKEM {
|
|
3543
3628
|
const id = 0x0041
|
|
3544
3629
|
const name = 'ML-KEM-768'
|
|
3545
3630
|
const kdf = KDF_SHAKE256()
|
|
@@ -3577,9 +3662,9 @@ export const KEM_ML_KEM_768: KEMFactory = function (): MLKEM {
|
|
|
3577
3662
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
3578
3663
|
*
|
|
3579
3664
|
* @group KEM Algorithms
|
|
3580
|
-
* @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-
|
|
3665
|
+
* @see [HPKE-PQ KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-3)
|
|
3581
3666
|
*/
|
|
3582
|
-
export const KEM_ML_KEM_1024: KEMFactory = function (): MLKEM {
|
|
3667
|
+
export const KEM_ML_KEM_1024: KEMFactory<CryptoKey> = function (): MLKEM {
|
|
3583
3668
|
const id = 0x0042
|
|
3584
3669
|
const name = 'ML-KEM-1024'
|
|
3585
3670
|
const kdf = KDF_SHAKE256()
|
|
@@ -3607,11 +3692,7 @@ interface WebCryptoAEAD extends AEAD {
|
|
|
3607
3692
|
|
|
3608
3693
|
type AEAD_BASE = Pick<AEAD, 'Seal' | 'Open'>
|
|
3609
3694
|
|
|
3610
|
-
function AEAD_SHARED(): AEAD_BASE {
|
|
3611
|
-
// Note: The per-invocation plaintext limits (P_MAX, e.g. 2^36 - 31 bytes for
|
|
3612
|
-
// AES-GCM and 2^38 - 64 bytes for ChaCha20-Poly1305) are not explicitly
|
|
3613
|
-
// enforced here as they exceed the maximum ArrayBuffer/Uint8Array sizes
|
|
3614
|
-
// attainable in JavaScript runtimes.
|
|
3695
|
+
function AEAD_SHARED(P_MAX: number): AEAD_BASE {
|
|
3615
3696
|
// Cache the WebCrypto CryptoKey derived from a given key-bytes Uint8Array.
|
|
3616
3697
|
// Across the lifetime of a SenderContext/RecipientContext, `this.#key` is a
|
|
3617
3698
|
// stable Uint8Array, so crypto.subtle.importKey() would otherwise be called
|
|
@@ -3630,6 +3711,9 @@ function AEAD_SHARED(): AEAD_BASE {
|
|
|
3630
3711
|
}
|
|
3631
3712
|
return {
|
|
3632
3713
|
async Seal(this: WebCryptoAEAD, key, nonce, aad, pt) {
|
|
3714
|
+
if (pt.byteLength > P_MAX) {
|
|
3715
|
+
throw new RangeError('"pt" exceeds P_MAX')
|
|
3716
|
+
}
|
|
3633
3717
|
const cryptoKey =
|
|
3634
3718
|
cache.get(key) ?? (await cacheValue(cache, key, () => importKey.call(this, key)))
|
|
3635
3719
|
return new Uint8Array(
|
|
@@ -3690,7 +3774,7 @@ function AEAD_SHARED(): AEAD_BASE {
|
|
|
3690
3774
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
3691
3775
|
*
|
|
3692
3776
|
* @group AEAD Algorithms
|
|
3693
|
-
* @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
3777
|
+
* @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.3)
|
|
3694
3778
|
*/
|
|
3695
3779
|
export const AEAD_AES_128_GCM: AEADFactory = function (): WebCryptoAEAD {
|
|
3696
3780
|
return {
|
|
@@ -3702,7 +3786,7 @@ export const AEAD_AES_128_GCM: AEADFactory = function (): WebCryptoAEAD {
|
|
|
3702
3786
|
Nt: 16,
|
|
3703
3787
|
algorithm: 'AES-GCM',
|
|
3704
3788
|
keyFormat: 'raw',
|
|
3705
|
-
...AEAD_SHARED(),
|
|
3789
|
+
...AEAD_SHARED(AES_GCM_P_MAX),
|
|
3706
3790
|
}
|
|
3707
3791
|
}
|
|
3708
3792
|
|
|
@@ -3722,7 +3806,7 @@ export const AEAD_AES_128_GCM: AEADFactory = function (): WebCryptoAEAD {
|
|
|
3722
3806
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
3723
3807
|
*
|
|
3724
3808
|
* @group AEAD Algorithms
|
|
3725
|
-
* @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
3809
|
+
* @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.3)
|
|
3726
3810
|
*/
|
|
3727
3811
|
export const AEAD_AES_256_GCM: AEADFactory = function (): WebCryptoAEAD {
|
|
3728
3812
|
return {
|
|
@@ -3734,7 +3818,7 @@ export const AEAD_AES_256_GCM: AEADFactory = function (): WebCryptoAEAD {
|
|
|
3734
3818
|
Nt: 16,
|
|
3735
3819
|
algorithm: 'AES-GCM',
|
|
3736
3820
|
keyFormat: 'raw',
|
|
3737
|
-
...AEAD_SHARED(),
|
|
3821
|
+
...AEAD_SHARED(AES_GCM_P_MAX),
|
|
3738
3822
|
}
|
|
3739
3823
|
}
|
|
3740
3824
|
|
|
@@ -3754,7 +3838,7 @@ export const AEAD_AES_256_GCM: AEADFactory = function (): WebCryptoAEAD {
|
|
|
3754
3838
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
3755
3839
|
*
|
|
3756
3840
|
* @group AEAD Algorithms
|
|
3757
|
-
* @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-
|
|
3841
|
+
* @see [HPKE AEAD Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04.html#section-7.3)
|
|
3758
3842
|
*/
|
|
3759
3843
|
export const AEAD_ChaCha20Poly1305: AEADFactory = function AEAD_ChaCha20Poly1305(): WebCryptoAEAD {
|
|
3760
3844
|
return {
|
|
@@ -3767,7 +3851,7 @@ export const AEAD_ChaCha20Poly1305: AEADFactory = function AEAD_ChaCha20Poly1305
|
|
|
3767
3851
|
algorithm: 'ChaCha20-Poly1305',
|
|
3768
3852
|
// @ts-expect-error
|
|
3769
3853
|
keyFormat: 'raw-secret',
|
|
3770
|
-
...AEAD_SHARED(),
|
|
3854
|
+
...AEAD_SHARED(CHACHA20_POLY1305_P_MAX),
|
|
3771
3855
|
}
|
|
3772
3856
|
}
|
|
3773
3857
|
|
|
@@ -3889,7 +3973,7 @@ function RandomScalarNist(t: HybridKEM['t'], seed: Uint8Array): Uint8Array {
|
|
|
3889
3973
|
return bigIntToUint8Array(sk_bigint, t.Nscalar!)
|
|
3890
3974
|
}
|
|
3891
3975
|
|
|
3892
|
-
/** @see [expandDecapsKeyG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-
|
|
3976
|
+
/** @see [expandDecapsKeyG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12.html#section-5.1.1) */
|
|
3893
3977
|
async function expandDecapsKeyG(PQTKEM: HybridKEM, seed: Uint8Array) {
|
|
3894
3978
|
const Nout = PQTKEM.pq.Nseed + PQTKEM.t.Nseed
|
|
3895
3979
|
const bits = Nout << 3
|
|
@@ -3915,7 +3999,7 @@ async function expandDecapsKeyG(PQTKEM: HybridKEM, seed: Uint8Array) {
|
|
|
3915
3999
|
return { ek_PQ, ek_T, dk_PQ, dk_T }
|
|
3916
4000
|
}
|
|
3917
4001
|
|
|
3918
|
-
/** @see [C2PRICombiner](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-
|
|
4002
|
+
/** @see [C2PRICombiner](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12.html#section-5.1.3) */
|
|
3919
4003
|
async function C2PRICombiner(
|
|
3920
4004
|
PQTKEM: HybridKEM,
|
|
3921
4005
|
ss_PQ: Uint8Array,
|
|
@@ -3929,7 +4013,7 @@ async function C2PRICombiner(
|
|
|
3929
4013
|
return new Uint8Array(await subtle((c) => c.digest('SHA3-256', data), PQTKEM.name))
|
|
3930
4014
|
}
|
|
3931
4015
|
|
|
3932
|
-
/** @see [prepareEncapsG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-
|
|
4016
|
+
/** @see [prepareEncapsG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12.html#section-5.1.1) */
|
|
3933
4017
|
async function prepareEncapsG(
|
|
3934
4018
|
PQTKEM: HybridKEM,
|
|
3935
4019
|
ek_PQ: CryptoKey,
|
|
@@ -3960,7 +4044,7 @@ async function prepareEncapsG(
|
|
|
3960
4044
|
return [ss_PQ, ss_T, ct_PQ, ct_T]
|
|
3961
4045
|
}
|
|
3962
4046
|
|
|
3963
|
-
/** @see [prepareDecapsG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-
|
|
4047
|
+
/** @see [prepareDecapsG](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12.html#section-5.1.1) */
|
|
3964
4048
|
async function prepareDecapsG(
|
|
3965
4049
|
PQTKEM: HybridKEM,
|
|
3966
4050
|
dk_PQ: CryptoKey,
|
|
@@ -3992,7 +4076,7 @@ async function prepareDecapsG(
|
|
|
3992
4076
|
return [ss_PQ, ss_T]
|
|
3993
4077
|
}
|
|
3994
4078
|
|
|
3995
|
-
interface HybridKEM extends KEM {
|
|
4079
|
+
interface HybridKEM extends KEM<HybridKey> {
|
|
3996
4080
|
readonly suite_id: Uint8Array
|
|
3997
4081
|
readonly kdf: KDF
|
|
3998
4082
|
readonly algorithm: KeyAlgorithm
|
|
@@ -4020,7 +4104,7 @@ interface HybridKEM extends KEM {
|
|
|
4020
4104
|
}
|
|
4021
4105
|
}
|
|
4022
4106
|
|
|
4023
|
-
function PQTKEM_SHARED(): KEM_BASE {
|
|
4107
|
+
function PQTKEM_SHARED(): KEM_BASE<HybridKey> {
|
|
4024
4108
|
Object.freeze(HybridKey.prototype)
|
|
4025
4109
|
return {
|
|
4026
4110
|
async DeriveKeyPair(this: HybridKEM, ikm: Uint8Array, extractable) {
|
|
@@ -4157,13 +4241,13 @@ function PQTKEM_SHARED(): KEM_BASE {
|
|
|
4157
4241
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
4158
4242
|
*
|
|
4159
4243
|
* @group KEM Algorithms
|
|
4160
|
-
* @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-
|
|
4244
|
+
* @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-4)
|
|
4161
4245
|
*/
|
|
4162
4246
|
export const KEM_MLKEM768_X25519: KEMFactory = function (): HybridKEM {
|
|
4163
4247
|
const id = 0x647a
|
|
4164
4248
|
const name = 'MLKEM768-X25519'
|
|
4165
4249
|
const kdf = KDF_SHAKE256()
|
|
4166
|
-
const pkcs8 = Uint8Array.of(0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x6e, 0x04, 0x22, 0x04, 0x20)
|
|
4250
|
+
const pkcs8 = Uint8Array.of(0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x6e, 0x04, 0x22, 0x04, 0x20) // prettier-ignore
|
|
4167
4251
|
// @ts-expect-error: so that NotSupportedError messages from kdf's subtle() are accurate
|
|
4168
4252
|
kdf.name = name
|
|
4169
4253
|
return {
|
|
@@ -4214,7 +4298,7 @@ export const KEM_MLKEM768_X25519: KEMFactory = function (): HybridKEM {
|
|
|
4214
4298
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
4215
4299
|
*
|
|
4216
4300
|
* @group KEM Algorithms
|
|
4217
|
-
* @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-
|
|
4301
|
+
* @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-4)
|
|
4218
4302
|
*/
|
|
4219
4303
|
export const KEM_MLKEM768_P256: KEMFactory = function (): HybridKEM {
|
|
4220
4304
|
const id = 0x0050
|
|
@@ -4270,7 +4354,7 @@ export const KEM_MLKEM768_P256: KEMFactory = function (): HybridKEM {
|
|
|
4270
4354
|
* > [`@panva/hpke-noble`](https://www.npmjs.com/package/@panva/hpke-noble)
|
|
4271
4355
|
*
|
|
4272
4356
|
* @group KEM Algorithms
|
|
4273
|
-
* @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-
|
|
4357
|
+
* @see [HPKE-PQ Hybrid KEM Identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05.html#section-4)
|
|
4274
4358
|
*/
|
|
4275
4359
|
export const KEM_MLKEM1024_P384: KEMFactory = function (): HybridKEM {
|
|
4276
4360
|
const id = 0x0051
|